Next Page >

Hide TOC

Quartz Event Services Reference

Framework	ApplicationServices/ApplicationServices.h
Declared in	CGEvent.h CGEventSource.h CGEventTypes.h CGRemoteOperation.h

Overview

This document describes the C API for event taps, which are filters used to observe and alter the stream of low-level user input events in Mac OS X. 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 Mac 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.

Functions by Task

Working With Quartz Events

Working With Quartz Event Taps

Working With Quartz Event Sources

Obsolete Functions

Functions

CGEnableEventStateCombining

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

CGError CGEnableEventStateCombining (
   boolean_t doCombineState
);

Parameters

doCombineState: Pass true to specify that the actual key and mouse state are merged with the application-specified state in a synthetic event; otherwise, pass false.

Return Value

A result code. See the result codes described in Quartz Display Services Reference.

Discussion

By default, the flags that indicate modifier key state (Command, Option, Shift, Control, and so on) from the system's keyboard and from other event sources are ORed together as an event is posted into the system, and current key and mouse button state is considered in generating new events. This function allows your application to enable or disable the merging of event state. When combining is turned off, the event state propagated in the events posted by your application reflect state built up only by your application. The state within your application’s generated event will not be combined with the system's current state, so the system-wide state reflecting key and mouse button state will remain unchanged. When called with doCombineState equal to false, this function initializes local (per application) state tracking information to a state of all keys, modifiers, and mouse buttons up. When called with doCombineState equal to true, the current global state of keys, modifiers, and mouse buttons are used in generating events.

This function is not recommended for general use because of undocumented special cases and undesirable side effects. The recommended replacement for this function is to use Quartz events and Quartz event sources. This allows you to control exactly which, if any, external event sources will contribute to the state used to create an event.

Availability

Available in Mac OS X v10.1 and later.

Declared In

CGRemoteOperation.h

CGEventCreate

Returns a new Quartz event.

CGEventRef CGEventCreate (
   CGEventSourceRef source
);

Parameters

source: The event source, or NULL to use a default source.

Return Value

A new event to be filled in, or NULL if the event could not be created. When you no longer need the event, you should release it using the function CFRelease.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventCreateCopy

Returns a copy of an existing Quartz event.

CGEventRef CGEventCreateCopy (
   CGEventRef event
);

Parameters

event: The event being copied.

Return Value

A copy of the specified event. When you no longer need the copy, you should release it using the function CFRelease.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventCreateData

Returns a flattened data representation of a Quartz event.

CFDataRef CGEventCreateData (
   CFAllocatorRef allocator,
   CGEventRef event
);

Parameters

allocator: The allocator to use to allocate memory for the data object. To use the current default allocator, pass NULL or kCFAllocatorDefault.
event: The event to flatten.

Return Value

The flattened data representation of the event, or NULL if the event parameter is invalid. When you no longer need the data object, you should release it using the function CFRelease.

Discussion

You can use this function to flatten an event for network transport to another system.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventCreateFromData

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

CGEventRef CGEventCreateFromData (
   CFAllocatorRef allocator,
   CFDataRef eventData
);

Parameters

allocator: The allocator to use to allocate memory for the event object. To use the current default allocator, pass NULL or kCFAllocatorDefault.
eventData: The flattened data representation of the event to reconstruct.

Return Value

An event built from the flattened data representation, or NULL if the eventData parameter is invalid.

Discussion

You can use this function to reconstruct a Quartz event received by network transport from another system.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventCreateKeyboardEvent

Returns a new Quartz keyboard event.

CGEventRef CGEventCreateKeyboardEvent (
   CGEventSourceRef source,
   CGKeyCode virtualKey,
   bool keyDown
);

Parameters

source: An event source taken from another event, or NULL.
virtualKey: The virtual key code for the event.
keyDown: Pass true to specify that the key position is down. To specify that the key position is up, pass false. This value is used to determine the type of the keyboard event—see “Event Types.”

Return Value

A new keyboard event, or NULL if the event could not be created. When you no longer need the event, you should release it using the function CFRelease.

Discussion

