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 forms 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 between platforms:

• On Microsoft Windows, GTK+ 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.

Examples

On Microsoft Windows, GTK+ 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)))

Here is an example with skeleton code for using with-dialog-results. Note that the dialog function (choose-file below) that is called by with-dialog-results must take a continuation keyword argument and pass it to a CAPI prompting function. Also note that the call to the CAPI prompting function must be the last form in the dialog function. Forms after the CAPI prompting function will be executed at an indeterminate time, and their values will not be used in the body of with-dialog-results

(defun choose-file (&key continuation)

  (print 'in-choose-file)

  (capi:prompt-for-file "Choose File"

                        :pathname "~/Desktop/"

                        :continuation continuation))

(defun open-file (rep)

  (format t "~%Opening ~a~%" rep))

(defun my-callback ()

  (print 'doing-something-before)

  (capi:with-dialog-results (res ok-p)

      (choose-file)

    (print 'after-choose-file)

    (if ok-p

        (open-file res)

      (print 'cancelled))))

(defun prompt-for-file-working ()

  (capi:contain

   (make-instance

    'capi:push-button

    :text "Click Here"

    :callback-type :none

    :callback 'my-callback)))

(prompt-for-file-working)

See also

display-dialog
popup-confirmer
Dialogs: Prompting for Input