Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

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

Events in Alert and Dialog Boxes

Handling events in an alert box is very simple: after you invoke an alert box, the Dialog Manager handles most events for you by automatically calling the ModalDialog procedure.

To handle events in a modal dialog box, your application must explicitly call the ModalDialog procedure after displaying the dialog box.

In either case, when an enabled item is clicked, the Dialog Manager returns the
item number. You'll then do whatever is appropriate in response to that click. For mouse-down events outside the alert box or modal dialog box, the ModalDialog procedure plays the system alert sound and gets the next event.

The Dialog Manager automatically removes an alert box when the user clicks any enabled item. For a modal dialog box, your application should continue calling ModalDialog until the user selects the OK or Cancel button, and then--after responding appropriately to the user's selection--your application should remove
the dialog box.

When it receives an event, ModalDialog passes the event to an event filter function before handling the event itself. You should provide an event filter function as a secondary event-handling loop for events that ModalDialog doesn't handle. For both alert and modal dialog boxes, you should provide a simple event filter function that performs the following tasks:

• return TRUE and the item number for the default button if the user presses the Return or Enter key
• return TRUE and the item number for the Cancel button if the user presses the Esc
  key or the Command-period key combination
• update your windows in response to update events (this also allows background applications to receive update events) and return FALSE
• return FALSE for all events that your event filter function doesn't handle

You can also use the event filter function to test for and respond to keyboard equivalents and more complex events--for instance, the user dragging the cursor within an application-defined item.

For your application's modeless and movable modal dialog boxes, you can pass events to the IsDialogEvent function, or you can use your own event-handling code to
learn whether the events need to be handled as part of a dialog box. If they do, call
the DialogSelect function to assist you in handling them instead of calling the ModalDialog procedure. Your application should not remove a modeless dialog box unless the user clicks its close box or chooses Close from the File menu when the modeless dialog box is the active window. Your application should remove a movable modal dialog box only after the user clicks one of its enabled buttons.

Instead of using the IsDialogEvent or DialogSelect function to handle events within modeless and movable modal dialog boxes, you can use Control Manager, Window Manager, and TextEdit routines (such as FindWindow, BeginUpdate, EndUpdate, FindControl, TrackControl, and TEClick) to handle these events without the aid of the Dialog Manager.