New function read-multiple-choice

* doc/lispref/commands.texi (Reading One Event): Document
read-multiple-choice.

* lisp/faces.el (read-multiple-choice-face): New face.

* lisp/subr.el (read-multiple-choice): New function.

1 files changed, 21 insertions, 0 deletions

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index 9c1df895161..1964ec8e3fe 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -2617,6 +2617,27 @@ 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
 
+@defun read-multiple-choice prompt choices
+Ask user a multiple choice question. @var{prompt} should be a string
+that will be displayed as the prompt.
+
+@var{choices} is an alist where the first element in each entry is a
+character to be entered, the second element is a short name for the
+entry to be displayed while prompting (if there's room, it might be
+shortened), and the third, optional entry is a longer explanation that
+will be displayed in a help buffer if the user requests more help.
+
+The return value is the matching value from @var{choices}.
+
+@lisp
+(read-multiple-choice
+ "Continue connecting?"
+ '((?a "always" "Accept this certificate this session and for all future sessions.")
+   (?s "session only" "Accept this certificate this session only.")
+   (?n "no" "Refuse to use this certificate, and close the connection.")))
+@end lisp
+@end defun
+
 @node Event Mod
 @subsection Modifying and Translating Input Events
 @cindex modifiers of events