basis/ui/gestures/gestures-docs.factor

   1 USING: ui.gadgets help.markup help.syntax
   2 hashtables strings kernel system ;
   3 IN: ui.gestures
   4
   5 HELP: set-gestures
   6 { $values { "class" "a class word" } { "hash" hashtable } }
   7 { $description "Sets the gestures a gadget class responds to. The hashtable maps gestures to quotations with stack effect " { $snippet "( gadget -- )" } "." } ;
   8
   9 HELP: handle-gesture
  10 { $values { "gesture" "a gesture" } { "gadget" "the receiver of the gesture" } { "?" "a boolean" } }
  11 { $contract "Handles a gesture sent to a gadget."
  12 $nl
  13 "Outputs " { $link f } " if the gesture was handled, and " { $link t } " if the gesture should be passed on to the gadget's parent."
  14 $nl
  15 "The default implementation looks at the " { $snippet "\"gestures\"" } " word property of each superclass of the gadget's class." }
  16 { $notes "Methods should be defined on this word if you desire to handle an arbitrary set of gestures. To define handlers for a fixed set, it is easier to use " { $link set-gestures } "." } ;
  17
  18 { propagate-gesture handle-gesture set-gestures } related-words
  19
  20 HELP: propagate-gesture
  21 { $values { "gesture" "a gesture" } { "gadget" gadget } }
  22 { $description "Calls " { $link handle-gesture } " on every parent of " { $snippet "gadget" } "." } ;
  23
  24 HELP: motion
  25 { $class-description "Mouse motion gesture." }
  26 { $examples { $code "motion" } } ;
  27
  28 HELP: drag
  29 { $class-description "Mouse drag gesture. The " { $snippet "#" } " slot is either set to a mouse button number, or " { $link f } " indicating no specific button is expected." } ;
  30
  31 HELP: button-up
  32 { $class-description "Mouse button up gesture. Instances have two slots:"
  33     { $list
  34         { { $snippet "mods" } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
  35         { { $snippet "#" } " - a mouse button number, or " { $link f } " indicating no specific button is expected" }
  36     }
  37 }
  38 { $examples { $code "T{ button-up f f 1 }" "T{ button-up }" } } ;
  39
  40 HELP: button-down
  41 { $class-description "Mouse button down gesture. Instances have two slots:"
  42     { $list
  43         { { $snippet "mods" } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
  44         { { $snippet "#" } " - a mouse button number, or " { $link f } " indicating no specific button is expected" }
  45     }
  46 }
  47 { $examples { $code "T{ button-down f f 1 }" "T{ button-down }" } } ;
  48
  49 HELP: mouse-scroll
  50 { $class-description "Scroll wheel motion gesture. When this gesture is sent, the " { $link scroll-direction } " global variable is set to a direction vector." }
  51 { $examples { $code "mouse-scroll" } } ;
  52
  53 HELP: mouse-enter
  54 { $class-description "Gesture sent when the mouse enters the bounds of a gadget." }
  55 { $examples { $code "mouse-enter" } } ;
  56
  57 HELP: mouse-leave
  58 { $class-description "Gesture sent when the mouse leaves the bounds of a gadget." }
  59 { $examples { $code "mouse-leave" } } ;
  60
  61 HELP: gain-focus
  62 { $class-description "Gesture sent when a gadget gains keyboard focus." }
  63 { $examples { $code "gain-focus" } } ;
  64
  65 HELP: lose-focus
  66 { $class-description "Gesture sent when a gadget loses keyboard focus." }
  67 { $examples { $code "lose-focus" } } ;
  68
  69 HELP: cut-action
  70 { $class-description "Gesture sent when the " { $emphasis "cut" } " standard window system action is invoked." }
  71 { $examples { $code "cut-action" } } ;
  72
  73 HELP: copy-action
  74 { $class-description "Gesture sent when the " { $emphasis "copy" } " standard window system action is invoked." }
  75 { $examples { $code "copy-action" } } ;
  76
  77 HELP: paste-action
  78 { $class-description "Gesture sent when the " { $emphasis "paste" } " standard window system action is invoked." }
  79 { $examples { $code "paste-action" } } ;
  80
  81 HELP: delete-action
  82 { $class-description "Gesture sent when the " { $emphasis "delete" } " standard window system action is invoked." }
  83 { $examples { $code "delete-action" } } ;
  84
  85 HELP: select-all-action
  86 { $class-description "Gesture sent when the " { $emphasis "select all" } " standard window system action is invoked." }
  87 { $examples { $code "select-all-action" } } ;
  88
  89 HELP: C+
  90 { $description "Control key modifier." } ;
  91
  92 HELP: A+
  93 { $description "Alt key modifier." } ;
  94
  95 HELP: M+
  96 { $description "Meta key modifier. This is the Command key on Mac OS X." } ;
  97
  98 HELP: S+
  99 { $description "Shift key modifier." } ;
 100
 101 HELP: key-down
 102 { $class-description "Key down gesture. Instances have two slots:"
 103     { $list
 104         { { $snippet "mods" } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
 105     { { $snippet "sym" } " - a string denoting the key pressed; see " { $link "keyboard-gestures" } }
 106     }
 107 }
 108 { $examples { $code "T{ key-down f { C+ } \"a\" }" "T{ key-down f f \"TAB\" }" } } ;
 109
 110 HELP: key-up
 111 { $class-description "Key up gesture. Instances have two slots:"
 112     { $list
 113         { { $snippet "mods" } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
 114     { { $snippet "sym" } " - a string denoting the key pressed; see " { $link "keyboard-gestures" } }
 115     }
 116 }
 117 { $examples { $code "T{ key-up f { C+ } \"a\" }" "T{ key-up f f \"TAB\" }" } } ;
 118
 119 HELP: hand-gadget
 120 { $var-description "Global variable. The gadget at the mouse location." } ;
 121
 122 HELP: hand-loc
 123 { $var-description "Global variable. The mouse location relative to the top-left corner of the " { $link hand-world } "." } ;
 124
 125 { hand-loc hand-rel } related-words
 126
 127 HELP: hand-clicked
 128 { $var-description "Global variable. The gadget at the location of the most recent click." } ;
 129
 130 HELP: hand-click-loc
 131 { $var-description "Global variable. The mouse location at the time of the most recent click relative to the top-left corner of the " { $link hand-world } "." } ;
 132
 133 { hand-clicked hand-click-loc } related-words
 134
 135 HELP: hand-click#
 136 { $var-description "Global variable. The number of times the mouse was clicked in short succession. This counter is reset when " { $link double-click-timeout } " expires." } ;
 137
 138 HELP: hand-last-button
 139 { $var-description "Global variable. The mouse button most recently pressed." } ;
 140
 141 HELP: hand-last-time
 142 { $var-description "Global variable. The timestamp of the most recent mouse button click. This timestamp has the same format as the output value of " { $link micros } "." } ;
 143
 144 HELP: hand-buttons
 145 { $var-description "Global variable. A vector of mouse buttons currently held down." } ;
 146
 147 HELP: scroll-direction
 148 { $var-description "Global variable. If the most recent gesture was a " { $link mouse-scroll } ", this holds a pair of integers indicating the direction of the scrolling as a two-dimensional vector." } ;
 149
 150 HELP: double-click-timeout
 151 { $var-description "Global variable. The maximum delay between two button presses which will still increment " { $link hand-click# } "." } ;
 152
 153 HELP: button-gesture
 154 { $values { "gesture" "a gesture" } }
 155 { $description "Sends a gesture to the most recently clicked gadget, and if the gadget does not respond to the gesture, removes specific button number information from the gesture and sends it again." } ;
 156
 157 HELP: fire-motion
 158 { $description "Sends a " { $link motion } " or " { $link drag } " gesture to the gadget under the mouse, depending on whether a mouse button is being held down or not." } ;
 159
 160 HELP: forget-rollover
 161 { $description "Sends " { $link mouse-leave } " gestures to all gadgets containing the gadget under the mouse, and resets the " { $link hand-gadget } " variable." } ;
 162
 163 HELP: request-focus
 164 { $values { "gadget" gadget } }
 165 { $description "Gives keyboard focus to the " { $link focusable-child } " of the gadget. This may result in " { $link lose-focus } " and " { $link gain-focus } " gestures being sent." } ;
 166
 167 HELP: drag-loc
 168 { $values { "loc" "a pair of integers" } }
 169 { $description "Outputs the distance travelled by the mouse since the most recent press. Only meaningful inside a " { $link drag } " gesture handler." } ;
 170
 171 HELP: hand-rel
 172 { $values { "gadget" gadget } { "loc" "a pair of integers" } }
 173 { $description "Outputs the location of the mouse relative to the top-left corner of the gadget. Only meaningful inside a " { $link button-down } ", " { $link button-up } ", " { $link motion } " or " { $link drag } " gesture handler, where the gadget is contained in the same world as the gadget receiving the gesture." } ;
 174
 175 HELP: hand-click-rel
 176 { $values { "gadget" gadget } { "loc" "a pair of integers" } }
 177 { $description "Outputs the location of the last mouse relative to the top-left corner of the gadget. Only meaningful inside a " { $link button-down } ", " { $link button-up } ", " { $link motion } " or " { $link drag } " gesture handler, where the gadget is contained in the same world as the gadget receiving the gesture." } ;
 178
 179 HELP: under-hand
 180 { $values { "seq" "a new sequence" } }
 181 { $description "Outputs a sequence where the first element is the " { $link hand-world } " and the last is the " { $link hand-gadget } ", with all parents in between." } ;
 182
 183 HELP: gesture>string
 184 { $values { "gesture" "a gesture" } { "string/f" { $maybe string } } }
 185 { $contract "Creates a human-readable string from a gesture object, returning " { $link f } " if the gesture does not have a human-readable form." }
 186 { $examples
 187     { $unchecked-example "USING: io ui.gestures ;" "T{ key-down f { C+ } \"x\" } gesture>string print" "C+x" }
 188 } ;
 189
 190 HELP: left-action
 191 { $class-description "Gesture sent when the user performs a multi-touch three-finger swipe left." } ;
 192
 193 HELP: right-action
 194 { $class-description "Gesture sent when the user performs a multi-touch three-finger swipe right." } ;
 195
 196 HELP: up-action
 197 { $class-description "Gesture sent when the user performs a multi-touch three-finger swipe up." } ;
 198
 199 HELP: down-action
 200 { $class-description "Gesture sent when the user performs a multi-touch three-finger swipe down." } ;
 201
 202 HELP: zoom-in-action
 203 { $class-description "Gesture sent when the user performs a multi-touch two-finger pinch in." } ;
 204
 205 HELP: zoom-out-action
 206 { $class-description "Gesture sent when the user performs a multi-touch two-finger pinch out." } ;
 207
 208 ARTICLE: "gesture-differences" "Gesture handling differences between platforms"
 209 "On Mac OS X, the modifier keys map as follows:"
 210 { $table
 211     { { $link S+ } "Shift" }
 212     { { $link A+ } "Command (Apple)" }
 213     { { $link C+ } "Control" }
 214     { { $link M+ } "Option" }
 215 }
 216 "On Windows and X11:"
 217 { $table
 218     { { $link S+ } "Shift" }
 219     { { $link A+ } "Alt" }
 220     { { $link C+ } "Control" }
 221     { { $link M+ } "Windows key" }
 222 }
 223 "On Windows, " { $link key-up } " gestures are not reported for all keyboard events."
 224 $nl
 225 { $link "multitouch-gestures" } " are only supported on Mac OS X." ;
 226
 227 ARTICLE: "ui-gestures" "UI gestures"
 228 "User actions such as keyboard input and mouse button clicks deliver " { $emphasis "gestures" } " to gadgets. If the direct receiver of the gesture does not handle it, the gesture is passed on to the receiver's parent, and this way it travels up the gadget hierarchy. Gestures which are not handled at some point are ignored."
 229 $nl
 230 "There are two ways to define gesture handling logic. The simplest way is to associate a fixed set of gestures with a class:"
 231 { $subsection set-gestures }
 232 "Another way is to define a generic word on a class which handles all gestures sent to gadgets of that class:"
 233 { $subsection handle-gesture }
 234 "Sometimes a gesture needs to be presented to the user:"
 235 { $subsection gesture>string }
 236 "Keyboard input:"
 237 { $subsection "ui-focus" }
 238 { $subsection "keyboard-gestures" }
 239 { $subsection "action-gestures" }
 240 { $subsection "ui-user-input" }
 241 "Mouse input:"
 242 { $subsection "mouse-gestures" }
 243 { $subsection "multitouch-gestures" }
 244 "Guidelines for cross-platform applications:"
 245 { $subsection "gesture-differences" }
 246 "Abstractions built on top of gestures:"
 247 { $subsection "ui-commands" }
 248 { $subsection "ui-operations" } ;
 249
 250 ARTICLE: "ui-focus" "Keyboard focus"
 251 "The gadget with keyboard focus is the current receiver of keyboard gestures and user input. Gadgets that wish to receive keyboard input should request focus when clicked:"
 252 { $subsection request-focus }
 253 "The following example demonstrates defining a handler for a mouse click gesture which requests focus:"
 254 { $code
 255     "my-gadget H{"
 256     "    { T{ button-down } [ request-focus ] }"
 257     "} set-gestures"
 258 }
 259 "To nominate a single child as the default focusable child, implement a method on a generic word:"
 260 { $subsection focusable-child* }
 261 "Gestures are sent to a gadget when it gains or loses focus; this can be used to change the gadget's appearance, for example by displaying a border:"
 262 { $subsection gain-focus }
 263 { $subsection lose-focus } ;
 264
 265 ARTICLE: "keyboard-gestures" "Keyboard gestures"
 266 "There are two types of keyboard gestures:"
 267 { $subsection key-down }
 268 { $subsection key-up }
 269 "Each keyboard gesture has a set of modifiers and a key symbol. The set modifiers is denoted by an array which must either be " { $link f } ", or an order-preserving subsequence of the following:"
 270 { $code "{ S+ C+ A+ M+ }" }
 271 { $subsection S+ }
 272 { $subsection C+ }
 273 { $subsection A+ }
 274 { $subsection M+ }
 275 "A key symbol is either a single-character string denoting literal input, or one of the following strings:"
 276 { $list
 277   { $snippet "CLEAR" }
 278   { $snippet "RET" }
 279   { $snippet "ENTER" }
 280   { $snippet "ESC" }
 281   { $snippet "TAB" }
 282   { $snippet "BACKSPACE" }
 283   { $snippet "HOME" }
 284   { $snippet "DELETE" }
 285   { $snippet "END" }
 286   { $snippet "F1" }
 287   { $snippet "F2" }
 288   { $snippet "F3" }
 289   { $snippet "F4" }
 290   { $snippet "F5" }
 291   { $snippet "F6" }
 292   { $snippet "F7" }
 293   { $snippet "F8" }
 294   { $snippet "LEFT" }
 295   { $snippet "RIGHT" }
 296   { $snippet "DOWN" }
 297   { $snippet "UP" }
 298   { $snippet "PAGE_UP" }
 299   { $snippet "PAGE_DOWN" }
 300 }
 301 "The " { $link S+ } " modifier is only ever used with the above action keys; alphanumeric input input with the shift key is delivered without the " { $link S+ } " modifier set, instead the input itself is upper case. For example, the gesture corresponding to " { $snippet "s" } " with the Control and Shift keys pressed is presented as "
 302 { $code "T{ key-down f { C+ } \"S\" }" }
 303 "The " { $snippet "RET" } ", " { $snippet "TAB" } " and " { $snippet "SPACE" } " keys are never delivered in their literal form (" { $snippet "\"\\n\"" } ", " { $snippet "\"\\t\"" } " or "  { $snippet "\" \"" } ")." ;
 304
 305 ARTICLE: "ui-user-input" "Free-form keyboard input"
 306 "Whereas keyboard gestures are intended to be used for keyboard shortcuts, certain gadgets such as text fields need to accept free-form keyboard input. This can be done by implementing a generic word:"
 307 { $subsection user-input* } ;
 308
 309 ARTICLE: "mouse-gestures" "Mouse gestures"
 310 "There are two types of mouse gestures indicating button clicks:"
 311 { $subsection button-down }
 312 { $subsection button-up }
 313 "When a mouse button is pressed or released, two gestures are sent. The first gesture indicates the specific button number, and if this gesture is not handled, the second has a button number set to " { $link f } ":"
 314 { $code "T{ button-down f 1 }" "T{ button-down f f }" }
 315 "Because tuple literals fill unspecified slots with " { $link f } ", the last gesture can be written as " { $snippet "T{ button-down }" } "."
 316 $nl
 317 "Gestures to indicate mouse motion, depending on whenever a button is held down or not:"
 318 { $subsection motion }
 319 { $subsection drag }
 320 "Gestures to indicate that the mouse has crossed gadget boundaries:"
 321 { $subsection mouse-enter }
 322 { $subsection mouse-leave }
 323 "A number of global variables are set after a mouse gesture is sent. These variables can be read to obtain additional information about the gesture."
 324 { $subsection hand-gadget }
 325 { $subsection hand-world }
 326 { $subsection hand-loc }
 327 { $subsection hand-buttons }
 328 { $subsection hand-clicked }
 329 { $subsection hand-click-loc }
 330 { $subsection hand-click# }
 331 "There are some utility words for working with click locations:"
 332 { $subsection hand-rel }
 333 { $subsection hand-click-rel }
 334 { $subsection drag-loc }
 335 "Mouse scroll wheel gesture:"
 336 { $subsection mouse-scroll }
 337 "Global variable set when a mouse scroll wheel gesture is sent:"
 338 { $subsection scroll-direction } ;
 339
 340 ARTICLE: "multitouch-gestures" "Multi-touch gestures"
 341 "Multi-touch gestures are only supported on Mac OS X with newer MacBook and MacBook Pro models."
 342 $nl
 343 "Three-finger swipe:"
 344 { $subsection left-action }
 345 { $subsection right-action }
 346 { $subsection up-action }
 347 { $subsection down-action }
 348 "Two-finger pinch:"
 349 { $subsection zoom-in-action }
 350 { $subsection zoom-out-action } ;
 351
 352 ARTICLE: "action-gestures" "Action gestures"
 353 "Action gestures exist to keep keyboard shortcuts for common clipboard operations consistent."
 354 { $subsection cut-action }
 355 { $subsection copy-action }
 356 { $subsection paste-action }
 357 { $subsection delete-action }
 358 { $subsection select-all-action }
 359 "The following keyboard gestures, if not handled directly, send action gestures:"
 360 { $table
 361     { { $strong "Keyboard gesture" } { $strong "Action gesture" } }
 362     { { $snippet "T{ key-down f { C+ } \"z\" }" } { $snippet "undo-action" } }
 363     { { $snippet "T{ key-down f { C+ } \"Z\" }" } { $snippet "redo-action" } }
 364     { { $snippet "T{ key-down f { C+ } \"x\" }" } { $snippet "cut-action" } }
 365     { { $snippet "T{ key-down f { C+ } \"c\" }" } { $snippet "copy-action" } }
 366     { { $snippet "T{ key-down f { C+ } \"v\" }" } { $snippet "paste-action" } }
 367     { { $snippet "T{ key-down f { C+ } \"a\" }" } { $snippet "select-all-action" } }
 368 }
 369 "Action gestures should be used in place of the above keyboard gestures if possible. For example, on Mac OS X, the standard " { $strong "Edit" } " menu items send action gestures." ;
 370
 371 ABOUT: "ui-gestures"