Function

Summary

The popup-confirmer function creates a dialog with predefined implementations of OK and Cancel buttons and a user specified pane in a layout with the buttons.

Syntax

popup-confirmer pane
 message

                &rest interface-args

                &key

                value-function
 

                ok-check
 ok-button
 no-button

                cancel-button
 screen

                exit-function
 ok-function
 no-function
 

                buttons
 callbacks
 callback-type

Description

The function popup-confirmer provides the quickest means to create new dialogs, as it will create and implement OK , Cancel and other buttons as required by your dialog, and will place a user specified pane in a layout along with the buttons.

The argument value-function should provide a callback which is passed pane and should return the value to return from popup-confirmer . If value-function is not supplied, then pane itself will be returned. If the value-function wants to indicate that the dialog cannot return a value currently, then it should return a second value that is non- nil .

The ok-check function is passed the result returned by the value-function and should return non- nil if it is acceptable for that value to be returned. These two functions are used by popup-confirmer to decide when the OK button should be enabled, thus stopping the dialog from returning with invalid data. The OK button's state can be updated by a call to redisplay-interface on the top-level, so the dialog should call it when the button may enable or disable.

The arguments ok-button , no-button and cancel-button are the text strings for the three buttons or nil meaning do not include such a button. The ok-button means return successfully from the dialog, the no-button means continue but return nil , and the cancel-button aborts the dialog. Note that there are clear expectations on the part of users as to the functions of these buttons -- check the style guidelines of the platform you are developing for.

The arguments exit-function , ok-function and no-function are the callbacks that get done when exiting, pressing OK and pressing No respectively. The exit-function defaults to exit-confirmer , the ok-function defaults to the exit-function and the no-function defaults to a function exiting the dialog with nil .

The arguments buttons , callbacks and callback-type are provided as a means of extending the available buttons. The buttons provided by buttons will be placed after the buttons generated by popup-confirmer , with the functions in callbacks being associated with them. Finally callback-type will be provided as the callback type for the buttons.

All other arguments will be passed to the call to make-instance for the interface that will be displayed using display-dialog . Thus geometry information, colors, and so on can be passed in here as well. By default, the dialog will pick up the foreground, background and font of pane .

Examples

Here are two simple examples which implement the basic functionality of two CAPI prompters: the first implements a simple prompt-for-string , while the second implements prompt-for-confirmation .

(capi:popup-confirmer

  (make-instance 'capi:text-input-pane

                 :callback 

                 'capi:exit-confirmer)

  "Enter some text:"

  :value-function 'capi:text-input-pane-text)

(capi:popup-confirmer nil 

  "Yes or no?"

  :callback-type :none

  :ok-button "Yes"

  :no-button "No"

  :cancel-button nil

  :value-function #'(lambda (dummy) t))

This example demonstrates the use of :redisplay-interface to make the OK button enable and disable on each keystroke.

(defun pane-integer (pane)

  (ignore-errors (values

                   (read-from-string

                    (capi:text-input-pane-text

                     pane)))))

(capi:popup-confirmer

  (make-instance 'capi:text-input-pane

                 :callback 'capi:exit-confirmer

                 :change-callback :redisplay-interface)

  "Enter an integer"

  :value-function 'pane-integer

  :ok-check 'integerp)

See also

exit-confirmer
display-dialog