Attributes of an Event Object

An NSEvent object is largely a read-only repository of information related to a specific event. Most methods of the NSEvent class are accessor methods for getting the values of event attributes. (NSEvent has no corresponding “setter” accessor methods, although you can specify certain attributes when creating an event object using various class factory methods.) An object such as a responder typically uses the accessor methods to get the details of an event and thus know how to handle it.

Some NSEvent attributes (and their corresponding accessor methods) are common to all types of events while others are specific to certain types of events. For example, the clickCount method pertains only to mouse events and the characters method pertains only to key events. Tablet events have a number of accessor methods that apply only to them. Some of the more important accessor methods of NSEvent are the following:

type

The type of event; see Event Types.

window

The NSWindow object representing the window in which the event occurred. With windowNumber you can also obtain the number assigned by the window server to the window. Most but not all events are associated with a window; when no window is associated, window returns nil.

locationInWindow

The location of the event within the window’s base coordinate system.

modifierFlags

An indication of which modifier keys (Command, Control, Shift, and so on) the user held down while the event occurred.

characters

The Unicode characters generated by a key event. You can also use charactersIgnoringModifiers to obtain the key-event characters minus those generated by modifier keys.

timestamp

The time the event occurred (in seconds since system startup).

clickCount

For mouse events within a certain time threshold, the number of clicks associated with a particular event. (This enables the detection of double- or triple-clicking.)

NSEvent Class Methods

Though you rarely need do so, you can create an event object from scratch and either insert it into the event queue for distribution or send it directly to its destination in an event message. The NSEvent class includes class methods for creating event objects of a specific type; for example, for creating a mouse-type event object, you can use the class method mouseEventWithType:location:modifierFlags:timestamp:windowNumber:context:eventNumber:clickCount:pressure:. You add event objects to the event queue by invoking the NSWindow method postEvent:atStart: or the identically named method of the NSApplication class.

Another NSEvent class method, mouseLocation, returns the current location of the mouse. It differs in a few important respects from the instance method locationInWindow. Being a class method, it doesn’t require an event object to send the message to; it returns the location in screen coordinates rather than base (window) coordinates; and it returns the current mouse location, which might be different from that of the current or any pending mouse event.

Event Objects in Methods of Other Classes

NSEvent objects are scattered throughout the Application Kit. For example, the classes NSCell, NSCursor, NSClipView, NSMenu, NSSlider, and NSTableView all have methods with event objects as return values or parameters. However, a few Application Kit methods that deal with event objects are particularly important.

Although most events are distributed automatically through the responder chain, sometimes an object needs to retrieve events explicitly—for example, while mouse tracking. Both NSWindow and NSApplication define the method nextEventMatchingMask:untilDate:inMode:dequeue:, which allows an object to retrieve events of specific types from the event queue.

NSApplication and NSWindow also both define the currentEvent method, which fetches the last event object retrieved from the event queue. These methods are a great convenience because they enable any object in an application to learn about the event currently being handled in the main event loop.

Finally, both NSWindow and NSApplication define the sendEvent: method. The implementations of these methods are critical for event dispatch. Because these methods are funnel points for events in an application, you may override them in certain circumstances to learn about events earlier in the event stream or to augment or modify the native event-dispatch behavior. Event Dispatch talks about the role played by the sendEvent: methods.

Mouse Events

Mouse events are generated by changes in the state of the mouse buttons and by changes in the position of the mouse cursor on the screen. They fall into two subcategories, one related to mouse clicks and movements and the other related to mouse tracking and cursor updates.

Key Events

Among the most common events sent to an application are direct reports of the user’s keyboard actions, identified by these NSEventType constants:

NSKeyDown

The user generated a character or characters by pressing a key.

NSKeyUp

The user released a key. This event is always preceded by a NSKeyDown event.

NSFlagsChanged

The user pressed or released a modifier key, or turned Caps Lock on or off.

Of these, key-down events are the most useful to an application. When the type of an event is NSKeyDown, the next step is typically to get the characters generated by the key-down using the characters method.

Key-up events are used less frequently since they follow almost automatically when there’s been a key-down event. And because the NSEvent modifierFlags method returns the state of the modifier keys regardless of the type of event, applications normally don’t need to receive flags-changed events; they’re useful only for applications that have to keep track of the state of these keys at all times.

