• a mapping from function names to event-handling procedures; and

• a mapping from key and mouse sequences to function names.

A handler procedure in a keymap is invoked with a key-event% object or a mouse-event% object. It is also given another value that depends on the context in which the keymap is used (or, more specifically, the arguments to handle-key-event or handle-mouse-event). For keymaps associated with editor<%> objects, the extra parameter is generally the editor<%> object that received the keyboard or mouse event.

If there was already a function mapped to this name, it will be replaced with the given function.

When the function is called, it gets the arguments that were passed to handle-key-event, handle-mouse-event, or call-function. For keymaps associated with an editor, this is normally the target editor.

This method doesn’t check chained keymaps to see if the function has been added to one of those.

A break callback function can be installed with set-break-sequence-callback.

The in and event arguments are passed on to the keymap handler procedure if one is found.

If try-chain? is not #f, keymaps chained to this one are searched for the function name. If the function is not found and try-chain? is #f; an exception is also raised, but the exception handler cannot escape (see Continuations and Event Dispatch).

Multiple keymaps can be chained off one keymap using chain-to-keymap. When keymaps are chained off a main keymap, events not handled by the main keymap are passed to the chained keymaps until some chained keymap handles the events. Keymaps can be chained together in an arbitrary acyclic graph.

Keymap chaining is useful because multiple-event sequences are handled correctly for chained groups. Without chaining, a sequence of events can produce state in a keymap that must be reset when a callback is invoked in one of the keymaps. This state can be manually cleared with break-sequence, though calling the break-sequence method also invokes the handler installed by set-break-sequence-callback.

The default interval is determined in a platform-specific way, but it can be overridden globally though the 'GRacket:doubleClickTime preference; see Preferences.

See also call-function.

See also call-function.

The modifier identifiers are:

• s: — All platforms: Shift

• c: — All platforms: Control

• a: — Mac OS X: Option

• m: — Windows: Alt; Unix: Meta; Mac OS X: Command, when map-command-as-meta-key produces #t

• d: — Mac OS X: Command

• l: — All platforms: Caps Lock

• g: — Windows: Control plus Alt as AltGr; see control+meta-is-altgr in key-event%

• ?: — All platforms: allow match to character produced by opposite use of Shift, AltGr/Option, and/or Caps Lock, when available; see get-other-shift-key-code in key-event%

If a particular modifier is not mentioned in a state string, it matches states whether that modifier is pressed or not pressed. A ~ preceding a modifier makes the string match only states where the corresponding modifier is not pressed. If the state string begins with :, then the string matches a state only if modifiers among Shift, Control, Option, Alt, Meta, and Command that are not mentioned in the string are not pressed.

A key identifier can be either a character on the keyboard (e.g., a, 2, ?) or a special name. The special names are as follows:

• leftbutton (button down)

• rightbutton

• middlebutton

• leftbuttondouble (button down for double-click)

• rightbuttondouble

• middlebuttondouble

• leftbuttontriple (button down for triple-click)

• rightbuttontriple

• middlebuttontriple

• leftbuttonseq (all events from button down through button up)

• rightbuttonseq

• middlebuttonseq

• wheelup

• wheeldown

• wheelleft

• wheelright

• esc

• delete

• del (same as delete)

• insert

• ins (same as insert)

• add

• subtract

• multiply

• divide

• backspace

• back

• return

• enter (same as return)

• tab

• space

• right

• left

• up

• down

• home

• end

• pageup

• pagedown

• semicolon (since ; separates sequence steps)

• colon (since : separates modifiers)

• numpad0

• numpad1

• numpad2

• numpad3

• numpad4

• numpad5

• numpad6

• numpad7

• numpad8

• numpad9

• numpadenter

• f1

• f2

• f3

• f4

• f5

• f6

• f7

• f8

• f9

• f10

• f11

• f12

• f13

• f14

• f15

• f16

• f17

• f18

• f19

• f20

• f21

• f22

• f23

• f24

For a special keyword, the capitalization does not matter. However, capitalization is important for single-letter keynames. Furthermore, single-letter ASCII keynames are treated specially: A and s:a are both treated as s:A. However, when c: is included on Windows without m:, or when d: is included on Mac OS X, then ASCII letters are not upcased with s:, since the upcasing behavior of the Shift key is cancelled by Control without Alt (on Windows) or by Command (on Mac OS X).

A state can match multiple state strings mapped in a keymap (or keymap chain); when a state matches multiple state strings, a mapping is selected by ranking the strings according to specificity. A state string that mentions more pressed modifiers ranks higher than other state strings, and if two strings mention the same number of pressed modifiers, the one that mentions more unpressed modifiers ranks higher. Finally, a state string that includes ?: and matches only with the opposite use of Shift, AltGr/Option, and/or Caps Lock ranks below all matches that do not depend on ?:, and one that requires the opposite use of both Shift and AltGr/Option ranks even lower. In the case that multiple matching strings have the same rank, a match is selected arbitrarily.

Examples:

• "space" — matches whenever the space bar is pressed, regardless of the state of modifiers keys.

• "~c:space" — matches whenever the space bar is pressed and the Control key is not pressed.

• "a" — matches whenever a is typed, regardless of the state of modifiers keys (other than Shift).

• ":a" — matches only when a is typed with no modifier keys pressed.

• "~c:a" — matches whenever a is typed and neither the Shift key nor the Control key is pressed.

• "c:m:~g:x" — matches whenever x is typed with Control and Alt (Windows) or Meta (Unix) is pressed, as long as the Control-Alt combination is not formed by AltGr on Windows.

• ":esc;:c:c" — matches an Escape key press (no modifiers) followed by a Control-C press (no modifiers other than Control).

• "?:d:+" — matches when Command is pressed with key that produces +, even if producing + normally requires pressing Shift.

A call to map-function that would map a particular key sequence both as a prefix and as a complete sequence raises an exception, but the exception handler cannot escape (see Continuations and Event Dispatch).

A function name does not have to be mapped to a handler before input states are mapped to the name; the handler is dispatched by name at the time of invocation. The event handler mapped to a function name can be changed without affecting the map from input states to function names.

Changed in version 1.2 of package gui-lib: Added g: and ~g: support.

If a grab callback returns a true value for a matching or non-matching callback, the event is considered handled. If the callback returns a true value for a matching callback, then the matching keymap function is not called by the keymap.

The callback procedure f will be invoked as:

(f str keymap editor event)

The str argument is the name of a function for a matching callback, or #f for a non-matching callback. The keymap argument is the keymap that matched (possibly a keymap chained to the one in which the callback was installed) or the keymap in which the callback was installed. The editor and event arguments are the same as passed on to the matching keymap function.

Key grab callback functions are de-installed with remove-grab-key-function.