HelpSource/Classes/JITGui.schelp

   1 class:: JITGui
   2 summary:: a superclass for just in time interfaces
   3 categories:: Libraries>JITLib>GUI
   4
   5 description::
   6 Proxies for synths, tasks and patterns as implemented in JITLib are extremely flexible. Having guis that represent their changeable states makes it easier to understand what is going on, especially when using multiple proxies together. JITGuis follow a special strategy described below.
   7
   8 subsection::See also
   9
  10 list::
  11 ## link::Classes/EnvirGui::,
  12 ## link::Classes/TdefGui::, link::Classes/TdefAllGui::, ( link::Classes/TaskProxyGui:: )        // TdefGui replaces obsolete TdefEditor
  13 ## link::Classes/PdefGui::, link::Classes/PdefAllGui::, ( link::Classes/TaskProxyAllGui:: )     // PdefGui replaces obsolete PdefEditor
  14 ## link::Classes/NdefGui::, link::Classes/MonitorGui::, link::Classes/NdefParamGui::    // replace NodeProxyEditor, ProxyMonitorGui
  15 ## link::Classes/ProxyMixer::
  16 ## link::Classes/NdefMixer::
  17 ::
  18
  19 subsection::still to be done
  20
  21 list::
  22 ## (ProxyChain) ProxyChainGui
  23 ## (PxPreset) PxPresetGui
  24 ## (maybe SoftSet)
  25 ::
  26
  27 ClassMethods::
  28
  29 private::initClass
  30
  31 subsection::Creation
  32
  33 method::new
  34 Create a new JITGui that will be watching an object and displaying its state.
  35
  36 code::
  37 g = JITGui.new(nil, 0);         // make one
  38 g.object = 123;                 // object gets shown asCompileString
  39 g.object = (key: \otto);        // if the object understands .key, key gets shown
  40 g.object = Pseq([1, 2, 3], inf);
  41 g.close;
  42 ::
  43
  44 argument::object
  45 the object to watch
  46
  47 argument::numItems
  48 the number of display items to use, e.g. how many fields for text, or how many EZSliders for single-number parameters.
  49
  50 argument::parent
  51 a parent view on which to display. If nil, a new window is created; strong::parent:: can also be an existing window or a composite view.
  52
  53 argument::bounds
  54 a desired size and position where to display a JITGui. can be nil, a link::Classes/Point::, or a link::Classes/Rect::. JITGuis know their minimum size ( strong::minSize:: ), and if bounds is nil, minSize is used. if bounds is a point or rect, it will be set to at least minSize. With a rect one can also supply a position where to display. If a point,shown size is the maximum of bounds and minSize
  55
  56 argument::makeSkip
  57 A flag whether to make a skipjack.
  58
  59 argument::options
  60 a list of additional information, e.g. flags about optional buttons. (this is used is some subclasses)
  61
  62 InstanceMethods::
  63
  64 subsection::Accessing Instance Variables
  65
  66 code::
  67 g.dump;
  68 ::
  69
  70 method::object
  71 the object to watch
  72
  73 method::numItems
  74 the number of display items to use, e.g. how many fields for text, or how many EZSliders for single-number parameters.
  75
  76 method::parent
  77 a parent view on which the gui is displayed.
  78
  79 method::bounds
  80 the size and position of the JITGui
  81
  82 method::zone
  83 a link::Classes/CompositeView:: inside the parent that holds the JITGui's views.
  84
  85 method::minSize
  86 a JITGuis calculates its own minimum size based on numItems and options.
  87
  88 method::defPos
  89 the default position where the JITGui is shown if it is in its own window.
  90
  91 method::skin
  92 (Appearance)
  93
  94 the GUI skin to use. By default this is code::GUI.skins.jit:: .
  95
  96 method::font
  97 (Appearance)
  98
  99 the font, also taken from JITGui.skin.
 100
 101 method::nameView
 102 (specific in the JITGui class)
 103
 104 displays the object's key if available.
 105
 106 method::csView
 107 (specific in the JITGui class)
 108
 109 displays the object's compileString.
 110
 111 method::prevState
 112 (common to all JITGuis)
 113
 114 the last observed state which is kept around for comparison.
 115
 116 method::skipjack
 117 (common to all JITGuis)
 118
 119 the skipjack that watches the object's state so it can be updated.
 120
 121 method::scroller
 122 (common to all JITGuis)
 123
 124 an link::Classes/EZScroller:: used for scrolling which of a list of items is shown. see e.g. link::Classes/TdefGui:: for usage.
 125
 126 method::hasWindow
 127 (common to all JITGuis)
 128
 129 a flag whether the JITGui has made its own window, and thus owns it.
 130
 131 subsection::Instance Methods
 132
 133 method::object
 134 put an object in the gui - if the gui accepts it.
 135
 136 method::accepts
 137 test whether obj is a valid object to show in a JITGui. In strong::JITGui:: itself, all objects are accepted, in the subclasses, strong::obj:: can either be nil or a specific class, such as link::Classes/Tdef::, link::Classes/Pdef::, link::Classes/Ndef::
 138
 139 method::name
 140 set the text of the link::#-nameView:: and the window (if it link::#-hasWindow::)
 141
 142 method::getName
 143 ask the object its name, or return code::'_anon_'::
 144
 145 method::winName
 146 return a suitable name for a window: "JITGui_objname"
 147
 148 method::moveTo
 149 if it has its own window, one can move it to some specific location.
 150
 151 method::close
 152 close its window.
 153
 154 subsection::How JITGuis work
 155
 156 A JITGui watches the state of its object by calling its (the gui's) link::#-getState:: method. It compares the new state of the object with the previous state stored in link::#-prevState::. When something has changed, the gui elements concerned are updated.
 157
 158 subsection::How JITGuis work: Methods that subclasses should implement
 159
 160 You can write your own subclasses to JITGui very efficiently by implementing appropriate variants of the following methods in your class. For examples of these methods, see link::Classes/TaskProxyGui::, link::Classes/EnvirGui::, link::Classes/NodeProxyGui::.
 161
 162 method::setDefaults
 163 used to calculate the required onscreen size for the jitGui's zone. Should determine zone size based on link::#-numItems:: and options. also, link::#-defPos:: (where to show your jitGui by default) can be set here, and possibly modifications to the skin used.
 164
 165 method::accepts
 166 a test whether strong::obj:: can be shown in the particular kind of JITGui. Subclasses of JITGui are made for special objects, e.g. Pdefs, so they should test whether obj is the right kind.
 167
 168 method::makeViews
 169 create all the views of the jitGui inside the zone.
 170
 171 subsection::How JITGuis work: For updating the JITGui, these are essential
 172
 173 method::getState
 174 ask the object for all aspects of its current state that will be displayed.
 175
 176 method::checkUpdate
 177 get the object's current state with link::#-prevState::, compare it with prevState, update all gui elements that need to be changed, and store the new state as prevState. This method is called in the skipJack.
 178
 179 subsection::How JITGuis work: More methods you may want to overwrite if required
 180
 181 method::calcBounds
 182 how to calculate the bounds for the zone in which to display
 183
 184 method::makeWindow
 185 how to make a window when no parent is given
 186
 187 method::makeZone
 188 how to initalize the zone within the parent window or view
 189
 190 method::getName
 191 a method for generating a name for the object.
 192
 193 method::winName
 194 a method for generating a name for the JITGui's window.
 195
 196 method::makeScroller
 197 Some objects may have more elements to display than the gui has slots, e.g. a link::Classes/ProxySpace:: can have more proxies than the mixer has numItems. Then, only link::#-numItems:: elements are shown, and the others can be scrolled to with link::#-scroller:: - an link::Classes/EZScroller:: next to the slot elements. The makeScroller method knows where in the zone to put the scroller.
 198 ::
 199
 200 Examples::
 201
 202 code::
 203         // some layout tests
 204
 205         // make its own window - defPos, minSize is used
 206 g = JITGui(Ndef(\a));
 207
 208         // make its own window, specific size
 209 g = JITGui(Ndef(\a), bounds: 390@20);
 210
 211         // provide full bounds
 212 g = JITGui(Ndef(\a), bounds: Rect(200, 500, 390, 24));
 213
 214         // extent is 0@0: minSize x, y is used
 215 g = JITGui(Ndef(\a), bounds: Rect(200, 500, 0, 0));
 216 g = JITGui(Ndef(\a), bounds: Rect(200, 500, 0, 50));
 217 g = JITGui(Ndef(\a), bounds: Rect(200, 500, 500, 0));
 218
 219
 220 (       // put a JITGui in an existing window:
 221 w = Window().front;
 222 g = JITGui(Ndef(\a), 0, w, bounds: 300@48);
 223 )
 224
 225 (       // 5 lines high
 226 w = Window().front;
 227 g = JITGui(Ndef(\a), 5, w);
 228 )
 229
 230 (       // recommended: use a FlowLayout.
 231 w = Window().front;
 232 w.addFlowLayout;
 233 EZSlider(w, 300@100, \test, []);
 234 g = JITGui(Ndef(\a), 0, w, bounds: 300@40);
 235 )
 236 ::