All keystrokes needed to generate a character must be entered, including modifier keys. For example, to produce a 'Z', the SHIFT key must be down, the 'z' key must go down, and then the SHIFT and 'z' key must be released:

CGEventRef event1, event2, event3, event4;

event1 = CGEventCreateKeyboardEvent (NULL, (CGKeyCode)56, true);

event2 = CGEventCreateKeyboardEvent (NULL, (CGKeyCode)6, true);

event3 = CGEventCreateKeyboardEvent (NULL, (CGKeyCode)6, false);

event4 = CGEventCreateKeyboardEvent (NULL, (CGKeyCode)56, false);

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventCreateMouseEvent

Returns a new Quartz mouse event.

CGEventRef CGEventCreateMouseEvent (
   CGEventSourceRef source,
   CGEventType mouseType,
   CGPoint mouseCursorPosition,
   CGMouseButton mouseButton
);

Parameters

source: An event source taken from another event, or NULL.
mouseType: A mouse event type. Pass one of the constants listed in “Event Types.”
mouseCursorPosition: The position of the mouse cursor in global coordinates.
mouseButton: The button that’s changing state. Pass one of the constants listed in “Mouse Buttons.” This parameter is ignored unless the mouseType parameter is kCGEventOtherMouseDown, kCGEventOtherMouseDragged, or kCGEventOtherMouseUp.

Return Value

A new mouse event, or NULL if the event could not be created. When you no longer need the event, you should release it using the function CFRelease.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventCreateScrollWheelEvent

Returns a new Quartz scrolling event.

CGEventRef CGEventCreateScrollWheelEvent (
   CGEventSourceRef source,
   CGScrollEventUnit units,
   CGWheelCount wheelCount,
   int32_t wheel1,
   
);

Parameters

source: An event source taken from another event, or NULL.
units: The unit of measurement for the scrolling event. Pass one of the constants listed in “Scrolling Event Units.”
wheelCount: The number of scrolling devices on the mouse, up to a maximum of 3.
wheel1: A value that reflects the movement of the primary scrolling device on the mouse. Scrolling movement is generally represented by small signed integer values, typically in a range from -10 to +10. Large values may have unexpected results, depending on the application that processes the event.
...: Up to two values that reflect the movements of the other scrolling devices on the mouse, if any.

Return Value

A new scrolling event, or NULL if the event could not be created. When you no longer need the event, you should release it using the function CFRelease.

Discussion

This function allows you to create a scrolling event and customize the event before posting it to the event system.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGEvent.h

CGEventCreateSourceFromEvent

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

CGEventSourceRef CGEventCreateSourceFromEvent (
   CGEventRef event
);

Parameters

event: The event to access.

Return Value

An event source created from the specified event, or NULL if the event was generated with a private event source owned by another process. When you no longer need this event source, you should release it using the function CFRelease.

Discussion

Event filters may use the event source to generate events that are compatible with an event being filtered.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventGetDoubleValueField

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

double CGEventGetDoubleValueField (
   CGEventRef event,
   CGEventField field
);

Parameters

event: The event to access.
field: A field in the specified event. Pass one of the constants listed in “Event Fields.”

Return Value

A floating point representation of the current value of the specified field.

Discussion

In cases where the field value is represented within the event by a fixed point number or an integer, the result is scaled to the appropriate range as part of creating the floating point representation.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventGetFlags

Returns the event flags of a Quartz event.

CGEventFlags CGEventGetFlags (
   CGEventRef event
);

Parameters

event: The event to access.

Return Value

The current flags of the specified event. For more information, see “Event Flags.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventGetIntegerValueField

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

int64_t CGEventGetIntegerValueField (
   CGEventRef event,
   CGEventField field
);

Parameters

event: The event to access.
field: A field in the specified event. Pass one of the constants listed in “Event Fields.”

Return Value

A 64-bit integer representation of the current value of the specified field.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventGetLocation

Returns the location of a Quartz mouse event.

CGPoint CGEventGetLocation (
   CGEventRef event
);

Parameters

event: The mouse event to locate.

Return Value

The current location of the specified mouse event in global display coordinates.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventGetTimestamp

Returns the timestamp of a Quartz event.

