Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Dialog Manager Routines / Handling Events in Dialog Boxes

ModalDialog
To handle events when you display a modal dialog box, use the ModalDialog procedure.
PROCEDURE ModalDialog (filterProc: ModalFilterProcPtr; 
                        VAR itemHit: Integer);
filterProc
A pointer to an event filter function.
itemHit
A number representing the position of the selected item in the item list resource for the active modal dialog box.

DESCRIPTION
Call the ModalDialog procedure immediately after displaying a modal dialog box. The ModalDialog procedure assumes that a modal dialog box is displayed as the current port, and ModalDialog repeatedly handles events inside that port until an event involving an enabled dialog box item--such as a click in a radio button, for example--occurs. If the event is a mouse-down event outside the content region of the dialog box, ModalDialog emits the system alert sound and gets the next event. After receiving an event involving an enabled item, ModalDialog returns its item number in the itemHit parameter. Your application should then do whatever is appropriate in response to an event in that item. Your application should continue calling ModalDialog until the user selects the OK or Cancel button.
For events inside the dialog box, ModalDialog passes the event to the event filter function pointed to in the filterProc parameter before handling the event. When the event filter returns FALSE, ModalDialog handles the event. If the event filter function handles the event, the event filter function returns TRUE, and ModalDialog performs no more event handling.
If you set the filterProc parameter to NIL, the standard event filter function is executed. The standard event filter function returns TRUE and causes ModalDialog to return item number 1, which is the number of the default button, when the user presses the Return key or the Enter key. However, your application should provide a simple event filter function that

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

You can use the same event filter function in most or all of your alert and modal
dialog boxes.
You can also use the event filter function specified in the filterProc parameter to test for and respond to keyboard equivalents and more complex events--for instance, the user dragging the cursor within an application-defined item.
To handle events, ModalDialog calls the IsDialogEvent function. If the result of IsDialogEvent is TRUE, then ModalDialog calls the DialogSelect function to handle the event. Unless the event filter function returns TRUE, ModalDialog handles the event as follows:

In response to an activate or update event for the dialog box, ModalDialog activates or updates its window.
If the user presses the mouse button while the cursor is in an editable text item, ModalDialog responds to the mouse activity as appropriate--that is, either by displaying an insertion point or by selecting text. If a key-down event occurs and there's an editable text item, ModalDialog uses TextEdit to handle text entry and editing automatically. If the editable text item is enabled, ModalDialog returns its item number after it receives either the mouse-down or key-down event. Normally, editable text items are disabled, and you use the GetDialogItemText procedure to read the information in the items only after the user clicks the OK button.
If the user presses the mouse button while the cursor is in a control, ModalDialog calls the Control Manager function TrackControl. If the user releases the mouse button while the cursor is in an enabled control, ModalDialog returns the control's item number. Your application should respond appropriately--for example, by performing a command after the user clicks the OK button.
If the user presses the mouse button while the cursor is in any other enabled item in the dialog box, ModalDialog returns the item's number, and your application should respond appropriately. Generally, only controls should be enabled. If your application creates a control more complex than a button, radio button, or checkbox, your application must handle events inside that item with your event filter function.
If the user presses the mouse button while the cursor is in a disabled item or in no item, or if any other event occurs, ModalDialog does nothing.

SPECIAL CONSIDERATIONS
Do not use ModalDialog for movable modal dialog boxes (that is, those created with the movableDBoxProc window definition ID) or for modeless dialog boxes (that is, those created with the noGrowDocProc window definition ID). If you want the Dialog Manager to assist you in handling events for movable modal and modeless dialog boxes, use the IsDialogEvent and DialogSelect functions instead.
The ModalDialog procedure calls the Event Manager function GetNextEvent with a mask that excludes disk-inserted events. To receive disk-inserted events, your event filter function can call the Event Manager procedure SetSystemEventMask.
When ModalDialog calls TrackControl, it does not allow you to specify the action procedure necessary for anything more complex than a button, radio button, or checkbox. If you need a more complex control (for example, one that measures how long the user holds down the mouse button or how far the user has moved an indicator), you can create your own control, a picture, or an application-defined item that draws a control- like object in your dialog box. You must then provide an event filter function that appropriately handles events in that item.

SEE ALSO
Listing 6-26 on page 6-83 illustrates the use of ModalDialog. "Responding to Events in Editable Text Items" beginning on page 6-79 describes how ModalDialog uses TextEdit to handle text entry and editing in editable text items. The IsDialogEvent and DialogSelect functions (which your application may use instead of ModalDialog for modeless and movable modal dialog boxes) are described on page 6-131 and page 6-132, respectively. See the description of MyEventFilter on page 6-138 for information about the event filter function your application should specify in the filterProc parameter.
The GetNextEvent and SetSystemEventMask routines are described in the chapter "Event Manager" in this book. See that chapter as well for a discussion of disk-inserted events. See "Responding to Events in Controls" on page 6-78 for a description of how your application should respond to events inside of controls; the TrackControl function is fully described in the chapter "Control Manager" in this book. Also see that chapter for information about creating your own nonstandard controls. TextEdit is described in the chapter "TextEdit" of Inside Macintosh: Text.