Some key presses generate key events that do not represent characters to be inserted as text. Instead they represent key equivalents, keyboard interface control commands, or keyboard actions. Key equivalents and keyboard interface control commands are typically handled by the application object and do not invoke the NSResponder method associated with NSKeyDown events, keyDown:. See The Path of Key Events for more information.

For more information on key events, see Handling Key Events.

Tablet Events

Tablet devices generate low-level events that a Cocoa application receives as NSEvent objects. The following sections describe tablet devices, the characteristics of tablet events, and how the Application Kit supports tablet events.

Types of Tablet Events

There are two types of tablet events in the Application Kit: proximity events and pointer events. The following sections describe what they are, how they are related to each other, and the sequence of proximity and pointer events in a typical tablet session.

Proximity Events

A proximity event is an event that a tablet device generates when a pointing transducer (for example, a stylus) comes near or moves away from the tablet surface. It indicates the start or the end of a related series of pointer events (a session). A proximity event is an NSEvent object of type NSTabletProximity. An application can determine whether a tablet-pointer session is beginning or ending by sending isEnteringProximity to the event object.

The main purpose of a proximity event is to provide an application with a set of identifiers for associating items of tablet hardware—entire tablet devices or individual transducers—with the current pointing session. A proximity tablet event can also furnish an application with information about the capabilities of a specific device.

A proximity-type tablet event carries with it a set of identifiers and device attributes that an application can fetch with accessor methods. These include the following:

• Device ID—The main identifier of a tablet device, used to associate pointer-type events with proximity events. All tablet pointer events in a session have the same device ID.

  Accessor: deviceID

• Pointing devices—To help an application distinguish among pointing devices, you can ask a proximity event for the device’s serial number, its type (for example, pen or eraser), and, for tablets that support multiple concurrent pointing devices, its device ID.

  Accessors: pointingDeviceSerialNumber, pointingDeviceType, pointingDeviceID

• Tablets—You can ask a proximity event for a tablet’s identifier (which is its USB model number) and, if there are multiple tablets connected to a system, its system tablet ID.

  Accessors: tabletID, systemTabletID

• Vendor information—An NSEvent object with a proximity type may contain an identifier of the vendor and an identifier of a pointing device within a vendor’s selection of devices.

  Accessors: vendorID, vendorPointingDeviceType

• Capabilities—A bit mask whose set bits indicate the capabilities of a tablet device. It is vendor-specific.

  Accessor: capabilityMask

Generally, when an application receives a proximity event, it stores the device ID and any other identifier that is needed to distinguish among various items of tablet hardware involved in the session. It then refers to these identifiers when handling pointer events to ensure it is processing the right events. An application can also extract device information from proximity events (for example, tablet capabilities or pointer type) and use this information to configure how it deals with pointer events.

Pointer Events

A pointer event is an event that a tablet device generates after a stylus has entered proximity of the tablet. It indicates a change in the state of the transducer. For example, if the user moves a stylus transducer over the surface of the tablet or increases pressure or tilts the pointing device, a pointer event is generated. A pointer event is an NSEvent object of type NSTabletPoint or an object representing a mouse-down, mouse-dragged, or mouse-up event with a subtype of NSTabletPointEventSubtype.

Applications generally use pointer events for drawing or user-interface manipulation. Although you can obtain the absolute three-dimensional coordinates of the current pointer location, these coordinates are in full tablet resolution and require you to scale them to the screen location. It is much simpler to use the NSEvent instance method locationInWindow or the class method mouseLocation.

In addition to pointer location, the information obtainable from pointer events include the following:

• Pressure, as a value between 0.0 and 1.0; you might use the pressure attribute to set the opacity of a color.

  Accessor: pressure

• Rotation, in degrees; you might use the rotation attribute to simulate a calligraphy pen.

  Accessor: rotation

• Tilt, an NSPoint structure, with both axes ranging from -1 to 1; you might use the tilt attribute to supply different colors, depending on the angle and direction of tilt.

  Accessor: tilt

• Tangential pressure, as a value between -1.0 and 1.0 (only on certain devices).

  Accessor: tangentialPressure

