ask-user-for-choice-from-list

Arguments: title choice-list &key stream initial-value allow-multiple simple-click-toggle (on-print (quote princ-to-string)) 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 keyword arguments are:

• stream: this keyword argument specifies the owner of the dialog. It defaults to the stream returned by selected-window-or-screen.
• initial-value: specifies the value or values (if any) that should already be selected when the dialog appears, typically as a suggested default choice. The value may be either an element of choice-list or else nil to select no value. If allow-multiple is true, then the value may alternately be a list containing any subset of the choice-list elements. If the argument is not specified (as opposed to specifying nil), then the first choice in choice-list will be selected.
• allow-multiple: if 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 chooses an item and unchooses anything else selected, all of which is standard Windows behavior.
• on-print: if specified, the value should be a function of one argument that returns a string. The strings resulting from applying the function to each element of the list will be used to print the elements of choice-list in the dialog. The value can be a function name or a function object. (See the similar on-print event handler for dialogs, whose value must be the name of a function of one argument that returns a string.) The default value is princ-to-string. Here is an example, where the choice-list contains integers and they are incremented by 1 before being displayed:

  (ask-user-for-choice-from-list "X" (list 4 5 6) 
                                 :on-print 
                                  #'(lamdba (x) 
                                            (format nil "~D" (+ 1 x))))
  

• 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 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.
• 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.
• 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 specified, should be a box (see make-box). The dialog will be the size of the box but the location will be specified by position-utility-dialog (the top and left of the box are ignored). Again, use of this argument 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).

An alternative way to ask the user for a choice from a list, especially if the list of choices is small, is to call pop-up-menu, pop-up-lettered-menu, or pop-up-shortcut-menu. For four choices or fewer, ask-user-for-choice may be used. See also yes-no-or-cancel-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.