Class

NSEvent

An object that contains information about an input action such as a mouse click or a key press.

Declaration

@interface NSEvent : NSObject

Overview

AppKit associates each user action, such as a mouse click, with a window and reports the event to the application that created the window. The NSEvent object contains pertinent information about each event, such as where the cursor was located or which character was typed. As the application receives events, it temporarily places them in a buffer called the event queue. When the application is ready to process an event, it takes one from the queue.

NSEvent objects can also represent tablet-pointing and tablet-proximity events. A tablet-proximity event is generated when a pointing device enters or leaves the proximity of its tablet; such event objects have a type of NSTypeProximity or a mouse subtype of NSTabletProximityEventSubtype. A tablet-pointing event is generated when a pointing device changes state, such as location, pressure, or tilt; such event objects have a type of NSTypePoint or a mouse subtype of NSTabletPointEventSubtype. AppKit reports all pure tablet events to responder objects through the NSResponder methods tabletPoint: and tabletProximity:. Mouse events can also contain tablet data (as event subtypes), so you can handle these events by overriding the NSResponder methods mouseDown:, mouseDragged:, and mouseUp:.

NSEvent objects can also represent touch and gesture events. Magnify (pinch), swipe, and rotate masks are supported, as are more generic gesture masks. Using the touchesMatchingPhase:inView: method, a view can get all of the touch events associated with a gesture without overriding the individual touch responder methods defined in NSResponder.

Pressure events are supported on devices that support pressure sensitivity. These events are reported as event type NSEventTypePressure, and invoke the responder method pressureChangeWithEvent: in NSResponder or pressureChangeWithEvent: in NSGestureRecognizer.

You can create application event monitors that call handlers in block objects for certain event types that are sent through the NSApplication sendEvent: method. You can create a local monitor that will be informed of the events in your application and allow you to modify or cancel them. You can also create a global event monitor that allows you to monitor events in other applications, although you are unable to alter those events. See Monitoring Application Events for more information.

Topics

Creating Events

+ mouseEventWithType:location:modifierFlags:timestamp:windowNumber:context:eventNumber:clickCount:pressure:

Returns a new NSEvent object describing a mouse-down, -up, -moved, or -dragged event.

+ enterExitEventWithType:location:modifierFlags:timestamp:windowNumber:context:eventNumber:trackingNumber:userData:

Returns a new NSEvent object describing a tracking-rectangle or cursor-update event.

+ eventWithEventRef:

Creates an event object that is based on a Carbon type of event.

+ eventWithCGEvent:

Creates and returns an event object that is based on a Core Graphics type of event.

Getting the Event Type

type

The event’s type.

NSEventType

Various types of events.

subtype

The event’s subtype.

NSEventSubtype

Subtypes for various types of events.

modifierFlags

An integer bit field indicating the event’s modifier keys.

NSEventMask

Constants that are masks for the events defined in NSEventType.

Getting General Event Information

context

The display graphics context for this event.

Deprecated
locationInWindow

The receiver’s location in the base coordinate system of the associated window.

timestamp

The time when the event occurred in seconds since system startup.

window

The window object associated with the event.

windowNumber

The identifier for the window device associated with the event.

eventRef

An opaque Carbon type associated with this event.

CGEvent

The Core Graphics event object corresponding to this event.

Getting Key Event Information

modifierFlags

Returns the currently pressed modifier flags.

NSEventModifierFlags

Flags that represent key states in an event object.

keyRepeatDelay

Returns the length of time a key must be held down in order to generate the first key repeat event.

keyRepeatInterval

Returns the length between subsequent key repeat events being posted.

characters

The characters associated with a key-up or key-down event.

charactersIgnoringModifiers

The characters generated by a key event as if no modifier key (except for Shift) applies.

ARepeat

A Boolean value that indicates whether the key event is a repeat.

keyCode

The virtual key code for the keyboard key associated with a key event.

Getting Mouse Event Information

pressedMouseButtons

Returns the indices of the currently depressed mouse buttons.

doubleClickInterval

Returns the time, in seconds, in which a second mouse click must occur in order to be considered a double click.

mouseLocation

Reports the current mouse position in screen coordinates.

buttonNumber

The button number for a mouse event.

clickCount

The number of mouse clicks associated with a mouse-down or mouse-up event.

associatedEventsMask

The associated events mask of a mouse event.

Getting Mouse-Tracking Event Information

eventNumber

The counter value of the latest mouse or tracking-rectangle event object; every system-generated mouse and tracking-rectangle event increments this counter.

trackingNumber

The identifier of a mouse-tracking event.

trackingArea

The NSTrackingArea object for the event.

userData

