Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager

This chapter describes how your application can use the Dialog Manager to alert users to unusual situations and to solicit information from users. For example, in some situations your application might not be able to carry out a command normally, and in other situations the user must specify multiple parameters before your application can execute a command. For circumstances like these, the Macintosh user interface includes these two features:

• alerts--including alert sounds and alert boxes--which warn the user whenever an unusual or potentially undesirable situation occurs within your application
• dialog boxes, which allow the user to provide additional information or to modify settings before your application carries out a command

Read this chapter to learn how and when to implement alerts and dialog boxes. For example, your application can use the Dialog Manager to ask the user whether to save new or altered documents before quitting and, if the situation arises, to inform the user that there is insufficient disk space to save the file.

Virtually all applications need to implement alerts and dialog boxes. To avoid needless development effort, use the Dialog Manager to implement alerts and to create most dialog boxes. It is possible, however--and sometimes desirable--to bypass the Dialog Manager and instead use Window Manager, Control Manager, QuickDraw, and Event Manager routines to create or respond to events in complex dialog boxes. Even if you decide not to use the Dialog Manager, read this chapter for information about effective human interface design and localization issues regarding dialog boxes.

To use this chapter, you should be familiar with resources, the Event Manager, the Window Manager, and the Control Manager.

You typically use resources to specify the items you wish to display in alert boxes and dialog boxes; for example, you specify the size, location, and appearance of a dialog
box in a dialog resource--a resource of type 'DLOG'. See the chapter "Introduction to the Macintosh Toolbox" in this book for general information about resources; detailed information about the Resource Manager and its routines is provided in the chapter "Resource Manager" of Inside Macintosh: More Macintosh Toolbox.

The Dialog Manager offers routines that handle most of the events relating to alerts
and dialog boxes, but your application still needs to handle a few additional events
as described in "Writing an Event Filter Function for Alert and Modal Dialog Boxes" beginning on page 6-86. See the chapter "Event Manager" in this book for general information about events and event handling.

The Dialog Manager uses the Window Manager to display your alert boxes and dialog boxes. Although the Dialog Manager uses most of the Window Manager routines necessary to activate and update your alert and dialog boxes, your application needs
to use Window Manager routines if it creates certain types of dialog boxes--such as modeless dialog boxes--as explained in this chapter. See the chapter "Window Manager" in this book for general information about windows.

The Dialog Manager uses the Control Manager to create and display buttons, radio buttons, checkboxes, and pop-up menus and to handle events in them. Generally, you shouldn't use any other controls--such as scroll bars--in your dialog boxes. If you need to implement a more complex control, see the chapter "Control Manager" in this book. Buttons are the only controls you should use in alert boxes.

If you include editable text items in your dialog boxes, the Dialog Manager uses TextEdit to handle associated editing tasks. For general information on TextEdit, see the chapter "TextEdit" in Inside Macintosh: Text.

This chapter provides a brief introduction to the concepts and functions of alerts and dialog boxes, and then it discusses how you can

• create and display alerts and dialog boxes
• include controls, informative text, editable text fields, and similar items in your alert boxes and dialog boxes
• respond to events in your alert boxes and dialog boxes

---

Chapter Contents

Introduction to Alerts and Dialog Boxes

Types of Alerts

Types of Dialog Boxes

Modal Dialog Boxes

Movable Modal Dialog Boxes

Modeless Dialog Boxes

Items in Alert and Dialog Boxes

Events in Alert and Dialog Boxes

Alert Boxes, Dialog Boxes, and the Window Manager

About the Dialog Manager

Using the Dialog Manager

Creating Alert Sounds and Alert Boxes

Creating Dialog Boxes

Providing Items for Alert and Dialog Boxes

Item Types

Display Rectangles

Enabled and Disabled Items

Resource IDs for Items

Titles for Buttons, Checkboxes, and Radio Buttons

Text Strings for Static Text and Editable Text Items

Pop-Up Menus as Items

Keyboard Navigation Among Items

Manipulating Items

Changing Static Text

Getting Text From Editable Text Items

Adding Items to an Existing Dialog Box

Using an Application-Defined Item to Draw the Bold Outline for a Default Button

Displaying Alert and Dialog Boxes

Positioning Alert and Dialog Boxes

Deactivating Windows Behind Alert and Modal Dialog Boxes

Displaying Modeless Dialog Boxes

Adjusting Menus for Modal Dialog Boxes

Adjusting Menus for Movable Modal and Modeless Dialog Boxes

Displaying Multiple Alert and Dialog Boxes

Displaying Alert and Dialog Boxes From the Background

Including Color in Your Alert and Dialog Boxes

Handling Events in Alert and Dialog Boxes

Responding to Events in Controls

Responding to Events in Editable Text Items

Responding to Events in Alert Boxes

Responding to Events in Modal Dialog Boxes

Writing an Event Filter Function for Alert and Modal Dialog Boxes

Responding to Mouse Events in Modeless and Movable Modal Dialog Boxes

Responding to Keyboard Events in Modeless and Movable Modal Dialog Boxes

Responding to Activate and Update Events in Modeless and Movable Modal Dialog Boxes

Closing Dialog Boxes

Dialog Manager Reference

Data Structure

The Dialog Record

Dialog Manager Routines

Initializing the Dialog Manager

Creating Alerts

Creating and Disposing of Dialog Boxes

Manipulating Items in Alert and Dialog Boxes

Handling Text in Alert and Dialog Boxes

Handling Events in Dialog Boxes

Application-Defined Routines

Resources

The Dialog Resource

The Alert Resource

The Item List Resource

The Dialog Color Table Resource

The Alert Color Table Resource

The Item Color Table Resource

Summary of the Dialog Manager

Pascal Summary

Constants

Data Types

Dialog Manager Routines

Application-Defined Routines

C Summary

Constants

Data Types

Dialog Manager Routines

Application-Defined Routines

Assembly-Language Summary

Data Structures

Global Variables