map-function

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:'' -- X: Alt; MacOS: Option
  • ``m:'' -- Windows: Alt; X: Meta; MacOS: Command
  • ``d:'' -- MacOS: 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"
  • "rightbutton"
  • "middlebutton"
  • "leftbuttondouble"
  • "rightbuttondouble"
  • "middlebuttondouble"
  • "leftbuttontriple"
  • "rightbuttontriple"
  • "middlebuttontriple"
  • "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.