How To Setup Keymapping In gschem

Stefan Petersen, spe@geda.seul.org
This document is released under GPL (http://www.fsf.org/copyleft/gpl.html)

1999-07-24

About this document

The purpose of this document is to try to explain how key mapping works in gEDA/gschem schematic entry program. It uses the langauge Scheme a lot, which is a Lisp-dialect and is used in gschem as a scripting language. If you're not familiar with this language, please see the dictionary (see appendix A, page X, for a short description of common data structures used in Scheme.

1 Functionality

When you press a button in gschem, a Scheme function is called. This function (press-key) accepts one argument, the name of the pressed key. Then there are Scheme routines to evaluate which key you pressed and call the appropriate action.

Since the evaluation routines are written in Scheme it's simple to change the behaviour of what happens when you presses a key. You can implement macros or do several things at each key press. For example, the ``repeat-last-key´´ command is implemented completly in Scheme.

2 Keymaps

The current implementation is built-up around ``keymaps''. A keymap is a list with pairs. Each pairs first element (the car-element) is which key to react on, and the second element (cdr) is a ``what-to-do-next''. This can either be an action, a function to call or another keymap.

2.1 An example on keymaps

Two simple examples of keymaps is seen in figure 1 and figure 2.

(define global-keymap
  '(("Escape" . cancel)
    ("a" . add-keymap)))
Figure 1: First example of an simple keymap

In figure 1 is the keymap called global-keymap. This keymap is the first keymap used. If you for example press the 'a'-key, global-keymap tells us that next key pressed will be interpreted by add-keymap (see figure 2).

(define add-keymap
  '(("c" . add-component)
    ("a" . add-attribute)
    ("n" . add-net-hotkey)))
Figure 2: Second example of an simple keymap

If you, after you pressed 'a', press a 'c' the built-in action add-component comes to live. This is exactly what had happend if you had selected Add, Component...in the menubar.

When an action has been performed the current keymap is reset back to
global-keymap.

Available built-in actions are listed in appendix B.

2.2 Description of keys

The key are described as:

For a	--	``a''
For Shift-A	--	``Shift A''
For Control-a	--	``Control a''
For Alt-a	--	``Alt a''

There are a few simple rules to follow when keys for a new keymap is defined:

Everything is case sensitive
At this point in time you can only have one modifier (shift, control, alt) at a time.
Keys must be unique in each keymap, especially the global one
Strings (without any modifers) are the same strings specified for the keys in the file /usr/lib/X11/XKeysymDB (at least on a linux box)

2.3 Actions

The built-in actions that can be called are listed in appendix B.

Sometimes you may notice that there are similar actions, like edit-rotate-90 and edit-rotate-90-hotkey. They do the same thing, just that the -hotkey actions is run immediately, while the other wait for you to select something.

2.4 Function calls

If the cdr-element is an ordinary Scheme function that function is called. The function can't receive any arguments.

This can be used if you want to do complex tasks, like several actions in a row or do some calculation. You can do rather advanced actions since the Guile dialect of Scheme used in gschem is extended from plain Scheme. For further information on Guile, please see the Guile documentation.

2.5 Another keymap

If the cdr-element is another keymap then that command is a multi-key command, ie you need to press at least two keys to cause an action. The first key is desribed in the first keymap, which points to the next keymap. The second keymap describes what should happen when the second key is pressed.

3 Where are the key mappings stored

The keymap is stored in the startup file for gschem, namely
<startpath, typically /usr/local>/share/gEDA/system-gschemrc.

You can then redefine or add keymaps as you like (I think) in your local setup file for gschem,
~/.gEDA/gschemrc

The Scheme functions used to resolve keypresses to actions are stored at
<startpath, typically /usr/local>/share/gEDA/scheme/gschem.scm.
This is configurable in the gschemrc files.

A Dictionary

function	A subprogram in Scheme, C or other programming languages.
action	What gschem (in this case) does when you press a key or a set of keys.
list	A data structure very common in Lisp-looking languages like Scheme. Simply put, a long list of values.
pair	(also dotted pair) A datstructure also very common in Lisp-looking languages.
car element	First element in a pair. Since lists are decendents from pairs, `car` is also the first element in a list.
cdr element	(pronounced cudr) The second element in a pair. In the list case it denotes the rest of list.

B Built-in actions in gschem

Run

grep gh_register_procedure_0_0 gschem/src/g_register.c

and do some work in emacsen.

file-new-window

file-new

file-open

file-script

file-save

file-save-as

file-save-all

file-print

file-image

file-close-window

file-quit

edit-select

edit-copy

edit-copy-hotkey

edit-move

edit-move-hotkey

edit-delete

edit-rotate-90

edit-rotate-90-hotkey

edit-mirror

edit-mirror-hotkey

edit-slot

edit-color

edit-edit

edit-lock

edit-unlock

edit-translate

edit-embed

edit-unembed

edit-hidden

view-redraw

view-zoom-full

view-zoom-limits

view-zoom-in

view-zoom-out

view-zoom-box

view-zoom-box-hotkey

view-pan

view-pan-hotkey

view-update-nets

page-manager

page-next

page-prev

page-new

page-close

page-discard

page-print

add-component

add-attribute

add-net

add-net-hotkey

add-text

add-line

add-line-hotkey

add-box

add-box-hotkey

add-circle

add-circle-hotkey

add-arc

add-arc-hotkey

add-pin

add-pin-hotkey

hierarchy-open-symbol

attributes-attach

attributes-detach

attributes-show-name

attributes-show-value

attributes-show-both

attributes-visibility-toggle

options-text-size

options-snap-size

options-action-feedback

options-grid

options-snap

options-show-log-window

options-show-coord-window

misc-misc

cancel

This document was translated from L^AT_EX by H^EV^EA.