A dialog is a window that is displayed transiently to interact with the user. While a dialog is on screen it is placed in front of other windows and user input is directed to it. Dialogs are used for interactions that are relatively rare, and so do not deserve a permanent place on the screen, and for alerting the user about something that they need to be aware of. For example, when an application needs to know where to save a file, it typically prompts with a file dialog. If there is a problem during saving the file, it would normally alert the user by some other 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 interact 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 and Reference Manual (Macintosh version) - 3 Aug 2017