Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

Event Manager Routines / Receiving Events

EventAvail

You can use the EventAvail function to retrieve the next available event from
the Event Manager without removing the returned event from your application's
event stream.

FUNCTION EventAvail (eventMask: Integer;
                     VAR theEvent: EventRecord): Boolean;

eventMask

A value that indicates which kinds of events are to be returned; this parameter is interpreted as a sum of event mask constants. You can use these constants to specify the event mask:

            CONST       
            mDownMask    = 2;       {mouse-down event    (bit 1)}
            mUpMask      = 4;       {mouse-up event      (bit 2)}
            keyDownMask  = 8;       {key-down event      (bit 3)}
            keyUpMask    = 16;      {key-up event        (bit 4)}
            autoKeyMask  = 32;      {auto-key event      (bit 5)}
            updateMask   = 64;      {update event        (bit 6)}
            diskMask     = 128;     {disk-inserted event (bit 7)}
            activMask    = 256;     {activate event      (bit 8)}
            highLevelEventMask
                         = 1024;    {high-level event    (bit 10)}
            osMask       = -32768;  {operating-system    (bit 15)}

To accept all events, you can specify the everyEvent constant as the event mask:

            CONST
            everyEvent   =  -1;     {every event}

If no event of any of the designated types is available, EventAvail returns a null event.

theEvent

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

DESCRIPTION

EventAvail returns FALSE as its function result if the event being returned is a null event; otherwise, EventAvail returns TRUE.

Like WaitNextEvent, the EventAvail function calls the SystemTask procedure to give time to each open desk accessory or device driver to perform any periodic action defined for it. The EventAvail function also makes the alarm go off if the alarm is set and the current time is the alarm time. The user sets the alarm using the Alarm Clock desk accessory.

SPECIAL CONSIDERATIONS

If EventAvail 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.

SEE ALSO

See "The Event Record," beginning on page 2-79, for a description of the fields in the event record.