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.




popup-confirmer pane message &rest interface-args &key modal
title title-font value-function exit-function
apply-function apply-check apply-button
ok-function ok-check ok-button no-button
no-function all-button all-function cancel-button
help-button help-function buttons print-function
callbacks callback-type button-position
foreground background font screen focus owner
x y position-relative-to button-container
=> result , successp



A CAPI pane or interface.


A string or nil .

modal , screen , focus , owner , x , y , and position-relative-to

These are passed to display-dialog.


A string specifying the title of the dialog window.


The font used in the title.


Controls the value returned, and whether a value can be returned.


Called on exiting the dialog.

apply-function , apply-check , apply-button

Define the callback, check function and title an Apply button.

ok-function, ok-check, ok-button

Define the callback, check function and title of an OK button.

no-button, no-function

Define the title and callback of a No button.

all-button , all-function

Define the title and callback of an All button.


Defines the title of a Cancel button.

help-button , help-function

Define the title and callback of a Help button.


Defines extra buttons.


Displays ok-button , no-button , cancel-button , apply-button and all-button as button titles.


Defines callbacks for buttons .


Specifies the callback-type of buttons .


One of :bottom , :top , :left , :right .

foreground , background

Specify colors.


A font or a font description.


A font or a font description.


A layout controlling where the buttons of the dialog appear.



The result of value-function , or pane , or nil .


nil if the dialog was cancelled, t otherwise.


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 each button, or nil meaning do not include that button. The ok-button returns successfully from the dialog (with the result of value-function ), 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.

apply-button , if passed, specifies the title of an extra button which appears near to the OK button. apply-check and apply-function define its functionality.

all-button , if passed, specifies the title of an extra button which is always enabled and which appears near to the apply-button (if that exists) or the OK button. all-function defines its functionality.

help-button , if passed, specifies the title of a help button which appears to the right of the Cancel button. help-function defines its functionality.

print-function is called on the various button arguments to generate a string to display for each button title.

button-position specifies where to put the buttons. The default is :bottom .

foreground and background specify colors to use for the parts of the dialog other than pane , including the buttons

font specifies the font to use in the message .

button-font specifies the font to use in the buttons.

button-container indicates where the buttons of the dialog appear. It must be a layout which is a descendent of pane . The description of this layout is automatically set to the button-panel containing the buttons.

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.

If any of callbacks need to access pane , you could use confirmer-pane together with a callback-type that passes the interface.

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 .


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 .

  (make-instance 'capi:text-input-pane
  "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
  (make-instance 'capi:text-input-pane
                 :callback 'capi:exit-confirmer
                 :change-callback :redisplay-interface)
  "Enter an integer"
  :value-function 'pane-integer
  :ok-check 'integerp)

An example illustrating the use of :button-container :

(let* ((bt (make-instance 'capi:simple-layout 
                          :title "Button Container" 
                          :title-position :left))
       (tip1 (make-instance 'capi:text-input-pane 
                            :title "Top"))
       (tip2 (make-instance 'capi:text-input-pane 
                            :title "Bottom"))
       (layout (make-instance 'capi:column-layout 
                              (list tip1 
  (capi:popup-confirmer layout nil 
                        "Dialog using button-container" 
                        :button-container bt))

An example with all the defined buttons in use:

(defun all-buttons-dialog (&optional (num 20))
  (let ((pane 
         (make-instance 'capi:list-panel 
                        (loop for ii from 1 
                              to num 
                              (format nil "~r" ii))
                        '(character 20))))
     "All Buttons"
     :callback-type :none
     :button-position :right
     :cancel-button "Cancel Button"
     :ok-button "OK Button"
     :ok-function #'(lambda (x)
                      (declare (ignorable x))
                       (capi:choice-selected-item pane)))
     :no-button "No Button"
     #'(lambda ()
          (cons :no 
                (capi:choice-selected-item pane))))
     :apply-button "Apply Button"
     #'(lambda ()
          "Applying to ~a" 
          (capi:choice-selected-item pane)))
     :help-button "Help Button"
     #'(lambda ()
          "~a is ~:[an odd~;an even~] number"
          (capi:choice-selected-item pane)
          (oddp (capi:choice-selection pane))))
     :all-button "All Button"
          (capi:collection-items pane))))))

A dialog with arbitrary buttons:

 (make-instance 'capi:text-input-pane)
 "Dialog with arbitrary buttons"
 :buttons '(:abc :xyz)
 (list #'(lambda (data) 
            "Button ~A was pressed" data))
       #'(lambda (data)
            "Button with ~A was pressed, exiting with ~S" data data)
           (capi:exit-dialog data)))
 :callback-type :data)
See also


LispWorks CAPI Reference Manual - 11 Apr 2005