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 callback-error-handler => result , successp
A CAPI pane or interface.
A string or
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.
Defines the title of a Cancel 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 .
A font or a font description.
A font or a font description.
A layout controlling where the buttons of the dialog appear.
A function or
The result of
nil if the dialog was cancelled,
popup-confirmer is the quickest way to create new dialogs. It creates a dialog with predefined implementations of buttons such as
and a programmer-specified pane in a layout with the buttons.
should provide a callback which is passed
and should return the value to return from
is not supplied, then
itself will be returned as
. If the
wants to indicate that the dialog cannot return a value currently, then it should return a second value that is non-nil.
function is passed the result returned by the
and should return true if it is acceptable for that value to be returned. These two functions are used by
popup-confirmer to decide when the
button should be enabled, thus stopping the dialog from returning with invalid data. The
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.
are the text strings for each button, or
nil meaning do not include that button. The
returns successfully from the dialog (with the result of
means continue but return
nil, and the
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.
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.
button-container indicates where the buttons of the dialog appear. It must be a layout which is a descendant of pane . The description of this layout is automatically set to the button-panel containing the buttons.
are the callbacks that get done when exiting, pressing
defaults to exit-confirmer, the
defaults to the
defaults to a function exiting the dialog with
are provided as a means of extending the available buttons. The buttons provided by
will be placed after the buttons generated by
popup-confirmer, with the functions in
being associated with them. Finally
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.
is non-nil, then it must be a function with a lambda list that accepts two arguments. The
function is called with the values that would normally be returned by
popup-confirmer. On Cocoa, passing
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
, if non-nil, should be a function designator for a function of one argument which is a condition, like the
cl:handler-bind. The handler is established (by
cl:handler-bind with type
cl:error) around each callback call inside the scope of
popup-confirmer or display-dialog. In recursive calls, only the handler of the innermost call to
popup-confirmer or display-dialog is established.
If callback-error-handler wants to do a non-local exit, it should either call abort-callback to abort the callback but leave the dialog, or exit-dialog (or abort-dialog) to exit (or abort) the dialog.
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
cl:handler-bind around the call to display-dialog or
popup-confirmer (the handler will also handle errors during raising the dialog, but these are not expected to happen). On Cocoa, using such an error handler does not necessarily work, because the callback may happen in another process.
ensures that the callback is in the scope of the handler on all platforms. From the same reason the handler should not rely on the dynamic environment (including catchers and restarts), and needs to use current-popup to find its "context" and use abort-callback, exit-dialog or abort-dialog for non-local exit.
popup-confirmer or display-dialog, the
handler will stay until the callback returns. Unless the recursive call handles the error, the handler of the outer call may be called to handle it, and needs to be written to deal with this possibility correctly. If the handler inside a recursive call needs to access the popup that was used in the same call that the handler was used, it should close over it, because current-popup returns the innermost one.
cl:handler-case) is inside the scope of the
, and therefore will be called first.
CAPI User Guide and Reference Manual (Unix version) - 25 Feb 2015