HelpSource/Classes/MultiSliderView.schelp

   1 CLASS:: MultiSliderView
   2 redirect:: implClass
   3 summary:: A view displaying an array of sliders
   4 categories:: GUI>Views
   5
   6 DESCRIPTION::
   7
   8 MultiSliderView displays a collection of values, each represented by the position of one of the sliders placed side by side.
   9
  10 When clicking into the view, the value of the slider under the mouse pointer will be set. Whenever the mouse is moved with a mouse button pressed, the slider currently under the mouse pointer will be adjusted.
  11
  12 The last slider modified is considered to be the strong::current:: one, i.e. the link::#-index:: method will return its index, and link::#-currentValue:: relates to its value.
  13
  14 The current slider is also considered to be the strong::selected:: one. Selection can be extended to more than one slider by modifying link::#-selectionSize::. Whenever a different slider becomes the current one, the selection size shrinks back to 1. Note that the selection will only be visually indicated if link::#-showIndex:: is code::true::.
  15
  16
  17 CLASSMETHODS::
  18
  19 PRIVATE:: key
  20
  21 METHOD:: new
  22
  23         note:: strong:: In Qt GUI: ::
  24
  25         A new MultiSliderView is created empty, without any columns. link::#-size:: or link::#-value:: has to be set in order to create some columns.
  26         ::
  27
  28         note:: strong:: Other GUI kits: ::
  29
  30         A new MultiSliderView is created with code::bounds.width/12:: sliders. However, the default link::#-thumbSize:: is 12 and the default link::#-gap:: is 1. The view width has to be code::13*n+2:: for all the sliders to automatically fit in the view.
  31
  32         So if you want a specific number of sliders, then it is best to specify the link::#-size:: and set link::#-elasticMode:: to 1. Then you will get a MultiSliderView which distributes link::#-size:: amount of sliders over code::bounds.width::, where the slider widths are at maximum link::#-indexThumbSize:: (default 12) and the link::#-gap:: is adjusted accordingly.
  33         ::
  34
  35
  36
  37 INSTANCEMETHODS::
  38
  39 SUBSECTION:: Data
  40
  41 METHOD:: size
  42         The amount of sliders.
  43
  44         When setting -size, if the new amount is larger then the current, new sliders will be added with the value of 0. In the opposite case, the value of sliders up to the new amount will be preserved, and the rest of the sliders will be removed.
  45
  46         note:: strong:: In Cocoa and SwingOSC GUIs: ::
  47
  48         Changing -size after the view has been drawn or after the link::#-value:: array has been set will lead to unexpected results. Instead, you should change the link::#-value::, if you need to change the contents of the view.
  49
  50         ::
  51
  52         argument::
  53                 An Integer.
  54
  55 METHOD:: value
  56
  57         Sets the values of the sliders to those of the elements of the argument.
  58
  59         note::
  60         If the amount of elements in the argument does not match link::#-size::, then makes link::#-size:: match before applying the new values.
  61         ::
  62
  63         argument::
  64                 An array of Floats.
  65
  66 METHOD:: valueAction
  67
  68         Sets link::#-value:: and triggeres link::#-action::.
  69
  70 METHOD:: reference
  71
  72         The reference values in relation to which the values will be visually represented. The default for each slider is 0.
  73
  74         argument::
  75                 An array of Floats.
  76
  77 METHOD:: index
  78
  79         The index of the current slider, i.e. the first one in the selection.
  80
  81         argument::
  82                 An Integer.
  83
  84 METHOD:: selectionSize
  85
  86         The amount of sliders in the selection (starting at link::#-index::).
  87
  88 METHOD:: currentvalue
  89
  90         The value of the slider at link::#-index::
  91
  92         argument::
  93                 A Float.
  94
  95
  96
  97 SUBSECTION:: Display
  98
  99 METHOD:: indexIsHorizontal
 100
 101         The orientation of the view: if true, the sliders are displayed in a horizontal order, otherwise in a vertical order.
 102
 103         argument::
 104                 A Boolean.
 105
 106 METHOD:: elasticMode
 107
 108         If enabled (set to 1), the sliders from link::#-startIndex:: to the last one will be distributed so as to occupy the whole area of the view. The link::#-gap:: variable will be ignored. The size of each slider in the direction of index will be maximally link::#-indexThumbSize::, or smaller in order for all the sliders to fit into the view.
 109
 110         argument::
 111                 0 (disabled) or 1 (enabled).
 112
 113 METHOD:: gap
 114
 115         The gap between the sliders in pixels when link::#-elasticMode:: is disabled.
 116
 117         argument::
 118                 An Integer.
 119
 120 METHOD:: indexThumbSize
 121
 122         The size of the sliders in the direction of index in pixels . If link::#-elasticMode:: is enabled, this will be the maximum size, but the actual size might be smaller in order for all the sliders to fit into the view.
 123
 124         argument::
 125                 An Integer.
 126
 127 METHOD:: valueThumbSize
 128
 129         The size of the slider handles in the direction of value in pixels (if drawn).
 130
 131         argument::
 132                 An Integer.
 133
 134 METHOD:: thumbSize
 135
 136         Sets both link::#-indexThumbSize:: and link::#-valueThumbSize:: to the argument.
 137
 138 METHOD:: startIndex
 139
 140         The index of the slider displayed at the left or top edge of the view (depending on whether link::#-indexIsHorizontal:: is true or false, respectively). Sliders with lower index than this will not be visible.
 141
 142         argument::
 143                 An Integer.
 144
 145
 146 SUBSECTION:: Appearance
 147
 148 METHOD:: showIndex
 149
 150         Wether the slider selection is visually indicated.
 151
 152         argument::
 153                 A Boolean.
 154
 155 METHOD:: drawRects
 156
 157         Whether to draw the sliders.
 158
 159         argument::
 160                 A Boolean.
 161
 162 METHOD:: drawLines
 163
 164         Whether to draw a line connecting the points that represent the link::#-value#values:: of the sliders, and a line connecting the points that represent the link::#-reference#references::.
 165
 166         argument::
 167                 A Boolean.
 168
 169 METHOD:: isFilled
 170
 171         If true, the sliders will have their area between the link::#-reference:: and the link::#-value:: colored, and the area bounded by the lines connecting the reference and the value points will be colored as well.
 172
 173         argument::
 174                 A Boolean.
 175
 176 METHOD:: strokeColor
 177
 178         The color used to draw the lines described in link::#-drawLines::.
 179
 180         argument::
 181                 A Color.
 182
 183 METHOD:: fillColor
 184
 185         The color used to visualize the areas described in link::#-isFilled::.
 186
 187         argument::
 188                 A Color.
 189
 190 METHOD:: colors
 191
 192         Sets link::#-strokeColor:: and link::#-fillColor:: to the two arguments, respectively.
 193
 194
 195
 196 SUBSECTION:: Interaction
 197
 198 METHOD:: editable
 199
 200         Whether the values can be edited using mouse or keyboard.
 201
 202         argument::
 203                 A Boolean.
 204
 205 METHOD:: readOnly
 206
 207         The opposite if link::#-editable::.
 208
 209         argument::
 210                 A Boolean.
 211
 212 METHOD:: step
 213
 214         If the argument is larger than 0, makes the MultiSliderView keep the values quantized to the nearest multiple of the argument.
 215
 216
 217
 218 SUBSECTION:: Actions
 219
 220
 221 METHOD:: action
 222         The action object evaluated whenever the user changes the value of a slider.
 223
 224 METHOD:: metaAction
 225         The action object evaluated whenever the user changes the value of a slider while the Ctrl key is pressed.
 226
 227 METHOD:: defaultKeyDownAction
 228
 229         Implements the default effects of key presses as follows:
 230
 231         table::
 232         ## strong::Key::   || strong::Effect::
 233         ## up arrow        || Qt: increment -currentValue by -step; Cocoa: decrement -gap by 1
 234         ## down arrow      || Qt: decrement -currentValue by -step; Cocoa: increment -gap by 1
 235         ## right arrow     || increment -index by 1
 236         ## left arrow      || decrement -index by 1
 237         ::
 238
 239
 240
 241 SUBSECTION:: Drag and drop
 242
 243 METHOD:: defaultGetDrag
 244         returns::
 245                 a) If link::#-selectionSize:: is 0, returns link::#-value::.
 246
 247                 b) If link::#-selectionSize:: > 1, returns an Array with the values at the indexes in the selection.
 248
 249                 If link::#-reference:: is not nil, returns an Array containing (a) or (b), and an Array of the corresponding reference values: code:: [[values], [references]] ::.
 250
 251 METHOD:: defaultCanReceiveDrag
 252         returns::
 253                 True for any drag data, but the data should either be an Array of values ( code:: [values] :: ), or an Array containg an Array of values and an Array of corresponding reference values ( code:: [[values], [references]] :: ).
 254
 255 METHOD:: defaultReceiveDrag
 256         If the drag data is in one of the acceptable forms (see link::#-defaultCanReceiveDrag:: above), sets link::#-value:: (and link::#-reference::) using that data.
 257
 258
 259
 260 EXAMPLES::
 261
 262 subsection:: Basic Examples
 263
 264 code::
 265 (
 266 n=20;
 267 w = Window.new.front;
 268 m = MultiSliderView(w,Rect(10,10,n*13+2,100)); //default thumbWidth is 13
 269 m.value=Array.fill(n, {|v| v*0.05}); // size is set automatically when you set the value
 270 m.action = { arg q;
 271     q.value.postln;
 272 };
 273 )
 274 ::
 275
 276 Looks like a candlestick graph:
 277
 278 code::
 279 (
 280 var size;
 281 size = 350 / 6;
 282 w = Window.new;
 283 w.view.decorator = FlowLayout(w.view.bounds);
 284 m = MultiSliderView(w, Rect(0, 0, 350, 100));
 285 m.value_(Array.fill(size, {0.01}));
 286 m.isFilled_(true); // width in pixels of each stick
 287 m.indexThumbSize_(2.0); // spacing on the value axis
 288 m.gap_(4);
 289 w.front;
 290 )
 291
 292 // rotate the above graph
 293 (
 294 m.bounds_(Rect(0, 0, 100, 350));
 295 m.indexIsHorizontal_(false);
 296 )
 297 ::
 298
 299
 300 subsection:: Interactive Example
 301
 302 A walk through all the graphic options:
 303
 304 code::
 305 (
 306 n=40;
 307
 308 w = Window("MultiSlider Options", Rect(200, Window.screenBounds.height-550, 600, 450));
 309 f={
 310     w.view.decorator = FlowLayout( w.view.bounds, 10@10, 10@2 );
 311     m = MultiSliderView(w,Rect(0,0,580,200)); // default thumbWidth is 13
 312     m.value=Array.fill(n, {|v| 0.5+((0.3*v).sin*0.25)});
 313     m.action = { arg q;q.value.postln; };
 314
 315     StaticText(w,380@18).string_("indexThumbSize or thumbSize");
 316     Slider(w,580@10).action_({arg sl; m.indexThumbSize=sl.value*24}).value_(0.5);
 317     StaticText(w,380@18).string_("valueThumbSize");
 318     Slider(w,580@10).action_({arg sl; m.valueThumbSize=sl.value*24}).value_(0.5);
 319     StaticText(w,580@18).string_("xOffset or gap");
 320     Slider(w,580@10).action_({arg sl; m.xOffset=sl.value*50});
 321     StaticText(w,580@18).string_("startIndex");
 322     Slider(w,580@10).action_({arg sl; m.startIndex = sl.value *m.size};);
 323
 324     CompositeView(w,580@10);//spacer
 325     Button(w,100@20).states_([["RESET",Color.red]])
 326         .action_({ w.view.removeAll; f.value; });
 327     h=StaticText(w,450@18).string_("").stringColor_(Color.yellow);
 328     Button(w,100@20).states_([["elasticMode = 0"],["elasticMode = 1",Color.white]])
 329         .action_({|b| m.elasticMode = b.value});
 330     Button(w,160@20).states_([["indexIsHorizontal = false"],["indexIsHorizontal = true",Color.white]])
 331         .action_({|b| m.indexIsHorizontal = b.value.booleanValue}).value_(1);
 332     Button(w,120@20).states_([["isFilled = false"],["isFilled = true",Color.white]])
 333         .action_({|b| m.isFilled = b.value.booleanValue});
 334     Button(w,120@20).states_([["drawRects = false"],["drawRects = true",Color.white]])
 335         .action_({|b| m.drawRects = b.value.booleanValue}).valueAction_(1);
 336     Button(w,100@20).states_([["drawLines = false"],["drawLines = true",Color.white]])
 337         .action_({|b| m.drawLines = b.value.booleanValue});
 338     Button(w,160@20).states_([["readOnly = false"],["readOnly = true",Color.white]])
 339         .action_({|b| m.readOnly = b.value.booleanValue});
 340     Button(w,120@20).states_([["showIndex = false"],["showIndex = true",Color.white]])
 341         .action_({|b| m.showIndex = b.value.booleanValue});
 342     Button(w,120@20).states_([["reference = nil"],["reference filled",Color.white],["reference random",Color.yellow]])
 343         .action_({|b| b.value.booleanValue.if({
 344             (b.value>1).if(
 345                 {m.reference=Array.fill(n, {1.0.rand})},
 346                 {m.reference=Array.fill(m.size, {0.5})});
 347                 },{ q=m.value;m.reference=[]; h.string="reference can't be returned to nil presently. please hit RESET."}
 348             )
 349         });
 350     Button(w,180@20).states_([["fillColor = Color.rand"]]).action_({m.fillColor=Color.rand});
 351     Button(w,180@20).states_([["strokeColor = Color.rand"]]).action_({m.strokeColor=Color.rand});
 352     Button(w,180@20).states_([["background = Color.rand"]]).action_({m.background=Color.rand});
 353
 354 };
 355 f.value;
 356 w.front;
 357
 358 )
 359 ::
 360
 361
 362 subsection:: Display a Sound File
 363
 364 code::
 365 (
 366 // press shift to extend the selection
 367 // use as waveView: scrubbing over the view returns index
 368 // if showIndex(false) the view is not refreshed (faster);
 369 // otherwise you can make a selection with shift - drag.
 370 var size, file, maxval, minval;
 371 size = 640;
 372 a = Window("test", Rect(200 , 140, 650, 150));
 373 a.view.decorator = FlowLayout(a.view.bounds);
 374 b = MultiSliderView(a, Rect(0, 0, size, 50));
 375 b.readOnly_(true);
 376 a.view.decorator.nextLine;
 377
 378 d = Array.new;
 379 c = FloatArray.newClear(65493);
 380
 381 r = Slider( a, Rect(0, 0, size, 12));
 382 r.action = {arg ex; b.gap = (ex.value * 4) + 1};
 383
 384 file = SoundFile.new;
 385 file.openRead(Platform.resourceDir +/+ "sounds/a11wlk01.wav");
 386 file.numFrames.postln;
 387 file.readData(c);
 388 // file.inspect;
 389 file.close;
 390 minval = 0;
 391 maxval = 0;
 392 f = Array.new;
 393 d = Array.new;
 394 c.do({arg fi, i;
 395     if(fi < minval, {minval = fi});
 396     if(fi > maxval, {maxval = fi});
 397
 398     //f.postln;
 399     if(i % 256 == 0,{
 400         d = d.add((1 + maxval ) * 0.5 );
 401         f = f.add((1 + minval ) * 0.5 );
 402
 403         minval = 0;
 404         maxval = 0;
 405     });
 406 });
 407
 408 b.reference_(d); // this is used to draw the upper part of the table
 409 b.value_(f);
 410
 411 r = Slider( a, Rect(0, 0, size, 12));
 412 r.action = {arg ex; b.startIndex = ex.value *f.size};
 413
 414 // b.enabled_(false);
 415 b.action = {arg xb; ("index: " ++ xb.index).postln};
 416 b.drawLines_(true);
 417 b.drawRects_(false);
 418 b.isFilled_(true);
 419 b.selectionSize_(10);
 420 b.index_(10);
 421 b.thumbSize_(1);
 422 b.gap_(0);
 423 b.colors_(Color.black, Color.blue(1.0,1.0));
 424 b.showIndex_(true);
 425 a.front;
 426
 427 )
 428 ::
 429
 430
 431 subsection:: Use as a Sequencer
 432
 433 code::
 434 (
 435 var size;
 436 size = 12;
 437 s.waitForBoot{
 438     n={arg freq=330; SinOsc.ar(freq,0,0.2)}.play;
 439
 440     w = Window("test", Rect(200 , 450, 10 + (size * 17), 10 + (size * 17)));
 441     w.view.decorator = FlowLayout(w.view.bounds);
 442     b = MultiSliderView(w, Rect(0, 0, size * 17, size * 17));
 443     b.value_( Array.fill(size,{|i| i/size}) );
 444     b.background_(Color.rand);
 445     b.action = {arg xb;
 446         n.set(\freq, 330+(1100*xb.value.at(xb.index)));
 447         ("index: " ++ xb.index ++" value: " ++ xb.value.at(xb.index)).postln};
 448     b.elasticMode_(1); // makes the squares fit evenly
 449     b.showIndex = true; // cursor mode
 450     b.readOnly=true;
 451     w.front;
 452
 453     r = Routine({
 454         0.1.wait;
 455         30.do({ arg i;
 456             b.index_(i%size);
 457
 458             b.doAction;
 459             0.1.wait;
 460         });
 461
 462         20.do({ arg i;
 463             b.index_(b.size.rand);
 464             b.doAction;
 465             [0.1,0.2].choose.wait;
 466         });
 467         1.wait;
 468         n.free;
 469         {w.close}.defer;
 470     });
 471     AppClock.play(r);
 472 };
 473 )
 474 ::