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