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.