1 CAPI Reference Entries

popup-confirmer

Summary

Thepopup-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 functionpopup-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 frompopup-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 bypopup-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 toredisplay-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 ornilmeaning do not include such a button. The ok-button means return successfully from the dialog, the no-button means continue but returnnil, 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 toexit-confirmer, the ok-function defaults to theexit-function and the no-function defaults to a function exiting the dialog withnil.

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 bypopup-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 tomake-instance for the interface that will be displayed usingdisplay-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 simpleprompt-for-string, while the second implementsprompt-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)

Example File

capi/tools/pathname-selector.lisp

See Also

exit-confirmer
display-dialog

Generated with Harlequin WebMaker