8.11 Event binding parameters

8.11.1 Event Patterns

An event pattern may take one of two forms. In the simplest case it is a single printing ASCII character, such as a or [. The character may not be a space character or the character <. This form of pattern matches a KeyPress event for the particular character. The second form of pattern is longer but more general. It is a virtual string of the form:

"<modifier-modifier-type-detail>"

The entire event pattern is surrounded by angle brackets. Inside the angle brackets are zero or more modifiers, an event type, and an extra piece of information (detail) identifying a particular button or keysym. Any of the fields may be omitted, as long as at least one of type and detail is present. The fields must be separated by white space or dashes.

MODIFIERS

Modifiers consist of any of the following values:

Event Modifier

Control

Mod2, M2

Shift

Mod3, M3

Lock

Mod4, M4

Button1, B1

Mod5, M5

Button2, B2

Meta, M

Button3, B3

Alt

Button4, B4

Double

Button5, B5

Triple

Mod1, M1

Quadruple

Where more than one value is listed, separated by commas, the values are equivalent. Most of the modifiers have the obvious X meanings. For example, Button1 requires that button 1 be depressed when the event occurs. For a binding to match a given event, the modifiers in the event must include all of those specified in the event pattern. An event may also contain additional modifiers not specified in the binding. For example, if button 1 is pressed while the shift and control keys are down, the pattern <Control-Button-1> will match the event, but <Mod1-Button-1> will not. If no modifiers are specified, then any combination of modifiers may be present in the event.

Meta and M refer to whichever of the M1 through M5 modifiers is associated with the meta key(s) on the keyboard (keysyms Meta_R and Meta_L). If there are no meta keys, or if they are not associated with any modifiers, then Meta and M will not match any events. Similarly, the Alt modifier refers to whichever modifier is associated with the alt key(s) on the keyboard (keysyms Alt_L and Alt_R).

The Double, Triple and Quadruple modifiers are a convenience for specifying double mouse clicks and other repeated events. They cause a particular event pattern to be repeated 2, 3 or 4 times, and also place a time and space requirement on the sequence: for a sequence of events to match a Double, Triple or Quadruple pattern, all of the events must occur close together in time and without substantial mouse motion in between. For example, <Double-Button-1> is equivalent to <Button-1><Button-1> with the extra time and space requirement.

EVENT TYPES

The type field may be any of the standard X event types, with a few extra abbreviations. The type field will also accept a couple non-standard X event types that were added to better support the Macintosh and Windows platforms. Below is a list of all the valid types; where two names appear together, they are synonyms.

Event Type

Active

Enter

Map

ButtonPress, Button

Expose

Motion

ButtonRelease

FocusIn

MouseWheel

Circulate

FocusOut

Property

Colormap

Gravity

Reparent

Configure

KeyPress, Key

Unmap

Deactivate

KeyRelease

Visibility

Destroy

Leave

Most of the above events have the same fields and behaviors as events in the X Windowing system. You can find more detailed descriptions of these events in any X window programming book. A couple of the events are extensions to the X event system to support features unique to the Macintosh and Windows platforms. We provide a little more detail on these events here. These include:

The last part of a long event specification is detail. In the case of a ButtonPress or ButtonRelease event, it is the number of a button (1-5). If a button number is given, then only an event on that particular button will match; if no button number is given, then an event on any button will match. Note: giving a specific button number is different than specifying a button modifier; in the first case, it refers to a button being pressed or released, while in the second it refers to some other button that is already depressed when the matching event occurs. If a button number is given then type may be omitted: if will default to ButtonPress. For example, the specifier <1> is equivalent to <ButtonPress-1>.

If the event type is KeyPress or KeyRelease, then detail may be specified in the form of an X keysym. Keysyms are textual specifications for particular keys on the keyboard; they include all the alphanumeric ASCII characters (e.g. "a" is the keysym for the ASCII character a), plus descriptions for non-alphanumeric characters ("comma" is the keysym for the comma character), plus descriptions for all the non-ASCII keys on the keyboard ("Shift_L" is the keysm for the left shift key, and "F1" is the keysym for the F1 function key, if it exists). The complete list of keysyms is not presented here; it is available in other X documentation and may vary from system to system. If necessary, you can use the "K" notation described below to print out the keysym name for a particular key. If a keysym detail is given, then the type field may be omitted; it will default to "KeyPress". For example, <Control-comma> is equivalent to <Control-KeyPress-comma>.

8.11.2 Event Arguments

The args option of the bind method takes a list of argument specifications. An argument specification describes the type of the argument and the argument itself. Figure 8.1 shows the valid types. Actual types used are the trivial mapping from the specified type. When the event is raised, all specified arguments are appended to the action to execute in the order they appear in the list. Below is a list of all the valid arguments; where two names appear together, they are synonyms.


Argument Type

string(A), A

atom(A)

int(A)

float(A)

list(string(A)), list(A)

list(atom(A))

list(int(A))

list(float(A))

Figure 8.1: Event arguments.


Argument codes

For more information please consult bind.


Donatien Grolaux
Version 1.3.0 (20040413)