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:: factor
  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.