Quartz Event Services

Provides features for managing event taps—filters for observing and altering the stream of low-level user input events in macOS.

Overview

Event taps make it possible to monitor and filter input events from several points within the system, prior to their delivery to a foreground application. Event taps complement and extend the capabilities of the Carbon event monitor mechanism, which allows an application to observe input events delivered to other processes (see the function GetEventMonitorTarget).

Event taps are designed to serve as a Section 508 enabling technology. For example, consider a software system to assist a person with language impairments, designed to perform keyboard filtering with spoken review. Such a system could use an event tap to monitor all keystrokes, perform dictionary checks and matches, and recite the assembled word back to the user on detection of a word break in the input stream. If acceptable to the user, as indicated by an additional input keystroke or other gesture, the events would be posted into the system for delivery to the foreground application.

Introduced in OS X version 10.4, event taps provide functionality similar to the Win32 functions SetWinEventHook when used to establish an out-of-context event hook, and SendInput. Quartz Event Services also includes an older set of event-related functions declared in the file CGRemoteOperation.h. These functions are still supported, but they are not recommended for new development.

Topics

Working With Events

CGEventGetTypeID

Returns the type identifier for the opaque type CGEventRef.

CGEventCreate

Returns a new Quartz event.

CGEventCreateData

Returns a flattened data representation of a Quartz event.

CGEventCreateFromData

Returns a Quartz event created from a flattened data representation of the event.

CGEventCreateMouseEvent

Returns a new Quartz mouse event.

CGEventCreateKeyboardEvent

Returns a new Quartz keyboard event.

CGEventCreateScrollWheelEvent

Returns a new Quartz scrolling event.

CGEventCreateCopy

Returns a copy of an existing Quartz event.

CGEventCreateSourceFromEvent

Returns a Quartz event source created from an existing Quartz event.

CGEventSetSource

Sets the event source of a Quartz event.

CGEventGetType

Returns the event type of a Quartz event (left mouse down, for example).

CGEventSetType

Sets the event type of a Quartz event (left mouse down, for example).

CGEventGetTimestamp

Returns the timestamp of a Quartz event.

CGEventSetTimestamp

Sets the timestamp of a Quartz event.

CGEventGetLocation

Returns the location of a Quartz mouse event.

CGEventGetUnflippedLocation

Returns the location of a Quartz mouse event.

CGEventSetLocation

Sets the location of a Quartz mouse event.

CGEventGetFlags

Returns the event flags of a Quartz event.

CGEventSetFlags

Sets the event flags of a Quartz event.

CGEventKeyboardGetUnicodeString

Returns the Unicode string associated with a Quartz keyboard event.

CGEventKeyboardSetUnicodeString

Sets the Unicode string associated with a Quartz keyboard event.

CGEventGetIntegerValueField

Returns the integer value of a field in a Quartz event.

CGEventSetIntegerValueField

Sets the integer value of a field in a Quartz event.

CGEventGetDoubleValueField

Returns the floating-point value of a field in a Quartz event.

CGEventSetDoubleValueField

Sets the floating-point value of a field in a Quartz event.

Working With Event Taps

CGEventTapCreate

Creates an event tap.

CGEventTapCreateForPSN

Creates an event tap for a specified process.

CGEventTapEnable

Enables or disables an event tap.

CGEventTapIsEnabled

Returns a Boolean value indicating whether an event tap is enabled.

CGEventTapPostEvent

Posts a Quartz event from an event tap into the event stream.

CGEventPost

Posts a Quartz event into the event stream at a specified location.

CGEventPostToPSN

Posts a Quartz event into the event stream for a specific application.

CGGetEventTapList

Gets a list of currently installed event taps.

CGEventMaskBit

Generates an event mask for a single type of event.

Working With Event Sources

CGEventSourceGetTypeID

Returns the type identifier for the opaque type CGEventSourceRef.

CGEventSourceCreate

Returns a Quartz event source created with a specified source state.

CGEventSourceGetKeyboardType

Returns the keyboard type to be used with a Quartz event source.

CGEventSourceSetKeyboardType

Sets the keyboard type to be used with a Quartz event source.

CGEventSourceGetSourceStateID

Returns the source state associated with a Quartz event source.

CGEventSourceButtonState

Returns a Boolean value indicating the current button state of a Quartz event source.

CGEventSourceKeyState

Returns a Boolean value indicating the current keyboard state of a Quartz event source.

CGEventSourceFlagsState

