ask-user-for-choice

Arguments: prompt button1 &optional button2 button3 button4 title stream &key topmost

This is another version of pop-up-message-dialog. A dialog is displayed with as many buttons (one, two, three, or four) as are specified non-nil. The user clicks on a button and the value of that button (the value specified as the argument) is returned.

If the user cancels the dialog by clicking on the close box or pressing the Escape key, ask-user-for-choice returns the same as if the rightmost non-nil button was clicked. If the user hits Enter, the value of button1 is returned. That is, the leftmost button (button1, which must be non-nil) acts as the default button and the rightmost non-nil button acts as the cancel button. If there is only one button (button2, button3, and button4 are all nil), then any action (clicking on it, pressing Escape, pressing Enter, or clicking on the close button) causes button1 to be returned.

If you have more than four choices, you can use ask-user-for-choice-from-list.

The arguments are:

• prompt: should be a string. It will be displayed in the dialog.
• button1: the value can be a symbol or a string naming the button, or a list whose first element is a symbol or string naming the button and whose second element is a help string. The button is labeled with the string or the print name of the symbol. If a help string is provided, it is displayed in the status bar when the cursor is over the button. If the user clicks on this button, the arguments value (a symbol, a string, or a list of a symbol or string and a string) is returned.
• button2, button3, and button4: the value can be a symbol or a string naming the button, or a list whose first element is a symbol or string naming the button and whose second element is a help string, or nil. If the value is nil, the button is not displayed. The button is labeled with the string or the print name of the symbol. If a help string is provided, it is displayed in the status bar when the cursor is over the button. If the user clicks on this button, the arguments value (a symbol, a string, or a list of a symbol or string and a string) is returned.
• title: this argument provides the title for the dialog. Its value should be a string. Note that all optional button arguments must be specified to supply a title (to preserve backward compatibility). Specify nil for a button that should not be displayed. If no title is specified, none is used.
• stream: the owning window of the dialog; defaults to the stream returned by selected-window-or-screen. Note that all optional button arguments and the title must be specified to supply stream. Specify nil for a button that should not be displayed and for title if you want no title.
• topmost: when this argument is true, the utility dialog invoked by this function will be topmost while it is present. A topmost window is one that remains on top of all other non-topmost windows, even those in other applications. This feature is particularly useful for modal dialogs that need to alert the user even if they have switched to another application. Note that all optional arguments must be specified to specify a value for topmost.

The position of the dialog when displayed is controlled by position-utility-dialog.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.