If no events are pending for the active application at a particular time, that application can choose to relinquish control of the CPU (central processing unit, or microprocessor) for a specified amount of time before again checking to see whether an event has occurred. Events are retrieved, and processor time is relinquished, using the WaitNextEvent function.

Information about a received event is placed in an event structure. An application may specify which types of events it wants to receive by including an event mask as a parameter in certain Event Manager functions.

Processes and Events

When multiple applications are open, the user chooses one, and only one, to interact with at any given time. This active application is known as the foreground process. The remaining open applications, if any, are known as background processes. The user can bring a background process to the foreground by clicking in one of its windows or by choosing its item in the Application menu. When an application is switched between background and foreground in this way, a major switch is said to have occurred.

The foreground process has first priority for accessing the CPU, background processes accessing the CPU only when the foreground process yields time to them. Any application whose 'SIZE' resource (see below) specifies that it should receive null events (see below) when it is in the background is eligible for CPU time when it is not in the foreground. A minor switch is said to have occurred when a background process gains a period of CPU access without being brought to the foreground.

Categories of Events

Of the three categories, this chapter is concerned only with low-level events and Operating System events. High-level events are addressed at Chapter 10 - Apple Events.

Low Level Events

The Window Manager also originates low-level events, specifically, two events relating to an application's windows:

• The activate event, which has to do with informing the application to make changes to the appearance of a window depending on whether or not it is the frontmost window.

• The update event, which has to do with informing the application to re-draw a window's contents.

Operating system events are invariably directed to the foreground process only.

Low-Level and Operating System Events, System Software, and Applications

In Fig 2, note that, in addition to the Operating System event queue created by the Operating System Event Manager, the Toolbox Event Manager maintains a separate event stream for each open application. An event stream contains only those events which are available to the related application. Also note that, when an application is in the background, its event stream can contain only update events and null events, and then only if the application's 'SIZE' resource so specifies.

An application in the background can also receive high-level events. (See Chapter 10 - Required Apple Events.)

• Activate events.

• Mouse-down, mouse-up, key-down, key-up and disk events in FIFO (first in, first out) order.

• Auto-key events.

• Update events, in front-to-back order of windows.

• Operating system events.

• High-level events.

• Null events.

The EventRecord data type defines the event structure:

     struct EventRecord
     {
       EventKind      what;
       UInt32         message;
       UInt32         when;
       Point          where;
       EventModifiers modifiers;
     };
     typedef struct EventRecord EventRecord;

nullEvent        = 0   No other pending events.
mouseDown        = 1   Mouse button pressed.
mouseUp          = 2   Mouse button released.
keyDown          = 3   Character key pressed.
keyUp            = 4   Character key released.
autoKey          = 5   Key held down in excess of autoKey threshold.
updateEvt        = 6   Window needs to be redrawn.
diskEvt          = 7   Disk was inserted.
activateEvt      = 8   Activate/deactivate window.
osEvt            = 15  Operating system event (suspend, resume, mouse moved).

charCodeMask          = 0x000000FF  Mask to extract ASCII character code.
keyCodeMask           = 0x0000FF00  Mask to extract key code.
osEvtMessageMask      = 0xFF000000  Mask to extract OS event message code.
mouseMovedMessage     = 0x00FA      osEvts: mouse-moved event?
suspendResumeMessage  = 0x0001      osEvts: suspend/resume event?
resumeFlag            = 1           osEvts: resume event or suspend event?
convertClipboardFlag  = 2           osEvts: convert clipboard?
     

switch((eventRecPtr->message >> 24) & 0x000000FF)
{
  case suspendResumeMessage:
    if((eventRecPtr->message & resumeFlag) == 1)
      // This is a resume event.
    else
      // This is a suspend event.
    break;
      
  case mouseMovedMessage:
    // This is a mouse-moved event.
    break;
}

activeFlag      = 0x0001  Window is to be activated? (activateEvt).
                          Foreground switch? (mouseDown).
btnState        = 0x0080  Mouse button up?
cmdKey          = 0x0100  Command key down?
shiftKey        = 0x0200  Shift key down?
alphaLock       = 0x0400  Caps Lock key down?
optionKey       = 0x0800  Option key down?
controlKey      = 0x1000  Control key down?
rightShiftKey   = 0x2000  Right Shift Key down?
rightOptionKey  = 0x4000  Right Option Key down?
rightControlKey = 0x8000  Right Control Key down?

Boolean becomingActive;

becomingActive = ((eventRecPtr->modifiers & activeFlag) == activeFlag);

if(becomingActive)
  // Application-defined window activation code here.
else
  // Application-defined window deactivation code here.

