Commit 921c067f authored by Glenn Morris's avatar Glenn Morris
Browse files

Document set-temporary-overlay-map

* doc/lispref/keymaps.texi (Active Keymaps, Searching Keymaps)
(Controlling Active Maps): Document set-temporary-overlay-map.

* etc/NEWS: Related markup.
parent e0ea8060
......@@ -2,6 +2,8 @@
* keymaps.texi (Searching Keymaps, Tool Bar): Untabify examples,
so they align better in info.
(Active Keymaps, Searching Keymaps, Controlling Active Maps):
Document set-temporary-overlay-map.
2012-11-12 Glenn Morris <rgm@gnu.org>
......
......@@ -664,7 +664,9 @@ additional active keymaps through the variable
The highest precedence normal keymap comes from the @code{keymap}
text or overlay property. If that is non-@code{nil}, it is the first
keymap to be processed, in normal circumstances.
keymap to be processed, in normal circumstances. Next comes
any keymap added by the function @code{set-temporary-overlay-map}.
@xref{Controlling Active Maps}.
However, there are also special ways for programs to substitute
other keymaps for some of those. The variable
......@@ -753,6 +755,7 @@ them:
(overriding-local-map
(@var{find-in} overriding-local-map))
((or (@var{find-in} (get-char-property (point) 'keymap))
(@var{find-in} @var{temp-map})
(@var{find-in-any} emulation-mode-map-alists)
(@var{find-in-any} minor-mode-overriding-map-alist)
(@var{find-in-any} minor-mode-map-alist)
......@@ -770,7 +773,8 @@ 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.
instead of the buffer. @var{temp-map} is a pseudo variable that
represents the effect of a @code{set-temporary-overlay-map} call.
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
......@@ -950,6 +954,21 @@ are used before @code{minor-mode-map-alist} and
@code{minor-mode-overriding-map-alist}.
@end defvar
@defun set-temporary-overlay-map keymap &optional keep
This function adds @var{keymap} as a temporary keymap that takes
precedence over most other keymaps. It does not take precedence over
the ``overriding'' maps (see above); and unlike them, if no match for
a key is found in @var{keymap}, the search continues.
Normally, @var{keymap} is used only once. If the optional argument
@var{pred} is @code{t}, the map stays active if a key from @var{keymap}
is used. @var{pred} can also be a function of no arguments: if it returns
non-@code{nil} then @var{keymap} stays active.
For a pseudo-Lisp description of exactly how and when this keymap applies,
@pxref{Searching Keymaps}.
@end defun
@node Key Lookup
@section Key Lookup
@cindex key lookup
......
......@@ -932,7 +932,7 @@ describing the cycle.
*** `function-get' fetches a function property, following aliases.
+++
*** `posnp' tests if an object is a `posn'.
+++
*** `set-temporary-overlay-map' sets up a temporary keymap that
takes precedence over most other maps for a short while (normally one key).
+++
......
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