Function

CGEventTapCreate

Creates an event tap.

Declaration

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

Parameters

tap

The location of the new event tap. Pass one of the constants listed in CGEventTapLocation. 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 CGEventTapPlacement.

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

  1. Pass the event tap to the CFMachPortCreateRunLoopSource function to create a run loop event source.

  2. Call the CFRunLoopAddSource function to add the source to the appropriate run loop.

See Also

Working With Event Taps

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.