with-dialog-results

with-dialog-results 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 => result1, result2

Arguments

`results`⇩	Variables.
`dialog-form`⇩	A function call form.
`body`⇩	Forms.

Values

`result1`	`:continuation`.
`result2`	`nil`.

Description

The macro with-dialog-results is designed to evaluate 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. dialog-form should be a function call form that displays a dialog.

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

The dynamic environment in which 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 body.
On Cocoa, dialog-form creates a sheet attached to the active window and the with-dialog-results macro returns immediately. body is evaluated when the user dismisses the sheet.

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 variables in results to its arguments and evaluates body. If there are more arguments than results variables, the extra arguments are discarded.

This macro is designed for use with function-names 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)