---

Introduction

Contents:

Organization of This Document
See Also

A primary responsibility of an event-driven application is to handle user events—that is, events generated by devices such as mice, keyboards, 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 NSView, NSWindow, or 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. It is recommended that you read Cocoa Fundamentals Guide before reading this document.

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 NSTrackingArea objects 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.

See Also

The following ADC Reference Library documents are conceptually related to Cocoa Event-Handling Guide:

• Cocoa Fundamentals Guide (prerequisite reading)

• View Programming Guide for Cocoa

• Text Input Management

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 in the ADC Reference Library 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

• FunkyOverlayWindow—mouse tracking

• ImageMapExample—mouse dragging, mouse tracking

• People—key events

• Sketch-112—mouse clicks, mouse dragging, key events, keyboard actions

The following sample code projects, which are installed in /Developer/Examples/AppKit, also contain useful event-handling code:

• Circle View—mouse clicks, mouse dragging

• Clock Control—responder related, keyboard actions

• Dot View—mouse clicks

• Rulers—mouse dragging

• Stickies—mouse clicks, mouse dragging

---