prompt-with-list Function

Summary

Prompts the user to select an item or items from a choice.

Package

capi

Signature

prompt-with-list items message &key choice-class interaction selection selected-item selected-items value-function pane-args popup-args continuation buttons callbacks all-button none-button => result, successp

Arguments

Values

Description

The function prompt-with-list prompts the user with a choice. The user's selection is normally returned by the prompter.

items supplies the items of the choice.

message supplies a title for the choice.

choice-class determines the type of choice used in the dialog. choice-class defaults to list-panel, and must be a subclass of choice.

interaction determines the interaction style of the choice in the dialog. By default interaction is :single-selection. For single selection, the dialog has an OK and a Cancel button, while for other selection styles it has Yes, No and Cancel buttons where Yes means accept the selection, No means accept a null selection and Cancel behaves as normal. Note that interaction :multiple-selection is not supported for lists on macOS.

One of selection, selected-item or selected-items can be used to set the initial selection of the choice.

The primary returned value is usually the selected items, but a value-function can be supplied that gets passed the result and can then return a new result. If value-function is nil (this is the default), then result is simply the selection.

If continuation is non-nil, then it must be a function with a lambda list that accepts two arguments. continuation is called with the values that would normally be returned by prompt-with-list. On Cocoa, passing continuation causes the dialog to be made as a window-modal sheet and prompt-with-list returns immediately, leaving the dialog on the screen. The with-dialog-results macro provides a convenient way to create a continuation function.

In addition to the choice showing the items, prompt-with-list can also display a panel of push buttons (the "action buttons") which perform actions related to the choice. Note that these buttons are separated from the "dialog buttons" such as OK and Cancel. The dialog buttons are controlled separately by keywords in popup-args.

By default, prompt-with-list does not display action buttons. However, if interaction is :multiple-selection, the default behavior is to display two action buttons, All and None. These change the selection to all of the items or none of the items respectively.

When buttons is :none, it specifies no action buttons in any case (including no All and None buttons). Otherwise buttons must be a list of strings specifying additional action buttons. Each of the strings specifies a button, and the string is displayed in the button.

callbacks specifies the callbacks of the buttons. It should be a list of callback specifiers matching the list in buttons. Each callback specifier is either a callable (a function or a symbol) which takes one argument, the choice, or a list where the car is a callable which is called as follows:

(apply (car callback-spec) choice (cdr callback-spec))

When all-button and none-button are supplied they override the default behavior of the All and None buttons. If all-button (none-button) is nil, then All (None) is not displayed. If all-button (none-button) is non-nil and buttons is not :none, the All (None) button is displayed, and if the value is string, that string is used instead of the default string.

The prompter is created by passing an appropriate pane (in this case an instance of class choice-class) to popup-confirmer. Arguments can be passed to the make-instance of the pane and the call to popup-confirmer using pane-args and popup-args respectively.

Examples

(capi:prompt-with-list
  '(1 2 3 4 5) "Select an item:")

(capi:prompt-with-list
 '(1 2 3 4 5) "Select some items:"
 :interaction :multiple-selection
 :selection '(0 2 4))

(capi:prompt-with-list
 '(1 2 3 4 5) "Select an item:"
 :interaction :multiple-selection
 :choice-class 'capi:button-panel)

(capi:prompt-with-list
  '(1 2 3 4 5) "Select an item:"
  :interaction :multiple-selection
  :choice-class 'capi:button-panel
  :pane-args 
  '(:layout-class capi:column-layout))

There is a more complex example in:

(example-edit-file "capi/choice/prompt-with-buttons")

See also

popup-confirmer
list-panel
choice
10 Dialogs: Prompting for Input