• Button number of transducer pressed.

  Accessor: buttonMask

• Vendor-defined data.

  Accessor: vendorDefined

Sequence of Tablet Events

A tablet proximity event signals the start of a series of related tablet pointer event and a subsequent proximity event signals the end of the series. These two proximity events thus provide a kind of frame for processing the pointer events in a session. The first proximity event is generated when a pointing device comes near a tablet surface; the second is generated when the same pointing device leaves the proximity of the tablet.

The sequence of proximity and pointer events have special significance to the application handling the tablet events. A tablet event generated by a pointing device that comes near the tablet lets the tablet application know that it should store identifiers and set configuration variables for the upcoming tablet session. The application processes the pointer events until it receivers the second proximity event, which tells it that those identifiers and configurations are no longer operative. A tablet session is thus a sequence of pointer events that are associated with a specific pair of proximity events.

The relationship between proximity and pointer events is simple and clear as long as only one pointing device is in play. But there can be multiple pointing devices on a tablet surface at one time, or more than one tablet devices can be connected to a system. In this case the application must store the identifiers it receivers in all initial proximity events and use those identifiers to differentiate among various series of pointer events.

Take, for example, a tablet device that supports multiple pointing device on the tablet surface at one time. One pointing device might be a stylus for line drawing; another pointing device might apply an airbrush painting effect. As Figure 2-1 illustrates, a proximity event is generated with the drawing stylus comes close to the tablet surface.

When handling this proximity event, the application stores the device ID of the tablet device, the device ID of the pointing device, and perhaps also the serial number of the pointing device and its type. Until it receives the next proximity event with these same identifiers, it processes all pointer events it receives for the pointing device—in this case, drawing lines (Figure 2-2).

Now the airbrush pointing device moves onto the surface of the tablet, generating another proximity event (Figure 2-3). Because this event carries with it different identifiers, the application knows its not the terminating proximity event for the first tablet session. Instead it announces an impending series of pointer events for another pointing device. So the application stores the identifiers and configuration information for this session.

For a period, the tablet application is processing two different series of pointer events, using the stored identifiers to distinguish between the two. Then, as depicted in Figure 2-4, the drawing pointing device moves away from the tablet surface. This action generates a proximity event. The application examines the event and sees that the identifiers for the pointing device are the same as what it initially stored for the line-drawing device. It nullifies the stored identifiers, bringing to a close the initial series of pointer events.

Other Types of Events

The Application Kit defines several minor event types. Some of these are rarely used, but they are available if you ever find need for them.

A periodic event (type NSPeriodic) simply notifies an application that a certain time interval has elapsed. Periodic events are particularly useful in situations where input events aren’t generated but you want them to be. For example, when the user holds the mouse down over a scroll button but doesn’t move it, no events are generated after the mouse-down event. The Application Kit’s scrolling mechanism then starts and uses a stream of periodic events to keep the document scrolling at a reasonable pace until the user releases the mouse. When a mouse-up event occurs, the scrolling mechanism terminates the periodic event stream.

You use the NSEvent class method startPeriodicEventsAfterDelay:withPeriod: to generate periodic events and have them placed in the event queue at a certain frequency. When you no longer need them, turn off the flow of periodic events by invoking stopPeriodicEvents. Unlike key and mouse events, periodic events aren’t dispatched to a window object. The application must retrieve them explicitly using the NSApplication method nextEventMatchingMask:untilDate:inMode:dequeue:, typically in a modal loop. An application can have only one stream of periodic events active for each thread. You use periodic events instead of timers because NSPeriodic events are delivered along with other events; this makes for a responder object to look for periodic events along with mouse-up and mouse-dragged events. such as is done (for example) during scrolling.

The remaining event types—NSAppKitDefined, NSSystemDefined, and NSApplicationDefined—are less structured, containing only generic subtype and data fields. Of these three miscellaneous event types, only NSApplicationDefined is of real use to application programs. It allows the application to generate custom events and insert them into the event queue. Each such event can have a subtype and two additional codes to differentiate it from others. The NSEvent method otherEventWithType:location:modifierFlags:timestamp:windowNumber:context:subtype:data1:data2: creates one of these events, and the subtype, data1, and data2 methods return the information specific to these events.