CGEventTimestamp CGEventGetTimestamp (
   CGEventRef event
);

Parameters

event: The event to access.

Return Value

The current timestamp of the specified event.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventGetType

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

CGEventType CGEventGetType (
   CGEventRef event
);

Parameters

event: The event to access.

Return Value

The current event type of the specified event. The return value is one of the constants listed in “Event Types.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventGetTypeID

Returns the type identifier for the opaque type CGEventRef.

CFTypeID CGEventGetTypeID (
   void
);

Return Value

The Core Foundation type identifier for the opaque type CGEventRef.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventGetUnflippedLocation

Returns the location of a Quartz mouse event.

CGPoint CGEventGetUnflippedLocation (
   CGEventRef event
);

Parameters

event: The mouse event whose location you wish to obtain.

Return Value

The current location of the specified mouse event relative to the lower-left corner of the main display.

Discussion

This function returns the location of the mouse cursor associated with the event. The coordinate system used is relative to the lower-left corner of the main display, and is compatible with the global coordinate system used by the Application Kit.

Note that the y-coordinate of the returned location is off by one from an idealized coordinate system originating at the lower-left corner of the main display. Effectively, the function is defined as follows:

CGPoint p = CGEventGetLocation(event);

p.y = main_display_height - p.y;

/* not p.y = (main_display_height - 1) - p.y */

return p;

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGEvent.h

CGEventKeyboardGetUnicodeString

Returns the Unicode string associated with a Quartz keyboard event.

void CGEventKeyboardGetUnicodeString (
   CGEventRef event,
   UniCharCount maxStringLength,
   UniCharCount *actualStringLength,
   UniChar unicodeString[]
);

Parameters

event: The keyboard event to access.
maxStringLength: The length of the array you provide in the unicodeString parameter.
actualStringLength: A pointer to a UniCharCount variable. On return, the variable contains the actual count of Unicode characters in the event data.
unicodeString: A pointer to a UniChar array. You are responsible for allocating storage for the array. On return, your array contains the Unicode string associated with the specified event.

Discussion

When you call this function and specify a NULL string or a maximum string length of 0, the function still returns the actual count of Unicode characters in the event data.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventKeyboardSetUnicodeString

Sets the Unicode string associated with a Quartz keyboard event.

void CGEventKeyboardSetUnicodeString (
   CGEventRef event,
   UniCharCount stringLength,
   const UniChar unicodeString[]
);

Parameters

event: The keyboard event to access.
stringLength: The length of the array you provide in the unicodeString parameter.
unicodeString: An array that contains the new Unicode string associated with the specified event.

Discussion

By default, the system translates the virtual key code in a keyboard event into a Unicode string based on the keyboard ID in the event source. This function allows you to manually override this string. Note that application frameworks may ignore the Unicode string in a keyboard event and do their own translation based on the virtual keycode and perceived event state.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventMaskBit

Generates an event mask for a single type of event.

CGEventMask CGEventMaskBit (
   CGEventType eventType
);

Parameters

eventType: An event type constant. Pass one of the constants listed in “Event Types.”

Return Value

An event mask that represents the specified event.

Discussion

This macro converts an event type constant into a mask. You can use this mask to specify that an event tap should observe the event. For more information, see CGEventMask.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventTypes.h

CGEventPost

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

void CGEventPost (
   CGEventTapLocation tap,
   CGEventRef event
);

Parameters

tap: The location at which to post the event. Pass one of the constants listed in “Event Tap Locations.”
event: The event to post.

Discussion

This function posts the specified event immediately before any event taps instantiated for that location, and the event passes through any such taps.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventPostToPSN

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

void CGEventPostToPSN (
   void *processSerialNumber,
   CGEventRef event
);

Parameters

processSerialNumber: The process to receive the event.
event: The event to post.

Discussion

This function makes it possible for an application to establish an event routing policy, for example, by tapping events at the kCGAnnotatedSessionEventTap location and then posting the events to another desired process.

This function posts the specified event immediately before any event taps instantiated for the specified process, and the event passes through any such taps.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventSetDoubleValueField

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

void CGEventSetDoubleValueField (
   CGEventRef event,
   CGEventField field,
   double value
);

