diff options
Diffstat (limited to 'lispref')
| -rw-r--r-- | lispref/keymaps.texi | 85 |
1 files changed, 58 insertions, 27 deletions
diff --git a/lispref/keymaps.texi b/lispref/keymaps.texi index 8182e18014d..77ac4ecce75 100644 --- a/lispref/keymaps.texi +++ b/lispref/keymaps.texi @@ -276,30 +276,51 @@ definition is a keymap; the same symbol appears in the new copy. @cindex keymap inheritance @cindex inheriting a keymap's bindings - A keymap can inherit the bindings of another keymap. Do do this, make -a keymap whose ``tail'' is another existing keymap to inherit from. -Such a keymap looks like this: + A keymap can inherit the bindings of another keymap, which we call the +@dfn{parent keymap}. Such a keymap looks like this: @example -(keymap @var{bindings}@dots{} . @var{other-keymap}) +(keymap @var{bindings}@dots{} . @var{parent-keymap}) @end example @noindent The effect is that this keymap inherits all the bindings of -@var{other-keymap}, whatever they may be at the time a key is looked up, +@var{parent-keymap}, whatever they may be at the time a key is looked up, but can add to them or override them with @var{bindings}. -If you change the bindings in @var{other-keymap} using @code{define-key} +If you change the bindings in @var{parent-keymap} using @code{define-key} or other key-binding functions, these changes are visible in the inheriting keymap unless shadowed by @var{bindings}. The converse is not true: if you use @code{define-key} to change the inheriting keymap, -that affects @var{bindings}, but has no effect on @var{other-keymap}. +that affects @var{bindings}, but has no effect on @var{parent-keymap}. + +The proper way to construct a keymap with a parent is to use +@code{set-keymap-parent}; if you have code that directly constructs a +keymap with a parent, please convert the program to use +@code{set-keymap-parent} instead. + +@defun keymap-parent keymap +This returns the parent keymap of @var{keymap}. If @var{keymap} +has no parent, @code{keymap-parent} returns @code{nil}. +@end defun + +@defun set-keymap-parent keymap parent +This sets the parent keymap of @var{keymap} to @var{parent}, and returns +@var{parent}. If @var{parent} is @code{nil}, this function gives +@var{keymap} no parent at all. + +If @var{keymap} has submaps (bindings for prefix keys), they too receive +new parent keymaps that reflect what @var{parent} specifies for those +prefix keys. +@end defun Here is an example showing how to make a keymap that inherits from @code{text-mode-map}: @example -(setq my-mode-map (cons 'keymap text-mode-map)) +(let ((map (make-sparse-keymap))) + (set-keymap-parent map text-mode-map) + map) @end example @node Prefix Keys @@ -1438,11 +1459,6 @@ binding with an item string looks like this: The item string for a binding should be short---one or two words. It should describe the action of the command it corresponds to. -As far as @code{define-key} is concerned, @var{string} is part of the -event's binding. However, @code{lookup-key} returns just -@var{real-binding}, and only @var{real-binding} is used for executing -the key. - You can also supply a second string, called the help string, as follows: @example @@ -1454,6 +1470,11 @@ how to ignore @var{help-string} in order to extract @var{real-binding}. In the future we may use @var{help-string} as extended documentation for the menu item, available on request. +As far as @code{define-key} is concerned, @var{string} and +@var{help-string} are part of the event's binding. However, +@code{lookup-key} returns just @var{real-binding}, and only +@var{real-binding} is used for executing the key. + If @var{real-binding} is @code{nil}, then @var{string} appears in the menu but cannot be selected. @@ -1470,6 +1491,20 @@ look at a menu. This is because the X toolkit requires the whole tree of menus in advance. To force recalculation of the menu bar, call @code{force-mode-line-update} (@pxref{Mode Line Format}). +You've probably noticed that menu items show the equivalent keyboard key +sequence (if any) to invoke the same command. To save time on +recalculation, menu display caches this information in a sublist in the +binding, like this: + +@c This line is not too long--rms. +@example +(@var{string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding}) +@end example + +Don't put these sublists in the menu item yourself; menu display +calculates them automatically. Don't add keyboard equivalents to the +item strings in a mouse menu, since that is redundant. + Sometimes it is useful to make menu items that use the ``same'' command but with different enable conditions. You can do this by defining alias commands. Here's an example that makes two aliases for @@ -1482,24 +1517,20 @@ commands. Here's an example that makes two aliases for (put 'make-writable 'menu-enable 'buffer-read-only) @end example -You've probably noticed that menu items show the equivalent keyboard key -sequence (if any) to invoke the same command. To save time on -recalculation, menu display caches this information in a sublist in the -binding, like this: +When using aliases in menus, often it is useful to display the +equivalent key bindings for the ``real'' command name, not the aliases +(which typically don't have any key bindings except for the menu +itself). To request this, give the alias symbol a non-@code{nil} +@code{menu-alias} property. Thus, -@c This line is not too long--rms. @example -(@var{string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding}) +(put 'make-read-only 'menu-alias t) +(put 'make-writable 'menu-alias t) @end example -Don't put these sublists in the menu item yourself; menu display -calculates them automatically. Don't add keyboard equivalents to the -item strings in a mouse menu, since that is redundant. - -If an alias command has no keyboard equivalent itself, menus show the -keyboard equivalent of its underlying command. In the example above, -menu items defined to run @code{make-read-only} or @code{make-writable} -would show the keyboard equivalents of @code{toggle-read-only}. +@noindent +causes menu items for @code{make-read-only} and @code{make-writable} to +show the keyboard bindings for @code{toggle-read-only}. @node Mouse Menus @subsection Menus and the Mouse |