HelpSource/Classes/NumberBox.schelp

   1 CLASS:: NumberBox
   2 redirect:: implClass
   3 summary:: A view displaying a modifiable numerical value.
   4 categories:: GUI>Views
   5
   6 DESCRIPTION::
   7
   8 A view that displays a numerical value and allows to modify it by typing the value in, and incrementing or decrementing it using the keyboard, or mouse.
   9
  10 Using the keyboard, the value will change on each arrow key press by the amount defined by link::#-step::.
  11
  12 Mouse scrolling is performed by pressing a mouse button inside the view and dragging the mouse vertically. The value will change according to the mouse cursor movement, in steps defined by link::#-scroll_step::.
  13
  14 By default, holding down the Shift, Ctrl, or Alt key while incrementing or decrementing the value will multiply the steps by 100, 10, or 0.1 respectively, though you can customize this by setting link::#-shift_scale::, link::#-ctrl_scale::, or link::#-alt_scale::. Scrolling can be enabled or disabled by modifying the link::#-scroll:: variable.
  15
  16
  17
  18
  19 CLASSMETHODS::
  20
  21 PRIVATE:: key
  22
  23
  24
  25
  26 INSTANCEMETHODS::
  27
  28
  29
  30
  31 SUBSECTION:: Data
  32
  33 METHOD:: value
  34         Numerical value between 0 and 1.
  35
  36         argument::
  37                 A Float.
  38
  39 METHOD:: valueAction
  40         Sets link::#-value:: to the argument and triggeres link::#-action::.
  41
  42 METHOD:: increment
  43         Increments the value by link::#-step:: multiplied by 'factor'.
  44
  45         argument:: factor
  46                 Any number.
  47
  48 METHOD:: decrement
  49         Decrements the value by link::#-step:: multiplied by 'factor'.
  50
  51         argument:: factor
  52                 Any number.
  53
  54 METHOD:: string
  55         Text to be displayed instead of the numerical value. Setting link::#-value:: after this will display the value again.
  56
  57         argument::
  58                 A String.
  59
  60 METHOD:: object
  61         If link::#-setBoth:: is true, setting this variable also sets link::#-string:: to the argument interpreted link::Classes/Object#-asString#as String::.
  62
  63         argument::
  64                 Any object, typically one which makes sense to display as a string, such as a Float.
  65
  66 METHOD:: setBoth
  67         A variable stating whether setting link::#-object:: will also set link::#-string::.
  68
  69         argument::
  70                 A Boolean.
  71
  72
  73
  74
  75 SUBSECTION:: Restrictions on data
  76
  77 METHOD:: clipLo
  78         The lowest numerical value allowed. Trying to set a lower value will clip it to this.
  79
  80         argument::
  81                 A Float.
  82
  83 METHOD:: clipHi
  84         The highest numerical value allowed. Trying to set a higher value will clip it to this.
  85
  86         argument::
  87                 A Float.
  88
  89 METHOD:: minDecimals
  90         The minimum amount of decimal places displayed. If the value can be completely described with less decimal places, zeros will be appended until reaching this.
  91
  92         argument::
  93                 An Integer.
  94
  95 METHOD:: maxDecimals
  96         The maximum amount of decimal places displayed. The value will always be rounded to this amount of decimals.
  97
  98         argument::
  99                 An Integer.
 100
 101 METHOD:: decimals
 102         Sets both link::#-minDecimals:: and link::#-maxDecimals:: to the argument.
 103
 104         argument::
 105                 An Integer.
 106
 107
 108
 109
 110 SUBSECTION:: Appearance
 111
 112 METHOD:: align
 113         The alignment of the displayed value.
 114
 115         argument::
 116                 One of the following symbols: \centered, \left, or \right.
 117
 118 METHOD:: stringColor
 119         The color used to display the value before it is ever changed by user interaction.
 120
 121         argument::
 122                 A Color.
 123
 124 METHOD:: normalColor
 125         The color used to display the value after is has been typed in.
 126
 127         argument::
 128                 A Color.
 129
 130 METHOD:: typingColor
 131         The color used to display the value while it is being typed in.
 132
 133         argument::
 134                 A Color.
 135
 136
 137
 138
 139 SUBSECTION:: Interaction
 140
 141 METHOD:: step
 142         The amount by which the value will changed when link::#-increment:: or link::#-decrement:: is called, or when related keys are pressed.
 143
 144         argument::
 145                 A Float.
 146
 147 METHOD:: scroll_step
 148         The amount by which the value will changed when scrolled using the mouse.
 149
 150         argument::
 151                 A Float.
 152
 153 METHOD:: shift_scale
 154         The factor by which link::#-step:: or link::#-scroll_step:: is multiplied when incrementing or decrementing the value using keyboard or mouse while the Shift key is pressed.
 155
 156         argument::
 157                 A Float.
 158
 159 METHOD:: ctrl_scale
 160         The factor by which link::#-step:: or link::#-scroll_step:: is multiplied when incrementing or decrementing the value using keyboard or mouse while the Ctrl key is pressed.
 161
 162         argument::
 163                 A Float.
 164
 165 METHOD:: alt_scale
 166         The factor by which link::#-step:: or link::#-scroll_step:: is multiplied when incrementing or decrementing the value using keyboard or mouse while the Alt key is pressed.
 167
 168         argument::
 169                 A Float.
 170
 171
 172
 173 SUBSECTION:: Actions
 174
 175 METHOD:: action
 176         The action object evaluated whenever the user changes the value by interacting with the view.
 177
 178 METHOD:: defaultKeyDownAction
 179
 180         Any key representing a character that can make part of a floating point number representation will initiated the editing of the value. Pressing Return (or Enter) will finish the editing and store the value typed in as a Float.
 181
 182         Aside from that, this method implements the default effects of key presses as follows:
 183
 184         table::
 185         ## strong::Key::   || strong::Effect::
 186         ## up arrow        || increment
 187         ## down arrow      || decrement
 188         ## right arrow     || increment
 189         ## left arrow      || decrement
 190         ::
 191
 192
 193
 194 SUBSECTION:: Drag and drop
 195
 196 METHOD:: defaultGetDrag
 197         returns::
 198                 The link::#-value::.
 199
 200 METHOD:: defaultCanReceiveDrag
 201         returns::
 202                 True if the current drag data is a number.
 203
 204 METHOD:: defaultReceiveDrag
 205         Sets link::#-valueAction:: to the current drag data.