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’.