Commit 3d8badf4 authored by Chong Yidong's avatar Chong Yidong
Browse files

Update Keymaps chapter of Lisp manual.

* doc/emacs/keymaps.texi (Format of Keymaps): The CACHE component of keymaps
was removed on 2009-09-10.  Update lisp-mode-map example.
(Inheritance and Keymaps): Minor clarification.
(Searching Keymaps): Remove out-of-place enumeration.
(Key Lookup): Remove unnecessary example (one was already given in
Format of Keymaps).
(Changing Key Bindings): Update suppress-keymap example.
(Menu Bar, Tool Bar): Copyedits.
(Tool Bar): Update tool-bar-map example.
parent 835bdcba
...@@ -204,7 +204,7 @@ hooks.texi ...@@ -204,7 +204,7 @@ hooks.texi
index.texi index.texi
internals.texi internals.texi
intro.texi cyd intro.texi cyd
keymaps.texi keymaps.texi cyd
lists.texi cyd lists.texi cyd
loading.texi cyd loading.texi cyd
locals.texi locals.texi
......
2012-02-14 Chong Yidong <cyd@gnu.org>
* keymaps.texi (Format of Keymaps): The CACHE component of keymaps
was removed on 2009-09-10. Update lisp-mode-map example.
(Inheritance and Keymaps): Minor clarification.
(Searching Keymaps): Remove out-of-place enumeration.
(Key Lookup): Remove unnecessary example (one was already given in
Format of Keymaps).
(Changing Key Bindings): Update suppress-keymap example.
(Menu Bar, Tool Bar): Copyedits.
(Tool Bar): Update tool-bar-map example.
2012-02-12 Chong Yidong <cyd@gnu.org> 2012-02-12 Chong Yidong <cyd@gnu.org>
* debugging.texi (Debugger Commands): Continuing is now allowed * debugging.texi (Debugger Commands): Continuing is now allowed
......
...@@ -173,13 +173,11 @@ ordinary binding applies to events of a particular @dfn{event type}, ...@@ -173,13 +173,11 @@ ordinary binding applies to events of a particular @dfn{event type},
which is always a character or a symbol. @xref{Classifying Events}. which is always a character or a symbol. @xref{Classifying Events}.
In this kind of binding, @var{binding} is a command. 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 This specifies a binding which is also a simple menu item that
displays as @var{item-name} in the menu. @var{cache}, if present, displays as @var{item-name} in the menu. @xref{Simple Menu Items}.
caches certain information for display 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}. This is a simple menu item with help string @var{help-string}.
@item (@var{type} menu-item .@: @var{details}) @item (@var{type} menu-item .@: @var{details})
...@@ -234,8 +232,9 @@ other input events; thus, @kbd{M-@key{end}} has nothing to do with ...@@ -234,8 +232,9 @@ other input events; thus, @kbd{M-@key{end}} has nothing to do with
@kbd{@key{ESC} @key{end}}. @kbd{@key{ESC} @key{end}}.
Here as an example is the local keymap for Lisp mode, a sparse 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 keymap. It defines bindings for @key{DEL}, @kbd{C-c C-z},
C-l}, @kbd{M-C-q}, and @kbd{M-C-x}. @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 @example
@group @group
...@@ -250,11 +249,8 @@ lisp-mode-map ...@@ -250,11 +249,8 @@ lisp-mode-map
@end group @end group
@group @group
(27 keymap (27 keymap
;; @r{@kbd{M-C-x}, treated as @kbd{@key{ESC} C-x}} ;; @r{@kbd{C-M-x}, treated as @kbd{@key{ESC} C-x}}
(24 . lisp-send-defun) (24 . lisp-send-defun))
keymap
;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}}
(17 . indent-sexp))
@end group @end group
@group @group
;; @r{This part is inherited from @code{lisp-mode-shared-map}.} ;; @r{This part is inherited from @code{lisp-mode-shared-map}.}
...@@ -264,9 +260,8 @@ lisp-mode-map ...@@ -264,9 +260,8 @@ lisp-mode-map
@end group @end group
@group @group
(27 keymap (27 keymap
;; @r{@kbd{M-C-q}, treated as @kbd{@key{ESC} C-q}} ;; @r{@kbd{C-M-q}, treated as @kbd{@key{ESC} C-q}}
(17 . indent-sexp)) (17 . indent-sexp)))
(9 . lisp-indent-line))
@end group @end group
@end example @end example
...@@ -441,10 +436,10 @@ This function returns a new keymap composed of the existing keymap(s) ...@@ -441,10 +436,10 @@ This function returns a new keymap composed of the existing keymap(s)
@var{maps}, and optionally inheriting from a parent keymap @var{maps}, and optionally inheriting from a parent keymap
@var{parent}. @var{maps} can be a single keymap or a list of more @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 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 searches in each of the @var{maps} in turn, and then in @var{parent},
at the first match. A @code{nil} binding in any one of @var{maps} stopping at the first match. A @code{nil} binding in any one of
overrides any binding in @var{parent}, but not a non-@code{nil} binding @var{maps} overrides any binding in @var{parent}, but it does not
in any other of the @var{maps}. override any non-@code{nil} binding in any other of the @var{maps}.
@end defun @end defun
@noindent For example, here is how Emacs sets the parent of @noindent For example, here is how Emacs sets the parent of
...@@ -762,35 +757,23 @@ them: ...@@ -762,35 +757,23 @@ them:
@end lisp @end lisp
@noindent @noindent
The @var{find-in} and @var{find-in-any} are pseudo functions that @var{find-in} and @var{find-in-any} are pseudo functions that search
search in one keymap and in an alist of keymaps, respectively. in one keymap and in an alist of keymaps, respectively. (Searching a
(Searching a single keymap for a binding is called @dfn{key lookup}; single keymap for a binding is called @dfn{key lookup}; see @ref{Key
see @ref{Key Lookup}.) If the key sequence starts with a mouse event, Lookup}.) If the key sequence starts with a mouse event, or a
or a symbolic prefix event followed by a mouse event, that event's symbolic prefix event followed by a mouse event, that event's position
position is used instead of point and the current buffer. Mouse is used instead of point and the current buffer. Mouse events on an
events on an embedded string use non-@code{nil} text properties from embedded string use non-@code{nil} text properties from that string
that string instead of the buffer. instead of the buffer.
@enumerate When a match is found (@pxref{Key Lookup}), if the binding in the
@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
keymap is a function, the search is over. However if the keymap entry 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 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 sequences with the variable's value or the string, and restarts the
search of the active keymaps. search of the active keymaps.
@end enumerate
The function finally found might also be remapped. @xref{Remapping
Commands}.
@node Controlling Active Maps @node Controlling Active Maps
@section Controlling the Active Keymaps @section Controlling the Active Keymaps
...@@ -1088,21 +1071,9 @@ lookup form a complete key, and the object is its binding, but the ...@@ -1088,21 +1071,9 @@ lookup form a complete key, and the object is its binding, but the
binding is not executable as a command. binding is not executable as a command.
@end table @end table
In short, a keymap entry may be a keymap, a command, a keyboard macro, In short, a keymap entry may be a keymap, a command, a keyboard
a symbol that leads to one of them, or an indirection or @code{nil}. macro, a symbol that leads to one of them, or an indirection or
Here is an example of a sparse keymap with two characters bound to @code{nil}.
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
@node Functions for Key Lookup @node Functions for Key Lookup
@section Functions for Key Lookup @section Functions for Key Lookup
...@@ -1472,23 +1443,21 @@ that is used for some other purpose is likely to cause trouble; for ...@@ -1472,23 +1443,21 @@ that is used for some other purpose is likely to cause trouble; for
example, suppressing @code{global-map} would make it impossible to use example, suppressing @code{global-map} would make it impossible to use
most of Emacs. most of Emacs.
Most often, @code{suppress-keymap} is used to initialize local This function can be used to initialize the local keymap of a major
keymaps of modes such as Rmail and Dired where insertion of text is not mode for which insertion of text is not desirable. But usually such a
desirable and the buffer is read-only. Here is an example taken from mode should be derived from @code{special-mode} (@pxref{Basic Major
the file @file{emacs/lisp/dired.el}, showing how the local keymap for Modes}); then its keymap will automatically inherit from
Dired mode is set up: @code{special-mode-map}, which is already suppressed. Here is how
@code{special-mode-map} is defined:
@smallexample @smallexample
@group @group
(setq dired-mode-map (make-keymap)) (defvar special-mode-map
(suppress-keymap dired-mode-map) (let ((map (make-sparse-keymap)))
(define-key dired-mode-map "r" 'dired-rename-file) (suppress-keymap map)
(define-key dired-mode-map "\C-d" 'dired-flag-file-deleted) (define-key map "q" 'quit-window)
(define-key dired-mode-map "d" 'dired-flag-file-deleted) @dots{}
(define-key dired-mode-map "v" 'dired-view-file) map))
(define-key dired-mode-map "e" 'dired-find-file)
(define-key dired-mode-map "f" 'dired-find-file)
@dots{}
@end group @end group
@end smallexample @end smallexample
@end defun @end defun
...@@ -2064,12 +2033,10 @@ event type (it doesn't matter what event type) to a binding like this: ...@@ -2064,12 +2033,10 @@ event type (it doesn't matter what event type) to a binding like this:
@noindent @noindent
The @sc{car}, @var{item-string}, is the string to be displayed in the 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 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 describe the action of the command it corresponds to. Note that not
not generally possible to display non-@acronym{ASCII} text in menus. It will all graphical toolkits can display non-@acronym{ASCII} text in menus
work for keyboard menus and will work to a large extent when Emacs is (it will work for keyboard menus and will work to a large extent with
built with the Gtk+ toolkit.@footnote{In this case, the text is first the GTK+ toolkit).
encoded using the @code{utf-8} coding system and then rendered by the
toolkit as it sees fit.}
You can also supply a second string, called the help string, as follows: You can also supply a second string, called the help string, as follows:
...@@ -2418,18 +2385,6 @@ this; @key{SPC} is the default.) ...@@ -2418,18 +2385,6 @@ this; @key{SPC} is the default.)
she should type the corresponding character---the one whose binding is she should type the corresponding character---the one whose binding is
that alternative. 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 @defvar menu-prompt-more-char
This variable specifies the character to use to ask to see This variable specifies the character to use to ask to see
the next line of a menu. Its initial value is 32, the code the next line of a menu. Its initial value is 32, the code
...@@ -2512,21 +2467,17 @@ can do it this way: ...@@ -2512,21 +2467,17 @@ can do it this way:
@subsection The Menu Bar @subsection The Menu Bar
@cindex menu bar @cindex menu bar
Most window systems allow each frame to have a @dfn{menu bar}---a On graphical displays, there is usually a @dfn{menu bar} at the top
permanently displayed menu stretching horizontally across the top of of each frame. @xref{Menu Bars,,,emacs, The GNU Emacs Manual}. Menu
the frame. (In order for a frame to display a menu bar, its bar items are subcommands of the fake ``function key''
@code{menu-bar-lines} parameter must be greater than zero. @code{menu-bar}, as defined in the active keymaps.
@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.
To add an item to the menu bar, invent a fake ``function key'' of your 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 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, @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. 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 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 that menu bar item, it brings up a single, combined menu containing
all the subcommands of that item---the global subcommands, the local all the subcommands of that item---the global subcommands, the local
...@@ -2540,11 +2491,6 @@ were @code{nil}. @xref{Active Keymaps}. ...@@ -2540,11 +2491,6 @@ were @code{nil}. @xref{Active Keymaps}.
Here's an example of setting up a menu bar item: Here's an example of setting up a menu bar item:
@example @example
@group
(modify-frame-parameters (selected-frame)
'((menu-bar-lines . 2)))
@end group
@group @group
;; @r{Make a menu keymap (with a prompt string)} ;; @r{Make a menu keymap (with a prompt string)}
;; @r{and make it the menu bar item's definition.} ;; @r{and make it the menu bar item's definition.}
...@@ -2618,20 +2564,17 @@ that the command does not actually have, it is ignored. ...@@ -2618,20 +2564,17 @@ that the command does not actually have, it is ignored.
@subsection Tool bars @subsection Tool bars
@cindex tool bar @cindex tool bar
A @dfn{tool bar} is a row of icons at the top of a frame, that execute A @dfn{tool bar} is a row of clickable icons at the top of a frame,
commands when you click on them---in effect, a kind of graphical menu just below the menu bar. @xref{Tool Bars,,,emacs, The GNU Emacs
bar. Manual}.
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.
If the value of @code{auto-resize-tool-bars} is @code{grow-only}, On each frame, the frame parameter @code{tool-bar-lines} controls
the tool bar expands automatically, but does not contract automatically. how many lines' worth of height to reserve for the tool bar. A zero
To contract the tool bar, the user has to redraw the frame by entering value suppresses the tool bar. If the value is nonzero, and
@kbd{C-l}. @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 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 fake ``function key'' called @code{tool-bar} (much like the way the menu
...@@ -2683,17 +2626,17 @@ button in disabled state by applying an edge-detection algorithm to the ...@@ -2683,17 +2626,17 @@ button in disabled state by applying an edge-detection algorithm to the
image. image.
The @code{:rtl} property specifies an alternative image to use for 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. at present.
Like the menu bar, the tool bar can display separators (@pxref{Menu Like the menu bar, the tool bar can display separators (@pxref{Menu
Separators}). Tool bar separators are vertical rather than Separators}). Tool bar separators are vertical rather than
horizontal, though, and only a single style is supported. Separators horizontal, though, and only a single style is supported. They are
are represented in the tool bar keymap in the same way as for the represented in the tool bar keymap by @code{(menu-item "--")} entries;
menu bar, i.e. using a @code{(menu-item "--"}) entry. The Gtk+ and properties like @code{:visible} are not supported for tool bar
Nextstep tool bars render separators natively, otherwise Emacs selects separators. Separators are rendered natively in GTK+ and Nextstep
a separator image that is appropriate for the display. Note that tool tool bars; in the other cases, they are rendered using an image of a
bar separators do not support any properties, such as @code{:visible}. vertical line.
The default tool bar is defined so that items specific to editing do not 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} appear for major modes whose command symbol has a @code{mode-class}
...@@ -2706,18 +2649,20 @@ using an indirection through @code{tool-bar-map}. ...@@ -2706,18 +2649,20 @@ using an indirection through @code{tool-bar-map}.
@defvar tool-bar-map @defvar tool-bar-map
By default, the global map binds @code{[tool-bar]} as follows: By default, the global map binds @code{[tool-bar]} as follows:
@example @example
(global-set-key [tool-bar] (global-set-key [tool-bar]
'(menu-item "tool bar" ignore `(menu-item ,(purecopy "tool bar") ignore
:filter (lambda (ignore) tool-bar-map))) :filter tool-bar-make-keymap))
@end example @end example
@noindent @noindent
Thus the tool bar map is derived dynamically from the value of variable The function @code{tool-bar-make-keymap}, in turn, derives the actual
@code{tool-bar-map} and you should normally adjust the default (global) tool bar map dynamically from the value of the variable
tool bar by changing that map. Major modes may replace the global bar @code{tool-bar-map}. Hence, you should normally adjust the default
completely by making @code{tool-bar-map} buffer-local and set to a (global) tool bar by changing that map. Some major modes, such as
keymap containing only the desired items. Info mode provides an Info mode, completely replace the global tool bar by making
example. @code{tool-bar-map} buffer-local and setting it to a different keymap.
@end defvar @end defvar
There are two convenience functions for defining tool bar items, as There are two convenience functions for defining tool bar items, as
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment