Class

NSEvent

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

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(with:) and tabletProximity(with:). Mouse events can also contain tablet data (as event subtypes), so you can handle these events by overriding the NSResponder methods mouseDown(with:), mouseDragged(with:), and mouseUp(with:).

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 touches(matching:in:) 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 pressure, and invoke the responder method pressureChange(with:) in NSResponder or pressureChange(with:) 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

Getting General Event Information

var context: NSGraphicsContext?

The display graphics context for this event.

Deprecated
var locationInWindow: NSPoint

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

var modifierFlags: NSEvent.ModifierFlags

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

var timestamp: TimeInterval

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

var type: NSEvent.EventType

The event’s type.

var window: NSWindow?

The window object associated with the event.

var windowNumber: Int

The identifier for the window device associated with the event.

var eventRef: UnsafeRawPointer?

An opaque Carbon type associated with this event.

var cgEvent: CGEvent?

The Core Graphics event object corresponding to this event.

Getting Key Event Information

class var modifierFlags: NSEvent.ModifierFlags

Returns the currently pressed modifier flags.

class var keyRepeatDelay: TimeInterval

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

class var keyRepeatInterval: TimeInterval

Returns the length between subsequent key repeat events being posted.

var characters: String?

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

var charactersIgnoringModifiers: String?

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

var isARepeat: Bool

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

var keyCode: UInt16

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

Getting Mouse Event Information

class var pressedMouseButtons: Int

Returns the indices of the currently depressed mouse buttons.

class var doubleClickInterval: TimeInterval

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

class var mouseLocation: NSPoint

Reports the current mouse position in screen coordinates.

var buttonNumber: Int

The button number for a mouse event.

var clickCount: Int

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

var associatedEventsMask: NSEvent.EventTypeMask

The associated events mask of a mouse event.

Getting Mouse-Tracking Event Information

var eventNumber: Int

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

var trackingNumber: Int

The identifier of a mouse-tracking event.

var userData: UnsafeMutableRawPointer?

The data associated with a mouse-tracking event.

Getting Custom Event Information

var data1: Int

Additional data associated with this event.

var data2: Int

Additional data associated with this event.

var subtype: NSEvent.EventSubtype

The event’s subtype.

Getting Scroll Wheel Event Information

var deltaX: CGFloat

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

var deltaY: CGFloat

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

var deltaZ: CGFloat

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

Getting Pressure Information

var pressure: Float

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

var stage: Int

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

var stageTransition: CGFloat

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

var pressureBehavior: NSEvent.PressureBehavior

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

Getting Tablet Proximity Information

var capabilityMask: Int

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

var deviceID: Int

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

var isEnteringProximity: Bool

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

var pointingDeviceID: Int

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

var pointingDeviceSerialNumber: Int

The vendor-assigned serial number of a pointing device.

var pointingDeviceType: NSEvent.PointingDeviceType

The kind of pointing device associated with this event.

var systemTabletID: Int

The index of the tablet device connected to the system.

var tabletID: Int

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

var uniqueID: UInt64

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

var vendorID: Int

The vendor identifier of the tablet associated with the event.

var vendorPointingDeviceType: Int

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

var absoluteX: Int

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

var absoluteY: Int

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

var absoluteZ: Int

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

var buttonMask: NSEvent.ButtonMask

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

var rotation: Float

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

var tangentialPressure: Float

The tangential pressure on the device that generated this event.

var tilt: NSPoint

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

var vendorDefined: Any

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

Requesting and Stopping Periodic Events

class func startPeriodicEvents(afterDelay: TimeInterval, withPeriod: TimeInterval)

Begins generating periodic events for the current thread.

class func stopPeriodicEvents()

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

Getting Touch and Gesture Information

var magnification: CGFloat

The change in magnification.

func touches(matching: NSTouch.Phase, in: NSView?)

Returns all the NSTouch objects associated with a specific phase.

Monitoring Application Events

class func addGlobalMonitorForEvents(matching: NSEvent.EventTypeMask, handler: (NSEvent) -> Void)

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

class func addLocalMonitorForEvents(matching: NSEvent.EventTypeMask, handler: (NSEvent) -> NSEvent?)

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

class func removeMonitor(Any)

Remove the specified event monitor.

Scroll Wheel and Flick Events

var hasPreciseScrollingDeltas: Bool

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

var scrollingDeltaX: CGFloat

The scroll wheel’s horizontal delta.

var scrollingDeltaY: CGFloat

The scroll wheel’s vertical delta.

var momentumPhase: NSEvent.Phase

The momentum phase for a scroll or flick gesture.

var phase: NSEvent.Phase

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

var isDirectionInvertedFromDevice: Bool

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

func location(in: SKNode)

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

Constants

struct NSEvent.SwipeTrackingOptions

Constants that specify swipe-tracking options.

enum NSEvent.GestureAxis

The gesture tracking axis.

struct NSEvent.Phase

Constants that represent the possible phases during an event phase.

enum NSEvent.EventType

Various types of events.

struct NSEvent.EventTypeMask

Constants that are masks for the events defined in NSEvent.EventType.

Modifier Flags

The following constants (except for NSDeviceIndependentModifierFlagsMask) represent device-independent bits found in event modifier flags:

enum NSEvent.PointingDeviceType

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

Mouse-event subtypes

The following constants represent mouse-event subtypes for mouse and tablet events (accessed with the subtype property).

Tablet event masks

The following constants represent button masks for NSTabletPoint events or mouse events with subtype NSTabletPointEventSubtype. The buttonMask property returns a bit mask, which you test with one or more of these constants to determine the state of the buttons on a tablet pointing device.

Types Defined by the Application Kit

These constants represent the types of events defined by the Application Kit.

Function-Key Unicodes

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

enum NSEvent.PressureBehavior

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

Enumerations

enum NSEvent.EventSubtype

Subtypes for various types of events.

Relationships

Inherits From

See Also

Mouse, Keyboard, and Touch Events

class NSTouch

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

init(type: NSEvent.EventType)

Returns the event mask for the specified type.