Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 2 - Event Manager / Event Manager Reference

Event Manager Routines / Receiving Events

WaitNextEvent

You can use the WaitNextEvent function to retrieve events one at a time from the Event Manager.

FUNCTION WaitNextEvent (eventMask: Integer;
                        VAR theEvent: EventRecord; sleep: LongInt;
                        mouseRgn: RgnHandle): 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, WaitNextEvent returns a null event. WaitNextEvent determines the next available event to return based on the eventMask parameter and the priority of the event.

Events not designated by the event mask remain in the event stream until retrieved by an application. Low-level events in the Operating System event queue are kept in the queue until they are retrieved by your application or another application or until the queue becomes full. Once the queue becomes full, the Operating System Event Manager begins discarding the oldest events in the queue.

theEvent

The next available event of the specified type or types. The WaitNextEvent 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. See "The Event Record," beginning on page 2-79, for a description of the fields in the event record.

In addition to the event record, high-level events can contain additional data; you use the AcceptHighLevelEvent or AEProcessAppleEvent functions to get additional data associated with these events.

sleep

The number of ticks (a tick is approximately 1/60 of a second) indicating the amount of time your application is willing to relinquish the processor if no events (other than null events) are pending for your application. If you specify a value greater than 0 for the sleep parameter, your application relinquishes the processor for the specified time or until an event occurs.

You should usually specify a value greater than 0 for the sleep parameter to allow background processes to receive processing time. You should not set the sleep parameter to a value greater than the number of ticks returned by GetCaretTime if your application provides text-editing capabilities. When the specified time expires, and if there are no pending events for your application, WaitNextEvent returns a null event in the parameter theEvent.

mouseRgn

A handle to a region that specifies a region inside of which mouse movement does not cause mouse-moved events. In other words, your application receives mouse-moved events only when the cursor is outside the specified region. You should specify the region in global coordinates. If you pass an empty region or a NIL region handle, the Event Manager does not report mouse-moved events to your application. Note that your application should recalculate the mouseRgn parameter when it receives a mouse-moved event, or it will continue to receive mouse-moved events as long as the cursor position is outside the original mouseRgn.

DESCRIPTION

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

If no events are pending for your application, WaitNextEvent waits for a specified amount of time for an event. (During this time, processing time may be allocated to background processes.) If an event occurs, it is returned as the value of the parameter theEvent, and WaitNextEvent returns a function result of TRUE. If the specified
time expires and there are no pending events for your application, WaitNextEvent returns a null event in theEvent and a function result of FALSE.

Before returning an event to your application, WaitNextEvent performs other processing and may intercept the event.

The WaitNextEvent function 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.

The WaitNextEvent 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 WaitNextEvent function also calls the SystemTask procedure, which gives time to each open desk accessory or device driver to perform any periodic action defined
for it. A desk accessory or device driver specifies how often the periodic action should occur, and SystemTask gives time to the desk accessory or device driver at the appropriate interval.

Some high-level events may be fully specified by their event records only, while others may include additional information in an optional buffer. To get any additional information and to find the sender of the event, use the AcceptHighLevelEvent function.

If the returned event is a high-level event and your application supports Apple events, use the Apple Event Manager function AEProcessAppleEvent to respond to the Apple event and to get additional information associated with the Apple event.

SPECIAL CONSIDERATIONS

In System 7, if your application is in the foreground and the user opens a desk accessory or other item from the Apple menu, clicks in the window belonging to another application or desk accessory, or chooses another process from the Application menu, the next event reported to your application by the WaitNextEvent function is a suspend event. After your application is switched out, the Event Manager directs events (other than events your application can receive in the background) to the newly activated process until the user switches back to your application or another application.

Note

In a single-application environment in System 6, and in a multiple- application environment in which the desk accessory is launched in
the application's partition (for example, a desk accessory opened by the user from the Apple menu while holding down the Option key), the Event Manager handles events for desk accessories in a slightly
different manner.

In these environments, when mouse-up, activate, update, and keyboard events (including keyboard equivalents of menu commands) occur, the Event Manager checks to see whether the active window belongs to a desk accessory and whether the desk accessory can handle the event. If so, it sends the event to the desk accessory and WaitNextEvent returns FALSE to your application. Also note that in these environments, the Event Manager returns TRUE for mouse-down events, regardless of whether the mouse-down event is for a desk accessory or not. For mouse-down events in these situations, if the mouse button was
pressed while the cursor was in a desk accessory window (as indicated by the inSystem constant returned by the FindWindow function),
your application should call the SystemClick procedure. The SystemClick procedure handles mouse-down events as appropriate for desk accessories, including sending your application an activate event to deactivate its front window if the desk accessory window needs to be activated.

SEE ALSO

For examples that use the WaitNextEvent function, see Listing 2-1 on page 2-23 and Listing 2-2 on page 2-24.

To get information about the sender of a high-level event and to retrieve any
additional data associated with the high-level event, see the description of the AcceptHighLevelEvent function on page 2-90. For details on how to process
an Apple event, see the description of the AEProcessAppleEvent function in
Inside Macintosh: Interapplication Communication.

For information on how to retrieve an event without removing it from the event stream, see the description of the EventAvail function, immediately following.