Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

Event Manager Routines / Receiving Events

OSEventAvail

The Toolbox Event Manager uses the OSEventAvail function to retrieve an event from the Operating System event queue without removing it. In most cases your application does not need to use this function.

FUNCTION OSEventAvail (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. OSEventAvail 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, OSEventAvail returns a null event.

theEvent

The next available event of the specified type or types. The OSEventAvail function does not remove the returned event from the Operating System event queue but does return information about the event in an event record. The event record includes the type of event received and other information.

DESCRIPTION

The OSEventAvail function retrieves an event from the Operating System event queue without removing it from the queue. The OSEventAvail function returns FALSE as its function result if the event being returned is a null event; otherwise, OSEventAvail returns TRUE.

OSEventAvail 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.

SPECIAL CONSIDERATIONS

If the OSEventAvail function returns a low-level event from the Operating System event queue, the event will not be accessible later if, in the meantime, the event
queue becomes full and the event is discarded from it; however, this is not a common occurrence.

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 OSEventAvail. When OSEventAvail returns, register D0 indicates whether the returned event is a null event or some other 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 OSEventAvail 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