Chapter 15 Extended Stream Input Facilities

15.3 Gestures and Gesture Names

A gesture name is a symbol that gives a name to a set of similar gestures. Gesture names are used in order to provide a level of abstraction above raw device events; greater portability can be achieved by avoiding referring directly to platform-dependent constructs, such as character objects that refer to a particular key on the keyboard. For example, the :complete gesture is used to name the gesture that causes the complete-input complete the current input string; on Genera, this may correspond to theCOMPLETE key on the keyboard (which generates a#\Complete character), but on a Unix workstation, it may correspond toTAB or some other key. Another example is :select, which is commonly used to indicate a left button click on the pointer.

Note that gesture names participate in a one-to-many mapping, that is, a single gesture name can name a group of physical gestures. For example, an :edit might include both a pointer button click and a key press.

CLIM uses event objects to represent user gestures. Some of the more common events are those of the class pointer-button-event. Event objects store the sheet associated with the event, a timestamp, and the modifier key state (a quantity that indicates which modifier keys were held down on the keyboard at the time the event occurred). Pointer button event objects also store the pointer object, the button that was clicked on the pointer, the window the pointer was over, and the x and y position within that window. Keyboard gestures store the key name.

In some contexts, the object used to represent a user gesture is referred to as an gesture object. An gesture object might be exactly the same as an event object, or might contain less information. For example, for a keyboard gesture that corresponds to a standard printing character, it may be enough to represent the gesture object as a character.

define-gesture-name [Macro]

Arguments:

name type gesture-spec&key (unique t)

Summary:

Defines a new gesture named by the symbol name. It expands into a call to add-gesture-name.

type is the type of gesture being created, and is either :keyboard or :pointer-button. gesture-spec specifies the physical gesture that corresponds to the named gesture; its syntax depends on the value of type.

• When type is :keyboard, gesture-spec is a list of the form (key-name . modifier-key-names). key-name is the name of a non-modifier key on the keyboard. modifier-key-names is a (possibly empty) list of modifier key names (:shift, :control, :meta, :super, and :hyper).

  For the standard Common Lisp characters (the 95 ASCII printing characters including#\Space), key-name is the character object itself. For the other "semi-standard" characters, key-name is a keyword symbol naming the character (:newline, :linefeed, :return, :tab, :backspace, :page, and :rubout).

  The names of the modifier keys have been chosen to be uniform across all platforms, even though not all platforms will have keys on the keyboard with these names. The per-port part of CLIM simply chooses a sensible mapping from the modifier key names to the names of the keys on the keyboard. For example, CLIM on the Macintosh maps :meta to theCOMMANDSHIFT key, and :super to theOPTIONSHIFT key.

• When type is :pointer-button, gesture-spec is a list of the form (button-name . modifier-key-names). button is the name of a pointer button (:left, :middle, or :right), and modifier-key-names is as for when type is :keyboard.

If unique is t (the default), all old gestures named by name are removed.

None of the arguments to define-gesture-name are evaluated.

Arguments:

name type gesture-spec&key unique

Summary:

Adds a gesture named by the symbol name to the set of gesture names. type and gesture-spec are as for define-gesture-name.

If unique is t, all old gestures named by name are removed. unique defaults to nil.

As an example, the :edit gesture name could be defined as follows using define-gesture-name:

        (define-gesture-name :edit :pointer-button (:left :meta))
        (define-gesture-name :edit :keyboard (#\E :control)) 

Arguments:

name

Summary:

Removes the gesture named by the symbol name.

• :abort--corresponds to gestures that cause the currently running application to be aborted back to top-level. In LispWorks CLIM, this may match the event corresponding to typingCONTROL-Z. In Liquid CLIM, this may match the event corresponding to typingCONTROL-C.

• :clear-input--corresponds to gestures that cause the current input buffer to be cleared. In LispWorks CLIM, this may match the event corresponding to typingCONTROL-BACKSPACE. In Liquid CLIM, this may match the event corresponding to typingCONTROL-U.

• :complete--corresponds to the gestures that tell the completion facility to complete the current input. On most systems, this will typically match the#\Tab or#\Escape character.

• :help--corresponds to the gestures that tell accept and the completion facility to display a help message. On most systems, this will typically match the event corresponding to typingCONTROL-/.

• :possibilities--corresponds to the gestures that tell the completion facility to display the current set of possible completions. On most systems, this will typically match the event corresponding to typingCONTROL-?.

• :select--corresponds to the gesture that is used to "select" the object being pointed to with the pointer. Typically, this will correspond to the left button on the pointer.

• :describe--corresponds to the gesture that is used to "describe" or display some sort of documentation on the object being pointed to with the pointer. Typically, this will correspond to the middle button on the pointer.

• :menu--corresponds to the gesture that is used to display a menu of all possible operations on the object being pointed to with the pointer. Typically, this will correspond to the right button on the pointer.

• :edit--corresponds to the gesture that is used to "edit" the object being pointed to with the pointer. Typically, this will correspond to the left button on the pointer with some modifier key held down (such as theMETA key).

• :delete--corresponds to the gesture that is used to "delete" the object being pointed to with the pointer. Typically, this will correspond to the middle button on the pointer with some modifier key held down (such as theSHIFT key).

Generated with Harlequin WebMaker