Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
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:
Mouse events are sent when users move a mouse and press its buttons. AppKit categorizes events generated by a mouse into general type, direction of click, and mouse button. General types are mouse clicks, mouse drags, and mouse movements (with no button pressed).
Key events are generated when uses press the keys of a keyboard. Specific key events are key down, key up, and flags changed (the latter used to detect modifier keys pressed).
Trackpad events are generated when users make multi-touch movements on a trackpad. There are two general kinds, gesture events and touch events.
Tablet events originate from tablet devices and can indicate either proximity to the tablet or a point on the tablet. Certain mouse events are also generated as tablet events.
Tracking-area events are generated when the mouse cursor enters a tracking area, moves around in it, and leaves it. For these actions, AppKit sends mouse-tracking, mouse-moved, and cursor-update messages to a handling object.
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.
Copyright © 2018 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2018-04-06