yes-no-or-cancel-list

Function

Package: cg

ToC

DocOverview

CGDoc

RelNotes

Index

PermutedIndex

Allegro CL version 7.0
Object described on page has changed in 7.0.

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.