@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1994, 1998-2012 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1994, 1998-2013 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Keymaps
@chapter Keymaps
For examples of key sequences written in string and vector
representations, @ref{Init Rebinding,,, emacs, The GNU Emacs Manual}.
-@defmac kbd keyseq-text
-This macro converts the text @var{keyseq-text} (a string constant)
+@defun kbd keyseq-text
+This function converts the text @var{keyseq-text} (a string constant)
into a key sequence (a string or vector constant). The contents of
@var{keyseq-text} should use the same syntax as in the buffer invoked
by the @kbd{C-x C-k @key{RET}} (@code{kmacro-edit-macro}) command; in
(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
+@end defun
@node Keymap Basics
@section Keymap Basics
event. The argument @var{prompt} specifies a
prompt string, as in @code{make-sparse-keymap}.
+@c This example seems kind of pointless, but I guess it serves
+@c to contrast the result with make-sparse-keymap above.
@example
@group
(make-keymap)
- @result{} (keymap #^[t nil nil nil @dots{} nil nil keymap])
+ @result{} (keymap #^[nil nil keymap nil nil nil @dots{}])
@end group
@end example
@node Active Keymaps
@section Active Keymaps
@cindex active keymap
-@cindex global keymap
-@cindex local keymap
- Emacs normally contains many keymaps; at any given time, just a few
-of them are @dfn{active}, meaning that they participate in the
-interpretation of user input. All the active keymaps are used
-together to determine what command to execute when a key is entered.
-
- Normally the active keymaps are the @code{keymap} property keymap,
-the keymaps of any enabled minor modes, the current buffer's local
-keymap, and the global keymap, in that order. Emacs searches for each
-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 (if the
-underlying buffer text contains map properties in its text properties
-or overlays, they are ignored).
-
- 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.
-
- Each buffer may have another keymap, its @dfn{local keymap}, which
-may contain new or overriding definitions for keys. The current
-buffer's local keymap is always active except when
-@code{overriding-local-map} overrides it. The @code{local-map} text
-or overlay property can specify an alternative local keymap for certain
-parts of the buffer; see @ref{Special Properties}.
-
- Each minor mode can have a keymap; if it does, the keymap is active
-when the minor mode is enabled. Modes for emulation can specify
-additional active keymaps through the variable
-@code{emulation-mode-map-alists}.
-
- The highest precedence normal keymap comes from the @code{keymap}
-text or overlay property. If that is non-@code{nil}, it is the first
-keymap to be processed, in normal circumstances. Next comes
-any keymap added by the function @code{set-temporary-overlay-map}.
-@xref{Controlling Active Maps}.
-
- However, there are also special ways for programs to substitute
-other keymaps for some of those. The variable
-@code{overriding-local-map}, if non-@code{nil}, specifies a keymap
-that replaces all the usual active keymaps except the global keymap.
-Another way to do this is with @code{overriding-terminal-local-map};
-it operates on a per-terminal basis. These variables are documented
-below.
+ Emacs contains many keymaps, but at any time only a few keymaps are
+@dfn{active}. When Emacs receives user input, it translates the input
+event (@pxref{Translation Keymaps}), and looks for a key binding in
+the active keymaps.
+
+ Usually, the active keymaps are: (i) the keymap specified by the
+@code{keymap} property, (ii) the keymaps of enabled minor modes, (iii)
+the current buffer's local keymap, and (iv) the global keymap, in that
+order. Emacs searches for each input key sequence in all these
+keymaps.
+
+ Of these ``usual'' keymaps, the highest-precedence one is specified
+by the @code{keymap} text or overlay property at point, if any. (For
+a mouse input event, Emacs uses the event position instead of point;
+@iftex
+see the next section for details.)
+@end iftex
+@ifnottex
+@pxref{Searching Keymaps}.)
+@end ifnottex
+
+ Next in precedence are keymaps specified by enabled minor modes.
+These keymaps, if any, are specified by the variables
+@code{emulation-mode-map-alists},
+@code{minor-mode-overriding-map-alist}, and
+@code{minor-mode-map-alist}. @xref{Controlling Active Maps}.
-@cindex major mode keymap
- Since every buffer that uses the same major mode normally uses the
-same local keymap, you can think of the keymap as local to the mode. A
-change to the local keymap of a buffer (using @code{local-set-key}, for
-example) is seen also in the other buffers that share that keymap.
-
- The local keymaps that are used for Lisp mode and some other major
-modes exist even if they have not yet been used. These local keymaps are
-the values of variables such as @code{lisp-mode-map}. For most major
-modes, which are less frequently used, the local keymap is constructed
-only when the mode is used for the first time in a session.
+@cindex local keymap
+ Next in precedence is the buffer's @dfn{local keymap}, containing
+key bindings specific to the buffer. The minibuffer also has a local
+keymap (@pxref{Intro to Minibuffers}). If there is a @code{local-map}
+text or overlay property at point, that specifies the local keymap to
+use, in place of the buffer's default local keymap.
- The minibuffer has local keymaps, too; they contain various completion
-and exit commands. @xref{Intro to Minibuffers}.
+@cindex major mode keymap
+ The local keymap is normally set by the buffer's major mode, and
+every buffer with the same major mode shares the same local keymap.
+Hence, if you call @code{local-set-key} (@pxref{Key Binding Commands})
+to change the local keymap in one buffer, that also affects the local
+keymaps in other buffers with the same major mode.
- Emacs has other keymaps that are used in a different way---translating
-events within @code{read-key-sequence}. @xref{Translation Keymaps}.
+@cindex global keymap
+ Finally, the @dfn{global keymap} contains key bindings that are
+defined regardless of the current buffer, such as @kbd{C-f}. It is
+always active, and is bound to the variable @code{global-map}.
+
+ Apart from the above ``usual'' keymaps, Emacs provides special ways
+for programs to make other keymaps active. Firstly, the variable
+@code{overriding-local-map} specifies a keymap that replaces the usual
+active keymaps, except for the global keymap. Secondly, the
+terminal-local variable @code{overriding-terminal-local-map} specifies
+a keymap that takes precedence over @emph{all} other keymaps
+(including @code{overriding-local-map}); this is normally used for
+modal/transient keybindings (the function @code{set-transient-map}
+provides a convenient interface for this). @xref{Controlling Active
+Maps}, for details.
+
+ Making keymaps active is not the only way to use them. Keymaps are
+also used in other ways, such as for translating events within
+@code{read-key-sequence}. @xref{Translation Keymaps}.
@xref{Standard Keymaps}, for a list of some standard keymaps.
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.
+Emacs signals an error if @var{key} is not a string or a vector.
@example
@group
@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
-pseudo-Lisp description of the order and conditions for searching
-them:
+Here is a pseudo-Lisp summary of how Emacs searches the active
+keymaps:
@lisp
-(or (cond
- (overriding-terminal-local-map
- (@var{find-in} overriding-terminal-local-map))
- (overriding-local-map
- (@var{find-in} overriding-local-map))
- ((or (@var{find-in} (get-char-property (point) 'keymap))
- (@var{find-in} @var{temp-map})
+(or (if overriding-terminal-local-map
+ (@var{find-in} overriding-terminal-local-map))
+ (if overriding-local-map
+ (@var{find-in} overriding-local-map)
+ (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-char-property (point) 'local-map))
- (@var{find-in} (current-local-map))))))
+ (@var{find-in} (current-local-map)))))
(@var{find-in} (current-global-map)))
@end lisp
@noindent
-@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. @var{temp-map} is a pseudo variable that
-represents the effect of a @code{set-temporary-overlay-map} call.
-
- When a match is found (@pxref{Key Lookup}), if the binding in the
-keymap is a function, the search is over. However if the keymap entry
-is a symbol with a value or a string, Emacs replaces the input key
-sequences with the variable's value or the string, and restarts the
-search of the active keymaps.
-
- The function finally found might also be remapped. @xref{Remapping
-Commands}.
+Here, @var{find-in} and @var{find-in-any} are pseudo functions that
+search in one keymap and in an alist of keymaps, respectively. Note
+that the @code{set-transient-map} function works by setting
+@code{overriding-terminal-local-map} (@pxref{Controlling Active
+Maps}).
+
+ In the above pseudo-code, if a key sequence starts with a mouse
+event (@pxref{Mouse Events}), that event's position is used instead of
+point, and the event's buffer is used instead of the current buffer.
+In particular, this affects how the @code{keymap} and @code{local-map}
+properties are looked up. If a mouse event occurs on a string
+embedded with a @code{display}, @code{before-string}, or
+@code{after-string} property (@pxref{Special Properties}), and the
+string has a non-@code{nil} @code{keymap} or @code{local-map}
+property, that overrides the corresponding property in the underlying
+buffer text (i.e., the property specified by the underlying text is
+ignored).
+
+ When a key binding is found in one of the active keymaps, and that
+binding is a command, the search is over---the command is executed.
+However, if the binding is a symbol with a value or a string, Emacs
+replaces the input key sequences with the variable's value or the
+string, and restarts the search of the active keymaps. @xref{Key
+Lookup}.
+
+ The command which is finally found might also be remapped.
+@xref{Remapping Commands}.
@node Controlling Active Maps
@section Controlling the Active Keymaps
@end defun
@code{current-local-map} returns a reference to the local keymap, not
-a copy of it; if you use @code{define-key} or other functions on it
+a copy of it; if you use @code{define-key} or other functions on it
you will alter local bindings.
@defun current-minor-mode-maps
commands use this function.
@end defun
-@c Emacs 19 feature
@defvar minor-mode-map-alist
@anchor{Definition of minor-mode-map-alist}
This variable is an alist describing keymaps that may or may not be
@end defvar
@defvar emulation-mode-map-alists
-This variable holds a list of keymap alists to use for emulations
+This variable holds a list of keymap alists to use for emulation
modes. It is intended for modes or packages using multiple minor-mode
keymaps. Each element is a keymap alist which has the same format and
meaning as @code{minor-mode-map-alist}, or a symbol with a variable
@code{minor-mode-overriding-map-alist}.
@end defvar
-@defun set-temporary-overlay-map keymap &optional keep
-This function adds @var{keymap} as a temporary keymap that takes
-precedence over most other keymaps. It does not take precedence over
-the ``overriding'' maps (see above); and unlike them, if no match for
-a key is found in @var{keymap}, the search continues.
-
-Normally, @var{keymap} is used only once. If the optional argument
-@var{pred} is @code{t}, the map stays active if a key from @var{keymap}
-is used. @var{pred} can also be a function of no arguments: if it returns
-non-@code{nil} then @var{keymap} stays active.
-
-For a pseudo-Lisp description of exactly how and when this keymap applies,
-@pxref{Searching Keymaps}.
+@cindex transient keymap
+@defun set-transient-map keymap &optional keep
+This function adds @var{keymap} as a @dfn{transient} keymap, which
+takes precedence over other keymaps for one (or more) subsequent keys.
+
+Normally, @var{keymap} is used just once, to look up the very next
+key. If the optional argument @var{pred} is @code{t}, the map stays
+active as long as the user types keys defined in @var{keymap}; when
+the user types a key that is not in @var{keymap}, the transient keymap
+is deactivated and normal key lookup continues for that key.
+
+The @var{pred} argument can also be a function. In that case, the
+function is called with no arguments, prior to running each command,
+while @var{keymap} is active; it should return non-@code{nil} if
+@var{keymap} should stay active.
+
+This function works by adding and removing @code{keymap} from the
+variable @code{overriding-terminal-local-map}, which takes precedence
+over all other active keymaps (@pxref{Searching Keymaps}).
@end defun
@node Key Lookup
The functions below signal an error if @var{keymap} is not 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 that are
-lists. The @code{kbd} macro (@pxref{Key Sequences}) is a convenient
-way to specify the key sequence.
+lists. The @code{kbd} function (@pxref{Key Sequences}) is a
+convenient way to specify the key sequence.
@defun define-key keymap key binding
This function sets the binding for @var{key} in @var{keymap}. (If
remapped to @code{my-kill-line}; if an ordinary binding specifies
@code{my-kill-line}, it is remapped to @code{my-other-kill-line}.
-To undo the remapping of a command, remap it to @code{nil}; e.g.
+To undo the remapping of a command, remap it to @code{nil}; e.g.,
@smallexample
(define-key my-mode-map [remap kill-line] nil)
after @code{input-decode-map} and before @code{key-translation-map}.
Entries in @code{local-function-key-map} are ignored if they conflict
-with bindings made in the minor mode, local, or global keymaps. I.e.
+with bindings made in the minor mode, local, or global keymaps. I.e.,
the remapping only applies if the original key sequence would
otherwise not have any binding.
@end group
@end smallexample
-This function is implemented simply using @code{define-key}:
+This function is equivalent to using @code{define-key} as follows:
@smallexample
@group
If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
listing includes only keys that start with @var{prefix}.
-The listing describes meta characters as @key{ESC} followed by the
-corresponding non-meta character.
-
When several characters with consecutive @acronym{ASCII} codes have the
same definition, they are shown together, as
@samp{@var{firstchar}..@var{lastchar}}. In this instance, you need to
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
+toolkit, e.g., on a text terminal.} Keyboard menus also display the
overall prompt string.
The easiest way to construct a keymap with a prompt string is to
and @code{:visible} for a menu separator:
@code{(menu-item @var{separator-type} nil . @var{item-property-list})}
-
+
For example:
-
+
@example
(menu-item "--" nil :visible (boundp 'foo))
@end example
items, the menu shows the contents of the nested keymap directly, not
as a submenu.
- However, if Emacs is compiled without X toolkit support, submenus
-are not supported. Each nested keymap is shown as a menu item, but
-clicking on it does not automatically pop up the submenu. If you wish
-to imitate the effect of submenus, you can do that by giving a nested
-keymap an item string which starts with @samp{@@}. This causes Emacs
-to display the nested keymap using a separate @dfn{menu pane}; the
-rest of the item string after the @samp{@@} is the pane label. If
-Emacs is compiled without X toolkit support, menu panes are not used;
-in that case, a @samp{@@} at the beginning of an item string is
-omitted when the menu label is displayed, and has no other effect.
+ However, if Emacs is compiled without X toolkit support, or on text
+terminals, submenus are not supported. Each nested keymap is shown as
+a menu item, but clicking on it does not automatically pop up the
+submenu. If you wish to imitate the effect of submenus, you can do
+that by giving a nested keymap an item string which starts with
+@samp{@@}. This causes Emacs to display the nested keymap using a
+separate @dfn{menu pane}; the rest of the item string after the
+@samp{@@} is the pane label. If Emacs is compiled without X toolkit
+support, or if a menu is displayed on a text terminal, menu panes are
+not used; in that case, a @samp{@@} at the beginning of an item string
+is omitted when the menu label is displayed, and has no other effect.
@node Keyboard Menus
@subsection Menus and the Keyboard
@subsection The Menu Bar
@cindex menu bar
- On graphical displays, there is usually a @dfn{menu bar} at the top
-of each frame. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu
-bar items are subcommands of the fake ``function key''
-@code{menu-bar}, as defined in the active keymaps.
+ Emacs usually shows a @dfn{menu bar} at the top of each frame.
+@xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu bar items are
+subcommands of the fake ``function key'' @code{menu-bar}, as defined
+in the active keymaps.
To add an item to the menu bar, invent a fake ``function key'' of your
own (let's call it @var{key}), and make a binding for the key sequence
A @dfn{tool bar} is a row of clickable icons at the top of a frame,
just below the menu bar. @xref{Tool Bars,,,emacs, The GNU Emacs
-Manual}.
+Manual}. Emacs normally shows a tool bar on graphical displays.
On each frame, the frame parameter @code{tool-bar-lines} controls
how many lines' worth of height to reserve for the tool bar. A zero
@end table
@end table
+The GTK+ and NS versions of Emacs ignores items 1 to 3, because disabled and/or
+deselected images are autocomputed from item 0.
+
If @var{image} is a single image specification, Emacs draws the tool bar
button in disabled state by applying an edge-detection algorithm to the
image.
HCoop / bpt / emacs.git / blobdiff