@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
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
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.
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
(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
HCoop / bpt / emacs.git / commitdiff