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" } { "?" 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 } ". If you define a method on " { $snippet "handle-gesture" } ", you should also override " { $link handles-gesture? } "." } ;
  17
  18 HELP: handles-gesture?
  19 { $values { "gesture" "a gesture" } { "gadget" "the receiver of the gesture" } { "?" boolean } }
  20 { $contract "Returns a true value if " { $snippet "gadget" } " would handle " { $snippet "gesture" } " in its " { $link handle-gesture } " method."
  21 $nl
  22 "The default implementation looks at the " { $snippet "\"gestures\"" } " word property of each superclass of the gadget's class and returns true if a handler is present for " { $snippet "gesture" } "." }
  23 { $notes "This word is used in Factor's MacOS X UI to validate menu items." } ;
  24
  25 HELP: parents-handle-gesture?
  26 { $values { "gesture" "a gesture" } { "gadget" "the receiver of the gesture" } { "?" boolean } }
  27 { $contract "Returns a true value if " { $snippet "gadget" } " or any of its ancestors would handle " { $snippet "gesture" } " in its " { $link handle-gesture } " method." } ;
  28
  29 { propagate-gesture handle-gesture handles-gesture? set-gestures } related-words
  30
  31 HELP: propagate-gesture
  32 { $values { "gesture" "a gesture" } { "gadget" gadget } }
  33 { $description "Calls " { $link handle-gesture } " on every parent of " { $snippet "gadget" } "." } ;
  34
  35 HELP: motion
  36 { $class-description "Mouse motion gesture." }
  37 { $examples { $code "motion" } } ;
  38
  39 HELP: drag
  40 { $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." } ;
  41
  42 HELP: button-up
  43 { $class-description "Mouse button up gesture. Instances have two slots:"
  44     { $list
  45         { { $snippet "mods" } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
  46         { { $snippet "#" } " - a mouse button number, or " { $link f } " indicating no specific button is expected" }
  47     }
  48 }
  49 { $examples { $code "T{ button-up f f 1 }" "T{ button-up }" } } ;
  50
  51 HELP: button-down
  52 { $class-description "Mouse button down gesture. Instances have two slots:"
  53     { $list
  54         { { $snippet "mods" } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
  55         { { $snippet "#" } " - a mouse button number, or " { $link f } " indicating no specific button is expected" }
  56     }
  57 }
  58 { $examples { $code "T{ button-down f f 1 }" "T{ button-down }" } } ;
  59
  60 HELP: mouse-scroll
  61 { $class-description "Scroll wheel motion gesture. When this gesture is sent, the " { $link scroll-direction } " global variable is set to a direction vector." }
  62 { $examples { $code "mouse-scroll" } } ;
  63
  64 HELP: mouse-enter
  65 { $class-description "Gesture sent when the mouse enters the bounds of a gadget." }
  66 { $examples { $code "mouse-enter" } } ;
  67
  68 HELP: mouse-leave
  69 { $class-description "Gesture sent when the mouse leaves the bounds of a gadget." }
  70 { $examples { $code "mouse-leave" } } ;
  71
  72 HELP: gain-focus
  73 { $class-description "Gesture sent when a gadget gains keyboard focus." }
  74 { $examples { $code "gain-focus" } } ;
  75
  76 HELP: lose-focus
  77 { $class-description "Gesture sent when a gadget loses keyboard focus." }
  78 { $examples { $code "lose-focus" } } ;
  79
  80 HELP: cut-action
  81 { $class-description "Gesture sent when the " { $emphasis "cut" } " standard window system action is invoked." }
  82 { $examples { $code "cut-action" } } ;
  83
  84 HELP: copy-action
  85 { $class-description "Gesture sent when the " { $emphasis "copy" } " standard window system action is invoked." }
  86 { $examples { $code "copy-action" } } ;
  87
  88 HELP: paste-action
  89 { $class-description "Gesture sent when the " { $emphasis "paste" } " standard window system action is invoked." }
  90 { $examples { $code "paste-action" } } ;
  91
  92 HELP: delete-action
  93 { $class-description "Gesture sent when the " { $emphasis "delete" } " standard window system action is invoked." }
  94 { $examples { $code "delete-action" } } ;
  95
  96 HELP: select-all-action
  97 { $class-description "Gesture sent when the " { $emphasis "select all" } " standard window system action is invoked." }
  98 { $examples { $code "select-all-action" } } ;
  99
 100 HELP: new-action
 101 { $class-description "Gesture sent when the " { $emphasis "new" } " standard window system action is invoked." }
 102 { $examples { $code "new-action" } } ;
 103
 104 HELP: open-action
 105 { $class-description "Gesture sent when the " { $emphasis "open" } " standard window system action is invoked." }
 106 { $examples { $code "open-action" } } ;
 107
 108 HELP: save-action
 109 { $class-description "Gesture sent when the " { $emphasis "save" } " standard window system action is invoked." }
 110 { $examples { $code "save-action" } } ;
 111
 112 HELP: save-as-action
 113 { $class-description "Gesture sent when the " { $emphasis "save as" } " standard window system action is invoked." }
 114 { $examples { $code "save-as-action" } } ;
 115
 116 HELP: revert-action
 117 { $class-description "Gesture sent when the " { $emphasis "revert" } " standard window system action is invoked." }
 118 { $examples { $code "revert-action" } } ;
 119
 120 HELP: close-action
 121 { $class-description "Gesture sent when the " { $emphasis "close" } " standard window system action is invoked." }
 122 { $examples { $code "close-action" } } ;
 123
 124 HELP: C+
 125 { $description "Control key modifier." } ;
 126
 127 HELP: A+
 128 { $description "Alt key modifier." } ;
 129
 130 HELP: M+
 131 { $description "Meta key modifier. This is the Command key on Mac OS X." } ;
 132
 133 HELP: S+
 134 { $description "Shift key modifier." } ;
 135
 136 HELP: key-down
 137 { $class-description "Key down gesture. Instances have two slots:"
 138     { $list
 139         { { $snippet "mods" } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
 140     { { $snippet "sym" } " - a string denoting the key pressed; see " { $link "keyboard-gestures" } }
 141     }
 142 }
 143 { $examples { $code "T{ key-down f { C+ } \"a\" }" "T{ key-down f f \"TAB\" }" } } ;
 144
 145 HELP: key-up
 146 { $class-description "Key up gesture. Instances have two slots:"
 147     { $list
 148         { { $snippet "mods" } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
 149     { { $snippet "sym" } " - a string denoting the key pressed; see " { $link "keyboard-gestures" } }
 150     }
 151 }
 152 { $examples { $code "T{ key-up f { C+ } \"a\" }" "T{ key-up f f \"TAB\" }" } } ;
 153
 154 HELP: hand-gadget
 155 { $var-description "Global variable. The gadget at the mouse location." } ;
 156
 157 HELP: hand-loc
 158 { $var-description "Global variable. The mouse location relative to the top-left corner of the " { $link hand-world } "." } ;
 159
 160 { hand-loc hand-rel } related-words
 161
 162 HELP: hand-clicked
 163 { $var-description "Global variable. The gadget at the location of the most recent click." } ;
 164
 165 HELP: hand-click-loc
 166 { $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 } "." } ;
 167
 168 { hand-clicked hand-click-loc } related-words
 169
 170 HELP: hand-click#
 171 { $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." } ;
 172
 173 HELP: hand-last-button
 174 { $var-description "Global variable. The mouse button most recently pressed." } ;
 175
 176 HELP: hand-last-time
 177 { $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 nano-count } "." } ;
 178
 179 HELP: hand-buttons
 180 { $var-description "Global variable. A vector of mouse buttons currently held down." } ;
 181
 182 HELP: scroll-direction
 183 { $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." } ;
 184
 185 HELP: double-click-timeout
 186 { $var-description "Global variable. The maximum delay between two button presses which will still increment " { $link hand-click# } "." } ;
 187
 188 HELP: button-gesture
 189 { $values { "gesture" "a gesture" } }
 190 { $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." } ;
 191
 192 HELP: fire-motion
 193 { $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." } ;
 194
 195 HELP: forget-rollover
 196 { $description "Sends " { $link mouse-leave } " gestures to all gadgets containing the gadget under the mouse, and resets the " { $link hand-gadget } " variable." } ;
 197
 198 HELP: request-focus
 199 { $values { "gadget" gadget } }
 200 { $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." } ;
 201
 202 HELP: drag-loc
 203 { $values { "loc" "a pair of integers" } }
 204 { $description "Outputs the distance travelled by the mouse since the most recent press. Only meaningful inside a " { $link drag } " gesture handler." } ;
 205
 206 HELP: hand-rel
 207 { $values { "gadget" gadget } { "loc" "a pair of integers" } }
 208 { $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." } ;
 209
 210 HELP: hand-click-rel
 211 { $values { "gadget" gadget } { "loc" "a pair of integers" } }
 212 { $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." } ;
 213
 214 HELP: under-hand
 215 { $values { "seq" "a new sequence" } }
 216 { $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." } ;
 217
 218 HELP: gesture>string
 219 { $values { "gesture" "a gesture" } { "string/f" { $maybe string } } }
 220 { $contract "Creates a human-readable string from a gesture object, returning " { $link f } " if the gesture does not have a human-readable form." }
 221 { $examples
 222     { $unchecked-example "USING: io ui.gestures ;" "T{ key-down f { C+ } \"x\" } gesture>string print" "C+x" }
 223 } ;
 224
 225 HELP: left-action
 226 { $class-description "Gesture sent when the user performs a multi-touch three-finger swipe left." } ;
 227
 228 HELP: right-action
 229 { $class-description "Gesture sent when the user performs a multi-touch three-finger swipe right." } ;
 230
 231 HELP: up-action
 232 { $class-description "Gesture sent when the user performs a multi-touch three-finger swipe up." } ;
 233
 234 HELP: down-action
 235 { $class-description "Gesture sent when the user performs a multi-touch three-finger swipe down." } ;
 236
 237 HELP: zoom-in-action
 238 { $class-description "Gesture sent when the user performs a multi-touch two-finger pinch in." } ;
 239
 240 HELP: zoom-out-action
 241 { $class-description "Gesture sent when the user performs a multi-touch two-finger pinch out." } ;
 242
 243 ARTICLE: "gesture-differences" "Gesture handling differences between platforms"
 244 "On Mac OS X, the modifier keys map as follows:"
 245 { $table
 246     { { $link S+ } "Shift" }
 247     { { $link A+ } "Command (Apple)" }
 248     { { $link C+ } "Control" }
 249     { { $link M+ } "Option" }
 250 }
 251 "On Windows and X11:"
 252 { $table
 253     { { $link S+ } "Shift" }
 254     { { $link A+ } "Alt" }
 255     { { $link C+ } "Control" }
 256     { { $link M+ } "Windows key" }
 257 }
 258 "On Windows, " { $link key-up } " gestures are not reported for all keyboard events."
 259 $nl
 260 { $link "multitouch-gestures" } " are only supported on Mac OS X." ;
 261
 262 ARTICLE: "ui-gestures" "UI gestures"
 263 "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."
 264 $nl
 265 "There are two ways to define gesture handling logic. The simplest way is to associate a fixed set of gestures with a class:"
 266 { $subsections set-gestures }
 267 "Another way is to define a generic word on a class which handles all gestures sent to gadgets of that class:"
 268 { $subsections handle-gesture }
 269 "Sometimes a gesture needs to be presented to the user:"
 270 { $subsections gesture>string }
 271 "Keyboard input:"
 272 { $subsections
 273     "ui-focus"
 274     "keyboard-gestures"
 275     "action-gestures"
 276     "ui-user-input"
 277 }
 278 "Mouse input:"
 279 { $subsections
 280     "mouse-gestures"
 281     "multitouch-gestures"
 282 }
 283 "Guidelines for cross-platform applications:"
 284 { $subsections "gesture-differences" }
 285 "Abstractions built on top of gestures:"
 286 { $subsections
 287     "ui-commands"
 288     "ui-operations"
 289 } ;
 290
 291 ARTICLE: "ui-focus" "Keyboard focus"
 292 "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:"
 293 { $subsections request-focus }
 294 "The following example demonstrates defining a handler for a mouse click gesture which requests focus:"
 295 { $code
 296     "my-gadget H{"
 297     "    { T{ button-down } [ request-focus ] }"
 298     "} set-gestures"
 299 }
 300 "To nominate a single child as the default focusable child, implement a method on a generic word:"
 301 { $subsections focusable-child* }
 302 "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:"
 303 { $subsections
 304     gain-focus
 305     lose-focus
 306 } ;
 307
 308 ARTICLE: "keyboard-gestures" "Keyboard gestures"
 309 "There are two types of keyboard gestures:"
 310 { $subsections
 311     key-down
 312     key-up
 313 }
 314 "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:"
 315 { $code "{ S+ C+ A+ M+ }" }
 316 { $subsections
 317     S+
 318     C+
 319     A+
 320     M+
 321 }
 322 "A key symbol is either a single-character string denoting literal input, or one of the following strings:"
 323 { $list
 324   { $snippet "CLEAR" }
 325   { $snippet "RET" }
 326   { $snippet "ENTER" }
 327   { $snippet "ESC" }
 328   { $snippet "TAB" }
 329   { $snippet "BACKSPACE" }
 330   { $snippet "HOME" }
 331   { $snippet "DELETE" }
 332   { $snippet "END" }
 333   { $snippet "F1" }
 334   { $snippet "F2" }
 335   { $snippet "F3" }
 336   { $snippet "F4" }
 337   { $snippet "F5" }
 338   { $snippet "F6" }
 339   { $snippet "F7" }
 340   { $snippet "F8" }
 341   { $snippet "LEFT" }
 342   { $snippet "RIGHT" }
 343   { $snippet "DOWN" }
 344   { $snippet "UP" }
 345   { $snippet "PAGE_UP" }
 346   { $snippet "PAGE_DOWN" }
 347 }
 348 "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 "
 349 { $code "T{ key-down f { C+ } \"S\" }" }
 350 "The " { $snippet "RET" } ", " { $snippet "TAB" } " and " { $snippet "SPACE" } " keys are never delivered in their literal form (" { $snippet "\"\\n\"" } ", " { $snippet "\"\\t\"" } " or "  { $snippet "\" \"" } ")." ;
 351
 352 ARTICLE: "ui-user-input" "Free-form keyboard input"
 353 "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:"
 354 { $subsections user-input* } ;
 355
 356 ARTICLE: "mouse-gestures" "Mouse gestures"
 357 "There are two types of mouse gestures indicating button clicks:"
 358 { $subsections
 359     button-down
 360     button-up
 361 }
 362 "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 } ":"
 363 { $code "T{ button-down f 1 }" "T{ button-down f f }" }
 364 "Because tuple literals fill unspecified slots with " { $link f } ", the last gesture can be written as " { $snippet "T{ button-down }" } "."
 365 $nl
 366 "Gestures to indicate mouse motion, depending on whenever a button is held down or not:"
 367 { $subsections
 368     motion
 369     drag
 370 }
 371 "Gestures to indicate that the mouse has crossed gadget boundaries:"
 372 { $subsections
 373     mouse-enter
 374     mouse-leave
 375 }
 376 "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."
 377 { $subsections
 378     hand-gadget
 379     hand-world
 380     hand-loc
 381     hand-buttons
 382     hand-clicked
 383     hand-click-loc
 384     hand-click#
 385 }
 386 "There are some utility words for working with click locations:"
 387 { $subsections
 388     hand-rel
 389     hand-click-rel
 390     drag-loc
 391 }
 392 "Mouse scroll wheel gesture:"
 393 { $subsections mouse-scroll }
 394 "Global variable set when a mouse scroll wheel gesture is sent:"
 395 { $subsections scroll-direction } ;
 396
 397 ARTICLE: "multitouch-gestures" "Multi-touch gestures"
 398 "Multi-touch gestures are only supported on Mac OS X with newer MacBook and MacBook Pro models."
 399 $nl
 400 "Three-finger swipe:"
 401 { $subsections
 402     left-action
 403     right-action
 404     up-action
 405     down-action
 406 }
 407 "Two-finger pinch:"
 408 { $subsections
 409     zoom-in-action
 410     zoom-out-action
 411 } ;
 412
 413 ARTICLE: "action-gestures" "Action gestures"
 414 "Action gestures exist to keep keyboard shortcuts for common application operations consistent."
 415 { $subsections
 416     undo-action
 417     redo-action
 418     cut-action
 419     copy-action
 420     paste-action
 421     delete-action
 422     select-all-action
 423     new-action
 424     open-action
 425     save-action
 426     save-as-action
 427     revert-action
 428     close-action
 429 }
 430 "The following keyboard gestures, if not handled directly, send action gestures:"
 431 { $table
 432     { { $strong "Keyboard gesture" } { $strong "Action gesture" } }
 433     { { $snippet "T{ key-down f { C+ } \"z\" }" } { $snippet "undo-action" } }
 434     { { $snippet "T{ key-down f { C+ } \"y\" }" } { $snippet "redo-action" } }
 435     { { $snippet "T{ key-down f { C+ } \"x\" }" } { $snippet "cut-action" } }
 436     { { $snippet "T{ key-down f { C+ } \"c\" }" } { $snippet "copy-action" } }
 437     { { $snippet "T{ key-down f { C+ } \"v\" }" } { $snippet "paste-action" } }
 438     { { $snippet "T{ key-down f { C+ } \"a\" }" } { $snippet "select-all-action" } }
 439     { { $snippet "T{ key-down f { C+ } \"n\" }" } { $snippet "new-action" } }
 440     { { $snippet "T{ key-down f { C+ } \"o\" }" } { $snippet "open-action" } }
 441     { { $snippet "T{ key-down f { C+ } \"s\" }" } { $snippet "save-action" } }
 442     { { $snippet "T{ key-down f { C+ } \"S\" }" } { $snippet "save-as-action" } }
 443     { { $snippet "T{ key-down f { C+ } \"w\" }" } { $snippet "close-action" } }
 444 }
 445 "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." ;
 446
 447 ABOUT: "ui-gestures"