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 => result , okp

Arguments

interface

A CAPI interface.

screen

A screen.

focus

A pane of interface .

modal

A boolean.

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 .

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.

modal indicates whether or not the dialog takes over all input to the application. The default is t .

owner specifies an owner window for the dialog. See the "Prompting for Input" chapter in the LispWorks 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.

Note: if you need to replace one dialog with another, you can use display-replacable-dialog and replace-dialog.

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*