Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Dialog Manager Routines / Creating Alerts

Alert

To display an alert box (or, if appropriate for the alert stage, to play an alert sound instead of or in addition to displaying the alert box), you can use the Alert function. This function does not display a default icon in the upper-left corner of the alert box;
you can leave this area blank, or you can specify your own icon in the alert's item list resource, which in turn is specified in the alert resource.

FUNCTION Alert (alertID: Integer; 
                filterProc: ModalFilterProcPtr): Integer;

alertID

The resource ID of an alert resource. If the alert resource is missing, the Dialog Manager returns to your application without creating the requested alert.

filterProc

A pointer to a function that responds to events not handled by the ModalDialog procedure.

DESCRIPTION

The Alert function creates the alert defined in the specified alert resource. The function calls the current alert sound procedure and passes it the sound number specified in the alert resource for the current alert stage. If no alert box is to be drawn at this stage, Alert returns -1; otherwise, it uses the NewDialog function to create and display the alert box. The default system window colors are used unless your application provides an alert color table resource with the same resource ID as the alert resource.

The Alert function uses the ModalDialog procedure, which repeatedly gets and handles most events for you. The ModalDialog procedure, in turn, gets each event by calling the Event Manager function GetNextEvent. If the event is a mouse-down event outside the content region of the alert box, ModalDialog emits an error sound and gets the next event.

The Alert function continues calling ModalDialog until the user selects an enabled control (typically a button), at which time the Alert function removes the alert box from the screen and returns the item number of the selected control. Your application then responds as appropriate when the user clicks this item.

For events inside the alert box, ModalDialog passes the event to an event filter function before handling the event. The event filter function provides a secondary event-handling loop for events that ModalDialog doesn't handle. You specify a pointer to your event filter function in the filterProc parameter of the Alert function.

If you set the filterProc parameter to NIL, the Dialog Manager uses the standard event filter function, which behaves as follows:

• If the user presses the Return or Enter key, the event filter function returns TRUE and returns the item number for the default button.

However, your application should provide a simple event filter function that not only replicates this behavior but also

• returns TRUE and the item number for the Cancel button if the user presses Esc or Command-period
• updates your windows in response to update events (this also allows background windows to receive update events) and returns FALSE
• returns 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.

Unless the event filter function handles the event in its own way and returns TRUE, ModalDialog handles the event inside the alert box as follows:

• If the user presses the mouse button while the cursor is in a control, the Control Manager function TrackControl tracks the cursor. If the user releases the
  mouse button while the cursor is in an enabled control, Alert, StopAlert, CautionAlert, and NoteAlert remove the alert box and return the control's
  item number. (Generally, buttons should be the only controls you use in alert boxes.)
• If the user presses the mouse button while the cursor is in any enabled item other than a control, Alert, StopAlert, CautionAlert, and NoteAlert remove the alert box and return the item number. (Generally, button controls should be the only enabled items in alert boxes.)
• If user presses the mouse button while the cursor is in a disabled item or in no item,
  or if any other event occurs, Alert, StopAlert, CautionAlert, and NoteAlert do nothing.

The Alert function uses the QuickDraw routine SetPort to make the alert box the current graphics port. It's not necessary for your application to call SetPort again before displaying alert boxes, because you can't draw into any other windows between the time you create an alert box and the time the Dialog Manager displays it.

SPECIAL CONSIDERATIONS

If you need to display an alert box while your application is running in the background or is otherwise invisible to the user, you should use the Notification Manager to post a notification to the user. The Notification Manager automatically displays an alert box containing whatever message you specify; you will not need to use the Dialog Manager to create the alert box yourself.

Note that the Notification Manager provides a one-way communications path from
your application to the user. There is no provision for carrying information back from
the user to your application while it is in the background (although it is possible for
your application to determine if the notification was received). If you need to solicit information from the user, use the Notification Manager to inform the user to bring
your application to the foreground, where the user can then respond to an alert box
that your application presents.

SEE ALSO

The ModalDialog procedure is described on page 6-128. See "Writing an Event Filter Function for Alert and Modal Dialog Boxes" beginning on page 6-86 for a discussion of how to write an event filter function. See "Creating Alert Sounds and Alert Boxes" beginning on page 6-18 for a discussion of alerts and alert stages. See "Titles for Buttons, Checkboxes, and Radio Buttons" beginning on page 6-37 and "Text Strings for Static Text and Editable Text Items" beginning on page 6-40 for recommendations about button titles and messages in alert boxes. Alert resources are described on page 6-142. Alert color table resources are described on page 6-149. The Dialog Manager uses the system alert sound as the error sound unless you change it by calling the ErrorSound pro- cedure, described on page 6-97. See "Responding to Events in Alert Boxes" beginning on page 6-81 for a discussion of how to respond to events returned by the Alert function. See the chapter "Notification Manager" in Inside Macintosh: Processes for information about the Notification Manager.

The NoteAlert, CautionAlert, and StopAlert functions are identical to the Alert function, except that NoteAlert (described on page 6-103), CautionAlert (described on page 6-104), and StopAlert (described next) display icons in the upper-left corners of alert boxes.