@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
@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
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
+ When the key sequence starts with a mouse event,
+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
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.
+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
(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} @var{temp-map})
+ (@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
@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
+Lookup}.) If the key sequence starts with 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.
+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
@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
@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}.
+@end defun
+
@node Key Lookup
@section Key Lookup
@cindex 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)
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
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., under MS-DOS.} 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
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
@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