Next: , Previous: Windows and views, Up: gschem API Reference


3.2 Key mapping

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

3.2.1 Key combinations

gschem 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 gschem 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 gschem 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'')
     => #(#<gschem-key "F"> #<gschem-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 actions or other keymaps.

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