yes-no-or-cancel-list

Arguments: title choice-list &key stream allow-multiple initial-value select-all on-print on-change width height dialog-exterior-box topmost

Displays a dialog with Yes, No, and Cancel buttons and a single or multiple item list widget. Two values are returned, the selected value (or the list of selected values if allow-multiple is true) and :yes or :no or nil as Yes, No, or Cancel is clicked. (Clicking the close box on the dialog is equivalent to clicking Cancel.)

The required arguments are title, which must be a string or nil and provides the title of the dialog (no title for nil), and choice-list, which must be a list. The items of choice-list will be displayed in the list widget on the dialog.

The keyword arguments are:

• stream: this argument specifies the owning window. It defaults to the stream returned by selected-window-or-screen.
• allow-multiple: if this argument is true, more than one item in choice-list can be chosen (using the Shift and Control keys in the usual Windows way). If select-all and allow-multiple are true, all items are selected when the dialog is displayed. (select-all is ignored if allow-multiple is not true.)
• initial-value: the value should be a value from choice-list. It will be highlighted when the dialog is displayed. It effectively defaults to the first item of choice-list.
• on-print: if specified, the value should be a function of one argument that will print the item in choice-list to the dialog.
• on-change: the value may be either nil or a function or function name. If true, it is used as the on-change event handler for the item-list of the yes-no-or-cancel-list dialog. The function will therefore be called as the user highlights each choice in the dialog. This may be handy for showing a help message for each choice. The function should take the three arguments widget, new-value, and old-value (as usual with an on-change handler), and should always return true (since returning nil would prevent the user from successfully selecting a choice). The default value of on-change is nil, which causes an internal on-change handler to be used. This argument was added in the 7.0 release.
• width and height: these arguments determine the width and height of the dialog displayed. The positioning of the dialog is determined, then, by position-utility-dialog. width and height should not be specified if dialog-exterior-box is specified, but use of dialog-exterior-box is deprecated in favor of width and height.
• dialog-exterior-box: if a value is specified for this argument, it should be a box (see make-box). The dialog will be the size of the box specified but the location will be specified by position-utility-dialog (thus the top and left of the box are ignored). But, as noted above, the use of dialog-exterior-box is deprecated in favor of the width and height arguments. If values are specified for width and height, no value should be specified for dialog-exterior-box.
• topmost: when 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.

See also y-or-n-dialog and ask-user-for-choice-from-list.

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.