A dialog is a window that receives some input from the user and returns it to the application. For instance, if the application wants to know where to save a file, it could prompt the user with a file dialog. Dialogs can also be cancelled, meaning that the application should cancel the current operation.
In order to let you know whether or not the dialog was cancelled, CAPI dialog functions always return two values. The first value is the return value itself, and the second value is
t
if the dialog returned normally and
nil
if the dialog was cancelled.
On Cocoa you can control whether a CAPI dialog is application-modal or window-modal. In the latter case the user can work with the application's other windows while the dialog is on screen.
The CAPI provides both a large set of predefined dialogs and the means to create your own. This chapter takes you through some example uses of the predefined dialogs, and then shows you how to create custom built dialogs.
The last section briefly describes a way to get input for completions via a special non-modal window.
CAPI User Guide (Windows version) - 30 Aug 2011