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 argument::options
  53 configuration options
  54
  55 InstanceMethods::
  56
  57 subsection::Instance Variables
  58
  59 method::numItems
  60 how many envir items to display
  61
  62 method::envir
  63 the envir displayed - actually an alias for object.
  64
  65 method::zone
  66 the composite view the envirgui makes for itself
  67
  68 method::valFields
  69 the areas in which the key-value pairs are displayed.
  70
  71 method::widgets
  72 the EZGuis that display the values:
  73 list::
  74 ## Single numbers will have an link::Classes/EZSlider::,
  75 ## pairs of numbers will be shown as an link::Classes/EZRanger::,
  76 ## all other values are shown as compileStrings in an link::Classes/EZText::.
  77 ::
  78
  79 method::specs
  80 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.
  81
  82 method::keysRotation
  83 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.
  84
  85 subsection::Some Methods
  86
  87 method::object
  88 set the environment to show
  89
  90 argument::obj
  91 can be nil, a dictionary, an environment, or an event.
  92
  93 code::
  94 g = EnvirGui((freq: 120, \amp: 0.2, \pan: -0.5), 12, nil, bounds: Rect(20, 400, 220, 100));
  95 g.object_((a: 1, b: [2, 3], c: \symbol, d: [4, 5, 6], f: { "boing".postln }))
  96 ::
  97
  98 method::envir
  99 same as object_(obj)
 100
 101 method::name
 102 if in its own window, set the window's name
 103
 104 code::
 105 g.name_("Yoohoo");
 106 ::
 107
 108 method::getSpec
 109 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.
 110
 111 code::
 112 // inline example
 113 g = EnvirGui.new;
 114 g.getSpec(\freq, 400);          // \freq exists as global spec, so use that
 115 g.object_((freq: 150));
 116
 117 g.getSpec(\iFrek, 500);         // no global spec, so make a new one:
 118                                 // exponential from val * 0.05 to val * 20;
 119 g.specs;                        // and keep it here
 120 g.envir.put(\iFrek, 500);
 121 ::
 122
 123 argument::key
 124 the parameter name for which to find a spec
 125
 126 argument::value
 127 the current value of that param, which may be used for guessing specs.
 128
 129 method::putSpec
 130 add a spec for a given key, or (if it is a global key) override a global spec with a local one:
 131
 132 code::
 133 g.putSpec(\iFrek, [10, 1000, \exp]);
 134 g.putSpec(\freq, [100, 1000, \exp]);
 135 g.object_((freq: 200, iFrek: 20));
 136 ::
 137
 138 subsection::Some internal methods
 139
 140 method::setField
 141 set a field by index, with the new key, value;
 142
 143 argument::index
 144 the index
 145
 146 argument::key
 147 a new key
 148
 149 argument::value
 150 the value
 151
 152 argument::sameKey
 153 means the field had the same key already.
 154
 155 method::setByKeys
 156 update the widgets for the current keys
 157
 158 method::clearField
 159 remove the link::Classes/EZGui:: at this index
 160
 161 method::clearFields
 162 remove all unused EZGuis
 163
 164 Examples::
 165
 166 code::
 167         // Setting envir variables in a Tdef:
 168 (
 169 Tdef(\text).set(\note, [0, 2, 7], \dur, { [0.1, 0.2, 0.4].choose }, \pan, 0, \amp, 0.1);
 170
 171 w = Window("EZTexts", Rect(200, 400, 304, 120)).front;
 172 w.addFlowLayout;
 173
 174 TdefGui(Tdef(\text), 0, parent: w);
 175
 176 e = EnvirGui(Tdef(\text).envir, 4, parent: w);
 177
 178 Tdef(\text, { |ev|
 179         var mydur;
 180         loop {
 181                 mydur = ev.dur;
 182                 (note: ev.note, dur: mydur, amp: ev.amp, pan: ev.pan).postln.play;
 183                 mydur.wait;
 184         }
 185 }).play;
 186 )
 187
 188         // or equivalently, use the built-in EnvirGui in TdefGui:
 189 TdefGui(Tdef(\text), 4);
 190
 191 Tdef(\text).set(\yuhu, Prand([2, 3, 5, 8, 13], inf), \magic, [\abra, \cadabra]);
 192
 193 Tdef(\text).clear;
 194 ::