Parameters

event: The event to access.
field: A field in the specified event. Pass one of the constants listed in “Event Fields.”
value: The new value of the specified field.

Discussion

Before calling this function, the event type must be set using a typed event creation function such as CGEventCreateMouseEvent, or by calling CGEventSetType.

In cases where the field’s value is represented within the event by a fixed point number or integer, the value parameter is scaled as needed and converted to the appropriate type.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventSetFlags

Sets the event flags of a Quartz event.

void CGEventSetFlags (
   CGEventRef event,
   CGEventFlags flags
);

Parameters

event: The event to access.
location: The new flags of the specified event. See “Event Flags.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventSetIntegerValueField

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

void CGEventSetIntegerValueField (
   CGEventRef event,
   CGEventField field,
   int64_t value
);

Parameters

event: The event to access.
field: A field in the specified event. Pass one of the constants listed in “Event Fields.”
value: The new value of the specified field.

Discussion

Before calling this function, the event type must be set using a typed event creation function such as CGEventCreateMouseEvent, or by calling CGEventSetType.

If you are creating a mouse event generated by a tablet, call this function and specify the field kCGMouseEventSubtype with a value of kCGEventMouseSubtypeTabletPoint or kCGEventMouseSubtypeTabletProximity before setting other parameters.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventSetLocation

Sets the location of a Quartz mouse event.

void CGEventSetLocation (
   CGEventRef event,
   CGPoint location
);

Parameters

event: The mouse event whose location to set.
location: The new location of the specified mouse event in global display coordinates.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventSetSource

Sets the event source of a Quartz event.

void CGEventSetSource (
   CGEventRef event,
   CGEventSourceRef source
);

Parameters

event: The event to access.
source: The new event source of the specified event.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventSetTimestamp

Sets the timestamp of a Quartz event.

void CGEventSetTimestamp (
   CGEventRef event,
   CGEventTimestamp timestamp
);

Parameters

event: The event to access.
timestamp: The new timestamp of the specified event.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventSetType

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

void CGEventSetType (
   CGEventRef event,
   CGEventType type
);

Parameters

event: The event to access.
type: The new event type of the specified event. The return value is one of the constants listed in “Event Types.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventSourceButtonState

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

bool CGEventSourceButtonState (
   CGEventSourceStateID sourceState,
   CGMouseButton button
);

Parameters

sourceState: The source state to access. Pass one of the constants listed in “Event Source States.”
button: The mouse button to test. Pass one of the constants listed in “Mouse Buttons.”

Return Value

If true, the button is down. If false, the button is up.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceCounterForEventType

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

uint32_t CGEventSourceCounterForEventType (
   CGEventSourceStateID source,
   CGEventType evType
);

Parameters

sourceState: The source state to access. Pass one of the constants listed in “Event Source States.”
eventType: The event type to access. To get the count of input events—keyboard, mouse, or tablet—specify kCGAnyInputEventType.

Return Value

The count of events of the specified type seen since the window server started.

Discussion

Quartz provides these counters for applications that monitor user activity. For example, an application could prompt a typist to take a break to reduce repetitive stress injuries.

Modifier keys produce kCGEventFlagsChanged events, not kCGEventKeyDown events, and do so both on press and release. The volume, brightness, and CD eject keys on some keyboards (both desktop and laptop) do not generate key up or key down events.

For various reasons, the number of key up and key down events may not be the same when all keyboard keys are up. As a result, a mismatch does not necessarily indicate that some keys are down.

Key autorepeat events are not counted.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceCreate

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

CGEventSourceRef CGEventSourceCreate (
   CGEventSourceStateID sourceState
);

Parameters

sourceState: The event state table to use for this event source. Pass one of the constants listed in “Event Source States.”

Return Value

A new event source, or NULL if the specified source state is not valid. When you no longer need the event source, you should release it using the function CFRelease.

Discussion

If two or more event sources are using the same source state and one of them is released, the remaining event sources will behave as if all keys and buttons on input devices are up in generating new events from this source.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceFlagsState

Returns the current flags of a Quartz event source.

