IN: gadgets
USING: help hashtables strings kernel ;

HELP: set-gestures
{ $values { "class" "a class word" } { "hash" hashtable } }
{ $description "Sets the gestures a gadget class responds to. The hashtable maps gestures to quotations with stack effect " { $snippet "( gadget -- )" } "." }
{ $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." } ;

HELP: handle-gesture*
{ $values { "gadget" "the receiver of the gesture" } { "gesture" "a gesture" } { "delegate" "an object" } { "?" "a boolean" } }
{ $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."
$terpri
"Outputs " { $link f } " if the gesture was handled, and " { $link t } " if the gesture should be passed on to the gadget's delegate." }
{ $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 } "." } ;

HELP: handle-gesture
{ $values { "gesture" "a gesture" } { "gadget" gadget } { "?" "a boolean" } }
{ $description "Calls " { $link handle-gesture* } " on every delegate of " { $snippet "gadget" } ". Outputs " { $link f } " if some delegate handled the gesture, else outputs " { $link t } "." }
{ $see-also set-gestures define-commands } ;

HELP: send-gesture
{ $values { "gesture" "a gesture" } { "gadget" gadget } { "?" "a boolean" } }
{ $description "Calls " { $link send-gesture } " on every parent of " { $snippet "gadget" } ". Outputs " { $link f } " if some parent handled the gesture, else outputs " { $link t } "." }
{ $see-also set-gestures define-commands } ;

HELP: user-input
{ $values { "str" string } { "gadget" gadget } }
{ $description "Calls " { $link user-input* } " on every parent of the gadget." } ;

HELP: motion
{ $class-description "Mouse motion gesture." } ;

HELP: drag
{ $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." } ;

HELP: button-up
{ $class-description "Mouse button up gesture. Instances have two slots:"
    { $list
        { { $link button-up-mods } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
        { { $link button-up-# } " - a mouse button number, or " { $link f } " indicating no specific button is expected" }
    }
} ;

HELP: button-down
{ $class-description "Mouse button down gesture. Instances have two slots:"
    { $list
        { { $link button-down-mods } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
        { { $link button-down-# } " - a mouse button number, or " { $link f } " indicating no specific button is expected" }
    }
} ;

HELP: mouse-scroll
{ $class-description "Scroll wheel motion gesture. When this gesture is sent, the " { $link scroll-direction } " global variable is set to a direction vector." } ;

HELP: mouse-enter
{ $class-description "Gesture sent when the mouse enters the bounds of a gadget." } ;

HELP: mouse-leave
{ $class-description "Gesture sent when the mouse leaves the bounds of a gadget." } ;

HELP: gain-focus
{ $class-description "Gesture sent when a gadget gains keyboard focus." } ;

HELP: lose-focus
{ $class-description "Gesture sent when a gadget loses keyboard focus." } ;

HELP: cut-action
{ $class-description "Gesture sent when the " { $emphasis "cut" } " standard window system action is invoked." } ;

HELP: copy-action
{ $class-description "Gesture sent when the " { $emphasis "copy" } " standard window system action is invoked." } ;

HELP: paste-action
{ $class-description "Gesture sent when the " { $emphasis "paste" } " standard window system action is invoked." } ;

HELP: delete-action
{ $class-description "Gesture sent when the " { $emphasis "delete" } " standard window system action is invoked." } ;

HELP: select-all-action
{ $class-description "Gesture sent when the " { $emphasis "select all" } " standard window system action is invoked." } ;

HELP: generalize-gesture
{ $values { "gesture" "a gesture" } { "newgesture" "a new gesture" } }
{ $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." } ;

HELP: C+
{ $description "Control key modifier." } ;

HELP: A+
{ $description "Alt key modifier." } ;

HELP: M+
{ $description "Meta key modifier. This is the Command key on Mac OS X." } ;

HELP: S+
{ $description "Shift key modifier." } ;

HELP: key-down
{ $class-description "Key down gesture. Instances have two slots:"
    { $list
        { { $link key-down-mods } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
    { { $link key-down-sym } " - a string denoting the key pressed; see " { $link "keyboard-gestures" } }
    }
} ;

HELP: key-up
{ $class-description "Key up gesture. Instances have two slots:"
    { $list
        { { $link key-up-mods } " - a sequence of modifiers; see " { $link "keyboard-gestures" } }
    { { $link key-up-sym } " - a string denoting the key pressed; see " { $link "keyboard-gestures" } }
    }
} ;

HELP: hand-gadget
{ $var-description "Global variable. The gadget at the mouse location." } ;

HELP: hand-world
{ $var-description "Global variable. The " { $link world } " containing the gadget at the mouse location." } ;

HELP: hand-loc
{ $var-description "Global variable. The mouse location relative to the top-left corner of the " { $link hand-world } "." } 
{ $see-also hand-rel } ;

HELP: hand-clicked
{ $var-description "Global variable. The gadget at the location of the most recent click." } ;

HELP: hand-click-loc
{ $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 } "." } 
{ $see-also hand-click-loc } ;

HELP: hand-click#
{ $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." } ;

HELP: hand-last-button
{ $var-description "Global variable. The mouse button most recently pressed." } ;

HELP: hand-last-time
{ $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 } "." } ;

HELP: hand-buttons
{ $var-description "Global variable. A vector of mouse buttons currently held down." } ;

HELP: scroll-direction
{ $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." } ;

HELP: double-click-timeout
{ $var-description "Global variable. The maximum delay between two button presses which will still increment " { $link hand-click# } "." } ;

HELP: button-gesture
{ $values { "gesture" "a gesture" } }
{ $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." } ;

HELP: fire-motion
{ $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." } ;

HELP: forget-rollover
{ $description "Sends " { $link mouse-leave } " gestures to all gadgets containing the gadget under the mouse, and resets the " { $link hand-gadget } " variable." } ;

HELP: focus-receiver
{ $values { "world" world } { "seq" "a new sequence" } }
{ $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 } "." }
{ $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." } ;

HELP: request-focus
{ $values { "gadget" gadget } }
{ $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." } ;

HELP: drag-loc
{ $values { "loc" "a pair of integers" } }
{ $description "Outputs the distance travelled by the mouse since the most recent press. Only meaningful inside a " { $link drag } " gesture handler." } ;

HELP: hand-rel
{ $values { "gadget" gadget } { "loc" "a pair of integers" } }
{ $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." }
{ $see-also hand-loc } ;

HELP: hand-click-rel
{ $values { "gadget" gadget } { "loc" "a pair of integers" } }
{ $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." } ;

HELP: under-hand
{ $values { "seq" "a new sequence" } }
{ $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." } ;