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

Improve documentation of 'read-choice' and related symbols

Browse source 
* doc/lispref/commands.texi (Reading One Event):
* lisp/subr.el (read-char-choice-use-read-key, read-char-choice)
(read-char-choice-with-read-key, y-or-n-p-use-read-key): Improve
documentation of these functions and variables.
This commit is contained in:
Eli Zaretskii 2023-03-28 21:08:12 +03:00
parent a8c9283e17
commit c1eac5b658
2 changed files with 45 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
doc/lispref/commands.texi
View file

@ -3215,15 +3215,24 @@ unspecified, the only fallback disabled is downcasing of the last
event.
@end defun
@vindex read-char-choice-use-read-key
@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.
This function uses @code{read-from-minibuffer} to read and return a
single character that is a member of @var{chars}, which should be a
list of single characters. It discards any input characters that are
not members of @var{chars}, and shows a message to that effect.
The optional argument @var{inhibit-quit} is by default ignored, but if
the variable @code{read-char-choice-use-read-key} is non-@code{nil},
this function uses @code{read-key} instead of
@code{read-from-minibuffer}, and in that case @var{inhibit-quit}
non-@code{nil} means ignore keyboard-quit events while waiting for
valid input. In addition, if @code{read-char-choice-use-read-key} is
non-@code{nil}, binding @code{help-form} (@pxref{Help Functions}) to a
non-@code{nil} value while calling this function causes it to evaluate
@code{help-form} and display the result when the user presses
@code{help-char}; it then continues to wait for a valid input
character, or for keyboard-quit.
@end defun
@defun read-multiple-choice prompt choices &optional help-string show-help long-form

52
lisp/subr.el
View file

@ -3196,34 +3196,38 @@ This function is used by the `interactive' code letter \"n\"."
n))
(defvar read-char-choice-use-read-key nil
"Prefer `read-key' when reading a character by `read-char-choice'.
Otherwise, use the minibuffer.
"If non-nil, use `read-key' when reading a character by `read-char-choice'.
Otherwise, use the minibuffer (this is the default).
When using the minibuffer, the user is less constrained, and can
use the normal commands available in the minibuffer, and can, for
instance, switch to another buffer, do things there, and then
switch back again to the minibuffer before entering the
character. This is not possible when using `read-key', but using
`read-key' may be less confusing to some users.")
When reading via the minibuffer, you can use the normal commands
available in the minibuffer, and can, for instance, temporarily
switch to another buffer, do things there, and then switch back
to the minibuffer before entering the character. This is not
possible when using `read-key', but using `read-key' may be less
confusing to some users.")
(defun read-char-choice (prompt chars &optional inhibit-keyboard-quit)
"Read and return one of CHARS, prompting for PROMPT.
Any input that is not one of CHARS is ignored.
"Read and return one of the characters in CHARS, prompting with PROMPT.
CHARS should be a list of single characters.
The function discards any input character that is not one of CHARS,
and shows a message to the effect that it is not one of the expected
charcaters.
By default, the minibuffer is used to read the key
non-modally (see `read-char-from-minibuffer'). If
`read-char-choice-use-read-key' is non-nil, the modal `read-key'
function is used instead (see `read-char-choice-with-read-key')."
By default, use the minibuffer to read the key non-modally (see
`read-char-from-minibuffer'). But if `read-char-choice-use-read-key'
is non-nil, the modal `read-key' function is used instead (see
`read-char-choice-with-read-key')."
(if (not read-char-choice-use-read-key)
(read-char-from-minibuffer prompt chars)
(read-char-choice-with-read-key prompt chars inhibit-keyboard-quit)))
(defun read-char-choice-with-read-key (prompt chars &optional inhibit-keyboard-quit)
"Read and return one of CHARS, prompting for PROMPT.
"Read and return one of the characters in CHARS, prompting with PROMPT.
CHARS should be a list of single characters.
Any input that is not one of CHARS is ignored.
If optional argument INHIBIT-KEYBOARD-QUIT is non-nil, ignore
`keyboard-quit' events while waiting for a valid input.
`keyboard-quit' events while waiting for valid input.
If you bind the variable `help-form' to a non-nil value
while calling this function, then pressing `help-char'
@ -3519,15 +3523,15 @@ Also discard all previous input in the minibuffer."
(sit-for 2)))
(defvar y-or-n-p-use-read-key nil
"Prefer `read-key' when answering a \"y or n\" question by `y-or-n-p'.
Otherwise, use the minibuffer.
"Use `read-key' when reading answers to \"y or n\" questions by `y-or-n-p'.
Otherwise, use the `read-from-minibuffer' to read the answers.
When using the minibuffer, the user is less constrained, and can
use the normal commands available in the minibuffer, and can, for
instance, switch to another buffer, do things there, and then
switch back again to the minibuffer before entering the
character. This is not possible when using `read-key', but using
`read-key' may be less confusing to some users.")
When reading via the minibuffer, you can use the normal commands
available in the minibuffer, and can, for instance, temporarily
switch to another buffer, do things there, and then switch back
to the minibuffer before entering the character. This is not
possible when using `read-key', but using `read-key' may be less
confusing to some users.")
(defvar from--tty-menu-p nil
"Non-nil means the current command was invoked from a TTY menu.")