Historically, Emacs has supported a number of different syntaxes for
defining keys. The documented way to bind a key today is to use the
syntax supported by key-valid-p, which is what all the
functions like keymap-set and keymap-lookup supports.
This section documents the old-style syntax and interface functions;
they should not be used in new code.
define-key (and other low-level functions that are used to
rebind keys) understand a number of different syntaxes for the keys.
You can use a list containing modifier names plus one base event (a
character or function key name). For example, [(control ?a)
(meta b)] is equivalent to C-a M-b and [(hyper control
left)] is equivalent to C-H-left.
Internally, key sequences are often represented as strings using the
special escape sequences for shift, control and meta modifiers
(see String Type), but this representation can also be used by
users when rebinding keys. A string like "\M-x" is read as
containing a single M-x, "\C-f" is read as containing a
single C-f, and "\M-\C-x" and "\C-\M-x" are both
read as containing a single C-M-x.
This is the other internal representation of key sequences. It supports a fuller range of modifiers than the string representation, and also support function keys. An example is ‘[?\C-\H-x home]’, which represents the C-H-x home key sequence. See Character Type.
This function is like keymap-set (see Changing Key Bindings, but understands only the legacy key syntaxes.
In addition, this function also has a remove argument. If it is
non-nil, the definition will be removed. This is almost the
same as setting the definition to nil, but makes a difference
if the keymap has a parent, and key is shadowing the same
binding in the parent. With remove, subsequent lookups will
return the binding in the parent, whereas with a nil definition the
lookups will return nil.
Here are other legacy key definition functions and commands, with the equivalent modern function to use instead in new code.
This function sets the binding of key in the current global map
to binding. Use keymap-global-set instead.
This function removes the binding of key from the current
global map. Use keymap-global-unset instead.
This function sets the binding of key in the current local
keymap to binding. Use keymap-local-set instead.
This function removes the binding of key from the current
local map. Use keymap-local-unset instead.
This function replaces olddef with newdef for any keys in
keymap that were bound to olddef. In other words,
olddef is replaced with newdef wherever it appears. The
function returns nil. Use keymap-substitute instead.
Define a binding in map for key, with value binding,
just like define-key, but position the binding in map after
the binding for the event after. The argument key should be
of length one—a vector or string with just one element. But
after should be a single event type—a symbol or a character, not
a sequence. The new binding goes after the binding for after. If
after is t or is omitted, then the new binding goes last, at
the end of the keymap. However, new bindings are added before any
inherited keymap. Use keymap-set-after instead of this function.
This function modifies keyboard-translate-table to translate
character code from into character code to. It creates
the keyboard translate table if necessary. Use key-translate
instead.
This function returns the binding for key according to the
current active keymaps. The result is nil if key is
undefined in the keymaps. The argument accept-defaults controls
checking for default bindings, as in lookup-key
(see Functions for Key Lookup). If no-remap is
non-nil, key-binding ignores command remappings
(see Remapping Commands) and returns the binding directly
specified for key. The optional argument position should
be either a buffer position or an event position like the value of
event-start; it tells the function to consult the maps
determined based on that position.
Emacs signals an error if key is not a string or a vector.
Use keymap-lookup instead of this function.
This function returns the definition of key in keymap. If the string or vector key is not a valid key sequence according to the prefix keys specified in keymap, it must be too long and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of key that compose a complete key.
If accept-defaults is non-nil, then lookup-key
considers default bindings as well as bindings for the specific events
in key. Otherwise, lookup-key reports only bindings for
the specific sequence key, ignoring default bindings except when
you explicitly ask about them.
Use keymap-lookup instead of this function.
This function returns the binding for key in the current
local keymap, or nil if it is undefined there.
The argument accept-defaults controls checking for default bindings,
as in lookup-key (above).
This function returns the binding for command key in the
current global keymap, or nil if it is undefined there.
The argument accept-defaults controls checking for default bindings,
as in lookup-key (above).
This function converts a list of modifier names and a basic event type to an event type which specifies all of them. The basic event type must be the last element of the list. For example,
(event-convert-list '(control ?a))
⇒ 1
(event-convert-list '(control meta ?a))
⇒ -134217727
(event-convert-list '(control super f1))
⇒ C-s-f1