Commit 7e2734bc authored by Glenn Morris's avatar Glenn Morris
Browse files

Document read-char-choice.

* doc/lispref/commands.texi (Reading One Event):
* doc/lispref/help.texi (Help Functions): Document read-char-choice.
* etc/NEWS: Markup.
parent f58b9822
2012-02-02 Glenn Morris <rgm@gnu.org>
* commands.texi (Reading One Event):
* help.texi (Help Functions): Document read-char-choice.
* hooks.texi (Standard Hooks):
* modes.texi (Keymaps and Minor Modes):
* text.texi (Commands for Insertion): Document post-self-insert-hook.
......
......@@ -2472,6 +2472,17 @@ The argument @var{prompt} is either a string to be displayed in the
echo area as a prompt, or @code{nil}, meaning not to display a prompt.
@end defun
@defun read-char-choice prompt chars &optional inhibit-quit
This function uses @code{read-key} to read and return a single
character. It ignores any input that is not a member of @var{chars},
a list of accepted characters. Optionally, it will also ignore
keyboard-quit events while it is waiting for valid input. If you bind
@code{help-form} (@pxref{Help Functions}) to a non-@code{nil} value
while calling @code{read-char-choice}, then pressing @code{help-char}
causes it to evaluate @code{help-form} and display the result. It
then continues to wait for a valid input character, or keyboard-quit.
@end defun
@node Event Mod
@subsection Modifying and Translating Input Events
......
......@@ -582,11 +582,12 @@ If this variable is non-@code{nil}, its value is a form to evaluate
whenever the character @code{help-char} is read. If evaluating the form
produces a string, that string is displayed.
A command that calls @code{read-event} or @code{read-char} probably
should bind @code{help-form} to a non-@code{nil} expression while it
does input. (The time when you should not do this is when @kbd{C-h} has
some other meaning.) Evaluating this expression should result in a
string that explains what the input is for and how to enter it properly.
A command that calls @code{read-event}, @code{read-char-choice}, or
@code{read-char} probably should bind @code{help-form} to a
non-@code{nil} expression while it does input. (The time when you
should not do this is when @kbd{C-h} has some other meaning.)
Evaluating this expression should result in a string that explains
what the input is for and how to enter it properly.
Entry to the minibuffer binds this variable to the value of
@code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
......
......@@ -1253,6 +1253,7 @@ jumping all the way to the top-level.
** The function format-time-string now supports the %N directive, for
higher-resolution time stamps.
+++
** New function `read-char-choice' reads a restricted set of characters,
discarding any inputs not inside the set.
......
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