From dac86404ae17873adeff3f1f977b443a72772884 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Sun, 5 Feb 2012 19:20:11 -0800 Subject: [PATCH] Document make-composed-keymap * doc/lispref/keymaps.texi (Inheritance and Keymaps): Mention make-composed-keymap and multiple inheritance. * etc/NEWS: Related edits. --- doc/lispref/ChangeLog | 2 ++ doc/lispref/keymaps.texi | 28 ++++++++++++++++++++++++++++ etc/NEWS | 7 +++++-- 3 files changed, 35 insertions(+), 2 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index e26f91b1b4c..5de2251c19f 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,6 +1,8 @@ 2012-02-06 Glenn Morris * keymaps.texi (Tool Bar): Mention separators. + (Inheritance and Keymaps): + Mention make-composed-keymap and multiple inheritance. * modes.texi (Running Hooks): Mention run-hook-wrapped. diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index 923989413ee..a4c8c3981f3 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -432,6 +432,34 @@ for every numeric character code without modifier bits, even if it is @code{nil}, so these character's bindings are never inherited from the parent keymap. +@cindex keymap inheritance from multiple maps + Sometimes you want to make a keymap that inherits from more than one +map. You can use the function @code{make-composed-keymap} for this. + +@defun make-composed-keymap maps &optional parent +This function returns a new keymap composed of the existing keymap(s) +@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}. +@end defun + +@noindent For example, here is how Emacs sets the parent of +@code{help-mode-map}, such that it inherits from both +@code{button-buffer-map} and @code{special-mode-map}: + +@example +(defvar help-mode-map + (let ((map (make-sparse-keymap))) + (set-keymap-parent map (make-composed-keymap button-buffer-map + special-mode-map)) + ... map) ... ) +@end example + + @node Prefix Keys @section Prefix Keys @cindex prefix key diff --git a/etc/NEWS b/etc/NEWS index f1088874eb8..2e50271d2dd 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1412,8 +1412,11 @@ as well as those in the -*- line. --- ** rx.el has a new `group-n' construct for explicitly numbered groups. -** keymaps can inherit from multiple parents. -There is a new function `make-composed-keymap' that [does something]. ++++ +** New function `make-composed-keymap' that constructs a new keymap +from multiple input maps. You can use this to make a keymap that +inherits from multiple maps, eg: + (set-keymap-parent newmap (make-composed-keymap othermap parent)) +++ ** Set `debug-on-event' to make Emacs enter the debugger e.g. on receipt -- 2.39.2