10.2 Prompting for values

The CAPI provides a number of different dialogs for accepting values from the user, ranging from accepting strings to accepting whole Lisp forms to be evaluated.

10.2.1 Prompting for strings

The simplest of the CAPI prompting dialogs is prompt-for-string which returns the string you enter into the dialog.

(prompt-for-string
 "Enter a string:")

An initial value can be placed in the dialog by specifying the keyword argument :initial-value.

10.2.2 Prompting for numbers

The CAPI also provides a number of more specific dialogs that allow you to enter other types of data. For example, to enter an integer, use the function prompt-for-integer. Only integers are accepted as valid input for this function.

(prompt-for-integer
 "Enter an integer:")

There are a number of extra options which allow you to specify more strictly which integers are acceptable. Firstly, there are two arguments :min and :max which specify the minimum and maximum acceptable integers.

(prompt-for-integer
 "Enter an integer in the inclusive range [10,20]:"
 :min 10 :max 20)

If this does not provide enough flexibility you can specify a function that validates the result with the keyword argument :ok-check. This function is passed the current value and must return non-nil if it is a valid result.

(prompt-for-integer
 "Enter an odd integer:"
 :ok-check 'oddp)

Try also the function prompt-for-number.

10.2.3 Prompting for an item in a list

If you would like the user to select an item from a list of items, the function prompt-with-list should handle the majority of cases. The simplest form just passes a list to the function and expects a single item to be returned.

(prompt-with-list
 '(:red :yellow :blue)
 "Select a color:")

You can also specify the interaction style that you would like for your dialog, which can be any of the interactions accepted by a choice. The specification of the interaction style to this choice is made using the keyword argument :interaction:

(prompt-with-list
 '(:red :yellow :blue)
 "Select a color:"
 :interaction :multiple-selection)

By default, the dialog is created using a list-panel to display the items, but the keyword argument :choice-class can be specified with any choice pane. Thus, for instance, you can present a list of buttons.

(prompt-with-list
 '(:red :yellow :blue)
 "Select a color:"
 :interaction :multiple-selection
 :choice-class 'button-panel)

Finally, as with any of the prompting functions, you can specify additional arguments to the pane that has been created in the dialog. Thus to create a column of buttons instead of the default row, use:

(prompt-with-list
 '(:red :yellow :blue)
 "Select a color:"
 :interaction :multiple-selection
 :choice-class 'button-panel
 :pane-args
 '(:layout-class column-layout))

There is a more complex example in:

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

10.2.4 Prompting for files

To prompt for a file, use the function prompt-for-file:

(prompt-for-file
 "Enter a file:")

You can also specify a starting pathname:

(prompt-for-file
  "Enter a filename:"
  :pathname (get-temp-directory))

Try also the function prompt-for-directory.

10.2.5 Prompting for fonts

To obtain a gp:font object from the user call prompt-for-font.

10.2.6 Prompting for colors

To obtain a color specification from the user call prompt-for-color.

10.2.7 Prompting for Lisp objects

The CAPI provides a number of dialogs specifically designed for creating Lisp aware applications. The simplest is the function prompt-for-form which accepts an arbitrary Lisp form and optionally evaluates it.

(prompt-for-form
 "Enter a form to evaluate:"
 :evaluate t)

(prompt-for-form
 "Enter a form (not evaluated):"
 :evaluate nil)

Another useful function is prompt-for-symbol which prompts the user for an existing symbol. The simplest usage accepts any symbol, as follows:

(prompt-for-symbol
 "Enter a symbol:")

If you have a list of symbols from which to choose, then you can pass prompt-for-symbol this list with the keyword argument :symbols.

Finally, using :ok-check you can accept only certain symbols. For example, to only accept a symbol which names a class, use:

(prompt-for-symbol
 "Enter a class-name symbol:"
 :ok-check #'(lambda (symbol)
               (find-class symbol nil)))

Cocoa programmers will notice that the dialog sheet displayed by this form prevents input to other LispWorks windows while it is displayed. For information about creating dialog sheets which are not application-modal, see 10.3 Window-modal Cocoa dialogs.