Arguments: title choice-list &key stream initial-value allow-multiple simple-click-toggle on-print on-change topmost width height dialog-exterior-box
Displays a modal dialog with title title offering
the choices in choice-list along with OK and
Cancel buttons. Two values are returned: the value or list of values
(if allow-multiple is true) chosen and t if the
OK button is clicked; nil and nil if the Cancel button is clicked. (The second
returned value allows the program to distinguish between the user
selecting the value nil and canceling the
dialog.)
The stream keyword argument specifies the owner of the dialog. The initial-value, which should be an element of choice-list, will be selected when the dialog is displayed. It defaults to the first element of choice-list.
If allow-multiple is true, the first returned value is a list and the user may choose more than one value (with the shift or control keys in the typical Windows manner).
simple-click-toggle has an effect only if
allow-multiple is true. In
that case, if simple-click-toggle is
true, then the user does not need to hold down
the control key while clicking in order to toggle individual
choices. Note, however, that using this feature also disables the
ability to choose a whole range of choices with a shift-click. When
this argument is nil (the default),
Control-click toggles individual choices; Shift-click selects
everything between the thing clicked on and a chosen item above,
inclusive; and a click choose an item and unchooses anything else
selected, all of which is standard Windows behavior.
The on-print argument, if specified, should be a
function of one argument that will be used to print the elements of
choice-list to the dialog. The on-change
argument 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 ask-user-for-choice-from-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.
When topmost 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.
The width and height 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-boxis deprecated in favor of width and height.
The use of dialog-exterior-box is deprecated in favor of the width and height arguments described just above. No value should be specified for this argument if values are specified for width and height (which override this argument). If a value is specified for this argument, it should be a box. The dialog will be that size but the location will still be specified by position-utility-dialog (the top and left of the box are ignored).
Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.
The documentation is described in introduction.htm and the index is in index.htm.
Copyright (c) 1998-2000, Franz Inc. Berkeley, CA., USA. All rights reserved.
Created 2000.10.5.