procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document read-char-choice.

Browse source 
* doc/lispref/commands.texi (Reading One Event):
* doc/lispref/help.texi (Help Functions): Document read-char-choice.
* etc/NEWS: Markup.
This commit is contained in:
Glenn Morris 2012-02-01 23:06:37 -08:00
parent f58b982241
commit 7e2734bc38
4 changed files with 21 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
doc/lispref/ChangeLog
View file

@ -1,5 +1,8 @@
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.

11
doc/lispref/commands.texi
View file

@ -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

11
doc/lispref/help.texi
View file

@ -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}).

1
etc/NEWS
View file

@ -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.