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
nil as Yes, No, or Cancel is
clicked. (Clicking the close box on the dialog is equivalent to
The required arguments are title, which must be a
nil and provides the title of the
dialog (no title for
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
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
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
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
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-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.