15.3 Gestures and Gesture Names

A
gesture
is some sort of input action by the user, such as typing a character or clicking a pointer button. A
keyboard gesture
refers to those gestures that are input by typing something on the keyboard. A
pointer gesture
refers to those gestures that are input by doing something with the pointer, such as clicking a button.

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 the
COMPLETE
key on the keyboard (which generates a
#\Complete
character), but on a Unix workstation, it may correspond to
TAB
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 the
COMMAND
SHIFT
key, and
:super
to the
OPTION
SHIFT
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.

add-gesture-name [Function]

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))

delete-gesture-name [Function]

Arguments: name

Summary: Removes the gesture named by the symbol
name
.

CLIM provides a standard set of gesture names that correspond to a common set of gestures. Here are the required, standard keyboard gesture names:

: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 typing
CONTROL-Z
.

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

: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 typing
CONTROL-/
.

: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 typing
CONTROL-?
.

Here are the required, standard pointer gesture names:

: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 the
META
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 the
SHIFT
key).