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 value-function pane-args popup-args continuation => result, successp

Arguments

items

A sequence.

message

A string.

choice-class

A class name.

interaction

One of :single-selection , :multiple-selection , or :extended-selection .

value-function

A function, or nil .

pane-args

Arguments to pass to the pane.

popup-args

Arguments to pass to the confirmer.

continuation

A function or nil .

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 sublass 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.

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. The continuation function 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.

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. The initial selection can be specified using choice initargs :selection , :selected-item or :selected-items in pane-args .

Example

(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))

See also

popup-confirmer
list-panel
choice