Commit 08244b81 authored by Chong Yidong's avatar Chong Yidong
Browse files

* keymaps.texi (Key Sequences): Renamed from Keymap Terminology.

	Explain string and vector representations of key sequences

	* keymaps.texi (Changing Key Bindings):
	* commands.texi (Interactive Codes, Interactive Codes):
	* help.texi (Describing Characters): Refer to it.
parent 60f7e8b6
2006-05-25 Chong Yidong <cyd@stupidchicken.com>
* keymaps.texi (Key Sequences): Renamed from Keymap Terminology.
Explain string and vector representations of key sequences
* keymaps.texi (Changing Key Bindings):
* commands.texi (Interactive Codes, Interactive Codes):
* help.texi (Describing Characters): Refer to it.
2006-05-23 Luc Teirlinck <teirllm@auburn.edu> 2006-05-23 Luc Teirlinck <teirllm@auburn.edu>
* frames.texi (Pointer Shape): @end table -> @end defvar. * frames.texi (Pointer Shape): @end table -> @end defvar.
......
...@@ -362,7 +362,7 @@ An irrelevant argument. This code always supplies @code{nil} as ...@@ -362,7 +362,7 @@ An irrelevant argument. This code always supplies @code{nil} as
the argument's value. No I/O. the argument's value. No I/O.
@item k @item k
A key sequence (@pxref{Keymap Terminology}). This keeps reading events A key sequence (@pxref{Key Sequences}). This keeps reading events
until a command (or undefined command) is found in the current key until a command (or undefined command) is found in the current key
maps. The key sequence argument is represented as a string or vector. maps. The key sequence argument is represented as a string or vector.
The cursor does not move into the echo area. Prompt. The cursor does not move into the echo area. Prompt.
......
...@@ -497,7 +497,7 @@ can also be used as a rough inverse for @code{key-description}. You ...@@ -497,7 +497,7 @@ can also be used as a rough inverse for @code{key-description}. You
call it with a string containing key descriptions, separated by spaces; call it with a string containing key descriptions, separated by spaces;
it returns a string or vector containing the corresponding events. it returns a string or vector containing the corresponding events.
(This may or may not be a single valid key sequence, depending on what (This may or may not be a single valid key sequence, depending on what
events you use; @pxref{Keymap Terminology}.) If @var{need-vector} is events you use; @pxref{Key Sequences}.) If @var{need-vector} is
non-@code{nil}, the return value is always a vector. non-@code{nil}, the return value is always a vector.
@end defun @end defun
......
...@@ -16,7 +16,7 @@ to look up the next input event; this continues until a command is ...@@ -16,7 +16,7 @@ to look up the next input event; this continues until a command is
found. The whole process is called @dfn{key lookup}. found. The whole process is called @dfn{key lookup}.
@menu @menu
* Keymap Terminology:: Definitions of terms pertaining to keymaps. * Key Sequences:: What a key sequence looks like as a Lisp object.
* Format of Keymaps:: What a keymap looks like as a Lisp object. * Format of Keymaps:: What a keymap looks like as a Lisp object.
* Creating Keymaps:: Functions to create and copy keymaps. * Creating Keymaps:: Functions to create and copy keymaps.
* Inheritance and Keymaps:: How one keymap can inherit the bindings * Inheritance and Keymaps:: How one keymap can inherit the bindings
...@@ -37,32 +37,26 @@ found. The whole process is called @dfn{key lookup}. ...@@ -37,32 +37,26 @@ found. The whole process is called @dfn{key lookup}.
* Menu Keymaps:: Defining a menu as a keymap. * Menu Keymaps:: Defining a menu as a keymap.
@end menu @end menu
@node Keymap Terminology @node Key Sequences
@section Keymap Terminology @section Key Sequences
@cindex key @cindex key
@cindex keystroke @cindex keystroke
@cindex key binding @cindex key binding
@cindex binding of a key @cindex binding of a key
@cindex complete key @cindex complete key
@cindex undefined key @cindex undefined key
@cindex key sequence
A @dfn{keymap} is a table mapping event types to definitions (which A keymap determines a binding or definition for a set of @dfn{key
can be any Lisp objects, though only certain types are meaningful for sequences}, or @dfn{keys} for short. A key sequence is a sequence of
execution by the command loop). Given an event (or an event type) and a one or more input events that form a unit.
keymap, Emacs can get the event's definition. Events include
characters, function keys, and mouse actions (@pxref{Input Events}).
A sequence of input events that form a unit is called a
@dfn{key sequence}, or @dfn{key} for short. A sequence of one event
is always a key sequence, and so are some multi-event sequences.
A keymap determines a binding or definition for any key sequence. If If a keymap binds a key sequence consisting of a single event, its
the key sequence is a single event, its binding is the definition of the binding is the definition of that event. The binding of a key
event in the keymap. The binding of a key sequence of more than one sequence of more than one event is found by an iterative process: the
event is found by an iterative process: the binding of the first event binding of the first event is found, and must be a keymap; then the
is found, and must be a keymap; then the second event's binding is found second event's binding is found in that keymap, and so on until all
in that keymap, and so on until all the events in the key sequence are the events in the key sequence are used up.
used up.
If the binding of a key sequence is a keymap, we call the key sequence If the binding of a key sequence is a keymap, we call the key sequence
a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because a @dfn{prefix key}. Otherwise, we call it a @dfn{complete key} (because
...@@ -99,8 +93,28 @@ keymaps shadow both local and global keymaps. @xref{Active Keymaps}, ...@@ -99,8 +93,28 @@ keymaps shadow both local and global keymaps. @xref{Active Keymaps},
for details. for details.
The Emacs Lisp representation for a key sequence is a string or vector. The Emacs Lisp representation for a key sequence is a string or vector.
You can enter key sequence constants using the ordinary string or vector
representation; it is also convenient to use @code{kbd}: In the string representation, alphanumeric characters ordinarily
stand for themselves; for example, @code{"a"} represents @key{a} and
and @code{"1"} represents @key{1}. Control character events are
prefixed by the substring @code{"\C-"}, and meta characters by
@code{"\M-"}; for example, @code{"\C-x"} represents the key @kbd{C-x}.
In addition, the @kbd{<TAB>}, @kbd{<RET>}, @kbd{<ESC>}, and
@kbd{<DEL>} events are represented by @code{"\t"}, @code{"\r"},
@code{"\e"}, and @code{"\d"} respectively. The string representation
of a complete key sequence is then obtained by concatenating the
string representations of each constituent event; thus, @code{"\C-x"}
represents the key sequence @kbd{C-x}.
Key sequences containing function keys, mouse button events, or
non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
represented as strings; they have to be represented as vectors.
In the vector representation, each element of the vector represents
a consecutive input element, in its Lisp form. @xref{Input Events}.
For example, ordinary keyboard events are represented by Lisp
characters (@pxref{Keyboard Events}), so the character @code{?a}
represents @key{a}.
@defmac kbd keyseq-text @defmac kbd keyseq-text
This macro converts the text @var{keyseq-text} (a string constant) This macro converts the text @var{keyseq-text} (a string constant)
...@@ -129,7 +143,13 @@ Macro,,, emacs, The GNU Emacs Manual}). ...@@ -129,7 +143,13 @@ Macro,,, emacs, The GNU Emacs Manual}).
@cindex full keymap @cindex full keymap
@cindex sparse keymap @cindex sparse keymap
A keymap is a list whose @sc{car} is the symbol @code{keymap}. The A @dfn{keymap} is a table mapping event types to definitions (which
can be any Lisp objects, though only certain types are meaningful for
execution by the command loop). Given an event (or an event type) and a
keymap, Emacs can get the event's definition. Events include
characters, function keys, and mouse actions (@pxref{Input Events}).
Each keymap is a list whose @sc{car} is the symbol @code{keymap}. The
remaining elements of the list define the key bindings of the keymap. remaining elements of the list define the key bindings of the keymap.
A symbol whose function definition is a keymap is also a keymap. Use A symbol whose function definition is a keymap is also a keymap. Use
the function @code{keymapp} (see below) to test whether an object is a the function @code{keymapp} (see below) to test whether an object is a
...@@ -1197,8 +1217,8 @@ numeric codes for the modifier bits don't appear in compiled files. ...@@ -1197,8 +1217,8 @@ numeric codes for the modifier bits don't appear in compiled files.
For the functions below, an error is signaled if @var{keymap} is not For the functions below, an error is signaled if @var{keymap} is not
a keymap or if @var{key} is not a string or vector representing a key a keymap or if @var{key} is not a string or vector representing a key
sequence. You can use event types (symbols) as shorthand for events sequence. You can use event types (symbols) as shorthand for events
that are lists. The @code{kbd} macro (@pxref{Keymap Terminology}) is that are lists. The @code{kbd} macro (@pxref{Key Sequences}) is a
a convenient way to specify the key sequence. convenient way to specify the key sequence.
@defun define-key keymap key binding @defun define-key keymap key binding
This function sets the binding for @var{key} in @var{keymap}. (If This function sets the binding for @var{key} in @var{keymap}. (If
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment