HelpSource/Classes/GUI.schelp

   1 class:: GUI
   2 summary:: Factory abstraction for all GUI related core classes
   3 categories:: GUI>GUI-Tools
   4 related:: Overviews/GUI-Classes, Overviews/GUI-Overview, Classes/ViewRedirect
   5
   6
   7 description::
   8 The GUI class provides a means of writing cross platform gui code. GUI provides Factory abstraction for all gui related core classes. Each gui kit is described by a gui scheme which maps class names to actual classes. These schemes are in turn used by link::Classes/ViewRedirect:: to provide a simple cross-platform gui syntax. It also provide utilities for switching kits and other cross platform tasks. You can get your available schemes (depending on what you installed) with:
   9 code::
  10 GUI.schemes;
  11 ::
  12 For a complete list of gui classes and redirects, see link::Overviews/GUI-Classes::.
  13
  14
  15 subsection:: Switching and Referring to GUI Kits
  16
  17 As of this writing, two GUI kits are available through the GUI class: link::Classes/CocoaGUI:: (Mac OS X native) and link::Classes/SwingGUI:: (Java). Note that link::Classes/SwingOSC:: is not part of every SuperCollider distribution, so you may have to install it separately.
  18
  19 You can switch the GUI kit by calling one of the following class methods:
  20 code::
  21 GUI.cocoa;      // use cocoa in subsequent GUI creation procedures
  22 GUI.swing;      // use swing in subsequent GUI creation procedures
  23                 // NOTE: If you do not have SwingOSC installed, you get
  24                 // a warning only, and do not switch; so you cannot
  25                 // accidentally disable your (mac) gui system.
  26 ::
  27 These methods return the new GUI kit implementation. The current implementation can be queried by calling
  28 code::
  29 GUI.current;    // returns the current GUI kit implementation
  30 ::
  31
  32 If you want to make a GUI kit specific switch (e.g. in a class), then you should use the following instead, as on non-OSX systems the class CocoaGUI is not in the class library path, and you cannot check for an undefined class:
  33 code::
  34 GUI.id; // returns the current GUI kit implementation id; this is currently either \cocoa or \swing
  35 ::
  36
  37 For persistency, you can store the identifier of the kit implementation and recall the kit through the class method code::fromID:::
  38 code::
  39 x = GUI.cocoa;
  40 y = x.id;               // store the identifier of a kit implementation
  41 y.postln;               // the id could be stored in a preferences file for example
  42 GUI.swing;
  43 // now switch back to the kit implementation with identifier y
  44 GUI.fromID( y );
  45 GUI.current.id.postln;  // --> cocoa
  46 ::
  47
  48 The code::*use:: and code::*useID:: methods allow you to temporarily switch the kit, so as to use it only for a dedicated block of statements:
  49 code::
  50 GUI.cocoa;
  51 GUI.useID(\swing, { Array.rand( 1000, 0.0, 1.0 ).plot });
  52 GUI.current.id.postln;  // --> still cocoa
  53 ::
  54
  55 You can get a particular kit using the code::*get:: method. You can switch to a particular kit using the code::*set:: method:
  56 code::
  57 x = GUI.get( \swing );  // note: unlike *swing and *cocoa, this does not _switch_ the current kit!
  58 GUI.current.id.postln;  // --> still cocoa
  59 GUI.set( x );                   // now we make SwingOSC the current kit
  60 GUI.window.viewPalette;
  61 ::
  62
  63 subsection:: Extending GUI Kits
  64
  65 GUI Kits can be extended with custom classes by using their respective code::put:: methods:
  66 code::
  67 GUI.get( \cocoa ).put( \myText, SCStaticText );
  68 GUI.get( \swing ).put( \myText, JSCStaticText );
  69
  70 GUI.cocoa;
  71 GUI.swing;
  72 (
  73         w = GUI.window.new;
  74         GUI.myText.new( w, w.view.bounds.insetBy( 20, 20 )).string_( "schoko" ).background_( Color.red );
  75         w.front;
  76 )
  77 ::
  78
  79 If you intend to add extensions from within your own classes upon class library initialization time, the preferred way is to do this in the startup process:
  80 code::
  81 MyGUIExtension {
  82         *initClass {
  83                 StartUp.add({
  84                         var scheme;
  85
  86                         scheme = GUI.get( \cocoa );
  87                         if( scheme.notNil, {scheme.put( \myText, SCStaticText )});
  88                         scheme = GUI.get( \swing );
  89                         if( scheme.notNil, {scheme.put( \myText, JSCStaticText )});
  90                 });
  91         }
  92 }
  93 ::
  94
  95 classmethods::
  96
  97 subsection:: Methods and Variables for GUI
  98
  99 method:: new
 100 argument:: key
 101
 102 method:: makeGUI
 103 argument:: key
 104 argument:: args
 105 argument:: properties
 106
 107 method:: initClass
 108 Sets the code::skin:: to default values on compile.
 109 code::
 110 fontSpecs: ["Helvetica", 10],
 111 fontColor: Color.black,
 112 background: Color(0.8, 0.85, 0.7, 0.5),
 113 foreground: Color.grey(0.95),
 114 onColor: Color(0.5, 1, 0.5),
 115 offColor: Color.clear,
 116 gap: 0@0,
 117 margin: 2@2,
 118 buttonHeight: 16
 119 ::
 120
 121 method:: cocoa
 122 Makes Cocoa (Mac OS X GUI) the current scheme and returns it. Subsequent GUI object calls to GUI are delegated to cocoa. Returns the current (cocoa) scheme.
 123
 124 method:: swing
 125 Makes Swing (Java GUI) the current scheme and returns it. Subsequent GUI object calls to GUI are delegated to swing. Returns the current (swing) scheme.
 126
 127 method:: fromID
 128 Changes the current scheme and returns the new scheme.
 129 argument:: id
 130 A link::Classes/Symbol::. The identifier of the scheme to use.
 131
 132
 133 method:: current
 134
 135 Returns the current scheme. This is useful for objects that, upon instantiation, wish to store the then-current scheme, so as to be able to consistently use the same scheme in future method calls.
 136
 137 Note:: the caller shouldn't make any assumptions about the nature (the class) of the returned object, so that the actual implementation (an Event) may change in the future. ::
 138
 139
 140 method:: get
 141 Returns the scheme for a given identifier. Does not switch the current scheme.
 142 argument:: id
 143 A link::Classes/Symbol::. The identifier of the scheme to retrieve, such as returned by calling code::aScheme.id::.
 144
 145 method:: set
 146 Changes the current scheme.
 147 argument:: aScheme
 148 An instance of link::Classes/Symbol::. The scheme to use as current scheme.
 149
 150 method:: use
 151 Executes a function body, temporarily setting the current GUI scheme. This is usefull inside view's action functions in order to make this function use the GUI scheme that was originally used for the view of the action, even if the scheme has been switched meanwhile.
 152 argument:: aScheme
 153 The scheme to use during the function execution.
 154 argument:: func
 155 An Instance of link::Classes/Function::.
 156
 157 method:: useID
 158 Same as code::use:: but using a scheme's id as first argument.
 159 argument:: id
 160 The id of the scheme to use during the function execution.
 161 argument:: func
 162 A body to execute.
 163
 164 method:: add
 165 Registers a new scheme. This is typically called by external libraries in their startup procedure. If a scheme with the same identifier (code::scheme.id::) exists, it is overwritten.
 166 argument:: aScheme
 167 The scheme to add.
 168
 169 method:: doesNotUnderstand
 170 All method calls are mapped to the current scheme, so that for example code::GUI.button:: can be used and is delegated to the button association of the current scheme.
 171 argument:: selector
 172 argument:: args
 173
 174 method:: setSkin
 175 argument:: skinName
 176
 177 method:: scheme
 178 A class variable. Returns the current scheme.
 179
 180 method:: schemes
 181 A class variable. Returns an link::Classes/IdentityDictionary:: of registered schemes.
 182
 183 method:: skin
 184 A class variable. Returns the current skin.
 185
 186 method:: skins
 187 A class variable. Returns an link::Classes/IdentityDictionary:: of registered skins.