CGEventFlags CGEventSourceFlagsState (
   CGEventSourceStateID sourceState
);

Parameters

sourceState: The source state to access. Pass one of the constants listed in “Event Source States.”

Return Value

The current flags of the specified event source. For more information, see “Event Flags.”

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceGetKeyboardType

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

CGEventSourceKeyboardType CGEventSourceGetKeyboardType (
   CGEventSourceRef source
);

Parameters

source: The event source to access. Pass one of the constants listed in “Event Source States.”

Return Value

The keyboard type to be used with the specified event source.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceGetLocalEventsFilterDuringSuppressionState

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

CGEventFilterMask CGEventSourceGetLocalEventsFilterDuringSuppressionState (
   CGEventSourceRef source,
   CGEventSuppressionState state
);

Parameters

source: The event source to access.
state: The type of event suppression interval during which the filter is applied. Pass one of the constants listed in “Event Suppression States.”

Return Value

A mask that specifies the categories of local hardware events to enable during the event suppression interval. See “Event Filter Masks.”

Discussion

You can configure the system to suppress local hardware events from the keyboard or mouse during a short interval after a Quartz event is posted or during a synthetic mouse drag (mouse movement with the left or only mouse button down). For information about setting this local events filter, see CGEventSourceSetLocalEventsFilterDuringSuppressionState.

This function lets you specify an event source and a suppression state (event suppression interval or mouse drag), and returns a filter mask of event categories to be passed through during suppression.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceGetLocalEventsSuppressionInterval

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

CFTimeInterval CGEventSourceGetLocalEventsSuppressionInterval (
   CGEventSourceRef source
);

Parameters

source: The event source to access.

Discussion

By default, the system does not suppress local hardware events from the keyboard or mouse during a short interval after a Quartz event is posted. You can use the function CGEventSourceSetLocalEventsFilterDuringSuppressionState to modify this behavior.

This function gets the period of time in seconds that local hardware events may be suppressed after posting a Quartz event created with the specified event source. You can use the function CGEventSourceSetLocalEventsSuppressionInterval to change this time interval.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceGetPixelsPerLine

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

double CGEventSourceGetPixelsPerLine (
   CGEventSourceRef source
);

Parameters

source: The event source to access.

Return Value

The scale of pixels per line in a scrolling event.

Discussion

This function returns the scale of pixels per line in the specified event source. For example, if the scale in the event source is 10.5 pixels per line, this function would return 10.5. Every scrolling event can be interpreted to be scrolling by pixel or by line. By default, the scale is about ten pixels per line. You can alter the scale with the function CGEventSourceSetPixelsPerLine.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGEventSource.h

CGEventSourceGetSourceStateID

Returns the source state associated with a Quartz event source.

CGEventSourceStateID CGEventSourceGetSourceStateID (
   CGEventSourceRef source
);

Parameters

source: The event source to access.

Return Value

The source state associated with the specified event source.

Discussion

This function returns the ID of the source state table associated with an event source.

For event sources created with the kCGEventSourceStatePrivate source state, this function returns the ID of the private source state table created for the event source. This unique ID may be passed to the CGEventSourceCreate function to create a second event source sharing the same state table. This may be useful, for example, in creating separate mouse and keyboard sources which share a common private state.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceGetTypeID

Returns the type identifier for the opaque type CGEventSourceRef.

CFTypeID CGEventSourceGetTypeID (
   void
);

Return Value

The Core Foundation type identifier for the opaque type CGEventSourceRef.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceGetUserData

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

int64_t CGEventSourceGetUserData (
   CGEventSourceRef source
);

Parameters

source: The event source to access.

Return Value

The user-specified data.

Discussion

Each input event includes 64 bits of user-specified data. This function gets the user-specified data for all events created by the specified event source. This data may also be obtained per event using the CGEventGetIntegerValueField function.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceKeyState

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

bool CGEventSourceKeyState (
   CGEventSourceStateID sourceState,
   CGKeyCode key
);

Parameters

sourceState: The source state to access. Pass one of the constants listed in “Event Source States.”
key: The virtual key code to test.

Return Value