The WaitNextEvent Function

WaitNextEvent returns true if it retrieves any event other than a null event. If there are no events of the types specified in the eventMask parameter (other than null events), false is returned.

Boolean WaitNextEvent(EventMask eventMask, EventRecord *theEvent, UInt32 sleep, RgnHandle mouseRgn) Returns: A return code: 0 = null event; 1 = event returned.
eventMask	A 16 bit binary mask which may be used to mask out the receipt of certain events. The following constants are defined in Events.h: mDownMask = 0x0002 Mouse button pressed. mUpMask = 0x0004 Mouse button released. keyDownMask = 0x0008 Key pressed. keyUpMask = 0x0010 Key released. autoKeyMask = 0x0020 Key repeatedly held down. updateMask = 0x0040 Window needs updating. diskMask = 0x0080 Disk inserted. activMask = 0x0100 Activate/deactivate window. highLevelEventMask = 0x0400 High-level events (includes AppleEvents). osMask = 0x8000 Operating system events (suspend, resume). everyEvent = 0xFFFF All of the above. Masked events are not removed from the event stream by the WaitNextEvent call. To remove events from the Operating System event queue, call FlushEvents with the appropriate mask.
theEvent	Address of a 16-byte event record.
sleep	The amount of time, in ticks, the application agrees to relinquish the processor if no events are pending for it. When that time expires, or when an event becomes available for the application, the Process Manager schedules the application for execution. If your application needs to perform small subsidiary tasks at frequent intervals, you must ensure that your application regains control of the CPU at frequent intervals. For example, if the user is editing text and the application needs to blink the caret, the application must specify a value for the sleep parameter which is equal to the desired blink rate.
mouseRgn	The screen region inside which the Event Manager does not generate mouse-moved events. The region should be specified in global coordinates. If the user moves the cursor outside this region and the application is the foreground process, the Event Manager reports mouse-moved events. If NULL is passed as this parameter, the Event Manager does not return mouse- moved events.

Before returning to the application, WaitNextEvent performs certain additional processing and may, in fact, intercept the received event so that it is never received by your application. As will be seen, key-up and key-down events are intercepted in this way in certain circumstances.

Flushing the Operating System Event Queue

Events related to the movement of the mouse are not stored in the event queue. The mouse driver automatically tracks the mouse and displays the cursor as the user moves the mouse.

• Which of your application's windows, if any, the mouse button was pressed in.

• Which window part the mouse button was pressed in. In this context, a window part includes the menu bar as well as various regions within the window.

     inDesk          = 0  In none of the following.
     inNoWindow      = 0  In none of the following.
     inMenuBar       = 1  In the menu bar.
     inSysWindow     = 2  In a desk accessory window.
     inContent       = 3  Anywhere in the content region except the grow region
                          if the window is active.  Anywhere in the content 
                          region including the grow region if the window is 
                          inactive.
     inDrag          = 4  In the drag (title bar) region.
     inGrow          = 5  In the grow region (active window only).
     inGoAway        = 6  In the go-away region (active window only).
     inZoomIn        = 7  In the zoom-in region (active window only).
     inZoomOut       = 8  In the zoom-out region (active window only).
     inCollapseBox   = 11 In the collapse region (active window only).
     inProxyIcon     = 12 In the window proxy icon (active window only).

The content region is the part of the window in which an application displays the contents of a document and the window's controls (for example, scroll bars).

• Drag Bar. If the cursor was in the drag bar:

  • Mac OS 8.1 and Earlier. Under Mac OS 8.1 and earlier, your application should call DragWindow to allow the user to drag the window to a new location. DragWindow retains control until the mouse button is released.

  • Mac OS 8.5 and Later. Under Mac OS 8.5 and later, your application should first call IsWindowPathSelect to determine whether the mouse-down event should activate the window path pop-up menu. If IsWindowPathSelect returns true, your application should then call WindowPathSelect to display the menu, otherwise your application should call DragWindow to allow the user to drag the window to a new location. (See Chapter 4B - More on Windows - Mac OS 8.5 Window Manager.)

• Grow Box. If the cursor was in the grow box:

  • Mac OS 8.1 and Earlier. Under Mac OS 8.1 and earlier, your application should first call GrowWindow to track user actions while the mouse button remains down. When GrowWindow returns (that is, when the mouse button is released), SizeWindow should be called to re-draw the window in its new size.

  • Mac OS 8.5 and Later. Under Mac OS 8.5 and later, your application should call ResizeWindow, which tracks user actions while the mouse button remains down. When the mouse button is released, ResizeWindow draws the window in its new size. (See Chapter 4B - More on Windows - Mac OS 8.5 Window Manager.)

