A Cocoa event is a message and a corresponding object that the Window Server sends to an application in response to some action taken by the user. Pressing a key on the keyboard generates an event, as does releasing that same key. Pressing the mouse button in a window generates an event, as does releasing the mouse button (and moving the mouse, too).

The Mac OS X Window Server, which was introduced in Chapter 1, is a low-level process running in the background that is responsible for sending events to applications and displaying images on the screen. It isolates you from the details of the Mac’s hardware. We’ll discuss the Window Server in detail in the next chapter.

Events drive applications. Every action that a user takes is turned into an event by the Window Server, which in turn sends the event information to the appropriate Mac OS X application. Each window has an event mask that it uses to tell the Window Server which events it wants to receive. We’ll describe event masks in more detail later in this chapter.

What is actually sent to the application is an event record, in the form of an NSEvent object. The NSApplication object stores events in an event queue.

When your program receives an event, it is packaged in an NSEvent object. The types of information that the object contains, along with the data types, is in the file NSEvent.h. Search for this file via the Find or Classes (vertical) tab in Project Builder if you’re curious about the class interface.

Cocoa supports many different kinds of events. The following 21 events are listed in the file NSEvent.h:

typedef enum _NSEventType {
        NSLeftMouseDown         = 1,
        NSLeftMouseUp           = 2,
        NSRightMouseDown        = 3,
        NSRightMouseUp          = 4,
        NSMouseMoved            = 5,
        NSLeftMouseDragged      = 6,
        NSRightMouseDragged     = 7,
        NSMouseEntered          = 8,
        NSMouseExited           = 9,
        NSKeyDown               = 10,
        NSKeyUp                 = 11,
        NSFlagsChanged          = 12,
        NSAppKitDefined         = 13,
        NSSystemDefined         = 14,
        NSApplicationDefined    = 15,
        NSPeriodic              = 16,
        NSCursorUpdate          = 17,
        NSScrollWheel           = 22,
        NSOtherMouseDown        = 25,
        NSOtherMouseUp          = 26,
        NSOtherMouseDragged     = 27
} NSEventType;

It’s unlikely that you’ll ever work with these event numbers, because whenever the NSApplication object receives event numbers from the Window Server, it automatically translates them into Objective-C messages. The corresponding methods are defined in the NSResponder class.

NSResponder is the abstract superclass that contains Cocoa’s event-responding mechanism. Most of the classes that we have discussed so far in this book, including NSApplication, NSWindow, and NSView, are subclasses of NSResponder. The NSResponder methods are defined in the file NSResponder.h. The methods that are important for event handling include the following.

                  - (void)mouseDown:(NSEvent *)theEvent;
- (void)mouseUp:(NSEvent *)theEvent;
- (void)mouseMoved:(NSEvent *)theEvent;
- (void)mouseDragged:(NSEvent *)theEvent;
- (void)scrollWheel:(NSEvent *)theEvent;
                  - (void)rightMouseDown:(NSEvent *)theEvent;
- (void)rightMouseUp:(NSEvent *)theEvent;
- (void)rightMouseDragged:(NSEvent *)theEvent;
- (void)mouseEntered:(NSEvent *)theEvent;
- (void)mouseExited:(NSEvent *)theEvent;
- (void)keyDown:(NSEvent *)theEvent;
- (void)keyUp:(NSEvent *)theEvent;
- (BOOL)performKeyEquivalent:(NSEvent *)theEvent;

This list contains about half of the event-handling methods available in NSResponder. Each of the methods in the list has a pointer to an NSEvent object as its first and only argument. By sending messages via this pointer to an NSEvent object, you can learn about the NSEvent itself. Table 8-1 describes the messages that you would typically send to an NSEvent object from your event-handler code.