Returns the current flags of a Quartz event source.

CGEventSourceSecondsSinceLastEventType

Returns the elapsed time since the last event for a Quartz event source.

CGEventSourceCounterForEventType

Returns a count of events of a given type seen since the window server started.

CGEventSourceGetUserData

Returns the 64-bit user-specified data for a Quartz event source.

CGEventSourceSetUserData

Sets the 64-bit user-specified data for a Quartz event source.

CGEventSourceGetLocalEventsFilterDuringSuppressionState

Returns the mask that indicates which classes of local hardware events are enabled during event suppression.

CGEventSourceSetLocalEventsFilterDuringSuppressionState

Sets the mask that indicates which classes of local hardware events are enabled during event suppression.

CGEventSourceGetLocalEventsSuppressionInterval

Returns the interval that local hardware events may be suppressed following the posting of a Quartz event.

CGEventSourceSetLocalEventsSuppressionInterval

Sets the interval that local hardware events may be suppressed following the posting of a Quartz event.

CGEventSourceGetPixelsPerLine

Gets the scale of pixels per line in a scrolling event source.

CGEventSourceSetPixelsPerLine

Sets the scale of pixels per line in a scrolling event source.

Callbacks

CGEventTapCallBack

A client-supplied callback function that’s invoked whenever an associated event tap receives a Quartz event.

Data Types

CGButtonCount

Represents the number of buttons being set in a synthetic mouse event.

CGCharCode

Represents a character generated by pressing one or more keys on a keyboard.

CGEventMask

Defines a mask that identifies the set of Quartz events to be observed in an event tap.

CGEventRef

Defines an opaque type that represents a low-level hardware event.

CGEventSourceKeyboardType

Defines a code that represents the type of keyboard used with a specified event source.

CGEventSourceRef

Defines an opaque type that represents the source of a Quartz event.

CGEventTapInformation

Defines the structure used to report information about event taps.

CGEventTapProxy

Defines an opaque type that represents state within the client application that’s associated with an event tap.

CGEventTimestamp

Defines the elapsed time in nanoseconds since startup that a Quartz event occurred.

CGKeyCode

Represents the virtual key codes used in keyboard events.

CGWheelCount

Represents the number of wheels being set in a scroll wheel event.

Constants

CGEventField

Constants used as keys to access specialized fields in low-level events.

CGEventFilterMask

Specify masks for classes of low-level events that can be filtered during event suppression states.

CGEventFlags

Constants that indicate the modifier key state at the time an event is created, as well as other event-related states.

CGEventSourceStateID

Constants that specify the possible source states of an event source.

Event Source Token

Specifies any input event type.

CGEventSuppressionState

Specify the event suppression states that can occur after posting an event.

CGEventTapLocation

Constants that specify possible tapping points for events.

CGEventTapOptions

Constants that specify whether a new event tap is an active filter or a passive listener.

CGEventTapPlacement

Constants that specify where a new event tap is inserted into the list of active event taps.

CGEventType

Constants that specify the different types of input events.

Event Type Mask

Specifies an event mask that represents all event types.

CGMouseButton

Constants that specify buttons on a one, two, or three-button mouse.

CGEventMouseSubtype

Constants used with the kCGMouseEventSubtype event field.

CGScrollEventUnit

Constants that specify the unit of measurement for a scrolling event.

Deprecated Functions

CGEventGetSource

Returns a Quartz event source created from an existing Quartz event.

CGPostKeyboardEvent

Synthesizes a low-level keyboard event on the local machine.

Deprecated
CGPostMouseEvent

Synthesizes a low-level mouse-button event on the local machine.

Deprecated
CGPostScrollWheelEvent

Synthesizes a low-level scrolling event on the local machine.

Deprecated
CGEnableEventStateCombining

Enables or disables the merging of actual key and mouse state with the application-specified state in a synthetic event.

Deprecated
CGInhibitLocalEvents

Turns off local hardware events in the current session.

Deprecated
CGSetLocalEventsFilterDuringSuppressionState

Filters local hardware events from the keyboard and mouse during the short interval after a synthetic event is posted.

Deprecated
CGSetLocalEventsSuppressionInterval

Sets the time interval in seconds that local hardware events are suppressed after posting a synthetic event.

Deprecated

See Also

Services

Quartz Display Services

Provides direct access to features in the macOS window server for configuring and controlling display hardware.

Quartz Window Services

Provides information about the windows managed by the macOS window server.