HelpSource/Classes/GUI.schelp

   1 class:: GUI
   2 summary:: Factory abstraction for all GUI related core classes
   3 categories:: GUI>Kits
   4 related:: Overviews/GUI-Classes, Guides/GUI-Introduction, Classes/ViewRedirect
   5
   6
   7 description::
   8 SuperCollider currently supports three operating system platforms: Macintosh OSX, UNIX (Linux and FreeBSD) and Windows (with some limitations).
   9
  10 Graphical User Interface (GUI) code, for the most part, does not need to worry about which platform is executing the code because of the strong::view redirect:: system. At any time, one and only one strong::GUI kit:: is active. This determines which GUI classes will be used for rendering. These classes, the active views, have prefixes for the GUI kit that created the view object: SCWindow vs. JSCWindow vs. QWindow.
  11
  12 table::
  13 ## strong::GUI kit:: || strong::Code to activate:: || strong::Supported platform(s):: || strong::Framework:: || strong::Prefix::
  14 ## Cocoa || code::GUI.cocoa:: || Mac OSX only || Cocoa || SC-
  15 ## SwingOSC || code::GUI.swing:: || All || Java + Swing || JSC-
  16 ## Qt || code::GUI.qt:: || All || Qt || Q-
  17 ::
  18
  19 In general, users should not concern themselves with the prefixes. Instead, work with the emphasis::redirect:: classes, which have no prefix: Window, Button, Slider, etc. The redirect class will ask the currently-selected kit which emphasis::implementation class:: should be used.
  20
  21 The GUI kit (CocoaGUI, QtGUI, SwingGUI) maps the generic view names to the implementing classes: code::Window --> SCWindow, QWindow or JSCWindow::. These schemes are in turn used by link::Classes/ViewRedirect:: to provide a simple cross-platform gui syntax. The GUI class provides utilities for switching kits and other cross platform tasks.
  22
  23 You can get your available schemes (depending on what you installed) with:
  24 code::
  25 GUI.schemes;
  26 ::
  27 For a complete list of gui classes and redirects, see link::Overviews/GUI-Classes::.
  28
  29
  30 subsection:: Switching and Referring to GUI Kits
  31
  32 As of this writing, three GUI kits are available through the GUI class: link::Classes/QtGUI:: (Qt framework), 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.
  33
  34 You can switch the GUI kit by calling one of the following class methods:
  35 code::
  36 GUI.qt;         // use Qt in subsequent GUI creation procedures
  37 GUI.cocoa;      // use cocoa in subsequent GUI creation procedures
  38 GUI.swing;      // use swing in subsequent GUI creation procedures
  39                 // NOTE: If you do not have SwingOSC installed, you get
  40                 // a warning only, and do not switch; so you cannot
  41                 // accidentally disable your gui system.
  42 ::
  43
  44 These methods return the new GUI kit implementation. The current implementation can be queried by calling
  45 code::
  46 GUI.current;    // returns the current GUI kit implementation
  47 ::
  48
  49 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:
  50 code::
  51 GUI.id; // returns the current GUI kit implementation id; this is currently either \cocoa or \swing
  52 ::
  53
  54 For persistency, you can store the identifier of the kit implementation and recall the kit through the class method code::fromID:::
  55 code::
  56 x = GUI.cocoa;
  57 y = x.id;               // store the identifier of a kit implementation
  58 y.postln;               // the id could be stored in a preferences file for example
  59 GUI.swing;
  60 // now switch back to the kit implementation with identifier y
  61 GUI.fromID( y );
  62 GUI.current.id.postln;  // --> cocoa
  63 ::
  64
  65 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:
  66 code::
  67 GUI.cocoa;
  68 GUI.useID(\swing, { Array.rand( 1000, 0.0, 1.0 ).plot });
  69 GUI.current.id.postln;  // --> still cocoa
  70 ::
  71
  72 You can get a particular kit using the code::*get:: method. You can switch to a particular kit using the code::*set:: method:
  73 code::
  74 x = GUI.get( \swing );  // note: unlike *swing and *cocoa, this does not _switch_ the current kit!
  75 GUI.current.id.postln;  // --> still cocoa
  76 GUI.set( x );                   // now we make SwingOSC the current kit
  77 GUI.window.viewPalette;
  78 ::
  79
  80 subsection:: Extending GUI Kits
  81
  82 GUI Kits can be extended with custom classes by using their respective code::put:: methods:
  83 code::
  84 GUI.get( \cocoa ).put( \myText, SCStaticText );
  85 GUI.get( \swing ).put( \myText, JSCStaticText );
  86
  87 GUI.cocoa;
  88 GUI.swing;
  89 (
  90         w = GUI.window.new;
  91         GUI.myText.new( w, w.view.bounds.insetBy( 20, 20 )).string_( "schoko" ).background_( Color.red );
  92         w.front;
  93 )
  94 ::
  95
  96 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:
  97 code::
  98 MyGUIExtension {
  99         *initClass {
 100                 StartUp.add({
 101                         var scheme;
 102
 103                         scheme = GUI.get( \cocoa );
 104                         if( scheme.notNil, {scheme.put( \myText, SCStaticText )});
 105                         scheme = GUI.get( \swing );
 106                         if( scheme.notNil, {scheme.put( \myText, JSCStaticText )});
 107                 });
 108         }
 109 }
 110 ::
 111
 112 classmethods::
 113
 114 subsection:: Methods and Variables for GUI
 115
 116 method:: new
 117
 118 method:: makeGUI
 119
 120 method:: initClass
 121 Sets the code::skin:: to default values on compile.
 122 code::
 123 fontSpecs: ["Helvetica", 10],
 124 fontColor: Color.black,
 125 background: Color(0.8, 0.85, 0.7, 0.5),
 126 foreground: Color.grey(0.95),
 127 onColor: Color(0.5, 1, 0.5),
 128 offColor: Color.clear,
 129 gap: 0@0,
 130 margin: 2@2,
 131 buttonHeight: 16
 132 ::
 133
 134 method:: cocoa
 135 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.
 136
 137 method:: swing
 138 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.
 139
 140 method:: fromID
 141 Changes the current scheme and returns the new scheme.
 142 argument:: id
 143 A link::Classes/Symbol::. The identifier of the scheme to use.
 144
 145
 146 method:: current
 147
 148 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.
 149
 150 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. ::
 151
 152
 153 method:: get
 154 Returns the scheme for a given identifier. Does not switch the current scheme.
 155 argument:: id
 156 A link::Classes/Symbol::. The identifier of the scheme to retrieve, such as returned by calling code::aScheme.id::.
 157
 158 method:: set
 159 Changes the current scheme.
 160 argument:: aScheme
 161 An instance of link::Classes/Symbol::. The scheme to use as current scheme.
 162
 163 method:: use
 164 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.
 165 argument:: aScheme
 166 The scheme to use during the function execution.
 167 argument:: func
 168 An Instance of link::Classes/Function::.
 169
 170 method:: useID
 171 Same as code::use:: but using a scheme's id as first argument.
 172 argument:: id
 173 The id of the scheme to use during the function execution.
 174 argument:: func
 175 A body to execute.
 176
 177 method:: add
 178 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.
 179 argument:: aScheme
 180 The scheme to add.
 181
 182 method:: doesNotUnderstand
 183 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.
 184 argument:: selector
 185 argument:: ... args
 186
 187 method:: setSkin
 188 argument:: skinName
 189
 190 method:: scheme
 191 A class variable. Returns the current scheme.
 192
 193 method:: schemes
 194 A class variable. Returns an link::Classes/IdentityDictionary:: of registered schemes.
 195
 196 method:: skin
 197 A class variable. Returns the current skin.
 198
 199 method:: skins
 200 A class variable. Returns an link::Classes/IdentityDictionary:: of registered skins.