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