display-dialog Function

Summary

Displays a CAPI interface as a dialog box.

Package

capi

Signature

display-dialog interface &key screen focus modal timeout owner x y position-relative-to continuation callback-error-handler => result, okp

Arguments

Values

Description

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.

Notes

1. If you need to replace one dialog with another, you can use display-replacable-dialog and replace-dialog.
2. In a modal dialog at least one button which aborts or exits the dialog must be provided in interface. This is the programmer's responsibility, as without such a button there is no way to clear the modal dialog. A straightforward way to add these buttons is to display the window via popup-confirmer which adds the buttons for you.

Examples

(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/")

See also

abort-dialog
display
display-replacable-dialog
exit-dialog
interface
popup-confirmer
with-dialog-results
*update-screen-interfaces-hooks*
10 Dialogs: Prompting for Input