HelpSource/Classes/Slider.schelp

   1 CLASS:: Slider
   2 redirect:: implClass
   3 summary:: A view consisting of a sliding handle.
   4 categories:: GUI>Views
   5
   6 DESCRIPTION::
   7
   8 A view that allows setting a numerical value by means of moving a sliding handle. It can have horizontal or vertical orientation, meaning the direction in which the handle moves.
   9
  10
  11
  12
  13 CLASSMETHODS::
  14
  15 PRIVATE:: key
  16
  17 METHOD:: new
  18
  19         When a new Slider is created, its link::#-orientation:: is determined by the initial size: if it is wider than high, the orientation will be horizontal, otherwise it will be vertical.
  20
  21
  22
  23
  24
  25 INSTANCEMETHODS::
  26
  27
  28
  29 SUBSECTION:: Data
  30
  31 METHOD:: value
  32         Numerical value between 0 and 1, represented by the handle position within the groove.
  33
  34         argument::
  35                 A Float.
  36
  37 METHOD:: valueAction
  38         Sets link::#-value:: and triggeres link::#-action::.
  39
  40 METHOD:: increment
  41         Increments the value by link::#-step:: multiplied by 'factor'.
  42
  43         argument:: factor
  44                 Any number.
  45
  46 METHOD:: decrement
  47         Decrements the value by link::#-step:: multiplied by 'factor'.
  48
  49         argument:: factor
  50                 Any number.
  51
  52
  53
  54
  55 SUBSECTION:: Appearance
  56
  57 METHOD:: orientation
  58         The orientation of the Slider - the direction in which the handle moves. The default value depends on the size of the view when created.
  59
  60         argument::
  61                 One of the two Symbols: \horizontal or \vertical.
  62
  63 METHOD:: thumbSize
  64         The size of the handle - its width or height, depending on link::#-orientation::.
  65
  66         argument::
  67                 An Integer amount of pixels.
  68
  69 METHOD:: knobColor
  70         The color of the handle.
  71
  72         argument::
  73                 A Color.
  74
  75
  76
  77 SUBSECTION:: Interaction
  78
  79 METHOD:: step
  80         The amount by which the value will changed when link::#-increment:: or link::#-decrement:: is called, or when related keys are pressed.
  81
  82         argument::
  83                 A Float.
  84
  85 METHOD:: pixelStep
  86         The absolute amount by which the value would change if the handle moved by one pixel.
  87
  88         returns::
  89                 A Float.
  90
  91 METHOD:: shift_scale
  92         The factor by which link::#-step:: is multiplied when incrementing or decrementing the value by keyboard while the Shift key is pressed.
  93
  94         argument::
  95                 A Float.
  96
  97 METHOD:: ctrl_scale
  98         The factor by which link::#-step:: is multiplied when incrementing or decrementing the value by keyboard while the Ctrl key is pressed.
  99
 100         argument::
 101                 A Float.
 102
 103 METHOD:: alt_scale
 104         The factor by which link::#-step:: is multiplied when incrementing or decrementing the value by keyboard while the Alt key is pressed.
 105
 106         argument::
 107                 A Float.
 108
 109
 110 SUBSECTION:: Actions
 111
 112 METHOD:: action
 113         The action object evaluated whenever the user moves the handle.
 114
 115 METHOD:: defaultKeyDownAction
 116
 117         Implements the default effects of key presses as follows:
 118
 119         table::
 120         ## strong::Key::   || strong::Effect::
 121         ## r               || valueAction_(1.0.rand)
 122         ## n               || valueAction_(0)
 123         ## x               || valueAction_(1)
 124         ## c               || valueAction_(0.5)
 125         ## ]               || increment
 126         ## [               || decrement
 127         ## up arrow        || increment
 128         ## down arrow      || decrement
 129         ## right arrow     || increment
 130         ## left arrow      || decrement
 131         ::
 132
 133
 134
 135 SUBSECTION:: Drag and drop
 136
 137 METHOD:: defaultGetDrag
 138         returns::
 139                 The link::#-value::.
 140
 141 METHOD:: defaultCanReceiveDrag
 142         returns::
 143                 True if the current drag data is a number.
 144
 145 METHOD:: defaultReceiveDrag
 146         Sets link::#-valueAction:: to the current drag data.
 147
 148
 149
 150 EXAMPLES::
 151 subsection:: Show the slider value in a NumberBox
 152 code::
 153 (
 154 w = Window.new.front;
 155 c = NumberBox(w, Rect(20, 20, 150, 20));
 156 a = Slider(w, Rect(20, 60, 150, 20))
 157         .action_({
 158                 c.value_(a.value)
 159                 });
 160 a.action.value;
 161 )
 162
 163 ( // change the bounds to become vertical
 164 w = Window.new.front;
 165 c = NumberBox(w, Rect(20, 20, 150, 20));
 166 a = Slider(w, Rect(200, 60, 20, 150))
 167         .action_({
 168                 c.value_(a.value)
 169                 });
 170 a.action.value;
 171 )
 172 ::
 173
 174 subsection:: Use a Spec to round and map the output range
 175 code::
 176 (
 177 w = Window.new.front;
 178 b = ControlSpec(-50, 50, \linear, 0.01); // min, max, mapping, step
 179 c = StaticText(w, Rect(20, 20, 150, 20)).align_(\center).background_(Color.rand);
 180 a = Slider(w, Rect(20, 50, 150, 20))
 181         .focusColor_(Color.red(alpha:0.2))
 182         .background_(Color.rand)
 183         .value_(0.5)
 184         .action_({
 185                 c.string_(b.map(a.value).asString)
 186                 // round the float so it will fit in the NumberBox
 187                 });
 188 a.action.value;
 189
 190 )
 191 ::
 192
 193 subsection:: Change the stepsize of the slider, selected via a PopUpMenu
 194 code::
 195 (
 196 w = Window.new.front;
 197 a = ["0", "0.0625", "0.125", "0.25", "0.5", "1"];
 198 b = Slider(w, Rect(20, 100, 100, 20))
 199         .action_({
 200                 c.value_(b.value)
 201                 }).background_(Color.rand);
 202 d = PopUpMenu(w, Rect(20, 60, 100, 20))
 203         .items_(a)
 204         .action_({
 205                 b.step_((a.at(d.value)).asFloat);
 206                 });
 207 StaticText(w, Rect(130, 60, 100, 20)).string_("change step");
 208 c = NumberBox(w, Rect(20, 20, 100, 20));
 209 )
 210 ::
 211
 212 subsection:: Use the slider view to accept key actions
 213 code::
 214 ( // select the slider, type something and watch the post window
 215 w = Window.new;
 216 c = Slider(w,Rect(0,0,100,30));
 217 c.keyDownAction = { arg view,char,modifiers,unicode,keycode;
 218 [char,modifiers,unicode,keycode].postln;
 219 };
 220 w.front;
 221 )
 222 ::
 223
 224 subsection:: Adding functionality to a view by the method addAction
 225 This is useful for adding things to existing frameworks that have action functions already.
 226 code::
 227 (
 228 w = Window.new("A Slider");
 229 a = Slider.new(w, Rect(40, 10, 300, 30));
 230 w.front
 231 );
 232
 233 // now incrementally add some action to the slider
 234 a.addAction({ |sl| sl.value.postln });
 235 a.addAction({ |sl| w.view.background = Color.green(sl.value) });
 236 a.addAction({ |sl| sl.background = Color.red(1 - sl.value) });
 237
 238 // adding and removing an action:
 239 f = { |sl| "--------*******-------".postln; };
 240 a.addAction(f);
 241 a.removeAction(f);
 242
 243 // or remove all, of course
 244 a.action = nil;
 245 ::
 246
 247 subsection:: Use Slider for triggering sounds
 248 code::
 249 (
 250 s.waitForBoot({
 251         SynthDef(\pluck,{arg freq=55;
 252                 Out.ar(0,
 253                 Pluck.ar(WhiteNoise.ar(0.06),
 254                         EnvGen.kr(Env.perc(0,4), 1.0, doneAction: 2),
 255                         freq.reciprocal,
 256                         freq.reciprocal,
 257                         10,
 258                 coef:0.1)
 259                 );
 260         }).send(s);
 261
 262
 263         w = Window.new("Hold arrow keys to trigger sound",Rect(300,Window.screenBounds.height-300,400,100)).front;
 264         a = Slider(w, Rect(50, 20, 300, 40))
 265                 .value_(0.5)
 266                 .step_(0.05)
 267                 .focus
 268                 .action_({
 269                         // trigger a synth with varying frequencies
 270                         Synth(\pluck, [\freq,55+(1100*a.value)]);
 271                         w.view.background_(Gradient(Color.rand,Color.rand));
 272                 })
 273 });
 274
 275 )
 276 ::
 277
 278 subsection:: Change background color of Window
 279 code::
 280 (
 281 w = Window("RGB fader", Rect(100, 500, 400, 400))
 282         .front;
 283 f = { w.view.background_(Color.new(r.value, g.value, b.value, 1)) };
 284 r = Slider(w, Rect(100, 140, 200, 20))
 285         .value_(0.5)
 286         .action_({ f.value });
 287 g = Slider(w, Rect(100, 170, 200, 20))
 288         .value_(0.5)
 289         .action_({ f.value });
 290 b = Slider(w, Rect(100, 200, 200, 20))
 291         .value_(0.5)
 292         .action_({ f.value });
 293 f.value;
 294 );
 295 ::