• Zoom Box. If the cursor was in the zoom box:

  • Mac OS 8.1 and Earlier. Under Mac OS 8.1 and earlier, your application should call TrackBox to track the mouse while the mouse button remains down. TrackBox returns true if the cursor is within the zoom box when the button is released, and false otherwise. If true is returned, the window content region should be erased, ZoomWindow should be called to redraw the window in its newly zoomed state, and the window's content region should be redrawn.

  • Mac OS 8.5 and Later. Under Mac OS 8.5 and later, your application should call IsWindowInStandardState to determine whether the window is currently in the standard state or the user state. ZoomWindowIdeal should then be called to zoom the window to the appropriate state, and the window's content region should be redrawn. (See Chapter 4B - More on Windows - Mac OS 8.5 Window Manager.)

• Go Away Box. If the cursor was in the go-away box, your application should call TrackGoAway to track user actions while the mouse button remains down. TrackGoAway, which returns only when the mouse is released, returns true if the cursor is still inside the close box when the mouse button is released, and false otherwise.

• Collapse Box. If the cursor was in the collapse box, your application should do nothing, because the system will collapse the window for you.

• Window Proxy Icon (Applicable Under Mac OS 8.5 and Later). If the cursor was in the window proxy icon, your application should call TrackWindowProxyDrag, which handles all aspects of the drag process while the user drags the proxy icon. (See Chapter 4B - More on Windows - Mac OS 8.5 Window Manager.)

When the mouse button is released, MenuSelect returns a long integer containing, ordinarily, the menu ID in the high word and the chosen menu item in the low word. However, if the cursor was outside the menu when the button was released, the high word contains 0.

In an Inactive Application Window

Ordinarily, the first click in an inactive window should simply activate the window and do nothing more. However, if the mouse click is in the drag bar, for example, you could elect to have your application activate the window and call DragWindow to allow the user to drag the window to a new location, all on the basis of the first mouse-down.

Detecting Mouse Double Clicks

The term keyboard equivalent refers to a keyboard combination, such as Command-C, or any other combination of the Command key, another key and one or more modifier keys (Shift, Option, or Control). The term Command-key equivalent refers specifically to a keyboard equivalent comprising the Command key and one other key other than a modifier key.

After determining the virtual key code, the system software uses a script-specific keyboard layout ('KCHR') resource to map the virtual keycode to a specific character code. Any given script system (that is, writing system) has one or more 'KCHR' resources (for example, a French 'KCHR' and a U.S. 'KCHR') which determine whether virtual key codes are mapped to, again for example, the French or the U.S. character set.

Usually, your application should use the character code rather than the virtual key code when responding to keyboard events. The following constants may be used as masks to access the virtual key code and character code in the message field:

     keyCodeMask   = 0x0000FF00  Mask to extract key code.
     charCodeMask  = 0x000000FF  Mask to extract ASCII character code.

• Command-Shift-Numeric Key Combinations. Some keystroke combinations are handled by the Event Manager and not returned to your application. These include certain combinations of Command-Shift-numeric keys, for example, Command-Shift-1 to eject a disk and Command-Shift-3 to take a snapshot of the screen. The action corresponding to such key combinations are implemented as a function that takes no parameters and which is stored in an 'FKEY' resource with a resource ID that corresponds to the number key that activates it. (Note that IDs of 1 to 4 are reserved by Apple.)

• Key-Up Events. At application launch, the Operating System initialises another event mask, called the system event mask, to exclude key-up messages. If an application needs to receive key-up events, the system event mask must be changed using the SetEventMask function.

The Window Manager maintains an update region for each window. It keeps track of all areas of a window's content region that need to be redrawn and accumulates them in this region. When the application calls WaitNextEvent, the Event Manager checks to see if any windows have an update region that is not empty. If it finds a non-empty update region, the Event Manager reports an update event to the appropriate application. If more than one window needs updating, the update events are issued for the front window first.

Updating the Window

This process is explained in more detail at Chapter 4 - Windows.

EndUpdate should then be called to restore the normal visible region.

Application-defined update functions should first determine if the window is a document window or a modeless dialog box and call separate application-defined functions for redrawing the window or the dialog box accordingly. (See Chapter 8 - Dialogs and Alerts.)

Updating Windows in the Background

SelectWindow does some of the activation/deactivation work for you, such as removing the highlighting from the window being deactivated and highlighting the window being activated. It also generates two activate events so that, at your application's next two requests for an event, an activate event is returned for the window being deactivated followed by an activate event for the window being activated. In response, your application must complete the action begun by SelectWindow, performing such actions as are necessary to complete the activation or deactivation process. Such actions might include, for example, showing or hiding the scroll bars, restoring or removing highlighting from any selections, adjusting menus, etc.

