rsc3/doc-schelp/HelpSource/Classes/GUI.schelp

class:: GUI
summary:: Factory abstraction for all GUI related core classes
categories:: GUI>Kits
related:: Overviews/GUI-Classes, Guides/GUI-Introduction


description::
SuperCollider currently supports three operating system platforms: macOS, UNIX (Linux and FreeBSD) and Windows (with some limitations).

warning::The redirect system has been deprecated, please use the view classes directly.::

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.

table::
## strong::GUI kit:: || strong::Code to activate:: || strong::Supported platform(s):: || strong::Framework:: || strong::Prefix::
## Cocoa || code::GUI.cocoa:: || macOS only || Cocoa || SC-
## SwingOSC || code::GUI.swing:: || All || Java + Swing || JSC-
## Qt || code::GUI.qt:: || All || Qt || Q-
::

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.

The GUI kit (CocoaGUI, QtGUI, SwingGUI) maps the generic view names to the implementing classes: code::Window --> SCWindow, QWindow or JSCWindow::. The GUI class provides utilities for switching kits and other cross platform tasks.

You can get your available schemes (depending on what you installed) with:
code::
GUI.schemes;
::
For a complete list of gui classes and redirects, see link::Overviews/GUI-Classes::.


subsection:: Switching and Referring to GUI Kits

As of this writing, three GUI kits are available through the GUI class: link::Classes/QtGUI:: (Qt framework), link::Classes/CocoaGUI:: (macOS 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.

You can switch the GUI kit by calling one of the following class methods:
code::
GUI.qt;		// use Qt in subsequent GUI creation procedures
GUI.cocoa;	// use cocoa in subsequent GUI creation procedures
GUI.swing;	// use swing in subsequent GUI creation procedures
		// NOTE: If you do not have SwingOSC installed, you get
		// a warning only, and do not switch; so you cannot
		// accidentally disable your gui system.
::

These methods return the new GUI kit implementation. The current implementation can be queried by calling
code::
GUI.current;	// returns the current GUI kit implementation
::

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-macOS systems the class CocoaGUI is not in the class library path, and you cannot check for an undefined class:
code::
GUI.id;	// returns the current GUI kit implementation id; this is currently either \cocoa or \swing
::

For persistency, you can store the identifier of the kit implementation and recall the kit through the class method code::fromID:::
code::
x = GUI.cocoa;
y = x.id;		// store the identifier of a kit implementation
y.postln;		// the id could be stored in a preferences file for example
GUI.swing;
// now switch back to the kit implementation with identifier y
GUI.fromID( y );
GUI.current.id.postln;	// --> cocoa
::

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:
code::
GUI.cocoa;
GUI.useID(\swing, { Array.rand( 1000, 0.0, 1.0 ).plot });
GUI.current.id.postln;	// --> still cocoa
::

You can get a particular kit using the code::*get:: method. You can switch to a particular kit using the code::*set:: method:
code::
x = GUI.get( \swing );	// note: unlike *swing and *cocoa, this does not _switch_ the current kit!
GUI.current.id.postln;	// --> still cocoa
GUI.set( x );			// now we make SwingOSC the current kit
GUI.window.viewPalette;
::

subsection:: Extending GUI Kits

GUI Kits can be extended with custom classes by using their respective code::put:: methods:
code::
GUI.get( \cocoa ).put( \myText, SCStaticText );
GUI.get( \swing ).put( \myText, JSCStaticText );

GUI.cocoa;
GUI.swing;
(
	w = GUI.window.new;
	GUI.myText.new( w, w.view.bounds.insetBy( 20, 20 )).string_( "schoko" ).background_( Color.red );
	w.front;
)
::

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:
code::
MyGUIExtension {
	*initClass {
		StartUp.add({
			var scheme;

			scheme = GUI.get( \cocoa );
			if( scheme.notNil, {scheme.put( \myText, SCStaticText )});
			scheme = GUI.get( \swing );
			if( scheme.notNil, {scheme.put( \myText, JSCStaticText )});
		});
	}
}
::

classmethods::

subsection:: Methods and Variables for GUI

method:: new

method:: makeGUI

method:: initClass
Sets the code::skin:: to default values on compile.
code::
fontSpecs: ["Helvetica", 10],
fontColor: Color.black,
background: Color(0.8, 0.85, 0.7, 0.5),
foreground: Color.grey(0.95),
onColor: Color(0.5, 1, 0.5),
offColor: Color.clear,
gap: 0@0,
margin: 2@2,
buttonHeight: 16
::

method:: cocoa
Makes Cocoa (macOS GUI) the current scheme and returns it. Subsequent GUI object calls to GUI are delegated to cocoa. Returns the current (cocoa) scheme.

method:: swing
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.

method:: fromID
Changes the current scheme and returns the new scheme.
argument:: id
A link::Classes/Symbol::. The identifier of the scheme to use.


method:: current

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.

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. ::


method:: get
Returns the scheme for a given identifier. Does not switch the current scheme.
argument:: id
A link::Classes/Symbol::. The identifier of the scheme to retrieve, such as returned by calling code::aScheme.id::.

method:: set
Changes the current scheme.
argument:: aScheme
An instance of link::Classes/Symbol::. The scheme to use as current scheme.

method:: use
Executes a function body, temporarily setting the current GUI scheme. This is useful 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.
argument:: aScheme
The scheme to use during the function execution.
argument:: func
An Instance of link::Classes/Function::.

method:: useID
Same as code::use:: but using a scheme's id as first argument.
argument:: id
The id of the scheme to use during the function execution.
argument:: func
A body to execute.

method:: add
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.
argument:: aScheme
The scheme to add.

method:: doesNotUnderstand
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.
argument:: selector
argument:: ... args

method:: setSkin
argument:: skinName

method:: scheme
A class variable. Returns the current scheme.

method:: schemes
A class variable. Returns an link::Classes/IdentityDictionary:: of registered schemes.

method:: skin
A class variable. Returns the current skin.

method:: skins
A class variable. Returns an link::Classes/IdentityDictionary:: of registered skins.