Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

Event Manager Routines / Receiving Events

GetSpecificHighLevelEvent

You can use the GetSpecificHighLevelEvent function to select and optionally retrieve a specific high-level event from your application's high-level event queue.

FUNCTION GetSpecificHighLevelEvent
            (aFilter: GetSpecificFilterProcPtr;
             yourDataPtr: UNIV Ptr; VAR err: OSErr): Boolean;

aFilter

Specifies the filter function that GetSpecificHighLevelEvent should use to search for a specific event. GetSpecificHighLevelEvent calls your filter function once for each event in your application's high-level event queue until your filter function returns TRUE or the end of the queue is reached.

yourDataPtr

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

err

GetSpecificHighLevelEvent returns in this parameter a value indicating if any errors occurred. The err parameter contains the noErr constant if no errors occurred or noOutstandingHLE if no high-level events are pending in your application's high-level event queue.

DESCRIPTION

You can use the GetSpecificHighLevelEvent function to search for a specific high-level event in your application's high-level event queue. You provide a pointer to a filter function as one of the parameters to GetSpecificHighLevelEvent. The GetSpecificHighLevelEvent function calls your filter function once for every event in your application's high-level event queue, until your filter function returns TRUE or the end of the queue is reached.

The GetSpecificHighLevelEvent function passes the value you specify in the yourDataPtr parameter to your filter function. Your filter function also receives as parameters the event record associated with the high-level event and the target ID record that identifies the sender of the event. Your filter function can compare the contents of the yourDataPtr parameter with any of the other information it receives.

If your filter function finds a match, it can call AcceptHighLevelEvent if necessary, and then return TRUE. If your filter function does not find a match, then it should
return FALSE.

If your filter function returns TRUE, the GetSpecificHighLevelEvent function returns TRUE. If your filter function returns FALSE for all high-level events in your application's event queue, or if there are no high-level events in the queue, GetSpecificHighLevelEvent returns FALSE.

SPECIAL CONSIDERATIONS

The GetSpecificHighLevelEvent function may move or purge memory. You
should not call this function from within an interrupt, such as in a completion routine
or VBL task.

ASSEMBLY-LANGUAGE INFORMATION

The trap macro and routine selector for the GetSpecificHighLevelEvent
function are

Trap macro	Selector
_OSDispatch	$0045

SEE ALSO

See "Filter Function for Searching the High-Level Event Queue" on page 2-114 for more information about how to define a filter function and the parameters that GetSpecificHighLevelEvent passes to your filter function.