The data associated with a mouse-tracking event.

Getting Custom Event Information

data1

Additional data associated with this event.

data2

Additional data associated with this event.

Getting Scroll Wheel Event Information

deltaX

The x-coordinate change for mouse-move, mouse-drag, and swipe events.

deltaY

The y-coordinate change for mouse-move, mouse-drag, and swipe events.

deltaZ

The z-coordinate change for a scroll wheel, mouse-move, or mouse-drag event.

Getting Pressure Information

pressure

A value from 0.0 through 1.0 indicating the degree of pressure applied to an appropriate input device.

stage

A value of 0, 1, or 2, indicating the stage of a gesture event of type NSEventTypePressure.

stageTransition

The transition value for the stage of a pressure gesture event of type NSEventTypePressure.

pressureBehavior

The pressure behavior and progression for an event of type NSEventTypePressure.

NSPressureBehavior

These constants describe the behavior and progression of a pressure gesture.

Getting Tablet Proximity Information

capabilityMask

A mask whose set bits indicate the capabilities of the tablet device that generated this event.

deviceID

A special identifier that is used to match tablet-pointer and tablet-proximity events.

enteringProximity

A Boolean value that indicates whether a pointing device is entering or leaving the proximity of its tablet.

pointingDeviceID

The index of the pointing device currently in proximity with the tablet.

pointingDeviceSerialNumber

The vendor-assigned serial number of a pointing device.

pointingDeviceType

The kind of pointing device associated with this event.

NSPointingDeviceType

The pointing-device types for tablet-proximity events or mouse events with a proximity event subtype.

systemTabletID

The index of the tablet device connected to the system.

tabletID

The USB model identifier of the tablet device associated with this event.

uniqueID

The unique identifier of the pointing device that generated this event.

vendorID

The vendor identifier of the tablet associated with the event.

vendorPointingDeviceType

A coded bit field whose set bits indicate the type of pointing device (within a vendor selection) associated with the event.

Getting Tablet Pointing Information

absoluteX

The absolute x coordinate of a pointing device on its tablet at full tablet resolution.

absoluteY

The absolute y coordinate of a pointing device on its tablet at full tablet resolution.

absoluteZ

The absolute z coordinate of pointing device on its tablet at full tablet resolution.

buttonMask

A bit mask identifying the buttons pressed for a tablet event.

rotation

The rotation in degrees of the tablet pointing device associated with this event.

tangentialPressure

The tangential pressure on the device that generated this event.

tilt

The scaled tilt values of the pointing device that generated this event.

vendorDefined

An array of three vendor-defined NSNumber objects associated with a pointing-type event.

Requesting and Stopping Periodic Events

+ startPeriodicEventsAfterDelay:withPeriod:

Begins generating periodic events for the current thread.

+ stopPeriodicEvents

Stops generating periodic events for the current thread and discards any periodic events remaining in the queue.

Getting Touch and Gesture Information

magnification

The change in magnification.

- touchesMatchingPhase:inView:

Returns all the NSTouch objects associated with a specific phase.

Monitoring Application Events

+ addGlobalMonitorForEventsMatchingMask:handler:

Installs an event monitor that receives copies of events posted to other applications.

+ addLocalMonitorForEventsMatchingMask:handler:

Installs an event monitor that receives copies of events posted to this application before they are dispatched.

+ removeMonitor:

Remove the specified event monitor.

Scroll Wheel and Flick Events

hasPreciseScrollingDeltas

A Boolean value that indicates whether precise scrolling deltas are available.

scrollingDeltaX

The scroll wheel’s horizontal delta.

scrollingDeltaY

The scroll wheel’s vertical delta.

momentumPhase

The momentum phase for a scroll or flick gesture.

phase

The phase of a gesture event, such as a magnify, scroll, or pressure change.

NSEventPhase

Constants that represent the possible phases during an event phase.

- trackSwipeEventWithOptions:dampenAmountThresholdMin:max:usingHandler:

Allows tracking and user interface feedback of scroll wheel events.

NSEventSwipeTrackingOptions

Constants that specify swipe-tracking options.

directionInvertedFromDevice

A Boolean value that indicates whether the user has changed the device inversion.

Converting a Mouse Event’s Position into a Sprite Kit Node’s Coordinate Space

- locationInNode:

Returns the location of the receiver in the coordinate system of the given node.

Getting Unicode Values

Function-Key Unicodes

Unicode characters (0xF700–0xF8FF) that are reserved for function keys on the keyboard.

Relationships

Inherits From

Conforms To

See Also

Mouse, Keyboard, and Touch Events

NSTouch

A snapshot of a particular touch at an instant in time.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software