User events (OS X)

An event is an object that encapsulates information about an action a user makes with a mouse, keyboard, or other input device. The AppKit framework delivers most events for handling to the view where the action occurred. AppKit defines many different types of events, including the following:


AppKit declares constants to represent most event types. It also declares the methods that you must override to handle events of specific types and categories.

Event and Touch Objects

When AppKit invokes an event-handling method, it passes in an NSEvent object. This object encapsulates information related to a user action such as the event type, a timestamp, and the associated window. Depending on the type of event, the information can also include the location of the event in the window, the number of of mouse clicks, Unicode characters (for a key press), and the modifier keys, if any, that were pressed.

An NSTouch object records a specific touch on the trackpad at specific moment. It is not persistent throughout a multitouch sequence; AppKit creates new instances the sequence progresses. However, you can follow a touch across its lifetime through an identity property. A gesture event is a series of touch objects that AppKit recognizes as a standard gesture (for example. rotate or swipe).

Event Delivery

Events begin as an asynchronous stream of low-level notifications delivered to an application through its main event loop. In the main event loop, an application gets an event from its event queue, converts it to an NSEvent object, and delivers it to an appropriate object for handling. After the event is handled, it gets the next event in the queue, dispatches it, and so on.

The path of event delivery varies by type and category of event. Generally, the application object (NSApp) sends the event to the window in which the user action occurred, and the window delivers the event to the view in which the user action occurred. For most key events, that view is the first responder; for mouse, tablet, and trackpad events, the view is the one in which the mouse click, stylus movement, or gesture took place. If the destination view does not handle the event, the event travels up the responder chain until it is either handled or discarded.

Handling an Event

To handle an event, a responder class (usually a custom view) first overrides the acceptsFirstResponder method (NSResponder) to return YES. (A view by default does not respond to events.) It then implements one or more methods declared by the NSResponder class for events of specific types and characteristics, such as mouseUp:, keyDown:, and tabletProximity:.

Many event-handling implementations examine the passed-in NSEvent object. For most mouse, tablet, and other events, you get the location of the event and convert that location to the view’s local coordinate system. You might also want to check the event type, subtype, timestamp, and modifier flags. If you completely handle the event, do not invoke the superclass implementation of the method. If you do not handle the event, or handle it only partially, pass it up the responder chain by invoking the superclass implementation.

Gesture events are handled the same way as other events. You implement methods such as magnifyWithEvent: and rotateWithEvent:. TheNSEvent class defines accessor methods such as magnification and rotation that give you the information you need to handle the event.

Prerequisite Articles

Related Articles

Definitive Discussion

Sample Code Projects