NextPrevUpTopContentsIndex

popup-confirmer

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.

Package

capi

Signature

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 buttons-uniform-size-p
foreground background font screen focus owner
x y position-relative-to button-container
button-font continuation
=> result , successp

Arguments

pane

A CAPI pane or interface.

message

A string or nil .

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

These are passed to display-dialog.

title

A string specifying the title of the dialog window.

title-font

The font used in the title.

value-function

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

exit-function

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.

cancel-button

Defines the title of a Cancel button.

help-button , help-function

Define the title and callback of a Help button.

buttons

Defines extra buttons.

print-function

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

callbacks

Defines callbacks for buttons .

callback-type

Specifies the callback-type of buttons .

button-position

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

buttons-uniform-size-p

Controls relative button sizes.

foreground , background

Specify colors.

font

A font or a font description.

button-font

A font or a font description.

button-container

A layout controlling where the buttons of the dialog appear.

continuation

A function or nil .

Values

result

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

successp

nil if the dialog was cancelled, t otherwise.

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.

Generally the Return key selects the dialog's OK button and the Escape key selects the Cancel button, if there is one.

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 as result . 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 .

buttons-uniform-size-p specifies whether the buttons are all the same size, regardless of the text on them. The default is t , but nil can be passed to make each button only as wide as its text.

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.

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 popup-confirmer . On Cocoa, passing continuation causes the dialog to be made as a window-modal sheet and popup-confirmer returns immediately, leaving the dialog on the screen. The with-dialog-results macro provides a convenient way to create a continuation function.

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)

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 
                              :description
                              (list tip1 
                                    bt
                                    tip2))))
  (capi:popup-confirmer layout nil 
                        :title 
                        "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 
                        :items
                        (loop for ii from 1 
                              to num 
                              collect 
                              (format nil "~r" ii))
                        :visible-min-width 
                        '(character 20))))
    (capi:popup-confirmer
     pane
     "All Buttons"
     :callback-type :none
     :button-position :right
     :cancel-button "Cancel Button"
     :ok-button "OK Button"
     :ok-function #'(lambda (x)
                      (declare (ignorable x))
                      (capi:exit-dialog 
                       (capi:choice-selected-item pane)))
     :no-button "No Button"
     :no-function 
     #'(lambda ()
         (capi:exit-dialog 
          (cons :no 
                (capi:choice-selected-item pane))))
     :apply-button "Apply Button"
     :apply-function
     #'(lambda ()
         (capi:display-message 
          "Applying to ~a" 
          (capi:choice-selected-item pane)))
     :help-button "Help Button"
     :help-function 
     #'(lambda ()
         (capi:display-message 
          "~a is ~:[an odd~;an even~] number"
          (capi:choice-selected-item pane)
          (oddp (capi:choice-selection pane))))
     :all-button "All Button"
     :all-function 
     #'(lambda()
         (capi:exit-dialog 
          (capi:collection-items pane))))))
(all-buttons-dialog)

A dialog with arbitrary buttons:

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

abort-dialog
abort-exit-confirmer
confirmer-pane
display-dialog
exit-confirmer
exit-dialog


LispWorks CAPI Reference Manual - 17 Mar 2008

NextPrevUpTopContentsIndex