# global-bind-key(2)

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

## NAME

global-bind-key - Bind a key to a named command or macro
global-unbind-key - "Unbind a key from a named command or macro"

## SYNOPSIS

n global-bind-key "command" "key" (esc k)
n global-unbind-key "key" (esc C-k)

## DESCRIPTION

global-bind-key takes one of the named commands and binds it to a key. Thereafter, whenever that key is struck, the bound command is executed. If an argument n is given then the bound command is executed n times when the key is struck. (i.e. the command is passed the numeric argument 'n').

global-unbind-key unbinds (detaches) a user entered key sequence (i.e. `C-x C-f`) from any command to which it may be bound. This does not work with buffer or message line key bindings, see buffer-unbind-key(2) and ml-unbind-key(2). If an argument of 0 is given to global-unbind-key, only a single key is obtained for the user, if the character is currently bound to the prefix command, the prefix binding and any sub-bindings are removed. global-bind-key calls global-unbind-key first if the key to be bound is already bound to something else.

If a negative argument is given to global-unbind-key then all bindings are removed, caution - removing all bindings interactively will render the current MicroEmacs session unusable. This can only be used within macro development where new bindings are created immediately afterwards.

The global-bind-key command, currently bound to `esc k`, prompts the user for the named command and the key to which it is to be bound. This help file gives a complete list of all built in commands, and some useful macros, a complete list of all commands and macros can be obtained by using the command completion (type `esc x` `tab` `tab`, see ml-bind-key(2)) or using the command describe-bindings(2).

The mouse buttons are considered to be keys, there is a key for each button press and release event, use describe-key(2) to get the binding key string.

The non-ASCII standard keys such as the cursor keys have 'standard' key names to make cross platform binding support easy. Some systems such as termcap do not have fixed key-bindings, for these key the users must use the command translate-key(2) to convert the system key binding to the standard key binding.

Permanent changes are done indirectly through the `me.emf` file. This is a file that MicroEmacs 2009 reads and executes (see execute-file(2)) during startup and hence results in the appearance of a permanent change in the key bindings. The syntax of commands in the `me.emf` file is described under the execute-file command. Of principal concern here are the two commands global-bind-key and global-unbind-key. The primary difference between the way parameters are passed to these commands in the `me.emf` file is that the keys are not typed in directly (as in the control-I key when you want `C-i`) but by symbolic names. Every key has a unique name which can be easily obtained with the current binding by using the command describe-key(2).

See help on Key Names for a description of the symbolic naming system and a complete list of valid key names. Also see Bindings for a complete list of default key bindings.

## EXAMPLE

Alt P

    global-bind-key "func" "A-p"

Control F2

    global-bind-key "func" "C-f3"

Shift Alt Left Cursor

    global-bind-key "func" "A-S-left"

Control Alt Delete

    global-bind-key "func" "C-A-delete"

Note that binding Control-Alt-Delete is not recommended for MS-DOS systems for obvious reasons.

## NOTES

Some ASCII keys, such as `<CR>` (C-m), `<tab>` (C-i), `<BACKSPACE>` (C-h) have non-ASCII key bindings, namely "return", "tab", "backspace" etc. this is to allow separate key-bindings for the real "C-m" etc.

Be very careful in binding and unbinding keys since you could get into some very peculiar situations such as being unable to abort out of a command (if you unbind CTRL-G or bind it to something else) or recover from the bad binding/unbinding if you unbind execute-named-command(2) or the global-unbind-key command. As long as you leave yourself the opportunity to do both of the last two commands, you can recover from disastrous bindings/unbindings.

## SEE ALSO

buffer-bind-key(2), buffer-unbind-key(2), describe-bindings(2), describe-key(2), ml-bind-key(2), ml-unbind-key(2), translate-key(2).

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

</HMTL>