A dialog box is a variant of a pop-up menu—it looks a little
different, it always appears in the center of a frame, and it has just
one level and one or more buttons. The main use of dialog boxes is
for asking questions that the user can answer with “yes”, “no”,
and a few other alternatives. With a single button, they can also
force the user to acknowledge important information. The functions
y-or-n-p and yes-or-no-p use dialog boxes instead of the
keyboard, when called from commands invoked by mouse clicks.
This function displays a pop-up dialog box and returns an indication of what selection the user makes. The argument contents specifies the alternatives to offer; it has this format:
(title (string . value)…)
which looks like the list that specifies a single pane for
x-popup-menu.
The return value is value from the chosen alternative.
As for x-popup-menu, an element of the list may be just a
string instead of a cons cell (string . value).
That makes a box that cannot be selected.
If nil appears in the list, it separates the left-hand items from
the right-hand items; items that precede the nil appear on the
left, and items that follow the nil appear on the right. If you
don’t include a nil in the list, then approximately half the
items appear on each side.
Dialog boxes always appear in the center of a frame; the argument
position specifies which frame. The possible values are as in
x-popup-menu, but the precise coordinates or the individual
window don’t matter; only the frame matters.
If header is non-nil, the frame title for the box is
‘Information’, otherwise it is ‘Question’. The former is used
for message-box (see message-box). (On text terminals, the
box title is not displayed.)
In some configurations, Emacs cannot display a real dialog box; so instead it displays the same items in a pop-up menu in the center of the frame.
If the user gets rid of the dialog box without making a valid choice,
for instance using the window manager, then this produces a quit and
x-popup-dialog does not return.