The message field of the event structure contains a pointer to the window being activated or deactivated and bit 0 of the modifiers field indicates whether the window is being activated or deactivated. The activeFlag constant may be used to test the state of this bit.

Activation/Deactivation in Response to Suspend and Resume Events

On the other hand, if your application has both the acceptSuspendResumeEvents and the doesActivateOnFGSwitch flags set, it does not receive an activate event immediately following suspend and resume events. In this case, your application must call its application-defined window activation/deactivation functions whenever it receives a suspend or resume event, in addition to the usual call made in response to an activate event.

The accepted practise is to set the doesActivateOnFGSwitch flag whenever the acceptSuspendResumeEvents flag is set.

Handling Disk-Inserted Events

In this latter case, your application should simply check if the disk was successfully mounted. If the disk was not successfully mounted (that is, if the high order word of the message field does not contain noErr), then the application should call the Disk Initialisation Manager function DIBadMount, which will inform the user via a dialog box. If the user clicks the OK box in this dialog, the disk will be initialised.

Basically, this handling is intended to give the user the chance to initialise or eject an uninitialised or damaged disk. If disk-inserted events are masked out, the event stays in the Operating System event queue until your application calls the Standard File Package Package or Navigation Services, or until an application which handles disk-inserted events becomes the foreground process. This behaviour can be confusing to the user; accordingly, your application should handle disk inserted events when they occur.

Handling Null Events

When your application receives a null event, and assuming it is the foreground process, it can perform what is known as idle processing, such as blinking the caret in the active window of the application.

As previously stated, your application's 'SIZE' resource can specify that the application receive null events while it is in the background. If your application receives a null event while it is in the background, it can perform tasks or do other processing.

In order not to deny a reasonable amount of processor time to other applications, idle processing and background processing should generally be kept to a minimum.

Handling Suspend and Resume Events

WaitNextEvent returns a suspend event when your application is about to be switched to the background and returns a resume event when your application becomes the foreground process.

Suspend Events

See Chapter 21- Floating Windows - Mac OS 8.5 and Earlier and Chapter 18 - Scrap.

The main requirement is to specify a region in the mouseRgn parameter of the WaitNextEvent function. This causes the Event Manager to report a mouse-moved event if the user moves the cursor outside that region. On receipt of the mouse-moved event, the application can change the shape of the cursor.

An application might define two regions: a region which encloses the text area of a window (the I-beam region) and a region which defines the scroll bars and all other areas outside the text area (the arrow region). By specifying the I-beam region to WaitNextEvent, the mouse driver continues to display the I-beam cursor until the user moves the cursor out of this region. When the cursor moves outside the region, WaitNextEvent reports a mouse-moved event. Your application can then change the I-beam cursor to the arrow cursor and change the mouseRgn parameter to the non-I-beam region. The cursor now remains an arrow until the user moves the cursor out of this region, at which point your application receives another mouse-moved event.

The application must, of course, recalculate and change the mouseRgn parameter immediately it receives a mouse-moved event. Otherwise, mouse-moved events will be continually received as long as the cursor is outside the original region.

The appearance of the cursor may be changed using the QuickDraw function SetCursor. The familiar I-beam, crosshairs, plus sign and wristwatch cursors are defined as resources, which can be retrieved by a call to GetCursor. (See Chapter 13 � Offcreen Graphics Worlds, Pictures Cursors and Icons). Alternatively, and assuming Mac OS 8.5 or later is present, the appearance of the cursor may be changed using the Appearance Manager function SetThemeCursor. (See Chapter 6 � The Appearance Manager.)

Cursor setting functions should account for whether a document window or modeless dialog box is active and set the cursor appropriately.

Handling Events in Alert Boxes and Dialog Boxes

The 'SIZE' Resource

An application's 'SIZE' resource informs the Operating System:

• About the memory requirements of the application.

• About certain scheduling options (for example, whether the application can accept suspend and resume events).

• Whether the application:

  • Is 32-bit clean.

  • Supports stationery documents.

  • Supports TextEdit's inline input services.

  • Wishes to receive notification of the termination of any application it has launched.

  • Wishes to receive high-level events.

Flags Fields. In CodeWarrior, the bits of the flags field can be set as desired using the 'SIZE' Flags pop-up menu in the 68K Target or PPC Target sections of the Settings dialog box, which appears when [Project Name] Settings... is chosen from the Edit Menu. The following descibes the meanings of the items in the pop-up menu, and thus of the relevant bits of the 16-bit flags field. Those items relevant to low-level and Operating System events appear on a blue background.

