Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 6 - Dialog Manager / Dialog Manager Reference

Application-Defined Routines /

MyEventFilter

To supplement the Dialog Manager's ability to handle events, your application should provide an event filter function that the Dialog Manager calls when it displays alert boxes and modal dialog boxes. Your event filter function should have three parameters and return a Boolean value. For example, this is how you would declare it if you were to name it MyEventFilter:

FUNCTION MyEventFilter (theDialog: DialogPtr; 
                        VAR theEvent: EventRecord; 
                        VAR itemHit: Integer): Boolean;

theDialog

A pointer to a dialog record for an alert box or a modal dialog box.

theEvent

An event record returned by an Event Manager function such as WaitNextEvent.

itemHit

A number corresponding to the position of an item in the item list resource for the alert or modal dialog box.

DESCRIPTION

After receiving an event that it does not handle, your function should return FALSE. When your function returns FALSE, ModalDialog handles the event, which you pass
in the parameter theEvent. (Your function can also change the event to simulate a different event and return FALSE, which passes the event to the Dialog Manager for handling.) If your function does handle the event, your function should return TRUE
as a function result, and in the itemHit parameter return the number of the item
that it handled. The ModalDialog procedure and, in turn, the Alert, NoteAlert, StopAlert, and CautionAlert functions then return this item number in their own itemHit parameters.

Your event filter function should perform the following tasks:

• return TRUE and the item number for the default button if the user presses Return
  or Enter
• return TRUE and the item number for the Cancel button if the user presses Esc or Command-period
• update your windows in response to update events (this 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 in an application- defined item. For example, if you provide an application-defined item that requires you to measure how long the user holds down the mouse button or how far the user drags the cursor, use the event filter function to handle events inside that item.

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.

You can use the same event filter function in most or all of your alert and modal
dialog boxes.

For alert and modal dialog boxes, the Dialog Manager provides a standard event filter function that checks whether the user has pressed the Enter or Return key and, if so, returns the item number of the default button. Your event filter function should always check whether the Return key or Enter key was pressed and, if so, return the number of the default button in the itemHit parameter and a function result of TRUE.

In all alert and dialog boxes, any buttons that are activated by key sequences should invert to indicate which item has been selected. Use the Control Manager procedure HiliteControl to invert a button for 8 ticks, long enough to be noticeable but not so long as to be annoying. The Control Manager performs this action whenever users click a button, and your application should do this whenever the user presses the keyboard equivalent of a button click.

For modal dialog boxes that contain editable text items, your application should handle menu bar access to allow use of your Edit menu and its Cut, Copy, Paste, Clear, and Undo commands. Your event filter function should then test for and handle clicks
in your Edit menu and keyboard equivalents for the appropriate commands in your
Edit menu. Your application should respond by using the procedures DialogCut, DialogCopy, DialogPaste, and DialogDelete to support the Cut, Copy, Paste, and Clear commands.

For an alert box, you specify a pointer to your event filter function in a parameter that you pass to the Alert, StopAlert, CautionAlert, and NoteAlert functions. For a modal dialog box, specify a pointer to your event filter function in a parameter that you pass to the ModalDialog procedure.

SEE ALSO

Listing 6-27 on page 6-88 illustrates an event filter function. The functions GetNextEvent and SetSystemEventMask are described in the chapter
"Event Manager" in this book.