HelpSource/Classes/EnvirGui.schelp

   1 class:: EnvirGui
   2 summary:: display the contents of an environment for editing
   3 categories:: Libraries>JITLib>GUI
   4 related:: Classes/EZText, Classes/TdefGui, Classes/PdefGui
   5
   6 description::
   7 EnvirGui displays all keys and values of an environment, so one can change them flexibly. Single number get displayed with an link::Classes/EZSlider::, pairs of numbers with an link::Classes/EZRanger::, and anything else is shown as an link::Classes/EZText:: (a text field).
   8
   9 ClassMethods::
  10
  11 subsection::Creation
  12
  13 method::new
  14 create a new EnvirGui
  15
  16 code::
  17 // simple example
  18 g = EnvirGui.new(nil, 5);                               // empty with 5 slots
  19 g.object_((a: 1, b: \werty, freq: [500, 2000]));        // put some things in
  20 g.envir.put(\karl, \otto1);                             // one more
  21 g.envir.putAll((b: -12, r: 1, s: 2, t: 3, u: 4, v: 5))
  22
  23 g.object_((x: 2));      // put something else in
  24
  25 g.envir.putAll((b: -12, r: 1, s: 2, t: 3, u: 4, v: 5))
  26
  27 g.envir.removeAt(\b)
  28 g.envir.removeAt(\r)
  29 g.envir.removeAt(\s)
  30 g.envir.removeAt(\t)
  31 g.envir.removeAt(\u)
  32 g.envir.removeAt(\v)
  33
  34 g.parent.close;
  35 ::
  36
  37 argument::object
  38 the envir to display
  39
  40 argument::numItems
  41 the number of items to display. If an envir is given, and no num, num is envir.size.
  42
  43 argument::parent
  44 the parent view to display in; if none is given, a new window is created.
  45
  46 argument::bounds
  47 the bounds within which to display; if none is given, bounds are calculated.
  48
  49 argument::makeSkip
  50 flag whether to make a skipjack to manage updates of the envirgui.
  51
  52 InstanceMethods::
  53
  54 subsection::Instance Variables
  55
  56 method::numItems
  57 how many envir items to display
  58
  59 method::envir
  60 the envir displayed - actually an alias for object.
  61
  62 method::zone
  63 the composite view the envirgui makes for itself
  64
  65 method::valFields
  66 the areas in which the key-value pairs are displayed.
  67
  68 method::widgets
  69 the EZGuis that display the values:
  70 list::
  71 ## Single numbers will have an link::Classes/EZSlider::,
  72 ## pairs of numbers will be shown as an link::Classes/EZRanger::,
  73 ## all other values are shown as compileStrings in an link::Classes/EZText::.
  74 ::
  75
  76 method::specs
  77 EZSlider and EZRanger needs specs for their display ranges; if there is a global spec for that key (key.asSpec), it will be used. If not, a spec is generated (see the link::#-getSpec:: method) and kept in these (local) specs.
  78
  79 method::keysRotation
  80 if the size of envir exceeds numItems, the keys displayed can be rotated: e.g. with 10 keys displayed on 5 valFields, keysRotation 0 means show keys (0..4), keysRotation 2 means show keys (2..6), etc.
  81
  82 subsection::Some Methods
  83
  84 method::object
  85 set the environment to show
  86
  87 argument::obj
  88 can be nil, a dictionary, an environment, or an event.
  89
  90 code::
  91 g = EnvirGui((freq: 120, \amp: 0.2, \pan: -0.5), 12, nil, bounds: Rect(20, 400, 220, 100));
  92 g.object_((a: 1, b: [2, 3], c: \symbol, d: [4, 5, 6], f: { "boing".postln }))
  93 ::
  94
  95 method::envir
  96 same as object_(obj)
  97
  98 method::name
  99 if in its own window, set the window's name
 100
 101 code::
 102 g.name_("Yoohoo");
 103 ::
 104
 105 method::getSpec
 106 For editing, specs for the parameter ranges are needed. These can be set locally in the EnvirGui, or global specs will be looked up. If no local or global specs exist for that parameter name, getSpec makes a usable guess for them.
 107
 108 code::
 109 // inline example
 110 g = EnvirGui.new;
 111 g.getSpec(\freq, 400);          // \freq exists as global spec, so use that
 112 g.object_((freq: 150));
 113
 114 g.getSpec(\iFrek, 500);         // no global spec, so make a new one:
 115                                 // exponential from val * 0.05 to val * 20;
 116 g.specs;                        // and keep it here
 117 g.envir.put(\iFrek, 500);
 118 ::
 119
 120 argument::key
 121 the parameter name for which to find a spec
 122
 123 argument::value
 124 the current value of that param, which may be used for guessing specs.
 125
 126 method::putSpec
 127 add a spec for a given key, or (if it is a global key) override a global spec with a local one:
 128
 129 code::
 130 g.putSpec(\iFrek, [10, 1000, \exp]);
 131 g.putSpec(\freq, [100, 1000, \exp]);
 132 g.object_((freq: 200, iFrek: 20));
 133 ::
 134
 135 subsection::Some internal methods
 136
 137 method::setField
 138 set a field by index, with the new key, value;
 139
 140 argument::sameKey
 141 means the field had the same key already.
 142
 143 method::setByKeys
 144 update the widgets for the current keys
 145
 146 method::clearField
 147 remove the link::Classes/EZGui:: at this index
 148
 149 method::clearFields
 150 remove all unused EZGuis
 151
 152 Examples::
 153
 154 code::
 155         // Setting envir variables in a Tdef:
 156 (
 157 Tdef(\text).set(\note, [0, 2, 7], \dur, { [0.1, 0.2, 0.4].choose }, \pan, 0, \amp, 0.1);
 158
 159 w = Window("EZTexts", Rect(200, 400, 304, 120)).front;
 160 w.addFlowLayout;
 161
 162 TdefGui(Tdef(\text), 0, parent: w);
 163
 164 e = EnvirGui(Tdef(\text).envir, 4, parent: w);
 165
 166 Tdef(\text, { |ev|
 167         var mydur;
 168         loop {
 169                 mydur = ev.dur;
 170                 (note: ev.note, dur: mydur, amp: ev.amp, pan: ev.pan).postln.play;
 171                 mydur.wait;
 172         }
 173 }).play;
 174 )
 175
 176         // or equivalently, use the built-in EnvirGui in TdefGui:
 177 TdefGui(Tdef(\text), 4);
 178
 179 Tdef(\text).set(\yuhu, Prand([2, 3, 5, 8, 13], inf), \magic, [\abra, \cadabra]);
 180
 181 Tdef(\text).clear;
 182 ::