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: Option

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

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

  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 only matches a state 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:

  • "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"

  • "colon"

  • "numpad1"

  • "numpad2"

  • "numpad3"

  • "numpad4"

  • "numpad5"

  • "numpad6"

  • "numpad7"

  • "numpad8"

  • "numpad9"

  • "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 (e.g., "A" is interpreted as "s:a").

  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 has a higher rank than other state strings, and if two strings mention the same number of pressed modifiers, the one that metions more unpressed modifiers has a higher rank. In that case that multiple matching strings have the same rank, one string 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).

  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.