@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-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/keymaps
@node Keymaps, Modes, Command Loop, Top
@chapter Keymaps
@cindex keymap
@kbd{C-x l}.
Key sequences containing function keys, mouse button events, or
-non-ASCII characters such as @kbd{C-=} or @kbd{H-a} cannot be
+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
which is always a character or a symbol. @xref{Classifying Events}.
In this kind of binding, @var{binding} is a command.
-@item (@var{type} @var{item-name} @r{[}@var{cache}@r{]} .@: @var{binding})
+@item (@var{type} @var{item-name} .@: @var{binding})
This specifies a binding which is also a simple menu item that
-displays as @var{item-name} in the menu. @var{cache}, if present,
-caches certain information for display in the menu. @xref{Simple Menu
-Items}.
+displays as @var{item-name} in the menu. @xref{Simple Menu Items}.
-@item (@var{type} @var{item-name} @var{help-string} @r{[}@var{cache}@r{]} .@: @var{binding})
+@item (@var{type} @var{item-name} @var{help-string} .@: @var{binding})
This is a simple menu item with help string @var{help-string}.
@item (@var{type} menu-item .@: @var{details})
@kbd{@key{ESC} @key{end}}.
Here as an example is the local keymap for Lisp mode, a sparse
-keymap. It defines bindings for @key{DEL} and @key{TAB}, plus @kbd{C-c
-C-l}, @kbd{M-C-q}, and @kbd{M-C-x}.
+keymap. It defines bindings for @key{DEL}, @kbd{C-c C-z},
+@kbd{C-M-q}, and @kbd{C-M-x} (the actual value also contains a menu
+binding, which is omitted here for the sake of brevity).
@example
@group
@end group
@group
(27 keymap
- ;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}}
- (24 . lisp-send-defun)
- keymap
- ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp))
+ ;; @r{@kbd{C-M-x}, treated as @kbd{@key{ESC} C-x}}
+ (24 . lisp-send-defun))
@end group
@group
;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
@end group
@group
(27 keymap
- ;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
- (17 . indent-sexp))
- (9 . lisp-indent-line))
+ ;; @r{@kbd{C-M-q}, treated as @kbd{@key{ESC} C-q}}
+ (17 . indent-sexp)))
@end group
@end example
@var{maps}, and optionally inheriting from a parent keymap
@var{parent}. @var{maps} can be a single keymap or a list of more
than one. When looking up a key in the resulting new map, Emacs
-searches in each of the @var{maps}, and then in @var{parent}, stopping
-at the first match. A @code{nil} binding in any one of @var{maps}
-overrides any binding in @var{parent}, but not a non-@code{nil} binding
-in any other of the @var{maps}.
+searches in each of the @var{maps} in turn, and then in @var{parent},
+stopping at the first match. A @code{nil} binding in any one of
+@var{maps} overrides any binding in @var{parent}, but it does not
+override any non-@code{nil} binding in any other of the @var{maps}.
@end defun
@noindent For example, here is how Emacs sets the parent of
Emacs has other keymaps that are used in a different way---translating
events within @code{read-key-sequence}. @xref{Translation Keymaps}.
- @xref{Standard Keymaps}, for a list of standard keymaps.
+ @xref{Standard Keymaps}, for a list of some standard keymaps.
@defun current-active-maps &optional olp position
This returns the list of active keymaps that would be used by the
@end lisp
@noindent
-The @var{find-in} and @var{find-in-any} are pseudo functions that
-search in one keymap and in an alist of keymaps, respectively.
-(Searching a single keymap for a binding is called @dfn{key lookup};
-see @ref{Key Lookup}.) If the key sequence starts with a mouse event,
-or a symbolic prefix event followed by a mouse event, that event's
-position is used instead of point and the current buffer. Mouse
-events on an embedded string use non-@code{nil} text properties from
-that string instead of the buffer.
-
-@enumerate
-@item
-The function finally found may be remapped
-(@pxref{Remapping Commands}).
-
-@item
-Characters that are bound to @code{self-insert-command} are translated
-according to @code{translation-table-for-input} before insertion.
-
-@item
-@code{current-active-maps} returns a list of the
-currently active keymaps at point.
-
-@item
-When a match is found (@pxref{Key Lookup}), if the binding in the
+@var{find-in} and @var{find-in-any} are pseudo functions that search
+in one keymap and in an alist of keymaps, respectively. (Searching a
+single keymap for a binding is called @dfn{key lookup}; see @ref{Key
+Lookup}.) 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.
-@end enumerate
+
+ The function finally found might also be remapped. @xref{Remapping
+Commands}.
@node Controlling Active Maps
@section Controlling the Active Keymaps
@defun current-local-map
This function returns the current buffer's local keymap, or @code{nil}
if it has none. In the following example, the keymap for the
-@samp{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
+@file{*scratch*} buffer (using Lisp Interaction mode) is a sparse keymap
in which the entry for @key{ESC}, @acronym{ASCII} code 27, is another sparse
keymap.
binding is not executable as a command.
@end table
- In short, a keymap entry may be a keymap, a command, a keyboard macro,
-a symbol that leads to one of them, or an indirection or @code{nil}.
-Here is an example of a sparse keymap with two characters bound to
-commands and one bound to another keymap. This map is the normal value
-of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB},
-127 for @key{DEL}, 27 for @key{ESC}, 17 for @kbd{C-q} and 24 for
-@kbd{C-x}.
-
-@example
-@group
-(keymap (9 . lisp-indent-line)
- (127 . backward-delete-char-untabify)
- (27 keymap (17 . indent-sexp) (24 . eval-defun)))
-@end group
-@end example
+ In short, a keymap entry may be a keymap, a command, a keyboard
+macro, a symbol that leads to one of them, or an indirection or
+@code{nil}.
@node Functions for Key Lookup
@section Functions for Key Lookup
example, suppressing @code{global-map} would make it impossible to use
most of Emacs.
-Most often, @code{suppress-keymap} is used to initialize local
-keymaps of modes such as Rmail and Dired where insertion of text is not
-desirable and the buffer is read-only. Here is an example taken from
-the file @file{emacs/lisp/dired.el}, showing how the local keymap for
-Dired mode is set up:
+This function can be used to initialize the local keymap of a major
+mode for which insertion of text is not desirable. But usually such a
+mode should be derived from @code{special-mode} (@pxref{Basic Major
+Modes}); then its keymap will automatically inherit from
+@code{special-mode-map}, which is already suppressed. Here is how
+@code{special-mode-map} is defined:
@smallexample
@group
-(setq dired-mode-map (make-keymap))
-(suppress-keymap dired-mode-map)
-(define-key dired-mode-map "r" 'dired-rename-file)
-(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
-(define-key dired-mode-map "d" 'dired-flag-file-deleted)
-(define-key dired-mode-map "v" 'dired-view-file)
-(define-key dired-mode-map "e" 'dired-find-file)
-(define-key dired-mode-map "f" 'dired-find-file)
-@dots{}
+(defvar special-mode-map
+ (let ((map (make-sparse-keymap)))
+ (suppress-keymap map)
+ (define-key map "q" 'quit-window)
+ @dots{}
+ map))
@end group
@end smallexample
@end defun
@deffn Command describe-bindings &optional prefix buffer-or-name
This function creates a listing of all current key bindings, and
-displays it in a buffer named @samp{*Help*}. The text is grouped by
+displays it in a buffer named @file{*Help*}. The text is grouped by
modes---minor modes first, then the major mode, then global bindings.
If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
@noindent
The @sc{car}, @var{item-string}, is the string to be displayed in the
menu. It should be short---preferably one to three words. It should
-describe the action of the command it corresponds to. Note that it is
-not generally possible to display non-@acronym{ASCII} text in menus. It will
-work for keyboard menus and will work to a large extent when Emacs is
-built with the Gtk+ toolkit.@footnote{In this case, the text is first
-encoded using the @code{utf-8} coding system and then rendered by the
-toolkit as it sees fit.}
+describe the action of the command it corresponds to. Note that not
+all graphical toolkits can display non-@acronym{ASCII} text in menus
+(it will work for keyboard menus and will work to a large extent with
+the GTK+ toolkit).
You can also supply a second string, called the help string, as follows:
It's often best to use a button-down event to trigger the menu. Then
the user can select a menu item by releasing the button.
- A single keymap can appear as multiple menu panes, if you explicitly
-arrange for this. The way to do this is to make a keymap for each pane,
-then create a binding for each of those maps in the main keymap of the
-menu. Give each of these bindings an item string that starts with
-@samp{@@}. The rest of the item string becomes the name of the pane.
-See the file @file{lisp/mouse.el} for an example of this. Any ordinary
-bindings with @samp{@@}-less item strings are grouped into one pane,
-which appears along with the other panes explicitly created for the
-submaps.
-
- X toolkit menus don't have panes; instead, they can have submenus.
-Every nested keymap becomes a submenu, whether the item string starts
-with @samp{@@} or not. In a toolkit version of Emacs, the only thing
-special about @samp{@@} at the beginning of an item string is that the
-@samp{@@} doesn't appear in the menu item.
-
- Multiple keymaps that define the same menu prefix key produce
-separate panes or separate submenus.
+@cindex submenu
+ If the menu keymap contains a binding to a nested keymap, the nested
+keymap specifies a @dfn{submenu}. There will be a menu item, labeled
+by the nested keymap's item string, and clicking on this item
+automatically pops up the specified submenu. As a special exception,
+if the menu keymap contains a single nested keymap and no other menu
+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.
@node Keyboard Menus
@subsection Menus and the Keyboard
she should type the corresponding character---the one whose binding is
that alternative.
-@ignore
-In a menu intended for keyboard use, each menu item must clearly
-indicate what character to type. The best convention to use is to make
-the character the first letter of the item string---that is something
-users will understand without being told. We plan to change this; by
-the time you read this manual, keyboard menus may explicitly name the
-key for each alternative.
-@end ignore
-
- This way of using menus in an Emacs-like editor was inspired by the
-Hierarkey system.
-
@defvar menu-prompt-more-char
This variable specifies the character to use to ask to see
the next line of a menu. Its initial value is 32, the code
@subsection The Menu Bar
@cindex menu bar
- Most window systems allow each frame to have a @dfn{menu bar}---a
-permanently displayed menu stretching horizontally across the top of
-the frame. (In order for a frame to display a menu bar, its
-@code{menu-bar-lines} parameter must be greater than zero.
-@xref{Layout Parameters}.)
-
- The items of the menu bar are the subcommands of the fake ``function
-key'' @code{menu-bar}, as defined in the active keymaps.
+ 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.
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
@code{[menu-bar @var{key}]}. Most often, the binding is a menu keymap,
so that pressing a button on the menu bar item leads to another menu.
- When more than one active keymap defines the same fake function key
+ When more than one active keymap defines the same ``function key''
for the menu bar, the item appears just once. If the user clicks on
that menu bar item, it brings up a single, combined menu containing
all the subcommands of that item---the global subcommands, the local
Here's an example of setting up a menu bar item:
@example
-@group
-(modify-frame-parameters (selected-frame)
- '((menu-bar-lines . 2)))
-@end group
-
@group
;; @r{Make a menu keymap (with a prompt string)}
;; @r{and make it the menu bar item's definition.}
@subsection Tool bars
@cindex tool bar
- A @dfn{tool bar} is a row of icons at the top of a frame, that execute
-commands when you click on them---in effect, a kind of graphical menu
-bar.
-
- The frame parameter @code{tool-bar-lines} (X resource @samp{toolBar})
-controls how many lines' worth of height to reserve for the tool bar. A
-zero value suppresses the tool bar. If the value is nonzero, and
-@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands and
-contracts automatically as needed to hold the specified contents.
+ 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}.
- If the value of @code{auto-resize-tool-bars} is @code{grow-only},
-the tool bar expands automatically, but does not contract automatically.
-To contract the tool bar, the user has to redraw the frame by entering
-@kbd{C-l}.
+ 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
+value suppresses the tool bar. If the value is nonzero, and
+@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar expands
+and contracts automatically as needed to hold the specified contents.
+If the value is @code{grow-only}, the tool bar expands automatically,
+but does not contract automatically.
The tool bar contents are controlled by a menu keymap attached to a
fake ``function key'' called @code{tool-bar} (much like the way the menu
image.
The @code{:rtl} property specifies an alternative image to use for
-right-to-left languages. Only the Gtk+ version of Emacs supports this
+right-to-left languages. Only the GTK+ version of Emacs supports this
at present.
Like the menu bar, the tool bar can display separators (@pxref{Menu
Separators}). Tool bar separators are vertical rather than
-horizontal, though, and only a single style is supported. Separators
-are represented in the tool bar keymap in the same way as for the
-menu bar, i.e. using a @code{(menu-item "--"}) entry. The Gtk+ and
-Nextstep tool bars render separators natively, otherwise Emacs selects
-a separator image that is appropriate for the display. Note that tool
-bar separators do not support any properties, such as @code{:visible}.
+horizontal, though, and only a single style is supported. They are
+represented in the tool bar keymap by @code{(menu-item "--")} entries;
+properties like @code{:visible} are not supported for tool bar
+separators. Separators are rendered natively in GTK+ and Nextstep
+tool bars; in the other cases, they are rendered using an image of a
+vertical line.
The default tool bar is defined so that items specific to editing do not
appear for major modes whose command symbol has a @code{mode-class}
@defvar tool-bar-map
By default, the global map binds @code{[tool-bar]} as follows:
+
@example
(global-set-key [tool-bar]
- '(menu-item "tool bar" ignore
- :filter (lambda (ignore) tool-bar-map)))
+ `(menu-item ,(purecopy "tool bar") ignore
+ :filter tool-bar-make-keymap))
@end example
+
@noindent
-Thus the tool bar map is derived dynamically from the value of variable
-@code{tool-bar-map} and you should normally adjust the default (global)
-tool bar by changing that map. Major modes may replace the global bar
-completely by making @code{tool-bar-map} buffer-local and set to a
-keymap containing only the desired items. Info mode provides an
-example.
+The function @code{tool-bar-make-keymap}, in turn, derives the actual
+tool bar map dynamically from the value of the variable
+@code{tool-bar-map}. Hence, you should normally adjust the default
+(global) tool bar by changing that map. Some major modes, such as
+Info mode, completely replace the global tool bar by making
+@code{tool-bar-map} buffer-local and setting it to a different keymap.
@end defvar
There are two convenience functions for defining tool bar items, as