@chapter Keymaps
@cindex keymap
- The bindings between input events and commands are recorded in data
-structures called @dfn{keymaps}. Each binding in a keymap associates
-(or @dfn{binds}) an individual event type, either to another keymap or to
-a command. When an event type is bound to a keymap, that keymap is used
-to look up the next input event; this continues until a command is
-found. The whole process is called @dfn{key lookup}.
+ The command bindings of input events are recorded in data structures
+called @dfn{keymaps}. Each entry in a keymap associates (or
+@dfn{binds}) an individual event type, either to another keymap or to
+a command. When an event type is bound to a keymap, that keymap is
+used to look up the next input event; this continues until a command
+is found. The whole process is called @dfn{key lookup}.
@menu
* Key Sequences:: Key sequences as Lisp objects.
* Key Lookup:: Finding a key's binding in one keymap.
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings:: Redefining a key in a keymap.
-* Remapping Commands:: Bindings that translate one command to another.
+* Remapping Commands:: A keymap can translate one command to another.
* Translation Keymaps:: Keymaps for translating sequences of events.
* Key Binding Commands:: Interactive interfaces for redefining keys.
* Scanning Keymaps:: Looking through all keymaps, for printing help.
(kbd "<f1> SPC") @result{} [f1 32]
(kbd "C-M-<down>") @result{} [C-M-down]
@end example
+
+This macro is not meant for use with arguments that vary---only
+with string constants.
@end defmac
@node Keymap Basics
This specifies one binding, for events of type @var{type}. Each
ordinary binding applies to events of a particular @dfn{event type},
which is always a character or a symbol. @xref{Classifying Events}.
+In this kind of binding, @var{binding} is a command.
+
+@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding})
+This specifies a binding which is also a simple menu item that
+displays as @var{item-name} in the menu. @var{cache}, if present,
+caches certain information for display in the menu. @xref{Simple Menu
+Items}.
+
+@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding})
+This is a simple menu item with help string @var{help-string}.
+
+@item (@var{type} menu-item .@: @var{details})
+This specifies a binding which is also an extended menu item. This
+allows use of other features. @xref{Extended Menu Items}.
@item (t .@: @var{binding})
@cindex default key binding
@cindex keymap prompt string
@cindex overall prompt string
@cindex prompt string of keymap
-Aside from bindings, a keymap can also have a string as an element.
-This is called the @dfn{overall prompt string} and makes it possible to
-use the keymap as a menu. @xref{Defining Menus}.
+Aside from elements that specify bindings for keys, a keymap can also
+have a string as an element. This is called the @dfn{overall prompt
+string} and makes it possible to use the keymap as a menu.
+@xref{Defining Menus}.
@end table
When the binding is @code{nil}, it doesn't constitute a definition
@end group
@end example
-If you specify @var{prompt}, that becomes the overall prompt string for
-the keymap. The prompt string should be provided for menu keymaps
-(@pxref{Defining Menus}).
+If you specify @var{prompt}, that becomes the overall prompt string
+for the keymap. You should specify this only for menu keymaps
+(@pxref{Defining Menus}). A keymap with an overall prompt string will
+always present a mouse menu or a keyboard menu if it is active for
+looking up the next input event. Don't specify an overall prompt string
+for the main map of a major or minor mode, because that would cause
+the command loop to present a keyboard menu every time.
@end defun
@defun make-keymap &optional prompt
@dfn{parent keymap}. Such a keymap looks like this:
@example
-(keymap @var{bindings}@dots{} . @var{parent-keymap})
+(keymap @var{elements}@dots{} . @var{parent-keymap})
@end example
@noindent
The effect is that this keymap inherits all the bindings of
@var{parent-keymap}, whatever they may be at the time a key is looked up,
-but can add to them or override them with @var{bindings}.
+but can add to them or override them with @var{elements}.
-If you change the bindings in @var{parent-keymap} using @code{define-key}
-or other key-binding functions, these changes are visible in the
-inheriting keymap unless shadowed by @var{bindings}. The converse is
-not true: if you use @code{define-key} to change the inheriting keymap,
-that affects @var{bindings}, but has no effect on @var{parent-keymap}.
+If you change the bindings in @var{parent-keymap} using
+@code{define-key} or other key-binding functions, these changed
+bindings are visible in the inheriting keymap, unless shadowed by the
+bindings made by @var{elements}. The converse is not true: if you use
+@code{define-key} to change bindings in the inheriting keymap, these
+changes are recorded in @var{elements}, but have no effect on
+@var{parent-keymap}.
The proper way to construct a keymap with a parent is to use
@code{set-keymap-parent}; if you have code that directly constructs a
input key sequence in all these keymaps. @xref{Searching Keymaps},
for more details of this procedure.
-This process is somewhat modified for mouse events: the local modes and
-keymaps of the buffer corresponding to the mouse click position are
-searched instead, text properties are taken from the mouse click
-position in the buffer rather than point, and if the click happens on a
-string embedded with a @code{display}, @code{before-string}, or
-@code{after-string} text property (@pxref{Special Properties}) or
-overlay property (@pxref{Overlay Properties}), any non-@code{nil} maps
-specified with text properties of this string are searched instead of
-those of the buffer.
+ When the key sequence starts with a mouse event (optionally preceded
+by a symbolic prefix), the active keymaps are determined based on the
+position in that event. If the event happened on a string embedded
+with a @code{display}, @code{before-string}, or @code{after-string}
+property (@pxref{Special Properties}), the non-@code{nil} map
+properties of the string override those of the buffer.
The @dfn{global keymap} holds the bindings of keys that are defined
regardless of the current buffer, such as @kbd{C-f}. The variable
@end defun
@defun key-binding key &optional accept-defaults no-remap position
-This function returns the binding for @var{key} according to the current
-active keymaps. The result is @code{nil} if @var{key} is undefined in
-the keymaps. If @var{key} is a key sequence started with the mouse, the
-consulted maps will be changed accordingly.
+This function returns the binding for @var{key} according to the
+current active keymaps. The result is @code{nil} if @var{key} is
+undefined in the keymaps.
-@c Emacs 19 feature
The argument @var{accept-defaults} controls checking for default
bindings, as in @code{lookup-key} (above).
if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
remappings and returns the binding directly specified for @var{key}.
-If @var{position} is non-@code{nil}, it specifies either a buffer
-position or a position like those returned from @code{event-start}. In
-this case, @var{position} instead of @var{key} determines the
-click-specific maps.
+If @var{key} starts with a mouse event (perhaps following a prefix
+event), the maps to be consulted are determined based on the event's
+position. Otherwise, they are determined based on the value of point.
+However, you can override either of them by specifying @var{position}.
+If @var{position} is non-@code{nil}, it should be either a buffer
+position or an event position like the value of @code{event-start}.
+Then the maps consulted are determined based on @var{position}.
An error is signaled if @var{key} is not a string or a vector.
@end lisp
@noindent
-The @var{find-in} and @var{find-in-any} are pseudo functions that search
-in one keymap and in an alist of keymaps, respectively. (Searching a
-single keymap for a binding is called @dfn{key lookup}; see @ref{Key
-Lookup}.) Mouse events on strings will use text properties from the
-string if non-@code{nil} instead of the buffer. Also, point and current
-buffer for mouse-based events are switched to correspond to the position
-of the event start while performing the lookup.
+The @var{find-in} and @var{find-in-any} are pseudo functions that
+search in one keymap and in an alist of keymaps, respectively.
+(Searching a single keymap for a binding is called @dfn{key lookup};
+see @ref{Key Lookup}.) If the key sequence starts with a mouse event,
+or a symbolic prefix event followed by a mouse event, that event's
+position is used instead of point and the current buffer. Mouse
+events on an embedded string use non-@code{nil} text properties from
+that string instead of the buffer.
@enumerate
@item
Let's use the term @dfn{keymap entry} to describe the value found by
looking up an event type in a keymap. (This doesn't include the item
-string and other extra elements in menu key bindings, because
+string and other extra elements in a keymap element for a menu item, because
@code{lookup-key} and other key lookup functions don't include them in
-the returned value.) While any Lisp object may be stored in a keymap as
-a keymap entry, not all make sense for key lookup. Here is a table of
-the meaningful kinds of keymap entries:
+the returned value.) While any Lisp object may be stored in a keymap
+as a keymap entry, not all make sense for key lookup. Here is a table
+of the meaningful types of keymap entries:
@table @asis
@item @code{nil}
@item @var{list}
@cindex list in keymap
-The meaning of a list depends on the types of the elements of the list.
+The meaning of a list depends on what it contains:
@itemize @bullet
@item
remap it to @code{my-other-kill-line}.
@defun command-remapping command &optional position
-This function returns the remapping for @var{command} (a symbol), given
-the current active keymaps. If @var{command} is not remapped (which is
-the usual situation), or not a symbol, the function returns @code{nil}.
-@code{position} can optionally specify a buffer position or a position
-like those returned from @code{event-start}: in that case, the active
-maps are changed like they are in @code{key-binding}.
+This function returns the remapping for @var{command} (a symbol),
+given the current active keymaps. If @var{command} is not remapped
+(which is the usual situation), or not a symbol, the function returns
+@code{nil}. @code{position} can optionally specify a buffer position
+or an event position to determine the keymaps to use, as in
+@code{key-binding}.
@end defun
@node Translation Keymaps
@section Menu Keymaps
@cindex menu keymaps
-@c Emacs 19 feature
-A keymap can define a menu as well as bindings for keyboard keys and
-mouse button. Menus are usually actuated with the mouse, but they can
-work with the keyboard also.
+A keymap can operate as a menu as well as defining bindings for
+keyboard keys and mouse buttons. Menus are usually actuated with the
+mouse, but they can function with the keyboard also. If a menu keymap
+is active for the next input event, that activates the keyboard menu
+feature.
@menu
* Defining Menus:: How to make a keymap that defines a menu.
* Mouse Menus:: How users actuate the menu with the mouse.
-* Keyboard Menus:: How they actuate it with the keyboard.
+* Keyboard Menus:: How users actuate the menu with the keyboard.
* Menu Example:: Making a simple menu.
* Menu Bar:: How to customize the menu bar.
* Tool Bar:: A tool bar is a row of images.
@cindex menu prompt string
@cindex prompt string (of menu)
-A keymap is suitable for menu use if it has an @dfn{overall prompt
-string}, which is a string that appears as an element of the keymap.
+A keymap acts as a menu if it has an @dfn{overall prompt string},
+which is a string that appears as an element of the keymap.
(@xref{Format of Keymaps}.) The string should describe the purpose of
the menu's commands. Emacs displays the overall prompt string as the
menu title in some cases, depending on the toolkit (if any) used for
displaying menus.@footnote{It is required for menus which do not use a
-toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the overall
-prompt string.
+toolkit, e.g.@: under MS-DOS.} Keyboard menus also display the
+overall prompt string.
-The easiest way to construct a keymap with a prompt string is to specify
-the string as an argument when you call @code{make-keymap},
+The easiest way to construct a keymap with a prompt string is to
+specify the string as an argument when you call @code{make-keymap},
@code{make-sparse-keymap} (@pxref{Creating Keymaps}), or
-@code{define-prefix-command} (@pxref{Definition of define-prefix-command}).
-
+@code{define-prefix-command} (@pxref{Definition of
+define-prefix-command}). If you do not want the keymap to operate as
+a menu, don't specify a prompt string for it.
@defun keymap-prompt keymap
This function returns the overall prompt string of @var{keymap},
or @code{nil} if it has none.
@end defun
+The menu's items are the bindings in the keymap. Each binding
+associates an event type to a definition, but the event types have no
+significance for the menu appearance. (Usually we use pseudo-events,
+symbols that the keyboard cannot generate, as the event types for menu
+item bindings.) The menu is generated entirely from the bindings that
+correspond in the keymap to these events.
+
The order of items in the menu is the same as the order of bindings in
the keymap. Since @code{define-key} puts new bindings at the front, you
should define the menu items starting at the bottom of the menu and
@node Simple Menu Items
@subsubsection Simple Menu Items
- The simpler and older way to define a menu keymap binding
-looks like this:
+ The simpler (and original) way to define a menu item is to bind some
+event type (it doesn't matter what event type) to a binding like this:
@example
(@var{item-string} . @var{real-binding})
encoded using the @code{utf-8} coding system and then rendered by the
toolkit as it sees fit.}
-You can also supply a second string, called the help string, as follows:
+ You can also supply a second string, called the help string, as follows:
@example
(@var{item-string} @var{help} . @var{real-binding})
@end example
+@noindent
@var{help} specifies a ``help-echo'' string to display while the mouse
is on that item in the same way as @code{help-echo} text properties
(@pxref{Help display}).
-As far as @code{define-key} is concerned, @var{item-string} and
+ As far as @code{define-key} is concerned, @var{item-string} and
@var{help-string} are part of the event's binding. However,
@code{lookup-key} returns just @var{real-binding}, and only
@var{real-binding} is used for executing the key.
-If @var{real-binding} is @code{nil}, then @var{item-string} appears in
+ If @var{real-binding} is @code{nil}, then @var{item-string} appears in
the menu but cannot be selected.
-If @var{real-binding} is a symbol and has a non-@code{nil}
+ If @var{real-binding} is a symbol and has a non-@code{nil}
@code{menu-enable} property, that property is an expression that
controls whether the menu item is enabled. Every time the keymap is
used to display a menu, Emacs evaluates the expression, and it enables
menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
cannot be selected.
-The menu bar does not recalculate which items are enabled every time you
+ The menu bar does not recalculate which items are enabled every time you
look at a menu. This is because the X toolkit requires the whole tree
of menus in advance. To force recalculation of the menu bar, call
@code{force-mode-line-update} (@pxref{Mode Line Format}).
-You've probably noticed that menu items show the equivalent keyboard key
+ You've probably noticed that menu items show the equivalent keyboard key
sequence (if any) to invoke the same command. To save time on
recalculation, menu display caches this information in a sublist in the
binding, like this:
@kindex menu-item
An extended-format menu item is a more flexible and also cleaner
-alternative to the simple format. It consists of a list that starts
-with the symbol @code{menu-item}. To define a non-selectable string,
-the item looks like this:
+alternative to the simple format. You define an event type with a
+binding that's a list starting with the symbol @code{menu-item}.
+For a non-selectable string, the binding looks like this:
@example
(menu-item @var{item-name})
see @ref{Menu Separators}.
To define a real menu item which can be selected, the extended format
-item looks like this:
+binding looks like this:
@example
(menu-item @var{item-name} @var{real-binding}
@node Keyboard Menus
@subsection Menus and the Keyboard
-When a prefix key ending with a keyboard event (a character or function
-key) has a definition that is a menu keymap, the user can use the
-keyboard to choose a menu item.
+ When a prefix key ending with a keyboard event (a character or
+function key) has a definition that is a menu keymap, the keymap
+operates as a keyboard menu; the user specifies the next event by
+choosing a menu item with the keyboard.
-Emacs displays the menu's overall prompt string followed by the
-alternatives (the item strings of the bindings) in the echo area. If
-the bindings don't all fit at once, the user can type @key{SPC} to see
-the next line of alternatives. Successive uses of @key{SPC} eventually
-get to the end of the menu and then cycle around to the beginning. (The
-variable @code{menu-prompt-more-char} specifies which character is used
-for this; @key{SPC} is the default.)
+ Emacs displays the keyboard menu with the map's overall prompt
+string, followed by the alternatives (the item strings of the map's
+bindings), in the echo area. If the bindings don't all fit at once,
+the user can type @key{SPC} to see the next line of alternatives.
+Successive uses of @key{SPC} eventually get to the end of the menu and
+then cycle around to the beginning. (The variable
+@code{menu-prompt-more-char} specifies which character is used for
+this; @key{SPC} is the default.)
-When the user has found the desired alternative from the menu, he or she
-should type the corresponding character---the one whose binding is that
-alternative.
+ When the user has found the desired alternative from the menu, he or
+she should type the corresponding character---the one whose binding is
+that alternative.
@ignore
In a menu intended for keyboard use, each menu item must clearly
key for each alternative.
@end ignore
-This way of using menus in an Emacs-like editor was inspired by the
+ This way of using menus in an Emacs-like editor was inspired by the
Hierarkey system.
@defvar menu-prompt-more-char