Size Fields. The minimum and preferred sizes of the application's partition may be set in the Preferred Heap Size (k) and MinimumHeap Size (k) sections of the 68K Target section of the Settings dialog box.

Notes on Multitasking

Under cooperative multitasking, individual applications continue executing until they "decide" to release control, thus allowing the background process of another application to begin executing. Even though this results in a usable form of multitasking, the operating system itself does not control the processor's scheduling. Even under the best of circumstances, an individual application (which has no way of knowing what other applications are running or whether they have a greater "need" to execute) makes inefficient use of the processor, which often results in the processor idling when it could be used for productive work.

Note also that, under this cooperative scheme, the assignment of zero to WaitNextEvent's sleep parameter will cause your application to completely "hog" the CPU whenever it is in the foreground, allowing no CPU time at all to the background processes.

Preemptive Multitasking

Main Event Manager Constants, Data Types and Functions

nullEvent    = 0   No other pending events.
mouseDown    = 1   Mouse button pressed.
mouseUp      = 2   Mouse button released.
keyDown      = 3   Character key pressed.
keyUp        = 4   Character key released.
autoKey      = 5   Key held down in excess of autoKey threshold.
updateEvt    = 6   Window needs to be redrawn.  
diskEvt      = 7   Disk was inserted.
activateEvt  = 8   Activate/deactivate window.
osEvt        = 15  Operating system event (suspend, resume or mouse moved).

mDownMask           = 0x0002  Mouse button pressed.
mUpMask             = 0x0004  Mouse button released.
keyDownMask         = 0x0008  Key pressed.
keyUpMask           = 0x0010  Key released.
autoKeyMask         = 0x0020  Key repeatedly held down.
updateMask          = 0x0040  Window needs updating.
diskMask            = 0x0080  Disk inserted.
activMask           = 0x0100  Activate/deactivate window.
highLevelEventMask  = 0x0400  High-level events (includes AppleEvents).
osMask              = 0x8000  Operating system events (suspend, resume).
everyEvent          = 0xFFFF  All of the above.Event Message

keyCodeMask   = 0x0000FF00  Mask to extract key code.
charCodeMask  = 0x000000FF  Mask to extract ASCII character code.

osEvtMessageMask      = 0xFF000000  Mask to extract OS event message code.
mouseMovedMessage     = 0x00FA      For osEvts, test for mouse-moved event.
suspendResumeMessage  = 0x0001      For osEvts, test for suspend/resume event.
resumeFlag            = 1           For osEvts, test Bit 0.
convertClipboardFlag  = 2           For osEvts, test whether to convert clipboard.

activeFlag       = 0x0001  Set if window being activated (activateEvt).
                           Set if event caused a foreground switch (mouseDown).
btnState         = 0x0080  Set if mouse button up.
cmdKey           = 0x0100  Set if Command key down.
shiftKey         = 0x0200  Set if Shift key down.
alphaLock        = 0x0400  Set if Caps Lock key down.
optionKey        = 0x0800  Set if Option key down.
controlKey       = 0x1000  Set if Control key down.
rightShiftKey    = 0x2000  Set if Right Shift Key down.
rightOptionKey   = 0x4000  Set if Right Option Key down.
rightControlKey  = 0x8000  Set if Right Control Key down.

struct EventRecord 
{
  EventKind       what;       // Event code.
  UInt32          message;    // Event message.
  UInt32          when;       // Ticks since system startup.
  Point           where;      // Mouse location in global coordinates.
  EventModifiers  modifiers;  // Modifier flags.
} EventRecord;
typedef struct EventRecord EventRecord;

Boolean  WaitNextEvent(EventMask eventMask,EventRecord *theEvent,UInt32 sleep,
                       RgnHandle mouseRgn);
Boolean  EventAvail(EventMask eventMask,EventRecord *theEvent;
void     FlushEvents(EventMask whichMask,EventMask stopMask);
void     SystemClick(const EventRecord *theEvent, WindowPtr theWindow);
void     SystemTask(void);
Boolean  GetOSEvent(EventMask mask,EventRecord *theEvent);
Boolean  OSEventAvail(EventMask mask,EventRecord *theEvent);
void     SetEventMask(EventMask value);

void     GetMouse(Point *mouseLoc);
Boolean  Button(void);
Boolean  StillDown(void);
Boolean  WaitMouseUp(void);

void     GetKeys(KeyMap theKeys);
UInt32   KeyTranslate(const void *transData,UInt16 keycode,UInt32 *state);

UInt32  TickCount(void);
UInt32  GetDblTime(void);
UInt32  GetCaretTime(void);