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.

Nested Types

NSEventType

Constants that represent various kinds of events.

NSPressureBehavior

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

NSEventSubtype

NSEventGestureAxis

These constants specify the gesture tracking axis.

NSPointingDeviceType

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

NSEventPhase

These constants represent the possible phases during an event phase.

NSEventSwipeTrackingOptions

These constants specify they swipe tracking options.

NSEventButtonMask

NSEventMask

These constants are masks for the events defined in NSEventType. Pass them to the NSCell method sendAction(on:) to specify when an NSCell object should send its action message.

NSEventModifierFlags

Symbols

Creating Events

class func keyEvent(with: NSEventType, location: NSPoint, modifierFlags: NSEventModifierFlags, timestamp: TimeInterval, windowNumber: Int, context: NSGraphicsContext?, characters: String, charactersIgnoringModifiers: String, isARepeat: Bool, keyCode: UInt16)

Returns a new NSEvent object describing a key event.

class func mouseEvent(with: NSEventType, location: NSPoint, modifierFlags: NSEventModifierFlags, timestamp: TimeInterval, windowNumber: Int, context: NSGraphicsContext?, eventNumber: Int, clickCount: Int, pressure: Float)

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

class func enterExitEvent(with: NSEventType, location: NSPoint, modifierFlags: NSEventModifierFlags, timestamp: TimeInterval, windowNumber: Int, context: NSGraphicsContext?, eventNumber: Int, trackingNumber: Int, userData: UnsafeMutableRawPointer?)

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

class func otherEvent(with: NSEventType, location: NSPoint, modifierFlags: NSEventModifierFlags, timestamp: TimeInterval, windowNumber: Int, context: NSGraphicsContext?, subtype: Int16, data1: Int, data2: Int)

Returns a new NSEvent object describing a custom event.

init?(eventRef: UnsafeRawPointer)

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

init?(cgEvent: CGEvent)

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

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: NSEventModifierFlags

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: NSEventType

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 func modifierFlags()

Returns the currently pressed modifier flags.

class func keyRepeatDelay()

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

class func keyRepeatInterval()

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 func pressedMouseButtons()

Returns the indices of the currently depressed mouse buttons.

class func doubleClickInterval()

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

class func mouseLocation()

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.

class func setMouseCoalescingEnabled(Bool)

Controls whether mouse-movement event coalescing is enabled.

class func isMouseCoalescingEnabled()

Indicates whether mouse-movement event coalescing is enabled.

var associatedEventsMask: NSEventMask

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 trackingArea: NSTrackingArea?

The NSTrackingArea object for the 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: NSEventSubtype

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: NSPressureBehavior

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: NSPointingDeviceType

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: NSEventButtonMask

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: NSTouchPhase, in: NSView?)

Returns all the NSTouch objects associated with a specific phase.

class func isSwipeTrackingFromScrollEventsEnabled()

Returns the user's preference about using gesture scrolls as a way to track fluid swipes.

Monitoring Application Events

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

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

class func addLocalMonitorForEvents(matching: NSEventMask, 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: NSEventPhase

The momentum phase for a scroll or flick gesture.

var phase: NSEventPhase

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

func trackSwipeEvent(options: NSEventSwipeTrackingOptions = [], dampenAmountThresholdMin: CGFloat, max: CGFloat, usingHandler: (CGFloat, NSEventPhase, Bool, UnsafeMutablePointer<ObjCBool>) -> Void)

Allows tracking and user interface feedback of scroll wheel events.

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

NSEventSwipeTrackingOptions

These constants specify they swipe tracking options.

NSEventGestureAxis

These constants specify the gesture tracking axis.

NSEventPhase

These constants represent the possible phases during an event phase.

NSEventType

Constants that represent various kinds of events.

NSEventMask

These constants are masks for the events defined in NSEventType. Pass them to the NSCell method sendAction(on:) to specify when an NSCell object should send its action message.

Modifier Flags

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

NSPointingDeviceType

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.

Power-off event

This constant denotes that the user is turning off the computer.

Function-Key Unicodes

These constants represent Unicode characters (0xF700–0xF8FF) that are reserved for function keys on the keyboard. Combined in NSStrings, they represent values that can be used with the characters and charactersIgnoringModifiers properties and may be used in some parameters in the NSEvent method keyEvent(with:location:modifierFlags:timestamp:windowNumber:context:characters:charactersIgnoringModifiers:isARepeat:keyCode:).