Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Introduction to Alerts and Dialog Boxes

Alert Boxes, Dialog Boxes, and the Window Manager

The Dialog Manager uses the Window Manager to draw your alert boxes and dialog boxes. You can use Window Manager or QuickDraw routines to manipulate an alert
box or a dialog box just like any other window--showing it, hiding it, moving it, and resizing it.

The Dialog Manager gets most of the descriptive information about alerts and dialog boxes from resources in a resource file. An alert resource is a resource that describes an alert, and a dialog resource is a resource that describes a dialog box. Both are analogous to a window resource. (In addition to providing information that the Dialog Manager passes to the Window Manager, you also include in your alert resources and dialog resources additional information that the Dialog Manager alone uses. These resources are described more fully in "Creating Alert Sounds and Alert Boxes" beginning on page 6-17 and "Creating Dialog Boxes" beginning on page 6-22.)

When you create an alert box, the Dialog Manager always passes to the Window Manager the dBoxProc window definition ID for the alert box; this is so that all alert boxes have the same standard appearance and behavior. The Window Manager always displays an alert box in front of all other windows. Because an alert box requires the user to respond before doing anything else, and the response dismisses the alert box, your application typically won't need to use any Window Manager or QuickDraw routines to manipulate an alert box.

The GetNewDialog function for creating dialog boxes is similar to the Window Manager function GetNewWindow. When you call GetNewDialog to create a
dialog box, you supply the same information as when you create a window with GetNewWindow. For example, you use a resource to specify the window definition ID, which determines how the dialog box looks and behaves, and a rectangle that defines
the dimensions of the dialog box's graphics port. As for any window, you specify the plane of the dialog box (which, by convention, should initially be frontmost), and you specify whether it is initially visible or invisible. If you create a dialog box that is initially invisible--for example, if you need to set a control's value before displaying it--you use the Window Manager procedure ShowWindow to display the dialog box.

The Dialog Manager creates the dialog window by calling the Window Manager function NewCWindow and then setting the window class in the window record to indicate that it's a dialog box. The Dialog Manager procedures for disposing of a dialog box, CloseDialog and DisposeDialog, are analogous to the Window Manager procedures CloseWindow and DisposeWindow.

When you create a dialog box (as described in "Creating Dialog Boxes" beginning on page 6-22), use the window definition ID of dBoxProc for modal dialog boxes. Use
the noGrowDocProc window definition ID for modeless dialog boxes. (If your dialog box absolutely needs a size box or scroll bars, you should use the Window Manager
to create the window instead of using the Dialog Manager.) And finally, use the movableDBoxProc window definition ID to create movable modal dialog boxes.

The Dialog Manager provides routines for handling most events in alert boxes and dialog boxes. For example, your application does not need to use such routines as the Window Manager function FindWindow and the Control Manager function TrackControl to determine when and where a mouse-down event occurs within an alert box's buttons. The Dialog Manager tells you which button the user clicks, and your application needs only to respond appropriately to the click. The Dialog Manager also automatically handles update and activate events for your alert boxes and dialog boxes. "Handling Events in Alert and Dialog Boxes" beginning on page 6-77 describes in detail how to use the Dialog Manager to help your application handle events.