HelpSource/Reference/softPut.schelp

   1 title:: softPut
   2 summary:: set a (number) parameter in an environment conditionally
   3 categories:: Libraries>JITLib>GUI
   4 related:: Reference/softSet, Reference/softVol_
   5
   6 description::
   7 code::softPut:: is an extension method to link::Classes/Dictionary:: that changes an existing numerical value for key in a dictionary only in two conditions:
   8 list::
   9 ## if the new value is close enough to the current value at that key;
  10 ## or if the setting controller knows the previous value and sends it along. the idea here is that if the controller knows it did the last value change, it has authority to jump now.
  11 ::
  12 Typical uses would be switching to a new preset, then using a faderbox, and avoiding sudden controller jumps that could occur (soft takeover).
  13
  14 method:: softPut (param, val, within = 0.025, lastVal, mapped = true, spec)
  15 argument:: param
  16 the name of the parameter (key) to set
  17 argument:: val
  18 the value to set the param to (can be mapped or unmapped)
  19 argument:: within
  20 the normalized range within which the set is accepted - default is 0.025
  21 argument:: mapped
  22 a flag whether strong::val:: is mapped (within the range of param.asSpec) or unmapped (0.0-1.0)
  23 argument:: lastVal
  24 the previous value that a control has set - see last examples.
  25 argument:: spec
  26 a link::Classes/ControlSpec:: can be passed in. if nil, param.asSpec is used.
  27 note::
  28 if no spec is given, or no value exists yet, softSet simply allows setting.
  29 ::
  30
  31 examples::
  32 code::
  33 (
  34 e = (amp: 0.1, dur: 0.2);
  35 Tdef(\test, {
  36         var dur;
  37         loop {
  38                 dur = e.dur;
  39                 (amp: e.amp, dur: dur, degree: 7.rand).play;
  40                 dur.wait;
  41         };
  42 }).play;
  43 )
  44
  45 e.put(\amp, 0.03);      // just set it
  46 e.put(\amp, 0.1);
  47 e.softPut(\amp, 0.11);  // small change, OK to set
  48 e.put(\amp, 0.1);
  49 e.softPut(\amp, 0.15);  // no bigger change
  50 e.softPut(\amp, 0.15, 0.1);     // bigger change is OK with larger within value
  51
  52 e.softPut(\amp, 0.01);  // no
  53 e.softPut(\amp, 0.01, lastVal: 0.15);   // can make big jumps when lastVal is close to current.
  54
  55         // no spec for dur exists by default:
  56         \dur.asSpec
  57
  58 e.softPut(\dur, 0.05);  // so this always really sets.
  59 ::
  60
  61 code::
  62
  63         // PatternProxies ( e.g. Tdefs, Pdefs) have a softSet method, which
  64         // forwards softPut to their envirs:
  65
  66 Pdef(\test, Pbind(\degree, Pseq((0..7), inf))).play;
  67
  68 Pdef(\test).set(\amp, 0.03)
  69 Pdef(\test).envir.softPut(\amp, 0.06); // no, too big
  70 Pdef(\test).envir.softPut(\amp, 0.06, 0.1); // ok with wider range
  71
  72         // equivalent:
  73 Pdef(\test).set(\amp, 0.03)
  74 Pdef(\test).softSet(\amp, 0.1); // no, too big
  75 Pdef(\test).softSet(\amp, 0.06, 0.1); // ok with wider "within"
  76 Pdef(\test).get(\amp)
  77
  78 Pdef(\test).softSet(\amp, 0.5); // no!
  79 Pdef(\test).softSet(\amp, 0.5, lastVal: 0.06); // ok!
  80 Pdef(\test).softSet(\amp, 0.05, lastVal: 0.5); // ok
  81
  82 Pdef(\test).softSet(\dur, 0.05); // alsways ok, no spec for dur.
  83 Pdef(\test).softSet(\dur, 0.1); // ok
  84
  85 Pdef(\test).softSet(\dur, 0.05, spec: [0.03, 3, \exp]); // not OK with that spec
  86 ::
  87
  88 code::
  89
  90         // softPut and softSet can be risky - one can lose a parameter when moving a controller
  91         // too quickly. So, if we know the last value (e.g. because the same controller
  92         // knows it has set to that value), it is OK to jump:
  93
  94         // example of softSet, softSet which knows lastVal,
  95         // softVol_ and softVol_ which knows lastVol:
  96 (
  97 w = Window("softSet, softVol", Rect(500, 200, 400, 240)).front;
  98 w.view.addFlowLayout;
  99 PdefGui(Pdef(\test), 2, w, 340@80);
 100
 101         // can lose control if wiggled too fast
 102 EZSlider(w, 340@30, \softSetDur, [0.03, 3, \exp], { |sl|
 103         Pdef(\test).softSet(\dur, sl.value, 0.05)
 104 });
 105
 106         // knows it was in control
 107 EZSlider(w, 340@30, \knowsLast, [0.03, 3, \exp], Routine { |sl|
 108         var newVal, lastVal;
 109         loop {
 110                 newVal = sl.value;
 111                 Pdef(\test).softSet(\dur, newVal, 0.05, lastVal: lastVal);
 112                 lastVal = newVal;
 113                 \dummy.yield;
 114         }
 115 });
 116 )
 117 ::