If true, the key is down. If false, the key is up.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceSecondsSinceLastEventType

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

CFTimeInterval CGEventSourceSecondsSinceLastEventType (
   CGEventSourceStateID source,
   CGEventType eventType
);

Parameters

source: The source state to access. Pass one of the constants listed in “Event Source States.”
eventType: The event type to access. To get the elapsed time since the previous input event—keyboard, mouse, or tablet—specify kCGAnyInputEventType.

Return Value

The time in seconds since the previous input event of the specified type.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceSetKeyboardType

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

void CGEventSourceSetKeyboardType (
   CGEventSourceRef source,
   CGEventSourceKeyboardType keyboardType
);

Parameters

source: The event source to access.
keyboardType: The keyboard type to be used with the specified event source.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceSetLocalEventsFilterDuringSuppressionState

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

void CGEventSourceSetLocalEventsFilterDuringSuppressionState (
   CGEventSourceRef source,
   CGEventFilterMask filter,
   CGEventSuppressionState state
);

Parameters

source: The event source to access.
filter: A mask that specifies the categories of local hardware events to enable during the event suppression interval. See “Event Filter Masks.”
state: The type of event suppression interval during which the filter is applied. Pass one of the constants listed in “Event Suppression States.”

Discussion

By default, the system does not suppress local hardware events from the keyboard or mouse during a short interval after a Quartz event is posted—see CGEventSourceSetLocalEventsSuppressionInterval—and during a synthetic mouse drag (mouse movement with the left or only mouse button down).

Some applications may want to disable events from some of the local hardware during this interval. For example, if you post mouse events only, you may wish to suppress local mouse events and permit local keyboard events to pass through. This function lets you specify an event source, a suppression state (event suppression interval or mouse drag), and a filter mask of event classes to be passed through. The new local events filter takes effect with the next Quartz event you post using this event source.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceSetLocalEventsSuppressionInterval

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

void CGEventSourceSetLocalEventsSuppressionInterval (
   CGEventSourceRef source,
   CFTimeInterval seconds
);

Parameters

source: The event source to access.
seconds: The period of time in seconds that local hardware events (keyboard or mouse) are suppressed after posting a Quartz event created with the specified event source. The value should be a number in the range [0.0, 10.0].

Discussion

This function sets the period of time in seconds that local hardware events may be suppressed after posting a Quartz event created with the specified event source. The default suppression interval is 0.25 seconds.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventSourceSetPixelsPerLine

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

void CGEventSourceSetPixelsPerLine (
   CGEventSourceRef source,
   double pixelsPerLine
);

Parameters

source: The event source to access.
pixelsPerLine: The scale of pixels per line in the specified event source.

Discussion

This function sets the scale of pixels per line in the specified event source. For example, if you pass the value 12.0 in the pixelsPerLine parameter, the scale of pixels per line in the event source would be changed to 12.0. Every scrolling event can be interpreted to be scrolling by pixel or by line. By default, the scale is about ten pixels per line. You can retrieve the scale with the function CGEventSourceGetPixelsPerLine.

Availability

Available in Mac OS X v10.5 and later.

Declared In

CGEventSource.h

CGEventSourceSetUserData

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

void CGEventSourceSetUserData (
   CGEventSourceRef source,
   int64_t userData
);

Parameters

source: The event source to access.
userData: The user-specified data. For example, you could specify a vendor hardware ID.

Discussion

Each input event includes 64 bits of user-specified data. This function sets the user-specified data for all events created by the specified event source. This data may also be set per event using the CGEventGetIntegerValueField function.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEventSource.h

CGEventTapCreate

Creates an event tap.

CFMachPortRef CGEventTapCreate (
   CGEventTapLocation tap,
   CGEventTapPlacement place,
   CGEventTapOptions options,
   CGEventMask eventsOfInterest,
   CGEventTapCallBack callback,
   void *refcon
);

Parameters

