HelpSource/Classes/Slider2D.schelp

   1 class:: Slider2D
   2 redirect:: implClass
   3 summary:: A view with a handle movable in two dimensions.
   4 categories:: GUI>Views
   5 related:: Classes/TabletSlider2D, Classes/TabletView
   6
   7 DESCRIPTION::
   8
   9 A view that allows setting two numerical values represented by the horizontal and vertical position of a handle movable in two dimensions.
  10
  11 The values are always within the range between 0 and 1. Scaling the output and input values to your needs can easily be achieved by using a link::Classes/ControlSpec:: with its link::Classes/ControlSpec#-map#-map:: and link::Classes/ControlSpec#-unmap#-unmap:: methods.
  12
  13 The link::#-step:: variable determines the amount by which the values will change when the handle is controlled using the keyboard. By default, holding down the Shift, Ctrl, or Alt key will multiply this amount by 100, 10, or 0.1 respectively, though you can customize this by setting link::#-shift_scale::, link::#-ctrl_scale::, or link::#-alt_scale::.
  14
  15 Drag and drop gives and accepts a link::Classes/Point:: of which the two coordinates represent the two values of the Slider2D.
  16
  17
  18
  19
  20 CLASSMETHODS::
  21
  22 PRIVATE:: key
  23
  24
  25
  26
  27 INSTANCEMETHODS::
  28
  29 SUBSECTION:: Data
  30
  31 METHOD:: x
  32         The value represented by the horizontal position of the handle. It will always be clipped to the range between 0 and 1.
  33
  34         argument::
  35                 A Float.
  36
  37 METHOD:: y
  38         The value represented by the vertical position of the handle. It will always be clipped to the range between 0 and 1.
  39
  40         argument::
  41                 A Float.
  42
  43 METHOD:: activex
  44         Sets link::#-x:: and triggers the link::#-action::.
  45
  46
  47 METHOD:: activey
  48         Sets link::#-y:: and triggers the link::#-action::.
  49
  50 METHOD:: setXY
  51         Sets link::#-x:: and link::#-y:: to the two arguments.
  52
  53 METHOD:: setXYActive
  54         Sets link::#-x:: and link::#-y:: to the two arguments, and triggers the link::#-action::.
  55
  56 METHOD:: incrementX
  57         Increments link::#-x:: by link::#-step:: multiplied by code::factor::.
  58
  59 METHOD:: decrementX
  60         Decrements link::#-x:: by link::#-step:: multiplied by code::factor::.
  61
  62 METHOD:: incrementY
  63         Increments link::#-y:: by link::#-step:: multiplied by code::factor::.
  64
  65 METHOD:: decrementY
  66         Decrements link::#-y:: by link::#-step:: multiplied by code::factor::.
  67
  68
  69
  70
  71 SUBSECTION:: Appearance
  72
  73 METHOD:: knobColor
  74         The color of the handle.
  75
  76         argument::
  77                 A Color.
  78
  79
  80
  81 SUBSECTION:: Interaction
  82
  83 METHOD:: step
  84         The amount by which link::#-x:: or link::#-y:: will change when incremented or decremented, either by calling relevant methods, or when related keys are pressed.
  85
  86         argument::
  87                 A Float.
  88
  89 METHOD:: pixelStepX
  90         The absolute amount by which link::#-x:: would change if the handle moved horizontally by one pixel.
  91
  92         returns::
  93                 A Float.
  94
  95 METHOD:: pixelStepY
  96         The absolute amount by which link::#-y:: would change if the handle moved vertically by one pixel.
  97
  98         returns::
  99                 A Float.
 100
 101 METHOD:: shift_scale
 102         The factor by which link::#-step:: is multiplied when incrementing or decrementing the values by keyboard while the Shift key is pressed.
 103
 104         argument::
 105                 A Float.
 106
 107 METHOD:: ctrl_scale
 108         The factor by which link::#-step:: is multiplied when incrementing or decrementing the values by keyboard while the Ctrl key is pressed.
 109
 110         argument::
 111                 A Float.
 112
 113 METHOD:: alt_scale
 114         The factor by which link::#-step:: is multiplied when incrementing or decrementing the values by keyboard while the Alt key is pressed.
 115
 116         argument::
 117                 A Float.
 118
 119
 120
 121 SUBSECTION:: Actions
 122
 123 METHOD:: action
 124         The action object evaluated whenever the user changes the position or size of the handle.
 125
 126 METHOD:: defaultKeyDownAction
 127
 128         Implements the default effects of key presses as follows:
 129
 130         table::
 131         ## strong::Key::   || strong::Effect::
 132         ## r               || x_(1.rand), y_(1.rand), and triggers action
 133         ## n               || x_(0), y_(0), and triggers action
 134         ## x               || x_(1), y_(1), and triggers action
 135         ## c               || x_(0.5), y_(0.5), and triggers action
 136         ## up arrow        || incrementY
 137         ## down arrow      || decrementY
 138         ## right arrow     || incrementX
 139         ## left arrow      || decrementX
 140         ::
 141
 142
 143
 144 SUBSECTION:: Drag and drop
 145
 146 METHOD:: defaultGetDrag
 147         returns::
 148                 A Point of which the x and y coordinates are set to link::#-x:: and link::#-y::, respectively.
 149
 150 METHOD:: defaultCanReceiveDrag
 151         returns::
 152                 True if the current drag data is a Point.
 153
 154 METHOD:: defaultReceiveDrag
 155         Sets link::#-x:: and link::#-y:: to the two coordinates of the Point stored as the current drag data, respectively, and triggers the link::#-action::.
 156
 157
 158
 159
 160 EXAMPLES::
 161
 162 code::
 163 (
 164 w = Window("Slider2D", Rect(100, 100, 140, 140));
 165 t = Slider2D(w, Rect(20, 20, 80, 80))
 166                 .x_(0.5) // initial location of x
 167                 .y_(1)   // initial location of y
 168                 .action_({|sl|
 169                         [\sliderX, sl.x, \sliderY, sl.y].postln;
 170                 });
 171 w.front;
 172 )
 173
 174 t.x        // get the x loc
 175 t.x_(0.25) // set the x loc
 176 ::
 177
 178 Drag an drop Points
 179 code::
 180 (
 181 w = Window("Slider2D", Rect(100, 100, 500, 300));
 182 w.view.decorator = FlowLayout(w.view.bounds);
 183 t = Slider2D(w, Rect(20, 20, 280, 280))
 184                 .x_(0.5) // initial location of x
 185                 .y_(1)   // initial location of y
 186                 .background_(Color.rand)
 187                 .action_({|sl|
 188                         [\sliderX, sl.x, \sliderY, sl.y].postln;
 189                 });
 190 t.step_(0.01);
 191
 192 n = CompositeView.new(w, 200@300);
 193 n.decorator = FlowLayout(n.bounds);
 194
 195 v = { |i| DragBoth.new(n, Rect(0, i * 20, 200, 20)).background_(Color.rand).align_(\center) }.dup(5);
 196
 197 StaticText.new(n, 200@150).string_("hold down cmd and drag points from the slider to the drag slots, or reverse").stringColor_(Color.white);
 198
 199 w.front;
 200 )
 201 ::
 202
 203 Shape a Sound
 204 code::
 205 (
 206 s.waitForBoot({
 207         a = {arg mod = 0.05, index = 0.05;
 208                         var r,out, out2;
 209                         r = Saw.ar(8, 0.03);
 210                         out = PMOsc.ar(
 211                                 440,
 212                                 660 * mod, 3 * index, 0,
 213                                 Lag.ar(r,0.01,1));
 214                         [out,Delay1.ar(out)];
 215         }.play;
 216
 217         w = Window("Slider2D", Rect(100,Window.screenBounds.height - 400, 300, 300));
 218         w.view.decorator = FlowLayout(w.view.bounds);
 219         t = Slider2D(w, Rect(0, 0,292, 292))
 220                         .y_(0.05)
 221                         .x_(0.05)
 222                         .background_(Color.rand)
 223                         .knobColor_(Color.rand)
 224                         .action_({|sl|
 225                                 a.set(\mod,sl.x,\index,sl.y);
 226                         });
 227         w.front;
 228         CmdPeriod.doOnce({w.close});
 229 })
 230 )
 231 ::