Generic Function

Summary

The display-dialog function displays a CAPI interface as a dialog box.

Package

capi

Signature

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

Arguments

interface

A CAPI interface.

screen

A screen.

focus

A pane of interface .

modal

t , :dismiss-on-input or nil .

owner

A pane.

x, y

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 .

Values

result

An object.

okp

A boolean.

Description

This is a complementary function that 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 the "Prompting for Input" chapter in the CAPI User Guide for details.

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. The continuation function 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 returrned 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.

Example

(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 in the directory examples/capi/dialogs/ .

See also

abort-dialog
display
display-replacable-dialog
exit-dialog
interface
popup-confirmer
with-dialog-results
*update-screen-interfaces-hooks*