### 3.2 Key mapping ¶

To use the functions described in this section, you will need to load the `(schematic keymap)` module.

#### 3.2.1 Key combinations ¶

lepton-schematic treats key combinations as first-class objects. A key combination consists of a non-modifier key press with some number of modifiers applied. For example, the key combination `Ctrl+Shift+A` (which calls Edit→Deselect by default) is typed by holding the `Ctrl` and `Shift` keys down, and then pressing `A`.

Function: key? obj ¶

  Returns ‘`#t`’ if and only if obj is a key combination.

Function: string->key str ¶

  Parses str to create a new key combination. The expected format looks like ‘`<Control>a`’ or ‘`<Shift><Alt>F1`’. Key names are parsed using `gdk_keyval_from_name()`, and modifiers may appear in any order. If str has invalid syntax or does not represent a valid key combination, raises a ‘`key-format`’ error.

Function: key->string key ¶

  Converts key to a string, using a format suitable for passing to `string->key`.

Function: key->display-string key ¶

  Converts key to a string, using a format suitable for display. This should be used when the key combination needs to be displayed to the user e.g. in the lepton-schematic menus or status area. The returned string is translated according to the user’s current locale.

      (key->display-string (string->key ``<Control>bracketright''))
      => ``Ctrl+]''

#### 3.2.2 Key sequences ¶

Most lepton-schematic functionality is bound not to single key combinations but to sequences of them. For example, File→New is bound to `F N` by default (i.e. press `F` followed by `N`). Key sequences are simply vectors of key bindings. For example:

    (string->keys ``F N'')
    => #(#<schematic-key "F"> #<schematic-key "N">)

In this case, `F` is a prefix key, because pressing it does not cause an action to be carried out directly, but just changes the effect of pressing subsequent keys.

Function: keys? obj ¶

  Returns ‘`#t`’ if and only if obj is a valid key sequence.

Function: string->keys str ¶

  Parses str into a key sequence. The expected format is a sequence of key combination specifications (as could be passed to `string->key`) separated by spaces.

Function: keys->string keys ¶

  Converts the key sequence keys to a string, using a format suitable for passing to `string->keys`.

Function: keys->display-string keys ¶

  Converts the key sequence keys to a string, using a format suitable for display.

#### 3.2.3 Keymaps ¶

A keymap maps key combinations to values (usually actions) or to other keymaps. See Actions.

Function: keymap? obj ¶

  Returns ‘`#t`’ if and only if obj is a keymap.

Function: make-keymap ¶

  Creates and returns a new, empty keymap.

Function: keymap-bind-key! keymap key [bindable] ¶

  Binds key to bindable in keymap. If bindable is ‘`#f`’ or not specified, removes the binding for key. bindable should be a thunk or a keymap.

Function: keymap-lookup-key keymap key ¶

  Looks up the binding for key in keymap. If key is not bound, returns ‘`#f`’.

Function: keymap-lookup-binding keymap bindable ¶

  Carries out a reverse lookup in keymap to find the key bound to bindable. If bindable is not bound in keymap, returns ‘`#f`’.

Function: keymap-for-each proc keymap ¶

  Applies proc to each binding in keymap. proc should take two arguments: the bound key, and its binding.

Actions are bound to key sequences by binding the first key combination to a keymap, then in the resulting keymap binding the second key combination, etc. This results in a directed graph of keymaps.

For example, to bind the key sequence `F N`, a keymap is created containing a binding for `N` to the desired action, and then in the main keymap the prefix key `F` is bound to the new keymap.

Three helper functions are provided for working with key sequence bindings.

Function: bind-keys! keymap keys [bindable] ¶

  Bind keys to bindable. Keys may be a key sequence vector, a single key combination, or a string representing a key sequence or key combination. If bindable is ‘`#f`’ or not specified, removes the binding for keys. bindable should be a thunk or a keymap.

  If keys contains invalid prefix keys (e.g. because one of the prefix keys is already bound to something other than a keymap), raises an error. Missing prefix keymaps are created as required.

Function: lookup-keys keymap keys ¶

  Looks up the binding for keys in keymap. keys is interpreted the same as for `bind-keys!`. If keys is not bound, returns ‘`#f`’.

Function: lookup-binding keymap bindable ¶

  Recursively searches keymap for the key sequence bound to bindable, which should be a thunk or a keymap. If bindable is not bound, returns ‘`#f`’.