All DatabasesInside Mac - Basic Toolbox
WaitNextEvent
WaitNextEvent Receive next event from Event Manager
#include <Events.h> Event Manager
Boolean WaitNext Event( eventMask, theEvent, sleep, mouseRgn)
short eventMask ; Event mask
EventRecord * theEvent ; Event record
long sleep ; Number of ticks to sleep
RgnHandle mouseRgn ; Region of null mouse events
returns Return Code; 0=null event; 1=event returned
WaitNextEvent function receives events one at a time from the
Event Manager.
The WaitNextEvent function returns in the theEvent parameter the next
available event of a specified type or types and, if the event is in the event
queue, removes it from the queue. 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. If no event occurs (and the queue is empty), WaitNextEvent
returns a null event in theEvent. WaitNextEvent returns FALSE if the event
being returned is a null event; otherwise, WaitNextEvent returns TRUE.
eventMask is interpreted as a sum of event mask constants. If no event of any of
the designated event types is available then a null event is returned.
See Event Mask for details. The event mask specifies which
event(s) should be checked. It is a 16-bit binary mask where a 1
elects to include an event and a 0 excludes the event. The most
common usage is to use eventMask=everyEvent, defined in Events.h as
-1. See Event Mask for the layout and named constants. See
Event Types for a list of the kinds of events which are defined in
Events.h and may be masked. These types are found in the field what
after the call is made.
theEvent is the address of a 16-byte EventRecord. Upon return, it is filled
with information about the event. The field values are described in
GetNextEvent.
sleep is the maximum number of sleepTicks (sixtieths of a second) that
your application agrees to relinquish the processor if no events are
pending for it. A large value (such as 0xFFFFFFFF) specifies that
you have no need to obtain null events. If sleepTicks =0, the
Event Manager will yield only a minimum amount of time to
background processes.
mousergn 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 of the specified
region. The region is specified in global coordinates. If you pass an
empty region or a NIL region handle then there are no
mouse-moved events. generated. Your application should recalculate
the mouseRgn parameter when it receives a
mouse-moved event or it will continue to receive notice of
mouse-moved events as long as the cursor position is outside the
original mouseRgn. Should the mouse move outside of this area, you
will receive an osEvt in which the high byte of the message field has
been set to 0xFA and the where field contains the current mouse
position. If mouseRgn=0, you will never receive such
" mouse-moved" events.
Returns: a result indicator. It will be one of:
FALSE (0) Null event returned
TRUE (1) Non-null Event returned
Notes: Some high-level events may be fully specified by their event record 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.
WaitNextEvent will give time to background applications when there are
no events pending for your application. Your application will still receive
nullEvents on a periodic basis, based on the value passed in thesleep
parameter(contrast this with GetNextEvent, which will repeatedly
return nullEvents to your application without giving background
applications any time to operate).
You must call this function only if the trap exists, otherwise you must use
GetNextEvent. To find out, use the following sequence that first checks
the machine type, then checks if the _WaitNextEvent trap is not set as an
unimplemented trap:
SysEnvRec theSysEnv;
Boolean wneAvail = FALSE;
SysEnvirons( 1, &theSysEnv );
if ( theSysEnv. machineType >= 1 ) {
if ( NGetTrapAddress( 0xA860, 1 ) != 0xA89F )
wneAvail = TRUE;
}
Calling SysEnvirons() is not recommended if Gestalt is available.
If you use WaitNextEvent, there is no need to call SystemTask, since
the Event Manager does this for you.
When calling WaitNextEvent with a non-zero sleepTicks, you can't
depend on doing repeated maintenance operations inside your event loop.
For instance, it is a common practice to maintain a context-sensitive mouse
cursor (e.g., when you move the mouse over a HyperLink in this
Reference). Thus, the reason for the mouseRgn parameter. One way to
setup your mouseRgn is to simply subtract you window's structure region
from the global GrayRgn, as in the example below.
The following code illustrates a skeletal usage of WaitNextEvent. It
checks for osEvts and processes mouse-movement events. It is only
interested in getting such events when the cursor is inside of a particular
window OR 1/2 second has elapsed. The idea of using a 30-tick timeout is to
ensure that you set the cursor to the standard arrow should the mouse stray
over some other application's window.
Example
#include <Events.h>
RgnHandle mouseRgn;
EventRecord theEvent;
Boolean wneAvail; // see text above
mouseRgn = NewRgn();
DiffRgn( GrayRgn, ((WindowPeek)myWindow)->strucRgn, mouseRgn );
while( TRUE ) {
if ( ! wneAvail ) {
GetNextEvent( everyEvent, &theEvent );
DoMaintainCursor();
SystemTask();
}
else {
if ( ! WaitNextEvent(everyEvent, & theEvent, 30, mouseRgn) ) {
DoMaintainCursor();
continue; // null event - timed out; loop back
}
}
switch( theEvent.what) {
case mouseDown:
DoMouse(& theEvent);
break;
case keyDown:
DoKey(& theEvent);
break;
/* Handle other types of events here */
case osEvt:
if ( theEvent. message & 0x01000000 ) { // suspend or resume
if ( theEvent. message & 0x00000001 )// resume evt
DoMyActivate(); // resume means activate
else
DoMyDeactivate( ); // suspend = deactivate
}
// -------- check for a mouse-moved event ------
if (( theEvent. message & 0xFF000000)==0xFA000000){ // moved
DoMaintainCursor( &theEvent );
}
break;
} // end switch
} // end while
Referenced by (195):