@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 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
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
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.
+
+The very highest precedence keymap comes from
+@code{overriding-terminal-local-map}; it operates on a per-terminal basis and
+is normally used for modal/transient keybindings.
@cindex major mode keymap
Since every buffer that uses the same major mode normally uses the
(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.
(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
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., 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