Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

Event Manager Routines / Receiving Events

GetNextEvent

Although you should normally use WaitNextEvent, you can also use the GetNextEvent function to retrieve events one at a time from the Event Manager.

FUNCTION GetNextEvent (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 (listed in "Setting the Event Mask" beginning on page 2-26). If no event of any of the designated types is available, GetNextEvent returns a null event.

theEvent

The next available event of the specified type or types. The GetNextEvent function removes the returned event from the
event stream and returns the information about the event in an
event record. The event record includes the type of event received
and other information.

DESCRIPTION

GetNextEvent returns FALSE as its function result if the event being returned is a null event or if GetNextEvent has intercepted the event; otherwise, GetNextEvent returns TRUE. The GetNextEvent function calls the Operating System Manager function SystemEvent to determine whether the event should be handled by the application or the Operating System.

Like WaitNextEvent, the GetNextEvent 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 GetNextEvent 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.)

The GetNextEvent function also intercepts Command-Shift-number key sequences
and calls the corresponding 'FKEY' resource to perform the associated action. The Event Manager's processing of Command-Shift-number key sequences with numbers
3 through 9 can be disabled by setting the ScrDmpEnable global variable (a byte) to 0.

SPECIAL CONSIDERATIONS

For greater support of the multitasking environment, your application should use WaitNextEvent instead of GetNextEvent whenever possible. If your application does call GetNextEvent, it should also call the SystemTask procedure.

SEE ALSO

See "The Event Record," beginning on page 2-79, for a description of the fields in the event record. For information on the SystemTask procedure, see page 2-95.