ask-user-for-choice-from-list

Function

Package: common-graphics

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.