HelpSource/Classes/Knob.schelp

   1 class:: Knob
   2 redirect:: implClass
   3 summary:: A rotary controller view
   4 categories:: GUI>Views
   5 related:: Classes/Slider, Classes/Slider2D
   6
   7 DESCRIPTION::
   8
   9 Knob displays a value from 0.0 to 1.0 in rotary fashon, and allows to control it with either circular or linear mouse motion.
  10
  11 It also displays the deviation of the value from either 0.0 or 0.5, which you can choose using link::#-centered::.
  12
  13 To switch between the mouse interaction modes, use link::#-mode::.
  14
  15 The amount by which the value changes at interaction can be fine-tuned using link::#-step::, link::#-keystep::, link::#-shift_scale::, link::#-ctrl_scale::, and link::#-alt_scale::
  16
  17 CLASSMETHODS::
  18
  19 PRIVATE:: key
  20
  21 METHOD:: defaultMode
  22
  23     The default link::#-mode:: for newly created Knobs.
  24
  25
  26 INSTANCEMETHODS::
  27
  28
  29 SUBSECTION:: Data
  30
  31 METHOD:: value
  32
  33     The displayed value.
  34
  35     argument::
  36         A Number in the range of 0.0 to 1.0.
  37
  38 METHOD:: valueAction
  39
  40     Sets the value and triggeres link::#-action::.
  41
  42 METHOD:: increment
  43     Increments the value by link::#-keystep:: multiplied by the argument.
  44
  45     argument::
  46         A Number.
  47
  48 METHOD:: decrement
  49     Decrements the value by link::#-keystep:: multiplied by the argument.
  50
  51     argument:: zoom
  52         A Number.
  53
  54
  55 SUBSECTION:: Interaction
  56
  57 METHOD:: mode
  58
  59     The way value is controlled with respect to mouse movement after clicking on the view:
  60     list::
  61     ## code::\round:: - value follows circular movement
  62     ## code::\horiz:: - value follows linear movement in horizontal direction
  63     ## code::\vert:: - value follows linear movement in vertical direction
  64     ::
  65
  66     Defaults to code::\round::.
  67
  68     Argument::
  69         One of the symbols listed above.
  70
  71 METHOD:: keystep
  72
  73     The amount by which the value is incremented/decremented when pressing a relevant key.
  74
  75     Defaults to 0.01;
  76
  77     Argument::
  78         A Number.
  79
  80 METHOD:: step
  81
  82     The amount by which the value is incremented/decremented using the mouse in 'horizontal' and 'vertical' link::#-mode#modes::.
  83
  84     Argument::
  85         A Number.
  86
  87 METHOD:: shift_scale
  88     The factor by which link::#-step:: or link::#-keystep:: is multiplied when used at mouse or keyboard interaction while the Shift key is pressed.
  89
  90     argument::
  91         A Float.
  92
  93 METHOD:: ctrl_scale
  94     The factor by which link::#-step:: or link::#-keystep:: is multiplied when used at mouse or keyboard interaction while the Ctrl key is pressed.
  95
  96     argument::
  97         A Float.
  98
  99 METHOD:: alt_scale
 100     The factor by which link::#-step:: or link::#-keystep:: is multiplied when used at mouse or keyboard interaction while the Alt key is pressed.
 101
 102     argument::
 103         A Float.
 104
 105
 106
 107 SUBSECTION:: Appearance
 108
 109 METHOD:: centered
 110
 111     Whether the deviation of value will be displayed in relation to 0.0 or 0.5 (e.g. as in a panning controller);
 112
 113     Argument::
 114         A Boolean.
 115
 116 METHOD:: color
 117
 118     The colors used by the Knob to draw the following elements:
 119
 120     list::
 121     ## the main Knob color
 122     ## the value indicator
 123     ## the deviation indicator
 124     ## the background of the deviation indicator
 125     ::
 126
 127     Argument::
 128         An Array of four Colors in the order listed above.
 129
 130
 131 SUBSECTION:: Actions
 132
 133 METHOD:: action
 134     The action object evaluated whenever the user interacts with the Knob using the mouse or the keyboard.
 135
 136 METHOD:: defaultKeyDownAction
 137
 138     Implements the default effects of key presses as follows:
 139
 140     table::
 141     ## strong::Key::   || strong::Effect::
 142     ## r               || valueAction_(1.0.rand)
 143     ## n               || valueAction_(0)
 144     ## x               || valueAction_(1)
 145     ## c               || valueAction_(0.5)
 146     ## ]               || increment
 147     ## [               || decrement
 148     ## up arrow        || increment
 149     ## down arrow      || decrement
 150     ## right arrow     || increment
 151     ## left arrow      || decrement
 152     ::
 153
 154     See also: link::#-keystep::, link::#-shift_scale::, link::#-ctrl_scale::, link::#-alt_scale::.
 155
 156 SUBSECTION:: Drag and drop
 157
 158 METHOD:: defaultGetDrag
 159     returns::
 160         The link::#-value::.
 161
 162 METHOD:: defaultCanReceiveDrag
 163     returns::
 164         True if the current drag data is a Number.
 165
 166 METHOD:: defaultReceiveDrag
 167     Sets link::#-valueAction:: to the current drag data.
 168
 169
 170 EXAMPLES::
 171
 172 subsection:: Basic Example
 173
 174 code::
 175 (
 176 var window, size = 32; // try different sizes - from 15 to 200 or more!
 177 window = Window.new("Knob", Rect(640,630,270,70)).front;
 178 k = Knob.new(window, Rect(20, 10, size, size));
 179 k.action_({|v,x,y,m| postf("action func called: %\n", v.value); });
 180 //k.color[1] = Color.gray(alpha:0);
 181 )
 182
 183 k.value
 184 k.value = 0.25
 185 k.valueAction = 0.125
 186
 187 // modes
 188 k.mode = \vert;
 189 k.mode = \horiz;
 190 k.mode = \round; // default
 191
 192 k.visible
 193 k.visible = false
 194 k.visible = true
 195 k.enabled = false
 196 k.enabled_(true)
 197 k.canFocus = false
 198 k.canFocus = true
 199 ::
 200
 201
 202 subsection:: Centered Mode
 203
 204 Center mode is useful for pan or eq gain control etc.
 205
 206 code::
 207 (
 208 var window;
 209 window = Window.new("Pan Knob", Rect(640,630,270,70)).front;
 210 k = Knob.new(window, Rect(20,10,36,36));
 211 k.action_({|v,x,y,m| \pan.asSpec.map(v.value).postln; })
 212 //  .mode_(\horiz)
 213     .centered_(false)
 214     .value_(\pan.asSpec.unmap(0)); // 0.5
 215 //k.color[1] = Color.gray(alpha:0);
 216 )
 217 k.centered
 218 k.centered = true
 219 k.centered = false
 220 ::
 221
 222
 223 subsection:: step
 224
 225 link::#-step:: only affects the 'horiz' and 'vert' modes:
 226
 227 code::
 228 (
 229 var window, midispec;
 230 midispec = [0,127,'linear',1].asSpec;
 231 window = Window.new("step Knob", Rect(640,630,270,70)).front;
 232 k = Knob.new(window, Rect(20,10,32,32));
 233 k.action_({|v,x,y,m| midispec.map(v.value).postln; })
 234        .value_(midispec.unmap(0));
 235
 236 k.mode = \vert;
 237
 238 )
 239 k.step
 240 k.step = 10/127 // step by 10
 241
 242 k.mode = \horiz;
 243 k.mode = \round;
 244 ::
 245
 246
 247 subsection:: mouseOverAction
 248
 249 code::
 250 (
 251 var size = 28;
 252 w = Window.new("Knobs", Rect(250,500,270,70));
 253 w.acceptsMouseOver=true; // must be true in parent window!
 254 w.view.decorator = FlowLayout(w.view.bounds);
 255 h = StaticText(w, 150 @ 20);
 256 w.view.decorator.nextLine;
 257 k = Array(8);
 258 8.do({|item, i|
 259     var knob;
 260     knob = Knob.new(w, size @ size)
 261         .action_({|v,x,y,m| h.string = "val: " ++ v.value.asString; })
 262         .mouseOverAction_({|v,x,y| h.string = "val: " ++ v.value.asString; });
 263
 264     k = k.add(knob);
 265 });
 266 w.front
 267 )
 268 k[4].value
 269 ::
 270
 271
 272 subsection:: Drag and Drop
 273
 274 code::
 275 (
 276 var w, txt, size = 36;
 277 w = Window.new("Knobs", Rect(400,400,250,100)).front;
 278 w.acceptsMouseOver=true;
 279 w.view.decorator = FlowLayout(w.view.bounds).gap_(10 @ 10).margin_(10 @10);
 280 txt = StaticText(w, 200 @ 14);
 281 w.view.decorator.nextLine;
 282
 283 k = Knob(w, size @ size);
 284 k.action = {arg v,x,y;  v.value.postln; txt.string_("value: " ++ v.value); };
 285 k.mouseOverAction = {|v| txt.string_("value: " ++ v.value); };
 286
 287 j = Knob(w, size @ size);
 288 j.action = {arg v,x,y;  j.value.postln; txt.string_("value: " ++ v.value); };
 289 j.mouseOverAction = { txt.string_("value: " ++ j.value); };
 290
 291 n = NumberBox(w, 100 @ 20);
 292 //n.setProperty(\boxColor,Color.grey(alpha:0.0));
 293 n.value = 0.0;
 294 )
 295
 296 // customize drag and drop methods
 297 k.canReceiveDragHandler
 298 k.canReceiveDragHandler = false; // don't accept drops
 299
 300 k.canReceiveDragHandler = { View.currentDrag.isFloat }; // accept only if drag is float
 301
 302 k.receiveDragHandler = { ("value dropped in: " ++ View.currentDrag).postln }
 303
 304 k.receiveDragHandler = { k.valueAction = View.currentDrag.clip(0.0, 1.0); }
 305
 306 k.beginDragAction = { ("drag out -> " ++ k.value).postln; }
 307
 308 k.beginDragAction = { k.value.asFloat; }
 309 ::