# keyNames(2)

[Home] [Commands] [Variables] [Macro-Dev] [Glossary]

## KEY BINDING NAMES

Every key which can be generated in MicroEmacs 2009 has a character string or name representation which can be used to bind and unbind the key to a command. The name of simple keys like "`a`" or "`$`" is simply the character, i.e. "`a`" and "`$`". Following is a list of other parts to a key name.

## Modify Keys

There are 3 modifying keys, Shift, Control and Alt, these are represented as "`S-`", "`C-`", "`A-`" respectively. For example the key "`A-C-S-up`" is generated when the up cursor key is pressed when Shift, Control and Alt keys where also pressed.

The Control and Alt modifiers are case insensitive so `C-a` is the same as `C-A` and `C-S-a`.

## Prefix Keys

Many binding are single stroke key sequences (e.g. "`C-a`" => beginning-of-line). However MicroEmacs 2009 has a prefix(2) command which can be used to bind up to 8 single stroke keys, turning them into two stroke keys; this greatly increasing the number of available bindable key sequences. For example prefix 1 is bound to the escape character (`esc`), this allows key sequences like "`esc a`" to be used. Following is a list of prefixes and their default bindings

prefix 1 => `esc`
prefix 2 => `C-x`
prefix 3 => `C-h`
prefix 4 => `C-c`

## Special Keys

Following is a complete list of recognized keyboard key names, not all are able to be generated on every platform:-

`backspace`, `delete`, `down`, `end`, `esc`, `f1`, `f2`, `f3`, `f4`, `f5`, `f6`, `f7`, `f8`, `f9`, `f10`, `f11`, `f12`, `f13`, `f14`, `f15`, `f16`, `f17`, `f18`, `f19`, `f20`, `home`, `insert`, `kp-0`, `kp-1`, `kp-2`, `kp-3`, `kp-4`, `kp-5`, `kp-6`, `kp-7`, `kp-8`, `kp-9`, `kp-add`, `kp-begin`, `kp-decimal`, `kp-delete`, `kp-divide`, `kp-down`, `kp-end`, `kp-enter`, `kp-home`, `kp-insert`, `kp-left`, `kp-multiply`, `kp-page-down`, `kp-page-up`, `kp-right`, `kp-subtract`, `kp-up`, `left`, `page-down`, `page-up`, `return`, `right`, `space`, `tab`, `up`

The name of any key can be obtained by using describe-key(2).

## Mouse Keys

Following is a list of mouse related keys:-

mouse-pick-1, mouse-pick-2, mouse-pick-3, mouse-pick-4, mouse-pick-5

These keys are generated when the user presses a mouse button, these key events are always created. On most systems button 1 is the left, 2 the middle and 3 the right mouse button. If the system only has a 2 button mouse then a `mouse-pick-2` cannot be generated. The order of the buttons can be revered (i.e. 1 becomes right) and the number of buttons can be set using the $system(5) variable. Note that X-servers support up to 5 buttons and with the growing popularity of pilot 'wheel' mice, the 4th and 5th button are often used to report wheel spin up and down events. The translate-key(2) command can be used to translate these buttons to the mouse wheel keys.

mouse-drop-1, mouse-drop-2, mouse-drop-3, mouse-drop-4, mouse-drop-5

These keys are generated when the user release a mouse button, these key events are always created.

mouse-move-1, mouse-move-2, mouse-move-3, mouse-move-4, mouse-move-5, mouse-move

These key events are generated when the user moves the mouse and are only if they are bound to a command. The key generated depends on whether a button is being held down by the user, if the user is pressing button 1 then a `mouse-move-1` key is created etc.

mouse-time-1, mouse-time-2, mouse-time-3, mouse-time-5, mouse-time-5, mouse-time

These key events are generated only when they are bound to a command. They are pseudo keys created when the user hold the mouse buttons done for a period of time, see Pseudo Keys below for more information.

mouse-wheel-up, mouse-wheel-down

Pilot mouse wheel events, generated when the wheel is spun up or down respectively.

## Modifier Keys

The Shift, Control and Alt modifier keys will also generate key input whenever pressed or released. The keys are however only generated if they are bound to a command. The key names are as follows:

S-pick, S-drop

Shift modifier.

C-pick, C-drop

Control modifier.

A-pick, A-drop

Alt modifier.

Note that the keys are only generated when another key is pressed, i.e. if the user presses and holds only the shift key, no "`S-pick`" key will be generated until another key, such as `down`, is also pressed. If the shift key is released before another key is pressed the event will not be reported.

## Pseudo Keys

Pseudo keys events cannot be directly created by the user, they are created internally by MicroEmacs. They are treated like normal keys to allow the user to handle the events properly themselves. Following is a complete list of the system generated pseudo keys:-

bell

The pseudo key is generated when the bell is rung.

callback

The pseudo key when a create-callback(2) macro is executed, this allows the executed macro to know it was executed via a create-callback as @cck(4) will be set to this.

idle-pick, idle-drop, idle-time

The commands bound to these keys are executed when the system becomes idle for a period of time. See help on $idle-time(5) for more information.

mouse-time-1, mouse-time-2, mouse-time-3, mouse-time-4, mouse-time-5, mouse-time

The command bound to these keys are executed when mouse button 1, 2, 3, 4, 5 or a combination are held bound for a period of time. See help on $delay-time(5) for more information.

redraw

The command bound to this pseudo key is executed whenever the screen needs redrawing, by default it is bound to screen-update(2). If the user unbinds this key then screen-update is still called, but if the user binds it to a function which does not redraw the screen, such as void(2), then the screen will not be up-dated.

The command executed is always given an argument, a non-zero argument indicates a forced complete redraw, an argument of zero indicates that just an up-date is required.

## Alt Key

The Alt Key has special binding priorities defined as follows:-

- Direct key binding (e.g. A-b executes file-browser)
- Main menu hot key (e.g. A-f opens the File menu)
- Meta key binding (e.g. A-space -> esc space -> set-mark)

If the `ALT` key is to be used strictly as the Emacs Meta key then the bindings for the menu should be over-ridden by Direct Key Bindings from the user configuration file i.e. to re-map the default MicroEmacs Alt key to equivalent `esc` keys then the following keys should be re-bound.

    global-bind-key forward-word "A-f"      ; Over-ride File menu binding
    :                                       ; For all of the other menu items.
    :
    global-bind-key backward-word "A-b"     ; Over-ride the file browser.
    global-bind-key replace-string "A-r"    ; Over-ride tools binding.

This creates a higher priority binding which overrides the underlying default. The commands that are displaced would have to be re-bound to different keys if required.

## KEYBOARD MACROS

Keyboard macros do not store the name of keys, instead a more machine oriented format is used (usually in the form "`\s??`") these will work across platforms (assuming the key bindings are the same) but they may not work across different releases.

As a result it is advised that any long term macro should avoid named keys like `up` in favor of using a standard key binding such as `C-p`. See help on execute-string(2) for more information.

(c) Copyright JASSPA 2009
Last Modified: 2009/08/29
Generated On: 2009/10/12

</HMTL>