A primary responsibility of an event-driven application is to handle user events—that is, events generated by devices such as mice, keyboards, trackpads, and tablets. For most Cocoa applications, the Application Kit assumes the largest share of this work. It ensures that events generated by the mouse, keyboard, and other devices are routed to the objects best suited to handle them. It also implements dozens of user-interface objects such as controls and text views to respond to events in expected ways—for example, by inserting typed text or sending an action message. But often an application, especially an application with custom
NSApplication objects, finds that it must handle some events itself.
Cocoa Event Handling Guide explains how to handle events of all types in a Cocoa application. It provides conceptual background for the task-based chapters by describing the Cocoa architecture for dispatching and handling events, and by giving an overview of
NSEvent objects, which all event-handling code must deal with. Reading this document will give you a solid foundation for handling events in your Cocoa application.
Organization of This Document
This document includes the following chapters:
Event Architecture describes how events enter a Cocoa application, how they are dispatched to view objects, and how they are handled, sometimes after traveling up a chain of responder objects.
Event Objects and Types examines the Cocoa objects that represent events and surveys the types of events a Cocoa application can receive.
Event Handling Basics presents the fundamental tasks in event-handling code regardless of event type.
Handling Mouse Events describes how you can handle events arising from the user clicking or dragging the mouse.
Handling Key Events describes how you can handle events resulting from the user pressing keys on a keyboard.
Using Tracking-Area Objects explains how to use
NSTrackingAreaobjects to manage mouse tracking and cursor updates within regions of views.
Handling Tablet Events describes how to handle events generated by moving and manipulating a stylus over a tablet device.
Text System Defaults and Key Bindings discusses the mechanism for binding key combinations to action messages and describes various defaults that can be applied to Cocoa’s text system.
The appendix Using Tracking-Area Objects covers the legacy API for mouse tracking and cursor updates. It explains how to set up tracking and cursor rectangles and handle the events that are subsequently generated when users move the mouse cursor into those areas.
The following documents are conceptually related to Cocoa Event-Handling Guide:
Because view objects often redraw themselves in response to events, it is also recommended that you peruse Cocoa Drawing Guide.
The following sample code projects include illustrative event-handling code:
BoingX—mouse dragging, key events
CIAnnotation—mouse clicks, mouse dragging
Cocoa OpenGL—mouse clicks, key events
Color Sampler—mouse clicks, mouse dragging
Cropped Image—mouse clicks, mouse dragging
DragItemAround—mouse clicks, mouse dragging, keyboard actions
ImageMapExample—mouse dragging, mouse tracking
CircleView—mouse clicks, mouse dragging
ClockControl—responder related, keyboard actions
SimpleStickies—mouse clicks, mouse dragging