@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, Modes, Command Loop, Top
+@node Keymaps
@chapter Keymaps
@cindex keymap
A @dfn{key sequence}, or @dfn{key} for short, is a sequence of one
or more input events that form a unit. Input events include
-characters, function keys, and mouse actions (@pxref{Input Events}).
+characters, function keys, mouse actions, or system events external to
+Emacs, such as @code{iconify-frame} (@pxref{Input Events}).
The Emacs Lisp representation for a key sequence is a string or
vector. Unless otherwise stated, any Emacs Lisp function that accepts
a key sequence as an argument can handle both representations.
constituent events; thus, @code{"\C-xl"} represents the key sequence
@kbd{C-x l}.
- Key sequences containing function keys, mouse button events, or
-non-@acronym{ASCII} characters such as @kbd{C-=} or @kbd{H-a} cannot be
-represented as strings; they have to be represented as vectors.
+ Key sequences containing function keys, mouse button events, system
+events, or non-@acronym{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
an input event, in its Lisp form. @xref{Input Events}. For example,
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 describe the key sequence using almost the same
-syntax used in this manual. More precisely, it uses the same syntax
-that Edit Macro mode uses for editing keyboard macros (@pxref{Edit
-Keyboard Macro,,, emacs, The GNU Emacs Manual}); you must surround
-function key names with @samp{<@dots{}>}.
+@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
+particular, you must surround function key names with
+@samp{<@dots{}>}. @xref{Edit Keyboard Macro,,, emacs, The GNU Emacs
+Manual}.
@example
(kbd "C-x") @result{} "\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
+@end defun
@node Keymap Basics
@section Keymap Basics
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}.
+
+@item (keymap @dots{})
+If an element of a keymap is itself a keymap, it counts as if this inner keymap
+were inlined in the outer keymap. This is used for multiple-inheritance, such
+as in @code{make-composed-keymap}.
@end table
When the binding is @code{nil}, it doesn't constitute a definition
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 Inheritance and Keymaps
@section Inheritance and Keymaps
@cindex keymap inheritance
-@cindex inheriting a keymap's bindings
+@cindex inheritance, keymap
A keymap can inherit the bindings of another keymap, which we call the
@dfn{parent keymap}. Such a keymap looks like this:
@example
(defvar help-mode-map
(let ((map (make-sparse-keymap)))
- (set-keymap-parent map (make-composed-keymap button-buffer-map
- special-mode-map))
+ (set-keymap-parent map
+ (make-composed-keymap button-buffer-map special-mode-map))
... map) ... )
@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.
-
- 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.
-
-@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.
+ 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}.
- 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-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))))))
+(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-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.
-
- 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
+@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
@section Key Lookup
@cindex key lookup
This feature permits you to define one key as an alias for another key.
For example, an entry whose @sc{car} is the keymap called @code{esc-map}
and whose @sc{cdr} is 32 (the code for @key{SPC}) means, ``Use the global
-binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
+binding of @kbd{Meta-@key{SPC}}, whatever that may be''.
@end itemize
@item @var{symbol}
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)
being read, as it is read, against @code{input-decode-map}, then
@code{local-function-key-map}, and then against @code{key-translation-map}.
-@defvar input-decode-map
-This variable holds a keymap that describes the character sequences sent
-by function keys on an ordinary character terminal. This keymap has the
-same structure as other keymaps, but is used differently: it specifies
-translations to make while reading key sequences, rather than bindings
-for key sequences.
+These keymaps have the same structure as other keymaps, but they are used
+differently: they specify translations to make while reading key sequences,
+rather than bindings for key sequences.
-If @code{input-decode-map} ``binds'' a key sequence @var{k} to a vector
+If one of these keymaps ``binds'' a key sequence @var{k} to a vector
@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
key sequence, it is replaced with the events in @var{v}.
this back into @kbd{C-c @key{PF1}}, which it returns as the vector
@code{[?\C-c pf1]}.
+@defvar input-decode-map
+This variable holds a keymap that describes the character sequences sent
+by function keys on an ordinary character terminal.
+
The value of @code{input-decode-map} is usually set up automatically
according to the terminal's Terminfo or Termcap entry, but sometimes
those need help from terminal-specific Lisp files. Emacs comes with
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 defvar
@cindex key translation function
-You can use @code{input-decode-map}, @code{local-function-key-map}, or
-@code{key-translation-map} for more than simple aliases, by using a
-function, instead of a key sequence, as the ``translation'' of a key.
-Then this function is called to compute the translation of that key.
+You can use @code{input-decode-map}, @code{local-function-key-map},
+and @code{key-translation-map} for more than simple aliases, by using
+a function, instead of a key sequence, as the ``translation'' of a
+key. Then this function is called to compute the translation of that
+key.
The key translation function receives one argument, which is the prompt
that was specified in @code{read-key-sequence}---or @code{nil} if the
(let ((symbol (if (symbolp e) e (car e))))
(setq symbol (intern (concat string
(symbol-name symbol))))
-@end group
-@group
(if (symbolp e)
symbol
(cons symbol (cdr e)))))
@end example
If you have enabled keyboard character set decoding using
-@code{set-keyboard-coding-system}, decoding is done after the
-translations listed above. @xref{Terminal I/O Encoding}. However, in
-future Emacs versions, character set decoding may be done at an
-earlier stage.
+@code{set-keyboard-coding-system}, decoding is done before the
+translations listed above. @xref{Terminal I/O Encoding}.
+
+@subsection Interaction with normal keymaps
+
+The end of a key sequence is detected when that key sequence either is bound
+to a command, or when Emacs determines that no additional event can lead
+to a sequence that is bound to a command.
+
+This means that, while @code{input-decode-map} and @code{key-translation-map}
+apply regardless of whether the original key sequence would have a binding, the
+presence of such a binding can still prevent translation from taking place.
+For example, let us return to our VT100 example above and add a binding for
+@kbd{C-c @key{ESC}} to the global map; now when the user hits @kbd{C-c
+@key{PF1}} Emacs will fail to decode @kbd{C-c @key{ESC} O P} into @kbd{C-c
+@key{PF1}} because it will stop reading keys right after @kbd{C-x @key{ESC}},
+leaving @kbd{O P} for later. This is in case the user really hit @kbd{C-c
+@key{ESC}}, in which case Emacs should not sit there waiting for the next key
+to decide whether the user really pressed @kbd{@key{ESC}} or @kbd{@key{PF1}}.
+
+For that reason, it is better to avoid binding commands to key sequences where
+the end of the key sequence is a prefix of a key translation. The main such
+problematic suffixes/prefixes are @kbd{@key{ESC}}, @kbd{M-O} (which is really
+@kbd{@key{ESC} O}) and @kbd{M-[} (which is really @kbd{@key{ESC} [}).
@node Key Binding Commands
@section Commands for Binding Keys
@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
is a list of keymaps, only those keymaps are searched.
Usually it's best to use @code{overriding-local-map} as the expression
-for @var{keymap}. Then @code{where-is-internal} searches precisely the
-keymaps that are active. To search only the global map, pass
-@code{(keymap)} (an empty keymap) as @var{keymap}.
+for @var{keymap}. Then @code{where-is-internal} searches precisely
+the keymaps that are active. To search only the global map, pass the
+value @code{(keymap)} (an empty keymap) as @var{keymap}.
If @var{firstonly} is @code{non-ascii}, then the value is a single
vector representing the first key sequence found, rather than a list of
follow indirect keymap bindings. This makes it possible to search for
an indirect definition itself.
-When command remapping is in effect (@pxref{Remapping Commands}),
-@code{where-is-internal} figures out when a command will be run due to
-remapping and reports keys accordingly. It also returns @code{nil} if
-@var{command} won't really be run because it has been remapped to some
-other command. However, if @var{no-remap} is non-@code{nil}.
-@code{where-is-internal} ignores remappings.
+The fifth argument, @var{no-remap}, determines how this function
+treats command remappings (@pxref{Remapping Commands}). There are two
+cases of interest:
-@smallexample
-@group
-(where-is-internal 'describe-function)
- @result{} ([8 102] [f1 102] [help 102]
- [menu-bar help-menu describe describe-function])
-@end group
-@end smallexample
+@table @asis
+@item If a command @var{other-command} is remapped to @var{command}:
+If @var{no-remap} is @code{nil}, find the bindings for
+@var{other-command} and treat them as though they are also bindings
+for @var{command}. If @var{no-remap} is non-@code{nil}, include the
+vector @code{[remap @var{other-command}]} in the list of possible key
+sequences, instead of finding those bindings.
+
+@item If @var{command} is remapped to @var{other-command}:
+If @var{no-remap} is @code{nil}, return the bindings for
+@var{other-command} rather than @var{command}. If @var{no-remap} is
+non-@code{nil}, return the bindings for @var{command}, ignoring the
+fact that it is remapped.
+@end table
@end defun
@deffn Command describe-bindings &optional prefix buffer-or-name
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
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 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.
-* Modifying Menus:: How to add new items to a 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 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.
+* Modifying Menus:: How to add new items to a menu.
+* Easy Menu:: A convenience macro for making menus.
@end menu
@node Defining Menus
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
@code{define-key-after} (@pxref{Modifying Menus}).
@menu
-* Simple Menu Items:: A simple kind of menu key binding,
- limited in capabilities.
-* Extended Menu Items:: More powerful menu item definitions
- let you specify keywords to enable
- various features.
+* Simple Menu Items:: A simple kind of menu key binding.
+* Extended Menu Items:: More complex menu item definitions.
* Menu Separators:: Drawing a horizontal line through a menu.
* Alias Menu Items:: Using command aliases in menu items.
-* Toolkit Differences:: Not all toolkits provide the same features.
@end menu
-
@node Simple Menu Items
@subsubsection Simple Menu Items
which toggles the variable @code{debug-on-error}.
@dfn{Radio buttons} are a group of menu items, in which at any time one
-and only one is ``selected.'' There should be a variable whose value
+and only one is ``selected''. There should be a variable whose value
says which one is selected at any time. The @var{selected} form for
each radio button in the group should check whether the variable has the
right value for selecting that button. Clicking on the button should
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
in Emacs now is with extended menu items; before that feature existed,
it could be done by defining alias commands and using them in menu
items. Here's an example that makes two aliases for
-@code{toggle-read-only} and gives them different enable conditions:
+@code{read-only-mode} and gives them different enable conditions:
@example
-(defalias 'make-read-only 'toggle-read-only)
+(defalias 'make-read-only 'read-only-mode)
(put 'make-read-only 'menu-enable '(not buffer-read-only))
-(defalias 'make-writable 'toggle-read-only)
+(defalias 'make-writable 'read-only-mode)
(put 'make-writable 'menu-enable 'buffer-read-only)
@end example
@noindent
causes menu items for @code{make-read-only} and @code{make-writable} to
-show the keyboard bindings for @code{toggle-read-only}.
-
-@node Toolkit Differences
-@subsubsection Toolkit Differences
-
-The various toolkits with which you can build Emacs do not all support
-the same set of features for menus. Some code works as expected with
-one toolkit, but not under another.
-
-One example is menu actions or buttons in a top-level menu bar. The
-following works with the Lucid toolkit or on MS Windows, but not with
-GTK or Nextstep, where clicking on the item has no effect.
-
-@example
-(defun menu-action-greet ()
- (interactive)
- (message "Hello Emacs User!"))
-
-(defun top-level-menu ()
- (interactive)
- (define-key lisp-interaction-mode-map [menu-bar m]
- '(menu-item "Action Button" menu-action-greet)))
-@end example
+show the keyboard bindings for @code{read-only-mode}.
@node Mouse Menus
@subsection Menus and the Mouse
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
Note the symbols which the bindings are ``made for''; these appear
inside square brackets, in the key sequence being defined. In some
cases, this symbol is the same as the command name; sometimes it is
-different. These symbols are treated as ``function keys,'' but they are
+different. These symbols are treated as ``function keys'', but they are
not real function keys on the keyboard. They do not affect the
functioning of the menu itself, but they are ``echoed'' in the echo area
when the user selects from the menu, and they appear in the output of
@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.
@example
(global-set-key [tool-bar]
- `(menu-item ,(purecopy "tool bar") ignore
- :filter tool-bar-make-keymap))
+ `(menu-item ,(purecopy "tool bar") ignore
+ :filter tool-bar-make-keymap))
@end example
@noindent
[work] '("Work" . work-command) 'break)
@end example
@end defun
+
+@node Easy Menu
+@subsection Easy Menu
+
+ The following macro provides a convenient way to define pop-up menus
+and/or menu bar menus.
+
+@defmac easy-menu-define symbol maps doc menu
+This macro defines a pop-up menu and/or menu bar submenu, whose
+contents are given by @var{menu}.
+
+If @var{symbol} is non-@code{nil}, it should be a symbol; then this
+macro defines @var{symbol} as a function for popping up the menu
+(@pxref{Pop-Up Menus}), with @var{doc} as its documentation string.
+@var{symbol} should not be quoted.
+
+Regardless of the value of @var{symbol}, if @var{maps} is a keymap,
+the menu is added to that keymap, as a top-level menu for the menu bar
+(@pxref{Menu Bar}). It can also be a list of keymaps, in which case
+the menu is added separately to each of those keymaps.
+
+The first element of @var{menu} must be a string, which serves as the
+menu label. It may be followed by any number of the following
+keyword-argument pairs:
+
+@table @code
+@item :filter @var{function}
+@var{function} must be a function which, if called with one
+argument---the list of the other menu items---returns the actual items
+to be displayed in the menu.
+
+@item :visible @var{include}
+@var{include} is an expression; if it evaluates to @code{nil}, the
+menu is made invisible. @code{:included} is an alias for
+@code{:visible}.
+
+@item :active @var{enable}
+@var{enable} is an expression; if it evaluates to @code{nil}, the menu
+is not selectable. @code{:enable} is an alias for @code{:active}.
+@end table
+
+The remaining elements in @var{menu} are menu items.
+
+A menu item can be a vector of three elements, @code{[@var{name}
+@var{callback} @var{enable}]}. @var{name} is the menu item name (a
+string). @var{callback} is a command to run, or an expression to
+evaluate, when the item is chosen. @var{enable} is an expression; if
+it evaluates to @code{nil}, the item is disabled for selection.
+
+Alternatively, a menu item may have the form:
+
+@smallexample
+ [ @var{name} @var{callback} [ @var{keyword} @var{arg} ]... ]
+@end smallexample
+
+@noindent
+where @var{name} and @var{callback} have the same meanings as above,
+and each optional @var{keyword} and @var{arg} pair should be one of
+the following:
+
+@table @code
+@item :keys @var{keys}
+@var{keys} is a keyboard equivalent to the menu item (a string). This
+is normally not needed, as keyboard equivalents are computed
+automatically. @var{keys} is expanded with
+@code{substitute-command-keys} before it is displayed (@pxref{Keys in
+Documentation}).
+
+@item :key-sequence @var{keys}
+@var{keys} is a hint for speeding up Emacs's first display of the
+menu. It should be nil if you know that the menu item has no keyboard
+equivalent; otherwise it should be a string or vector specifying a
+keyboard equivalent for the menu item.
+
+@item :active @var{enable}
+@var{enable} is an expression; if it evaluates to @code{nil}, the item
+is make unselectable.. @code{:enable} is an alias for @code{:active}.
+
+@item :visible @var{include}
+@var{include} is an expression; if it evaluates to @code{nil}, the
+item is made invisible. @code{:included} is an alias for
+@code{:visible}.
+
+@item :label @var{form}
+@var{form} is an expression that is evaluated to obtain a value which
+serves as the menu item's label (the default is @var{name}).
+
+@item :suffix @var{form}
+@var{form} is an expression that is dynamically evaluated and whose
+value is concatenated with the menu entry's label.
+
+@item :style @var{style}
+@var{style} is a symbol describing the type of menu item; it should be
+@code{toggle} (a checkbox), or @code{radio} (a radio button), or
+anything else (meaning an ordinary menu item).
+
+@item :selected @var{selected}
+@var{selected} is an expression; the checkbox or radio button is
+selected whenever the expression's value is non-nil.
+
+@item :help @var{help}
+@var{help} is a string describing the menu item.
+@end table
+
+Alternatively, a menu item can be a string. Then that string appears
+in the menu as unselectable text. A string consisting of dashes is
+displayed as a separator (@pxref{Menu Separators}).
+
+Alternatively, a menu item can be a list with the same format as
+@var{menu}. This is a submenu.
+@end defmac
+
+Here is an example of using @code{easy-menu-define} to define a menu
+similar to the one defined in the example in @ref{Menu Bar}:
+
+@example
+(easy-menu-define words-menu global-map
+ "Menu for word navigation commands."
+ '("Words"
+ ["Forward word" forward-word]
+ ["Backward word" backward-word]))
+@end example
HCoop / bpt / emacs.git / blobdiff