HelpSource/Classes/ControlSpec.schelp

   1 class:: ControlSpec
   2 summary:: numerical input specification
   3 related:: Classes/Warp
   4 categories:: Control, Spec
   5
   6 description::
   7
   8 The original, and most common spec (see link::Classes/Spec::). A ControlSpec is used by GUI sliders and knobs to specify the range and curve of the controls. ControlSpec may be used in many ways to map from linear 0..1 range to your desired range and back.
   9
  10 The most common way to create a ControlSpec is by
  11 code::
  12 anObject.asSpec // the object may be an array or a symbol
  13 ::
  14
  15 ClassMethods::
  16
  17 private::initClass
  18
  19 method::new
  20
  21 argument::minval
  22 The minimum value of the range.
  23
  24 argument::maxval
  25 The maximium value of the range.
  26
  27 argument::warp
  28 a link::Classes/Warp::, a symbol (e.g. \lin or \exponential: Default value is \lin), or something else that returns a Warp when sent the message .asWarp. A CurveWarp is defined by a number.
  29
  30 argument::step
  31 The smallest possible increment.
  32
  33 argument::default
  34 The default value.
  35
  36 argument::units
  37 The units, e.g. "hz". Used by some gui's as a unit label.
  38
  39 argument::grid
  40
  41 InstanceMethods::
  42
  43 method::map
  44 Maps and constrains a strong::value:: between 0 and 1 to the range between minval and maxval.
  45
  46 method::unmap
  47 Maps and constrains a strong::value:: between minval and maxval to the range between 0 and 1.
  48 code::
  49 g = ControlSpec(0.01, 2000, \exp, 0.1, 220, "Hz");
  50 g.map(0.5); // convert from [0..1] to [0.01..2000]
  51 g.unmap(1000); // convert from [0.01..2000] to [0..1]
  52
  53 // fore and back translation should be close to identical:
  54 g.unmap(g.map(0.5));
  55 ::
  56
  57 method::clipLo
  58 The lower of maxval and minval.
  59
  60 method::clipHi
  61 The higher of maxval and minval.
  62
  63 method::constrain
  64 Returns code::value.asFloat.clip(clipLo, clipHi).round(step)::.
  65
  66 method::range
  67 Returns code::maxval - minval::.
  68
  69 method::guessNumberStep
  70 Used for EZ GUI classes for guessing a sensible strong::step:: if none is specified.
  71
  72 Examples::
  73
  74 code::
  75 g = ControlSpec(0.01, 2000, \exp, 0.1, 220, "Hz");
  76
  77 // or alternatively
  78
  79 [0.001, 2000, \exp, 0.1, 220, "hz"].asSpec;
  80
  81 // or add it to the ControlSpec.specs IdentityDictionary:
  82
  83 ControlSpec.specs[\myFreq] = ControlSpec(0.01, 2000, \exp, 0.01, 440, units: "Hz");
  84 ::
  85
  86 code::
  87 // array is used as arguments to ControlSpec.new(minval, maxval, warp, step, default)
  88 [300,3000,\exponential,100].asSpec.dump
  89 Instance of ControlSpec {    (0313FC08, gc=00, fmt=00, flg=00, set=03)
  90   instance variables [6]
  91     minval : Integer 300
  92     maxval : Integer 3000
  93     warp : Symbol 'exponential'
  94     step : Integer 100
  95     default : Integer 300
  96 }
  97
  98 // partially specified ...
  99 [-48,48].asSpec.dump
 100 Instance of ControlSpec {    (0313FF18, gc=00, fmt=00, flg=00, set=03)
 101   instance variables [6]
 102     minval : Integer -48
 103     maxval : Integer 48
 104     warp : Symbol 'linear'
 105     step : Float 0
 106     default : Integer -48
 107 }
 108
 109 // a Symbol
 110 \freq.asSpec.dump
 111 Instance of ControlSpec {    (180F4910, gc=3C, fmt=00, flg=00, set=03)
 112   instance variables [8]
 113     minval : Integer 20
 114     maxval : Integer 20000
 115     warp : instance of ExponentialWarp (17FEDB30, size=1, set=1)
 116     step : Integer 0
 117     default : Integer 440
 118     units : " Hz"
 119     clipLo : Integer 20
 120     clipHi : Integer 20000
 121 }
 122
 123
 124 // nil becomes a default ControlSpec
 125 nil.asSpec.dump
 126 Instance of ControlSpec {    (0313FF18, gc=00, fmt=00, flg=00, set=03)
 127   instance variables [6]
 128     minval : Float 0
 129     maxval : Float 1
 130     warp : Symbol 'linear'
 131     step : Float 0
 132     default : Float 0
 133 }
 134 ::
 135
 136 code::
 137 // make a frequency spec with an exponential range from 20 to 20000,
 138 // give it a rounding of 30 (Hz)
 139 a = \freq.asSpec;
 140 a.step = 100;
 141
 142 // equivalent:
 143 a = [20, 20000, 'exp', 100, 440].asSpec;
 144 a.dump;
 145
 146 a.constrain(800); // make sure it is in range and round it.
 147 a.constrain(803); // make sure it is in range and round it.
 148
 149 a.map(0.5);
 150 a.map(0.0); // returns min
 151 a.map(1.5); // exceeds the area: clip, returns max
 152
 153 a.unmap(4000);
 154 a.unmap(22.0);
 155 ::
 156
 157 code::
 158 // like in envelopes, a CurveWarp is created by a number:
 159
 160 a = [0, 1, -4].asSpec;
 161 a.map(0.5);
 162 a.unmap(0.99);
 163 a.map((0..10).normalize).plot;
 164
 165 // look at different distributions:
 166 (
 167 var invals = (0..10).normalize;
 168 (-4..4).do { |curve|
 169         var a = [0, 1, curve].asSpec;
 170         a.map(invals).plot;
 171 }
 172 );
 173 ::
 174
 175 code::
 176 // using spec for sliders:
 177 (
 178 var w, c, d;
 179 w = Window.new("control", Rect(128, 64, 340, 160));
 180 w.front;
 181 c = Slider.new(w, Rect(10, 10, 300, 30));
 182 d = StaticText.new(w, Rect(10, 40, 300, 30));
 183 c.action = {
 184         d.string = "unmapped value"
 185         + c.value.round(0.01)
 186         + "......"
 187         + "mapped value"
 188         + a.map(c.value)
 189 };
 190 )
 191 ::
 192
 193 code::
 194 // ControlSpec-map can also be used to map ugens
 195 (
 196 var spec;
 197 spec = [ 100, 18000, \exp].asSpec;
 198 {
 199         var freq,osc;
 200         osc = SinOsc.kr(0.1).range(0,1);
 201         freq = spec.map( osc );
 202
 203         freq.dump;// BinaryOpUGen
 204
 205         SinOsc.ar(
 206                 freq.poll
 207         )
 208 }.play
 209 )
 210 ::