Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

Event Manager Routines / Receiving Events

GetOSEvent

The Toolbox Event Manager calls the GetOSEvent function to retrieve low-level events stored in the Operating System event queue. In most cases your application should not use this function.

FUNCTION GetOSEvent (mask: Integer;
                     VAR theEvent: EventRecord): Boolean;

mask

A value that indicates which kinds of events are to be returned; this parameter is interpreted as a sum of event mask constants. GetOSEvent returns only low-level events stored in the Operating System event queue; it does not return activate, update, operating-system, or high-level events. If no low-level event of any of the designated types is available, GetOSEvent returns a null event.

theEvent

The next available low-level event of the specified type or types in the Operating System event queue. The GetOSEvent function removes the returned event from the Operating System event queue and returns the information about the event in an event record. The event record includes the type of event received and other information.

DESCRIPTION

The GetOSEvent function retrieves and removes an event from the Operating System event queue. GetOSEvent returns FALSE as its function result if the event being returned is a null event; otherwise, GetOSEvent returns TRUE. GetOSEvent does not intercept or respond to the event in any way. It also does not process Command-Shift- number key combinations or process any alarms set by the user through the Alarm Clock desk accessory.

ASSEMBLY-LANGUAGE INFORMATION

You must set up register A0 with the address of an event record and register D0 with the event mask before invoking GetOSEvent. When GetOSEvent returns, register D0 indicates whether the returned event is a null event or an event other than a null event and the returned event is accessible through register A0.

Registers on entry
A0	Address of event record
D0	Event mask (low-order word)

Registers on exit
A0	Address of event record
D0	0 if GetOSEvent returns any event other than a null event, or -1 if it returns a null event (low-order byte)

SEE ALSO

See "The Event Record," beginning on page 2-79, for a description of the fields in the event record. See "Setting the Event Mask," beginning on page 2-26, for information on how to specify an event mask.