Function: read-multiple-choice

read-multiple-choice is a byte-compiled function defined in rmc.el.gz.

Signature

(read-multiple-choice PROMPT CHOICES &optional HELP-STRING SHOW-HELP LONG-FORM)

Documentation

Ask user to select an entry from CHOICES, prompting with PROMPT.

This function allows to ask the user a multiple-choice question.

CHOICES should be a list of the form (KEY NAME [DESCRIPTION]). KEY is a character the user should type to select the entry. NAME is a short name for the entry to be displayed while prompting
(if there's no room, it might be shortened).
DESCRIPTION is an optional longer description of the entry; it will be displayed in a help buffer if the user requests more help. This help description has a fixed format in columns. For greater flexibility, instead of passing a DESCRIPTION, the caller can pass the optional argument HELP-STRING. This argument is a string that should contain a more detailed description of all of the possible choices. read-multiple-choice will display that description in a help buffer if the user requests that. If optional argument SHOW-HELP is non-nil, show the help screen immediately, before any user input. If SHOW-HELP is a string, use it as the name of the help buffer.

This function translates user input into responses by consulting the bindings in query-replace-map; see the documentation of that variable for more information. The relevant bindings for the purposes of this function are recenter, scroll-up, scroll-down, and edit. If the user types the recenter, scroll-up, or scroll-down responses, the function performs the requested window recentering or scrolling, and then asks the question again. If the user enters edit, the function starts a recursive edit. When the user exit the recursive edit, the multiple-choice prompt gains focus again.

When use-dialog-box is t (the default), and the command using this function was invoked via the mouse, this function pops up a GUI dialog to collect the user input, but only if Emacs is capable of using GUI dialogs. Otherwise, the function will always use text-mode dialogs.

The return value is the matching entry from the CHOICES list.

If LONG-FORM is non-nil, do a completing-read over the NAME elements in CHOICES instead. In this case, GUI dialog is not used, regardless of the value of use-dialog-box and whether the function was invoked via a mouse gesture.

Usage example:

(read-multiple-choice "Continue connecting?"
                      '((?a "always")
                        (?s "session only")
                        (?n "no")))

View in manual

Probably introduced at or before Emacs version 26.1.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/rmc.el.gz
;;;###autoload
(defun read-multiple-choice (prompt choices &optional help-string show-help
                                    long-form)
  "Ask user to select an entry from CHOICES, prompting with PROMPT.
This function allows to ask the user a multiple-choice question.

CHOICES should be a list of the form (KEY NAME [DESCRIPTION]).
KEY is a character the user should type to select the entry.
NAME is a short name for the entry to be displayed while prompting
\(if there's no room, it might be shortened).
DESCRIPTION is an optional longer description of the entry; it will
be displayed in a help buffer if the user requests more help.  This
help description has a fixed format in columns.  For greater
flexibility, instead of passing a DESCRIPTION, the caller can pass
the optional argument HELP-STRING.  This argument is a string that
should contain a more detailed description of all of the possible
choices.  `read-multiple-choice' will display that description in a
help buffer if the user requests that.
If optional argument SHOW-HELP is non-nil, show the help screen
immediately, before any user input.  If SHOW-HELP is a string,
use it as the name of the help buffer.

This function translates user input into responses by consulting
the bindings in `query-replace-map'; see the documentation of
that variable for more information.  The relevant bindings for the
purposes of this function are `recenter', `scroll-up', `scroll-down',
and `edit'.
If the user types the `recenter', `scroll-up', or `scroll-down'
responses, the function performs the requested window recentering or
scrolling, and then asks the question again.  If the user enters `edit',
the function starts a recursive edit.  When the user exit the recursive
edit, the multiple-choice prompt gains focus again.

When `use-dialog-box' is t (the default), and the command using this
function was invoked via the mouse, this function pops up a GUI dialog
to collect the user input, but only if Emacs is capable of using GUI
dialogs.  Otherwise, the function will always use text-mode dialogs.

The return value is the matching entry from the CHOICES list.

If LONG-FORM is non-nil, do a `completing-read' over the NAME elements
in CHOICES instead.  In this case, GUI dialog is not used, regardless
of the value of `use-dialog-box' and whether the function was invoked
via a mouse gesture.

Usage example:

\(read-multiple-choice \"Continue connecting?\"
                      \\='((?a \"always\")
                        (?s \"session only\")
                        (?n \"no\")))"
  (if long-form
      (read-multiple-choice--long-answers prompt choices)
    (read-multiple-choice--short-answers
     prompt choices help-string show-help)))