tap: The location of the new event tap. Pass one of the constants listed in “Event Tap Locations.” Only processes running as the root user may locate an event tap at the point where HID events enter the window server; for other users, this function returns NULL.
place: The placement of the new event tap in the list of active event taps. Pass one of the constants listed in “Event Tap Placement.”
options: A constant that specifies whether the new event tap is a passive listener or an active filter.
eventsOfInterest: A bit mask that specifies the set of events to be observed. For a list of possible events, see “Event Types.” For information on how to specify the mask, see CGEventMask. If the event tap is not permitted to monitor one or more of the events specified in the eventsOfInterest parameter, then the appropriate bits in the mask are cleared. If that action results in an empty mask, this function returns NULL.
callback: An event tap callback function that you provide. Your callback function is invoked from the run loop to which the event tap is added as a source. The thread safety of the callback is defined by the run loop’s environment. To learn more about event tap callbacks, see CGEventTapCallBack.
refcon: A pointer to user-defined data. This pointer is passed into the callback function specified in the callback parameter.

Return Value

A Core Foundation mach port that represents the new event tap, or NULL if the event tap could not be created. When you are finished using the event tap, you should release the mach port using the function CFRelease. Releasing the mach port also releases the tap.

Discussion

Event taps receive key up and key down events if one of the following conditions is true:

The current process is running as the root user.
Access for assistive devices is enabled. In Mac OS X v10.4, you can enable this feature using System Preferences, Universal Access panel, Keyboard view.

After creating an event tap, you can add it to a run loop as follows:

Pass the event tap to the CFMachPortCreateRunLoopSource function to create a run loop event source.
Call the CFRunLoopAddSource function to add the source to the appropriate run loop.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventTapCreateForPSN

Creates an event tap for a specified process.

CFMachPortRef CGEventTapCreateForPSN (
   void *processSerialNumber,
   CGEventTapPlacement place,
   CGEventTapOptions options,
   CGEventMask eventsOfInterest,
   CGEventTapCallBack callback,
   void *refcon
);

Parameters

processSerialNumber: The process to monitor.
place: The placement of the new event tap in the list of active event taps. Pass one of the constants listed in “Event Tap Placement.”
options: A constant that specifies whether the new event tap is a passive listener or an active filter.
eventsOfInterest: A bit mask that specifies the set of events to be observed. For a list of possible events, see “Event Types.” For information on how to specify the mask, see CGEventMask. If the event tap is not permitted to monitor one or more of the events specified in the eventsOfInterest parameter, then the appropriate bits in the mask are cleared. If that action results in an empty mask, this function returns NULL.
callback: An event tap callback function that you provide. Your callback function is invoked from the run loop to which the event tap is added as a source. The thread safety of the callback is defined by the run loop’s environment. To learn more about event tap callbacks, see CGEventTapCallBack.
refcon: A pointer to user-defined data. This pointer is passed into the callback function specified in the callback parameter.

Return Value

Discussion

This function creates an event tap that receives events being routed by the window server to the specified process. For more information about creating event taps, see CGEventTapCreate.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventTapEnable

Enables or disables an event tap.

void CGEventTapEnable (
   CFMachPortRef myTap,
   bool enable
);

Parameters

myTap: The event tap to enable or disable.
enable: Pass true to enable the event tap. To disable it, pass false.

Discussion

Event taps are normally enabled when created. If an event tap becomes unresponsive, or if a user requests that event taps be disabled, then a kCGEventTapDisabled event is passed to the event tap callback function. Event taps may be re-enabled by calling this function.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventTapIsEnabled

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

bool CGEventTapIsEnabled (
   CFMachPortRef myTap
);

Parameters

myTap: The event tap to test.

Return Value

If true, the specified event tap is enabled; otherwise, false.

Discussion

For more information, see the function CGEventTapEnable.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h

CGEventTapPostEvent

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

void CGEventTapPostEvent (
   CGEventTapProxy proxy,
   CGEventRef event
);

Parameters

proxy: A proxy that identifies the event tap posting the event. Your event tap callback function is passed this proxy when it is invoked.
event: The event to post.

Discussion

You can use this function to post a new event at the same point to which an event returned from an event tap callback function would be posted. The new event enters the system before the event returned by the callback enters the system. Events posted into the system will be seen by all taps placed after the tap posting the event.

Availability

Available in Mac OS X v10.4 and later.

Declared In

CGEvent.h