Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

Application-Defined Routine / Filter Function for Searching the High-Level Event Queue

MyFilter

When you use GetSpecificHighLevelEvent to search the high-level event queue
of your application for a specific event, you supply a pointer to a filter function. GetSpecificHighLevelEvent calls your filter function once for each event in the high-level event queue until your filter function returns TRUE or the end of the queue
is reached. Your filter function can examine each event and determine whether that
event is the desired event. If so, your filter function should return TRUE.

Here's how you declare the filter function MyFilter:

FUNCTION MyFilter (yourDataPtr: Ptr; 
                   msgBuff: HighLevelEventMsgPtr;
                   sender: TargetID): Boolean;

yourDataPtr

Specifies the criteria your filter function should use to select a specific event. For example, you can specify the yourDataPtr parameter as a reference constant to search for a particular event, as a pointer to a target ID record to search for a specific sender of an event, or as an event class to search for a specific class of event.

msgBuff

Contains a pointer to a record of data type HighLevelEventMsg, which provides: the event record for the high-level event and the reference constant of the event. The HighLevelEventMsg data type is described in "The High-Level Event Message Record" on page 2-82.

sender

Contains the target ID record of the application that sent the event. The TargetID data type is described in "The Target ID Record" on page 2-81.

DESCRIPTION

Your filter function can compare the contents of the yourDataPtr parameter with the contents of the msgBuff and sender parameters. If your filter function finds a match, it can call AcceptHighLevelEvent, if necessary, and your filter function should return TRUE. If your filter function does not find a match, it should return FALSE.

SEE ALSO

For information about how to specify your filter function to the GetSpecificHighLevelEvent function, see page 2-92.