@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2002, 2003,
-@c 2004, 2005, 2006 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2000, 2001,
+@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/keymaps
@node Keymaps, Modes, Command Loop, Top
@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.
a key sequence as an argument can handle both representations.
In the string representation, alphanumeric characters ordinarily
-stand for themselves; for example, @code{"a"} represents @kbd{a} and
+stand for themselves; for example, @code{"a"} represents @kbd{a}
and @code{"2"} represents @kbd{2}. 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}.
(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
(24 . lisp-send-defun)
keymap
;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp)))
+ (17 . indent-sexp))
@end group
@group
;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
@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.
+ 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
@code{global-map} holds this keymap, which is always active.
@xref{Standard Keymaps}, for a list of standard keymaps.
-@defun current-active-maps &optional olp
+@defun current-active-maps &optional olp position
This returns the list of active keymaps that would be used by the
command loop in the current circumstances to look up a key sequence.
Normally it ignores @code{overriding-local-map} and
-@code{overriding-terminal-local-map}, but if @var{olp} is
-non-@code{nil} then it pays attention to them.
+@code{overriding-terminal-local-map}, but if @var{olp} is non-@code{nil}
+then it pays attention to them. @var{position} can optionally be either
+an event position as returned by @code{event-start} or a buffer
+position, and may change the keymaps as described for
+@code{key-binding}.
@end defun
-@defun key-binding key &optional accept-defaults no-remap
+@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.
-@c Emacs 19 feature
The argument @var{accept-defaults} controls checking for default
-bindings, as in @code{lookup-key} (above).
-
-When @var{key} is a vector containing an input event, such as a mouse
-click, @code{key-binding} first looks for the binding in the keymaps
-that would be active at the position where the click was done.
+bindings, as in @code{lookup-key} (@pxref{Functions for Key Lookup}).
When commands are remapped (@pxref{Remapping Commands}),
@code{key-binding} normally processes command remappings so as to
if @var{no-remap} is non-@code{nil}, @code{key-binding} ignores
remappings and returns the binding directly specified for @var{key}.
+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.
@example
@node Searching Keymaps
@section Searching the Active Keymaps
+@cindex searching active keymaps for keys
After translation of event subsequences (@pxref{Translation
Keymaps}) Emacs looks for them in the active keymaps. Here is a
(@var{find-in} overriding-terminal-local-map)
(if overriding-local-map
(@var{find-in} overriding-local-map)
- (or (@var{find-in} (get-text-property (point) 'keymap))
+ (or (@var{find-in} (get-char-property (point) 'keymap))
(@var{find-in-any} emulation-mode-map-alists)
(@var{find-in-any} minor-mode-overriding-map-alist)
(@var{find-in-any} minor-mode-map-alist)
(if (get-text-property (point) 'local-map)
- (@var{find-in} (get-text-property (point) 'local-map))
+ (@var{find-in} (get-char-property (point) 'local-map))
(@var{find-in} (current-local-map))))))
(@var{find-in} (current-global-map)))
@end lisp
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}.)
+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
does matter for menu keymaps (@pxref{Menu Keymaps}).
@end defun
- Here is an example that creates a sparse keymap and makes a number of
+ This example creates a sparse keymap and makes a number of
bindings in it:
@smallexample
if an ordinary binding specifies @code{my-kill-line}, this keymap will
remap it to @code{my-other-kill-line}.
-@defun command-remapping command
+@defun command-remapping command &optional position keymaps
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{nil}. @code{position} can optionally specify a buffer position
+or an event position to determine the keymaps to use, as in
+@code{key-binding}.
+
+If the optional argument @code{keymaps} is non-@code{nil}, it
+specifies a list of keymaps to search in. This argument is ignored if
+@code{position} is non-@code{nil}.
@end defun
@node Translation Keymaps
@section Keymaps for Translating Sequences of Events
+@cindex keymaps for translating events
This section describes keymaps that are used during reading a key
sequence, to translate certain event sequences into others.
@smallexample
@group
(where-is-internal 'describe-function)
- @result{} ("\^hf" "\^hd")
+ @result{} ([8 102] [f1 102] [help 102]
+ [menu-bar help-menu describe describe-function])
@end group
@end smallexample
@end defun
@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}
string. Thus, the string need not be a constant. The third element,
@var{real-binding}, is the command to execute. The tail of the list,
@var{item-property-list}, has the form of a property list which contains
-other information. Here is a table of the properties that are supported:
+other information.
+
+ When an equivalent keyboard key binding is cached, the extended menu
+item binding looks like this:
+
+@example
+(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
+ . @var{item-property-list})
+@end example
+
+ Here is a table of the properties that are supported:
@table @code
@item :enable @var{form}
safely be called at any time.
@end table
- When an equivalent key binding is cached, the binding looks like this.
-
-@example
-(menu-item @var{item-name} @var{real-binding} (@var{key-binding-data})
- . @var{item-property-list})
-@end example
-
@node Menu Separators
@subsubsection Menu Separators
@cindex menu separators
@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
@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
contracts automatically as needed to hold the specified contents.
+ If the value of @code{auto-resize-tool-bars} is @code{grow-only},
+the tool bar expands automatically, but does not contract automatically.
+To contract the tool bar, the user has to redraw the frame by entering
+@kbd{C-l}.
+
The tool bar contents are controlled by a menu keymap attached to a
fake ``function key'' called @code{tool-bar} (much like the way the menu
bar is controlled). So you define a tool bar item using
If this variable is non-@code{nil}, the tool bar automatically resizes to
show all defined tool bar items---but not larger than a quarter of the
frame's height.
+
+If the value is @code{grow-only}, the tool bar expands automatically,
+but does not contract automatically. To contract the tool bar, the
+user has to redraw the frame by entering @kbd{C-l}.
@end defvar
@defvar auto-raise-tool-bar-buttons
HCoop / bpt / emacs.git / blobdiff