map-function in keymap%

Maps an input state to the name of an event handler.

• (send a-keymap map-function keyname fname) -> void
     keyname : string
     fname : string

  Maps an input state sequence to a function name using a string-encoded sequence in keyname. The format of keyname is a sequence of semicolon-delimited input states; each state is made up of a sequence of modifier identifiers followed by a key identifier.

  The modifier identifiers are:

  • ``s:'' -- All platforms: Shift

  • ``c:'' -- All platforms: Control

  • ``a:'' -- Mac OS X: Option

  • ``m:'' -- Windows: Alt; X: Meta

  • ``d:'' -- Mac OS X: Command

  • ``?:'' -- All platforms: allow match to character produced by opposite use of Shift, 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 tilde (~) preceding a modifier makes the string match only states where the corresponding modifier is not pressed. If the state string begins with a colon, then the string matches a state only if modifiers 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"

  • "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 inclued under Windows without "m:", or when "d:" is included under Mac OS X, then ASCII letters are not upcased with "s:", since the normal behavior of the Shift key is cancelled by Control without Alt under Windows and Command under 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 ranks below all matches that do not depend on ``?:''. 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.

  • ":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 Exceptions and Continuation Jumps).

  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.