Class

NSEvent

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

Declaration

class 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(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 NSEvent.EventType.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

Creating Events

class func keyEvent(with: NSEvent.EventType, location: NSPoint, modifierFlags: NSEvent.ModifierFlags, timestamp: TimeInterval, windowNumber: Int, context: NSGraphicsContext?, characters: String, charactersIgnoringModifiers: String, isARepeat: Bool, keyCode: UInt16) -> NSEvent?

Returns a new NSEvent object describing a key event.

class func mouseEvent(with: NSEvent.EventType, location: NSPoint, modifierFlags: NSEvent.ModifierFlags, timestamp: TimeInterval, windowNumber: Int, context: NSGraphicsContext?, eventNumber: Int, clickCount: Int, pressure: Float) -> NSEvent?

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

class func enterExitEvent(with: NSEvent.EventType, location: NSPoint, modifierFlags: NSEvent.ModifierFlags, timestamp: TimeInterval, windowNumber: Int, context: NSGraphicsContext?, eventNumber: Int, trackingNumber: Int, userData: UnsafeMutableRawPointer?) -> NSEvent?

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

class func otherEvent(with: NSEvent.EventType, location: NSPoint, modifierFlags: NSEvent.ModifierFlags, timestamp: TimeInterval, windowNumber: Int, context: NSGraphicsContext?, subtype: Int16, data1: Int, data2: Int) -> NSEvent?

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 the Event Type

var type: NSEvent.EventType

The event’s type.

enum NSEvent.EventType

Various types of events.

var subtype: NSEvent.EventSubtype

The event’s subtype.

enum NSEvent.EventSubtype

Subtypes for various types of events.

var modifierFlags: NSEvent.ModifierFlags

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

struct NSEvent.EventTypeMask

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

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 timestamp: TimeInterval

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

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.

struct NSEvent.ModifierFlags

Flags that represent key states in an event object.

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 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.

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 NSEvent.EventType.pressure.

var stageTransition: CGFloat

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

var pressureBehavior: NSEvent.PressureBehavior

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

enum NSEvent.PressureBehavior

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

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.

enum NSEvent.PointingDeviceType

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

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.

struct NSEvent.ButtonMask

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?) -> Set<NSTouch>

Returns all the NSTouch objects associated with a specific phase.

func allTouches() -> Set<NSTouch>

func touches(for: NSView) -> Set<NSTouch>

func coalescedTouches(for: NSTouch) -> [NSTouch]

class var isMouseCoalescingEnabled: Bool

Monitoring Application Events

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

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

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

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.

struct NSEvent.Phase

Constants that represent the possible phases during an event phase.

class var isSwipeTrackingFromScrollEventsEnabled: Bool

func trackSwipeEvent(options: NSEvent.SwipeTrackingOptions, dampenAmountThresholdMin: CGFloat, max: CGFloat, usingHandler: (CGFloat, NSEvent.Phase, Bool, UnsafeMutablePointer<ObjCBool>) -> Void)

Allows tracking and user interface feedback of scroll wheel events.

struct NSEvent.SwipeTrackingOptions

Constants that specify swipe-tracking options.

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) -> CGPoint

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.

The gesture tracking axis.

Relationships

Inherits From

NSObject