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
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.
-
-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')."
+ "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, 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'
(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.
-
-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.")
+ "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 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.")