Macro

Summary

Displays a dialog and executes a body when the dialog is dismissed.

Package

capi

Signature

with-dialog-results (&rest results ) dialog-form &body body => :continuation, nil

Arguments

results

Variables.

dialog-form

A function call form.

body

Forms.

Description

The macro with-dialog-results is designed to evaluate the dialog-form in a special way to allow dialogs on Cocoa to use window-modal sheets. It is not needed unless you want to make code that is portable to Cocoa. The dialog-form should be a function call form that displays a dialog.

The overall effect is that the body forns are evaluated with the results variables bound to the values returned by the dialog-form when the dialog is dismissed.

The dynamic environment in which the body is evaluated varies bewteen platforms:

• On Microsoft Windows and Motif, the with-dialog-results macro waits until the dialog has been dismissed and then evaluates the body forms.
• On Cocoa, the dialog-form creates a sheet attached to the active window and the with-dialog-results macro returns immediately. The body forms are evaluated when the user dismisses the sheet.

The dialog-form must be a cons with one of the following two formats:

• ( function-name . arguments )
• (apply function-name . arguments )

The function-name is called with all the given arguments , plus an additional pair of arguments, :continuation and a continuation function created from body . In the first format, the additional arguments are placed after all the given arguments . In the second format, the additional arguments are placed just before the last of the given arguments (i.e. before the list of remaining argument to apply ).

The continuation function binds the results variables to its arguments and evaluates the body forms. If there are more arguments than results variables, the extra arguments are discarded.

This macro is designed for use with function-name s such as popup-confirmer or prompt-for-string, which take a :continuation keyword. You can define your own such functions provided that they call one of the CAPI functions, passing the received continuation argument.

Example

On Microsoft Windows and Motif, this displays a dialog, calls record-label-in-database when the user clicks OK and then returns. On Cocoa, this creates a sheet and returns; record-label-in-database will be called when the user clicks OK.

(with-dialog-results (new-label okp)

    (prompt-for-string "Enter a label")

  (when okp  ; the user clicked in the OK button

    (record-label-in-database new-label)))

See also

display-dialog
popup-confirmer