core/ui/gestures.facts

   1 IN: gadgets
   2 USING: help hashtables strings kernel ;
   3
   4 HELP: set-gestures
   5 { $values { "class" "a class word" } { "hash" hashtable } }
   6 { $description "Sets the gestures a gadget class responds to. The hashtable maps gestures to quotations with stack effect " { $snippet "( gadget -- )" } "." }
   7 { $notes "Only one of " { $link define-commands } " and " { $link set-gestures } " can be used on a given gadget class, since each word will overwrite the other word's definitions." } ;
   8
   9 HELP: handle-gesture*
  10 { $values { "gadget" "the receiver of the gesture" } { "gesture" "a gesture" } { "delegate" "an object" } { "?" "a boolean" } }
  11 { $contract "Handles a gesture sent to a gadget. As the delegation chain is traversed, this generic word is called with every delegate of the gadget at the top of the stack, however the front-most delegate remains fixed as the " { $snippet "gadget" } " parameter."
  12 $terpri
  13 "Outputs " { $link f } " if the gesture was handled, and " { $link t } " if the gesture should be passed on to the gadget's delegate." }
  14 { $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 } " or " { $link define-commands } "." } ;
  15
  16 HELP: handle-gesture
  17 { $values { "gesture" "a gesture" } { "gadget" gadget } { "?" "a boolean" } }
  18 { $description "Calls " { $link handle-gesture* } " on every delegate of " { $snippet "gadget" } ". Outputs " { $link f } " if some delegate handled the gesture, else outputs " { $link t } "." }
  19 { $see-also set-gestures define-commands } ;
  20
  21 HELP: send-gesture
  22 { $values { "gesture" "a gesture" } { "gadget" gadget } { "?" "a boolean" } }
  23 { $description "Calls " { $link send-gesture } " on every parent of " { $snippet "gadget" } ". Outputs " { $link f } " if some parent handled the gesture, else outputs " { $link t } "." }
  24 { $see-also set-gestures define-commands } ;
  25
  26 HELP: user-input
  27 { $values { "str" string } { "gadget" gadget } }
  28 { $description "Calls " { $link user-input* } " on every parent of the gadget." } ;
  29
  30 HELP: motion
  31 { $class-description "Mouse motion gesture." } ;
  32
  33 HELP: drag
  34 { $class-description "Mouse drag gesture. The " { $link drag-# } " slot is either set to a mouse button number, or " { $link f } " indicating no specific button is expected." } ;
  35
  36 HELP: button-up
  37 { $class-description "Mouse button up gesture. Instances have two slots:"
  38     { $list
  39         { { $link button-up-mods } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
  40         { { $link button-up-# } " - a mouse button number, or " { $link f } " indicating no specific button is expected" }
  41     }
  42 } ;
  43
  44 HELP: button-down
  45 { $class-description "Mouse button down gesture. Instances have two slots:"
  46     { $list
  47         { { $link button-down-mods } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
  48         { { $link button-down-# } " - a mouse button number, or " { $link f } " indicating no specific button is expected" }
  49     }
  50 } ;
  51
  52 HELP: mouse-scroll
  53 { $class-description "Scroll wheel motion gesture. When this gesture is sent, the " { $link scroll-direction } " global variable is set to a direction vector." } ;
  54
  55 HELP: mouse-enter
  56 { $class-description "Gesture sent when the mouse enters the bounds of a gadget." } ;
  57
  58 HELP: mouse-leave
  59 { $class-description "Gesture sent when the mouse leaves the bounds of a gadget." } ;
  60
  61 HELP: gain-focus
  62 { $class-description "Gesture sent when a gadget gains keyboard focus." } ;
  63
  64 HELP: lose-focus
  65 { $class-description "Gesture sent when a gadget loses keyboard focus." } ;
  66
  67 HELP: cut-action
  68 { $class-description "Gesture sent when the " { $emphasis "cut" } " standard window system action is invoked." } ;
  69
  70 HELP: copy-action
  71 { $class-description "Gesture sent when the " { $emphasis "copy" } " standard window system action is invoked." } ;
  72
  73 HELP: paste-action
  74 { $class-description "Gesture sent when the " { $emphasis "paste" } " standard window system action is invoked." } ;
  75
  76 HELP: delete-action
  77 { $class-description "Gesture sent when the " { $emphasis "delete" } " standard window system action is invoked." } ;
  78
  79 HELP: select-all-action
  80 { $class-description "Gesture sent when the " { $emphasis "select all" } " standard window system action is invoked." } ;
  81
  82 HELP: generalize-gesture
  83 { $values { "gesture" "a gesture" } { "newgesture" "a new gesture" } }
  84 { $description "Turns a " { $link button-down } ", " { $link button-up } " or " { $link drag } " action naming a specific mouse button into one which can apply regardless of which mouse button was pressed." } ;
  85
  86 HELP: C+
  87 { $description "Control key modifier." } ;
  88
  89 HELP: A+
  90 { $description "Alt key modifier." } ;
  91
  92 HELP: M+
  93 { $description "Meta key modifier. This is the Command key on Mac OS X." } ;
  94
  95 HELP: S+
  96 { $description "Shift key modifier." } ;
  97
  98 HELP: key-down
  99 { $class-description "Key down gesture. Instances have two slots:"
 100     { $list
 101         { { $link key-down-mods } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
 102     { { $link key-down-sym } " - a string denoting the key pressed; see " { $link "keyboard-gestures" } }
 103     }
 104 } ;
 105
 106 HELP: key-up
 107 { $class-description "Key up gesture. Instances have two slots:"
 108     { $list
 109         { { $link key-up-mods } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
 110     { { $link key-up-sym } " - a string denoting the key pressed; see " { $link "keyboard-gestures" } }
 111     }
 112 } ;
 113
 114 HELP: hand-gadget
 115 { $var-description "Global variable. The gadget at the mouse location." } ;
 116
 117 HELP: hand-world
 118 { $var-description "Global variable. The " { $link world } " containing the gadget at the mouse location." } ;
 119
 120 HELP: hand-loc
 121 { $var-description "Global variable. The mouse location relative to the top-left corner of the " { $link hand-world } "." }
 122 { $see-also hand-rel } ;
 123
 124 HELP: hand-clicked
 125 { $var-description "Global variable. The gadget at the location of the most recent click." } ;
 126
 127 HELP: hand-click-loc
 128 { $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 } "." }
 129 { $see-also hand-click-loc } ;
 130
 131 HELP: hand-click#
 132 { $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." } ;
 133
 134 HELP: hand-last-button
 135 { $var-description "Global variable. The mouse button most recently pressed." } ;
 136
 137 HELP: hand-last-time
 138 { $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 millis } "." } ;
 139
 140 HELP: hand-buttons
 141 { $var-description "Global variable. A vector of mouse buttons currently held down." } ;
 142
 143 HELP: scroll-direction
 144 { $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." } ;
 145
 146 HELP: double-click-timeout
 147 { $var-description "Global variable. The maximum delay between two button presses which will still increment " { $link hand-click# } "." } ;
 148
 149 HELP: button-gesture
 150 { $values { "gesture" "a gesture" } }
 151 { $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." } ;
 152
 153 HELP: fire-motion
 154 { $description "Sends a " { $link motion } " or " { $link drag } " gesture to the gadget under the mouse, depending on whenever a mouse button is being held down or not." } ;
 155
 156 HELP: forget-rollover
 157 { $description "Sends " { $link mouse-leave } " gestures to all gadgets containing the gadget under the mouse, and resets the " { $link hand-gadget } " variable." } ;
 158
 159 HELP: focus-receiver
 160 { $values { "world" world } { "seq" "a new sequence" } }
 161 { $description "If the top-level window containing the world has focus, outputs a sequence of parents of the currently focused gadget, otherwise outputs " { $link f } "." }
 162 { $notes "This word is used to avoid sending " { $link gain-focus } " gestures to a gadget which requests focus on an unfocused top-level window, so that, for instance, a text editing caret does not appear in this case." } ;
 163
 164 HELP: request-focus
 165 { $values { "gadget" gadget } }
 166 { $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." } ;
 167
 168 HELP: drag-loc
 169 { $values { "loc" "a pair of integers" } }
 170 { $description "Outputs the distance travelled by the mouse since the most recent press. Only meaningful inside a " { $link drag } " gesture handler." } ;
 171
 172 HELP: hand-rel
 173 { $values { "gadget" gadget } { "loc" "a pair of integers" } }
 174 { $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." }
 175 { $see-also hand-loc } ;
 176
 177 HELP: hand-click-rel
 178 { $values { "gadget" gadget } { "loc" "a pair of integers" } }
 179 { $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." } ;
 180
 181 HELP: under-hand
 182 { $values { "seq" "a new sequence" } }
 183 { $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." } ;