Displays a CAPI interface as a dialog box.
capi
display-dialog interface &key screen focus modal timeout owner x y position-relative-to continuation callback-error-handler => result, okp
interface⇩ |
A CAPI interface. |
screen⇩ |
A screen. |
focus⇩ |
A pane of interface. |
modal⇩ | t , :dismiss-on-input or nil . |
timeout⇩ | nil or a real number. |
owner⇩ |
A pane. |
Real numbers representing coordinates, or keywords or lists specifying an adjusted position. | |
position-relative-to⇩ | :owner or nil . |
continuation⇩ |
A function or nil . |
callback-error-handler⇩ | |
A function designator or nil . |
result⇩ |
An object. |
okp |
A boolean. |
The function display-dialog
displays the CAPI interface interface as a dialog box.
screen is the screen for the dialog to be displayed on.
focus should be the pane within the interface that should be given the focus initially. If a focus is not supplied, then it lets the window system decide.
A true value of modal indicates that the dialog takes over all input to the application. Additionally, if modal is :dismiss-on-input
then any user gesture (a button or key press) causes the dialog to disappear. :dismiss-on-input
works on platforms other than Motif. The default value of modal is t
.
owner specifies an owner window for the dialog. See 10.4 Dialog Owners for details.
If timeout is non-nil, the dialog automatically aborts if it is still displayed after timeout seconds.
If x and y are numbers they specify the coordinates of the dialog. Alternatively x and y can be keywords like :left
and :top
, or lists like (:left 100)
, (:bottom 50)
and so on.. These values cause the dialog to be positioned relative to its owner in the same way as the adjust argument to pane-adjusted-position. The default location is at the center of the dialog's owner.
position-relative-to has a default value :owner
, meaning that x and y are relative to dialog's owner. The value nil
means that x and y are relative to the screen.
If continuation is non-nil, then it must be a function with a lambda list that accepts two arguments. continuation is called with the values that would normally be returned by display-dialog
. On Cocoa, passing continuation causes the dialog to be made as a window-modal sheet and display-dialog
returns immediately, leaving the dialog on the screen. The with-dialog-results macro provides a convenient way to create a continuation function.
The values returned depend on how the dialog is dismissed. Typically a user gesture will trigger a call to abort-dialog, causing the values nil
, nil
to be returned or to exit-dialog causing the values result, t
to be returned, where result is the argument to exit-dialog. If continuation is non-nil, then the returned values are always :continuation
, nil
.
The CAPI also provides popup-confirmer which gives you the standard OK and Cancel button functionality.
callback-error-handler allows error handling in callbacks which is uniform across platforms, as described for popup-confirmer.
(capi:display-dialog (capi:make-container (make-instance 'capi:push-button-panel :items '("OK" "Cancel") :callback-type :data :callbacks '(capi:exit-dialog capi:abort-dialog)) :title "Empty Dialog"))
There are further examples:
(example-edit-file "capi/dialogs/")
abort-dialog
display
display-replacable-dialog
exit-dialog
interface
popup-confirmer
with-dialog-results
*update-screen-interfaces-hooks*
10 Dialogs: Prompting for Input
CAPI User Guide and Reference Manual (Unix version) - 01 Dec 2021 19:32:42