Mac Developer Library

Developer

ApplicationServices Framework Reference Quartz Event Services Reference

Options
Deployment Target:

On This Page
Language:

Quartz Event Services Reference

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

  • Returns the type identifier for the opaque type CGEventRef.

    Declaration

    Swift

    func CGEventGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGEventGetTypeID ( void );

    Return Value

    The Core Foundation type identifier for the opaque type CGEventRef.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns a new Quartz event.

    Declaration

    Swift

    func CGEventCreate(_ source: CGEventSource!) -> Unmanaged<CGEvent>!

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns a flattened data representation of a Quartz event.

    Declaration

    Swift

    func CGEventCreateData(_ allocator: CFAllocator!, _ event: CGEvent!) -> Unmanaged<CFData>!

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventCreateFromData(_ allocator: CFAllocator!, _ eventData: CFData!) -> Unmanaged<CGEvent>!

    Objective-C

    CGEventRef CGEventCreateFromData ( CFAllocatorRef allocator, CFDataRef data );

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns a new Quartz mouse event.

    Declaration

    Swift

    func CGEventCreateMouseEvent(_ source: CGEventSource!, _ mouseType: CGEventType, _ mouseCursorPosition: CGPoint, _ mouseButton: CGMouseButton) -> Unmanaged<CGEvent>!

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns a new Quartz keyboard event.

    Declaration

    Swift

    func CGEventCreateKeyboardEvent(_ source: CGEventSource!, _ virtualKey: CGKeyCode, _ keyDown: Bool) -> Unmanaged<CGEvent>!

    Objective-C

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

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns a new Quartz scrolling event.

    Declaration

    Objective-C

    CGEventRef CGEventCreateScrollWheelEvent ( CGEventSourceRef source, CGScrollEventUnit units, uint32_t 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.

    Import Statement

    Availability

    Available in OS X v10.5 and later.

  • Returns a copy of an existing Quartz event.

    Declaration

    Swift

    func CGEventCreateCopy(_ event: CGEvent!) -> Unmanaged<CGEvent>!

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventCreateSourceFromEvent(_ event: CGEvent!) -> Unmanaged<CGEventSource>!

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Sets the event source of a Quartz event.

    Declaration

    Swift

    func CGEventSetSource(_ event: CGEvent!, _ source: CGEventSource!)

    Objective-C

    void CGEventSetSource ( CGEventRef event, CGEventSourceRef source );

    Parameters

    event

    The event to access.

    source

    The new event source of the specified event.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventGetType(_ event: CGEvent!) -> CGEventType

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

    See Also

    CGEventSetType

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

    Declaration

    Swift

    func CGEventSetType(_ event: CGEvent!, _ type: CGEventType)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

    See Also

    CGEventGetType

  • Returns the timestamp of a Quartz event.

    Declaration

    Swift

    func CGEventGetTimestamp(_ event: CGEvent!) -> CGEventTimestamp

    Objective-C

    CGEventTimestamp CGEventGetTimestamp ( CGEventRef event );

    Parameters

    event

    The event to access.

    Return Value

    The current timestamp of the specified event.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Sets the timestamp of a Quartz event.

    Declaration

    Swift

    func CGEventSetTimestamp(_ event: CGEvent!, _ timestamp: CGEventTimestamp)

    Objective-C

    void CGEventSetTimestamp ( CGEventRef event, CGEventTimestamp timestamp );

    Parameters

    event

    The event to access.

    timestamp

    The new timestamp of the specified event.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns the location of a Quartz mouse event.

    Declaration

    Swift

    func CGEventGetLocation(_ event: CGEvent!) -> CGPoint

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns the location of a Quartz mouse event.

    Declaration

    Swift

    func CGEventGetUnflippedLocation(_ event: CGEvent!) -> CGPoint

    Objective-C

    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;

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.5 and later.

  • Sets the location of a Quartz mouse event.

    Declaration

    Swift

    func CGEventSetLocation(_ event: CGEvent!, _ location: CGPoint)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns the event flags of a Quartz event.

    Declaration

    Swift

    func CGEventGetFlags(_ event: CGEvent!) -> CGEventFlags

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Sets the event flags of a Quartz event.

    Declaration

    Swift

    func CGEventSetFlags(_ event: CGEvent!, _ location: CGEventFlags)

    Objective-C

    void CGEventSetFlags ( CGEventRef event, CGEventFlags flags );

    Parameters

    event

    The event to access.

    location

    The new flags of the specified event. See Event Flags.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns the Unicode string associated with a Quartz keyboard event.

    Declaration

    Swift

    func CGEventKeyboardGetUnicodeString(_ event: CGEvent!, _ maxStringLength: UniCharCount, _ actualStringLength: UnsafeMutablePointer<UniCharCount>, _ unicodeString: UnsafeMutablePointer<UniChar>)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Sets the Unicode string associated with a Quartz keyboard event.

    Declaration

    Swift

    func CGEventKeyboardSetUnicodeString(_ event: CGEvent!, _ stringLength: UniCharCount, _ unicodeString: UnsafePointer<UniChar>)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventGetIntegerValueField(_ event: CGEvent!, _ field: CGEventField) -> Int64

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSetIntegerValueField(_ event: CGEvent!, _ field: CGEventField, _ value: Int64)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventGetDoubleValueField(_ event: CGEvent!, _ field: CGEventField) -> Double

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSetDoubleValueField(_ event: CGEvent!, _ field: CGEventField, _ value: Double)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Creates an event tap.

    Declaration

    Swift

    func CGEventTapCreate(_ tap: CGEventTapLocation, _ place: CGEventTapPlacement, _ options: CGEventTapOptions, _ eventsOfInterest: CGEventMask, _ callback: CGEventTapCallBack, _ refcon: UnsafeMutablePointer<Void>) -> Unmanaged<CFMachPort>!

    Objective-C

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

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Creates an event tap for a specified process.

    Declaration

    Swift

    func CGEventTapCreateForPSN(_ processSerialNumber: UnsafeMutablePointer<Void>, _ place: CGEventTapPlacement, _ options: CGEventTapOptions, _ eventsOfInterest: CGEventMask, _ callback: CGEventTapCallBack, _ refcon: UnsafeMutablePointer<Void>) -> Unmanaged<CFMachPort>!

    Objective-C

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

    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

    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

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Enables or disables an event tap.

    Declaration

    Swift

    func CGEventTapEnable(_ myTap: CFMachPort!, _ enable: Bool)

    Objective-C

    void CGEventTapEnable ( CFMachPortRef tap, 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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventTapIsEnabled(_ myTap: CFMachPort!) -> Bool

    Objective-C

    bool CGEventTapIsEnabled ( CFMachPortRef tap );

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventTapPostEvent(_ proxy: CGEventTapProxy, _ event: CGEvent!)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventPost(_ tap: CGEventTapLocation, _ event: CGEvent!)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventPostToPSN(_ processSerialNumber: UnsafeMutablePointer<Void>, _ event: CGEvent!)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Gets a list of currently installed event taps.

    Declaration

    Swift

    func CGGetEventTapList(_ maxNumberOfTaps: UInt32, _ tapList: UnsafeMutablePointer<CGEventTapInformation>, _ eventTapCount: UnsafeMutablePointer<UInt32>) -> CGError

    Objective-C

    CGError CGGetEventTapList ( uint32_t maxNumberOfTaps, CGEventTapInformation tapList[], uint32_t *eventTapCount );

    Parameters

    maxNumberOfTaps

    The length of the array you provide in the tapList parameter.

    tapList

    An array of event tap information structures. You are responsible for allocating storage for the array. On return, your array contains a list of currently installed event taps. If you pass NULL in this parameter, the maxNumberOfTaps parameter is ignored, and the eventTapCount variable is filled in with the number of event taps that are currently installed.

    eventTapCount

    A pointer to a CGTableCount variable. On return, the variable contains actual number of array elements filled in.

    Return Value

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

    Discussion

    Each call to this function has the side effect of resetting the minimum and maximum latency values in the tapList parameter to the corresponding average values. Values reported in these fields reflect the minimum and maximum values seen since the preceding call, or the instantiation of the tap. This allows a monitoring tool to evaluate the best and worst case latency over time and under various operating conditions.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Generates an event mask for a single type of event.

    Declaration

    Objective-C

    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.

    Import Statement

    Availability

    Available in OS X v10.4 and later.

  • Returns the type identifier for the opaque type CGEventSourceRef.

    Declaration

    Swift

    func CGEventSourceGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGEventSourceGetTypeID ( void );

    Return Value

    The Core Foundation type identifier for the opaque type CGEventSourceRef.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceCreate(_ sourceState: CGEventSourceStateID) -> Unmanaged<CGEventSource>!

    Objective-C

    CGEventSourceRef CGEventSourceCreate ( CGEventSourceStateID stateID );

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceGetKeyboardType(_ source: CGEventSource!) -> CGEventSourceKeyboardType

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceSetKeyboardType(_ source: CGEventSource!, _ keyboardType: CGEventSourceKeyboardType)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns the source state associated with a Quartz event source.

    Declaration

    Swift

    func CGEventSourceGetSourceStateID(_ source: CGEventSource!) -> CGEventSourceStateID

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceButtonState(_ sourceState: CGEventSourceStateID, _ button: CGMouseButton) -> Bool

    Objective-C

    bool CGEventSourceButtonState ( CGEventSourceStateID stateID, 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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceKeyState(_ sourceState: CGEventSourceStateID, _ key: CGKeyCode) -> Bool

    Objective-C

    bool CGEventSourceKeyState ( CGEventSourceStateID stateID, 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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Returns the current flags of a Quartz event source.

    Declaration

    Swift

    func CGEventSourceFlagsState(_ sourceState: CGEventSourceStateID) -> CGEventFlags

    Objective-C

    CGEventFlags CGEventSourceFlagsState ( CGEventSourceStateID stateID );

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceSecondsSinceLastEventType(_ source: CGEventSourceStateID, _ eventType: CGEventType) -> CFTimeInterval

    Objective-C

    CFTimeInterval CGEventSourceSecondsSinceLastEventType ( CGEventSourceStateID stateID, 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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceCounterForEventType(_ sourceState: CGEventSourceStateID, _ eventType: CGEventType) -> UInt32

    Objective-C

    uint32_t CGEventSourceCounterForEventType ( CGEventSourceStateID stateID, CGEventType eventType );

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceGetUserData(_ source: CGEventSource!) -> Int64

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceSetUserData(_ source: CGEventSource!, _ userData: Int64)

    Objective-C

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

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceGetLocalEventsFilterDuringSuppressionState(_ source: CGEventSource!, _ state: CGEventSuppressionState) -> CGEventFilterMask

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceSetLocalEventsFilterDuringSuppressionState(_ source: CGEventSource!, _ filter: CGEventFilterMask, _ state: CGEventSuppressionState)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceGetLocalEventsSuppressionInterval(_ source: CGEventSource!) -> CFTimeInterval

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceSetLocalEventsSuppressionInterval(_ source: CGEventSource!, _ seconds: CFTimeInterval)

    Objective-C

    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

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

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func CGEventSourceGetPixelsPerLine(_ source: CGEventSource!) -> Double

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func CGEventSourceSetPixelsPerLine(_ source: CGEventSource!, _ pixelsPerLine: Double)

    Objective-C

    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.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.5 and later.

  • CGEventGetSource CGEventGetSource Available in OS X v10.4 through OS X v10.4

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

    Deprecation Statement

    Use CGEventCreateSourceFromEvent instead.

    Declaration

    Objective-C

    CGEventSourceRef CGEventGetSource ( CGEventRef event );

    Import Statement

    Availability

    Available in OS X v10.4 through OS X v10.4.

    Deprecated in OS X v10.4.

    Not available to 64-bit applications.

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

    Declaration

    Objective-C

    CGError CGPostKeyboardEvent ( CGCharCode keyChar, CGKeyCode virtualKey, boolean_t keyDown );

    Parameters

    keyChar

    The value of the character to generate, or 0 to specify that the system should guess an appropriate value based on the default key mapping.

    virtualKey

    The virtual key code for the event. See CGKeyCode.

    keyDown

    Pass true to specify that the key position is down; otherwise, pass false.

    Return Value

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

    Discussion

    This function is not recommended for general use because of undocumented special cases and undesirable side effects. The recommended replacement for this function is CGEventCreateKeyboardEvent, which allows you to create a keyboard event and customize the event before posting it to the event system.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    CGError CGPostMouseEvent ( CGPoint mouseCursorPosition, boolean_t updateMouseCursorPosition, CGButtonCount buttonCount, boolean_t mouseButtonDown, ... );

    Parameters

    mouseCursorPosition

    The new coordinates of the mouse in global display space.

    updateMouseCursorPosition

    Pass true if the on-screen cursor should be moved to the location specified in the mouseCursorPosition parameter; otherwise, pass false.

    buttonCount

    The number of mouse buttons, up to a maximum of 32.

    mouseButtonDown

    Pass true to specify that the primary or left mouse button is down; otherwise, pass false.

    ...

    Zero or more Boolean values that specify whether the remaining mouse buttons are down (true) or up (false). The second value, if any, should specify the state of the secondary mouse button (right). A third value would specify the state of the center button, and the remaining buttons would be in USB device order.

    Return Value

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

    Discussion

    Based on the arguments you pass to this function, the function generates the appropriate mouse-down, mouse-up, mouse-move, or mouse-drag events by comparing the new state with the current state.

    This function is not recommended for general use because of undocumented special cases and undesirable side effects. The recommended replacement for this function is CGEventCreateMouseEvent, which allows you to create a mouse event and customize the event before posting it to the event system.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    CGError CGPostScrollWheelEvent ( CGWheelCount wheelCount, int32_t wheel1, ... );

    Parameters

    wheelCount

    The number of scrolling devices, up to a maximum of 3.

    wheel1

    A value that reflects the movement of the primary scrolling device on the mouse.

    ...

    Up to two values that reflect the movements of the other scrolling devices on the mouse (if any).

    Return Value

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

    Discussion

    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.

    This function is not recommended for general use because of undocumented special cases and undesirable side effects. The recommended replacement for this function is CGEventCreateScrollWheelEvent, which allows you to create a scrolling event and customize the event before posting it to the event system.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    CGError CGEnableEventStateCombining ( boolean_t combineState );

    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.

    Import Statement

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.6.

  • Turns off local hardware events in the current session.

    Declaration

    Objective-C

    CGError CGInhibitLocalEvents ( boolean_t inhibit );

    Parameters

    doInhibit

    Pass true to specify that local hardware events on the remote system should be inhibited; otherwise, pass false.

    Return Value

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

    Discussion

    This function is typically used during remote operation of a system to disconnect the keyboard and mouse for a short period of time, as in automated system testing or telecommuting applications.

    The CGInhibitLocalEvents function is not recommended for general use because of undocumented special cases and undesirable side effects. For example, this function can permanently disable the keyboard and mouse, rendering the system unusable. The recommended replacement for this function is CGEventSourceSetLocalEventsFilterDuringSuppressionState.

    Special Considerations

    In OS X v10.2 and earlier, this function inhibits local events only after a synthetic keyboard or mouse event is posted by the calling application. In OS X v10.3 and later, event inhibition takes effect immediately. If your application terminates for any reason, event inhibition on the remote system is immediately turned off.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    CGError CGSetLocalEventsFilterDuringSuppressionState ( CGEventFilterMask filter, CGEventSuppressionState state );

    Parameters

    filter

    The class of local hardware events to enable after a synthetic event is posted. Pass one of the constants listed in Event Filter Masks.

    state

    The type of interval during which the filter is applied. Pass one of the constants listed in Event Suppression States.

    Return Value

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

    Discussion

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

    Some applications may want to enable events from some of the local hardware. For example, if you post mouse events only, you may wish to permit local keyboard hardware events to pass through.

    This function lets you specify a state (event suppression interval or mouse drag), and a mask of event categories to be passed through. The new filter state takes effect with the next synthetic event you post.

    This function is not recommended for general use because of undocumented special cases and undesirable side effects. The recommended replacement for this function is CGEventSourceSetLocalEventsFilterDuringSuppressionState, which allows the filter behavior to be associated only with events created from a specific event source.

    Import Statement

    Availability

    Available in OS X v10.1 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    CGError CGSetLocalEventsSuppressionInterval ( CFTimeInterval seconds );

    Parameters

    seconds

    The desired time interval in seconds. The value should be a number in the range [0.0, 10.0].

    Return Value

    A result code. If the seconds parameter is outside the allowed range, returns kCGErrorRangeCheck.

    Discussion

    This function determines how long local events matching an event filter are to be suppressed following the posting of a synthetic event. The default time interval for event suppression is 0.25 seconds.

    This function is not recommended for general use because of undocumented special cases and undesirable side effects. The recommended replacement for this function is CGEventSourceSetLocalEventsSuppressionInterval, which allows the suppression interval to be adjusted for a specific event source, affecting only events posted using that event source.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

Callbacks

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

    Declaration

    Objective-C

    typedef CGEventRef (*CGEventTapCallBack) ( CGEventTapProxy proxy, CGEventType type, CGEventRef event, void *refcon );

    Parameters

    proxy

    A proxy for the event tap. See CGEventTapProxy. This callback function may pass this proxy to other functions such as the event-posting routines.

    type

    The event type of this event. See Event Types.

    event

    The incoming event. This event is owned by the caller, and you do not need to release it.

    refcon

    A pointer to user-defined data. You specify this pointer when you create the event tap. Several different event taps could use the same callback function, each tap with its own user-defined data.

    Discussion

    If the event tap is an active filter, your callback function should return one of the following:

    • The (possibly modified) event that is passed in. This event is passed back to the event system.

    • A newly-constructed event. After the new event has been passed back to the event system, the new event will be released along with the original event.

    • NULL if the event passed in is to be deleted.

    If the event tap is an passive listener, your callback function may return the event that is passed in, or NULL. In either case, the event stream is not affected.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

Data Types

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

    Declaration

    Swift

    typealias CGButtonCount = UInt32

    Objective-C

    typedef uint32_t CGButtonCount;

    Discussion

    In mouse events, the button count parameter ranges from 0 to 31. See the function CGPostMouseEvent.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias CGCharCode = UInt16

    Objective-C

    typedef uint16_t CGCharCode;

    Discussion

    This data type represents a 16-bit character code. Values of this type may or may not correspond to UTF-16 character codes. See the function CGPostKeyboardEvent.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias CGEventMask = UInt64

    Objective-C

    typedef uint64_t CGEventMask;

    Discussion

    When you call either CGEventTapCreate or CGEventTapCreateForPSN to register an event tap, you supply a bit mask that identifies the set of events to be observed. You specify each event using one of the event type constants listed in Event Types. To form the bit mask, use the CGEventMaskBit macro to convert each constant into an event mask and then OR the individual masks together. For example:

    • CGEventMask mask = CGEventMaskBit(kCGEventLeftMouseDown) |
    • CGEventMaskBit(kCGEventLeftMouseUp);

    You can also supply a mask to observe all events:

    • CGEventMask mask = kCGEventMaskForAllEvents;

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    typealias CGEventRef = CGEvent

    Objective-C

    typedef struct __CGEvent *CGEventRef;

    Discussion

    Low-level hardware events of this type are referred to as Quartz events. A typical event in OS X originates when the user manipulates an input device such as a mouse or a keyboard. The device driver associated with that device, through the I/O Kit, creates a low-level event, puts it in the window server’s event queue, and notifies the window server. The window server creates a Quartz event, annotates the event, and dispatches the event to the appropriate run-loop port of the target process. There the event is picked up by the Carbon Event Manager and forwarded to the event-handling mechanism appropriate to the application environment. You can use event taps to gain access to Quartz events at several different steps in this process.

    This opaque type is derived from CFType and inherits the properties that all Core Foundation types have in common. For more information, see CFType Reference.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    typealias CGEventSourceKeyboardType = UInt32

    Objective-C

    typedef uint32_t CGEventSourceKeyboardType;

    Discussion

    This code is the same keyboard type identifier used with the UCKeyTranslate function to drive keyboard translation.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    typealias CGEventSourceRef = CGEventSource

    Objective-C

    typedef struct __CGEventSource * CGEventSourceRef;

    Discussion

    A Quartz event source is an object that contains accumulated state related to event generation and event posting. Every event source has an associated global event state table called a source state. When you call CGEventSourceCreate to create an event source, you specify which source state to use. For more information about source states, see Event Source States.

    A typical use of an event source would be to obtain the source from a Quartz event received by an event tap callback function, and then to use that source for any new events created as a result of the received event. This has the effect of marking the events as being related.

    This opaque type is derived from CFType and inherits the properties that all Core Foundation types have in common. For more information, see CFType Reference.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Defines the structure used to report information about event taps.

    Declaration

    Swift

    typealias CGEventTapInformation = __CGEventTapInformation

    Objective-C

    typedef struct CGEventTapInformation { uint32_t eventTapID; CGEventTapLocation tapPoint; CGEventTapOptions options; CGEventMask eventsOfInterest; pid_t tappingProcess; pid_t processBeingTapped; bool enabled; float minUsecLatency; float avgUsecLatency; float maxUsecLatency; } CGEventTapInformation;

    Fields

    eventTapID

    The unique identifier for the event tap.

    tapPoint

    The location of the event tap. See Event Tap Locations.

    options

    The type of event tap (passive listener or active filter).

    eventsOfInterest

    The mask that identifies the set of events to be observed.

    tappingProcess

    The process ID of the application that created the event tap.

    processBeingTapped

    The process ID of the target application (non-zero only if the event tap was created using the function CGEventTapCreateForPSN.

    enabled

    TRUE if the event tap is currently enabled; otherwise FALSE.

    minUsecLatency

    Minimum latency in microseconds. In this data structure, latency is defined as the time in microseconds it takes for an event tap to process and respond to an event passed to it.

    avgUsecLatency

    Average latency in microseconds. This is a weighted average that gives greater weight to more recent events.

    maxUsecLatency

    Maximum latency in microseconds.

    Discussion

    To learn how to obtain information about event taps, see the function CGGetEventTapList.

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    typealias CGEventTapProxy = COpaquePointer

    Objective-C

    typedef struct __CGEventTapProxy * CGEventTapProxy;

    Discussion

    An event tap proxy object is passed to your event tap callback function when it receives a new Quartz event. Your callback function needs the proxy to post Quartz events using the function CGEventTapPostEvent.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    typealias CGEventTimestamp = UInt64

    Objective-C

    typedef uint64_t CGEventTimestamp;

    Discussion

    An event timestamp is a big, unsigned, 64-bit number. That's big, really big. You just won't believe how vastly, hugely, mind-bogglingly big it is. You may think your application has been running for a long time, but that's just peanuts to an event timestamp.

    For information about how event timestamps are used, see the functions CGEventGetTimestamp and CGEventSetTimestamp.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Represents the virtual key codes used in keyboard events.

    Declaration

    Swift

    typealias CGKeyCode = UInt16

    Objective-C

    typedef uint16_t CGKeyCode;

    Discussion

    In OS X, the hardware scan codes generated by keyboards are mapped to a set of virtual key codes that are hardware-independent. Pressing a given key always generates the same virtual key code on any supported keyboard.

    As keys are pressed, the system uses the virtual key codes to create low-level keyboard events. For information on how to simulate a keyboard event, see the function CGEventCreateKeyboardEvent.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    typealias CGWheelCount = UInt32

    Objective-C

    typedef uint32_t CGWheelCount;

    Discussion

    See the function CGPostScrollWheelEvent.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.0 and later.

Constants

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

    Declaration

    Swift

    typealias CGEventField = UInt32

    Objective-C

    enum _CGEventField { kCGMouseEventNumber = 0, kCGMouseEventClickState = 1, kCGMouseEventPressure = 2, kCGMouseEventButtonNumber = 3, kCGMouseEventDeltaX = 4, kCGMouseEventDeltaY = 5, kCGMouseEventInstantMouser = 6, kCGMouseEventSubtype = 7, kCGKeyboardEventAutorepeat = 8, kCGKeyboardEventKeycode = 9, kCGKeyboardEventKeyboardType = 10, kCGScrollWheelEventDeltaAxis1 = 11, kCGScrollWheelEventDeltaAxis2 = 12, kCGScrollWheelEventDeltaAxis3 = 13, kCGScrollWheelEventFixedPtDeltaAxis1 = 93, kCGScrollWheelEventFixedPtDeltaAxis2 = 94, kCGScrollWheelEventFixedPtDeltaAxis3 = 95, kCGScrollWheelEventPointDeltaAxis1 = 96, kCGScrollWheelEventPointDeltaAxis2 = 97, kCGScrollWheelEventPointDeltaAxis3 = 98, kCGScrollWheelEventInstantMouser = 14, kCGTabletEventPointX = 15, kCGTabletEventPointY = 16, kCGTabletEventPointZ = 17, kCGTabletEventPointButtons = 18, kCGTabletEventPointPressure = 19, kCGTabletEventTiltX = 20, kCGTabletEventTiltY = 21, kCGTabletEventRotation = 22, kCGTabletEventTangentialPressure = 23, kCGTabletEventDeviceID = 24, kCGTabletEventVendor1 = 25, kCGTabletEventVendor2 = 26, kCGTabletEventVendor3 = 27, kCGTabletProximityEventVendorID = 28, kCGTabletProximityEventTabletID = 29, kCGTabletProximityEventPointerID = 30, kCGTabletProximityEventDeviceID = 31, kCGTabletProximityEventSystemTabletID = 32, kCGTabletProximityEventVendorPointerType = 33, kCGTabletProximityEventVendorPointerSerialNumber = 34, kCGTabletProximityEventVendorUniqueID = 35, kCGTabletProximityEventCapabilityMask = 36, kCGTabletProximityEventPointerType = 37, kCGTabletProximityEventEnterProximity = 38, kCGEventTargetProcessSerialNumber = 39, kCGEventTargetUnixProcessID = 40, kCGEventSourceUnixProcessID = 41, kCGEventSourceUserData = 42, kCGEventSourceUserID = 43, kCGEventSourceGroupID = 44, kCGEventSourceStateID = 45, kCGScrollWheelEventIsContinuous = 88 }; typedef uint32_t CGEventField;

    Constants

    • kCGMouseEventNumber

      kCGMouseEventNumber

      Key to access an integer field that contains the mouse button event number. Matching mouse-down and mouse-up events will have the same event number.

      Available in OS X v10.4 and later.

    • kCGMouseEventClickState

      kCGMouseEventClickState

      Key to access an integer field that contains the mouse button click state. A click state of 1 represents a single click. A click state of 2 represents a double-click. A click state of 3 represents a triple-click.

      Available in OS X v10.4 and later.

    • kCGMouseEventPressure

      kCGMouseEventPressure

      Key to access a double field that contains the mouse button pressure. The pressure value may range from 0 to 1, with 0 representing the mouse being up. This value is commonly set by tablet pens mimicking a mouse.

      Available in OS X v10.4 and later.

    • kCGMouseEventButtonNumber

      kCGMouseEventButtonNumber

      Key to access an integer field that contains the mouse button number. For information about the possible values, see Mouse Buttons.

      Available in OS X v10.4 and later.

    • kCGMouseEventDeltaX

      kCGMouseEventDeltaX

      Key to access an integer field that contains the horizontal mouse delta since the last mouse movement event.

      Available in OS X v10.4 and later.

    • kCGMouseEventDeltaY

      kCGMouseEventDeltaY

      Key to access an integer field that contains the vertical mouse delta since the last mouse movement event.

      Available in OS X v10.4 and later.

    • kCGMouseEventInstantMouser

      kCGMouseEventInstantMouser

      Key to access an integer field. The value is non-zero if the event should be ignored by the Inkwell subsystem.

      Available in OS X v10.4 and later.

    • kCGMouseEventSubtype

      kCGMouseEventSubtype

      Key to access an integer field that encodes the mouse event subtype as a kCFNumberIntType.

      Available in OS X v10.4 and later.

    • kCGKeyboardEventAutorepeat

      kCGKeyboardEventAutorepeat

      Key to access an integer field, non-zero when this is an autorepeat of a key-down, and zero otherwise.

      Available in OS X v10.4 and later.

    • kCGKeyboardEventKeycode

      kCGKeyboardEventKeycode

      Key to access an integer field that contains the virtual keycode of the key-down or key-up event.

      Available in OS X v10.4 and later.

    • kCGKeyboardEventKeyboardType

      kCGKeyboardEventKeyboardType

      Key to access an integer field that contains the keyboard type identifier.

      Available in OS X v10.4 and later.

    • kCGScrollWheelEventDeltaAxis1

      kCGScrollWheelEventDeltaAxis1

      Key to access an integer field that contains scrolling data. This field typically contains the change in vertical position since the last scrolling event from a Mighty Mouse scroller or a single-wheel mouse scroller.

      Available in OS X v10.4 and later.

    • kCGScrollWheelEventDeltaAxis2

      kCGScrollWheelEventDeltaAxis2

      Key to access an integer field that contains scrolling data. This field typically contains the change in horizontal position since the last scrolling event from a Mighty Mouse scroller.

      Available in OS X v10.4 and later.

    • kCGScrollWheelEventDeltaAxis3

      kCGScrollWheelEventDeltaAxis3

      This field is not used.

      Available in OS X v10.4 and later.

    • kCGScrollWheelEventFixedPtDeltaAxis1

      kCGScrollWheelEventFixedPtDeltaAxis1

      Key to access a field that contains scrolling data. The scrolling data represents a line-based or pixel-based change in vertical position since the last scrolling event from a Mighty Mouse scroller or a single-wheel mouse scroller. The scrolling data uses a fixed-point 16.16 signed integer format. For example, if the field contains a value of 1.0, the integer 0x00010000 is returned by CGEventGetIntegerValueField. If this key is passed to CGEventGetDoubleValueField, the fixed-point value is converted to a double value.

      Available in OS X v10.5 and later.

    • kCGScrollWheelEventFixedPtDeltaAxis2

      kCGScrollWheelEventFixedPtDeltaAxis2

      Key to access a field that contains scrolling data. The scrolling data represents a line-based or pixel-based change in horizontal position since the last scrolling event from a Mighty Mouse scroller. The scrolling data uses a fixed-point 16.16 signed integer format. For example, if the field contains a value of 1.0, the integer 0x00010000 is returned by CGEventGetIntegerValueField. If this key is passed to CGEventGetDoubleValueField, the fixed-point value is converted to a double value.

      Available in OS X v10.5 and later.

    • kCGScrollWheelEventFixedPtDeltaAxis3

      kCGScrollWheelEventFixedPtDeltaAxis3

      This field is not used.

      Available in OS X v10.5 and later.

    • kCGScrollWheelEventPointDeltaAxis1

      kCGScrollWheelEventPointDeltaAxis1

      Key to access an integer field that contains pixel-based scrolling data. The scrolling data represents the change in vertical position since the last scrolling event from a Mighty Mouse scroller or a single-wheel mouse scroller.

      Available in OS X v10.5 and later.

    • kCGScrollWheelEventPointDeltaAxis2

      kCGScrollWheelEventPointDeltaAxis2

      Key to access an integer field that contains pixel-based scrolling data. The scrolling data represents the change in horizontal position since the last scrolling event from a Mighty Mouse scroller.

      Available in OS X v10.5 and later.

    • kCGScrollWheelEventPointDeltaAxis3

      kCGScrollWheelEventPointDeltaAxis3

      This field is not used.

      Available in OS X v10.5 and later.

    • kCGScrollWheelEventInstantMouser

      kCGScrollWheelEventInstantMouser

      Key to access an integer field that indicates whether the event should be ignored by the Inkwell subsystem. If the value is non-zero, the event should be ignored.

      Available in OS X v10.4 and later.

    • kCGTabletEventPointX

      kCGTabletEventPointX

      Key to access an integer field that contains the absolute X coordinate in tablet space at full tablet resolution.

      Available in OS X v10.4 and later.

    • kCGTabletEventPointY

      kCGTabletEventPointY

      Key to access an integer field that contains the absolute Y coordinate in tablet space at full tablet resolution.

      Available in OS X v10.4 and later.

    • kCGTabletEventPointZ

      kCGTabletEventPointZ

      Key to access an integer field that contains the absolute Z coordinate in tablet space at full tablet resolution.

      Available in OS X v10.4 and later.

    • kCGTabletEventPointButtons

      kCGTabletEventPointButtons

      Key to access an integer field that contains the tablet button state. Bit 0 is the first button, and a set bit represents a closed or pressed button. Up to 16 buttons are supported.

      Available in OS X v10.4 and later.

    • kCGTabletEventPointPressure

      kCGTabletEventPointPressure

      Key to access a double field that contains the tablet pen pressure. A value of 0.0 represents no pressure, and 1.0 represents maximum pressure.

      Available in OS X v10.4 and later.

    • kCGTabletEventTiltX

      kCGTabletEventTiltX

      Key to access a double field that contains the horizontal tablet pen tilt. A value of 0.0 represents no tilt, and 1.0 represents maximum tilt.

      Available in OS X v10.4 and later.

    • kCGTabletEventTiltY

      kCGTabletEventTiltY

      Key to access a double field that contains the vertical tablet pen tilt. A value of 0.0 represents no tilt, and 1.0 represents maximum tilt.

      Available in OS X v10.4 and later.

    • kCGTabletEventRotation

      kCGTabletEventRotation

      Key to access a double field that contains the tablet pen rotation.

      Available in OS X v10.4 and later.

    • kCGTabletEventTangentialPressure

      kCGTabletEventTangentialPressure

      Key to access a double field that contains the tangential pressure on the device. A value of 0.0 represents no pressure, and 1.0 represents maximum pressure.

      Available in OS X v10.4 and later.

    • kCGTabletEventDeviceID

      kCGTabletEventDeviceID

      Key to access an integer field that contains the system-assigned unique device ID.

      Available in OS X v10.4 and later.

    • kCGTabletEventVendor1

      kCGTabletEventVendor1

      Key to access an integer field that contains a vendor-specified value.

      Available in OS X v10.4 and later.

    • kCGTabletEventVendor2

      kCGTabletEventVendor2

      Key to access an integer field that contains a vendor-specified value.

      Available in OS X v10.4 and later.

    • kCGTabletEventVendor3

      kCGTabletEventVendor3

      Key to access an integer field that contains a vendor-specified value.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventVendorID

      kCGTabletProximityEventVendorID

      Key to access an integer field that contains the vendor-defined ID, typically the USB vendor ID.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventTabletID

      kCGTabletProximityEventTabletID

      Key to access an integer field that contains the vendor-defined tablet ID, typically the USB product ID.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventPointerID

      kCGTabletProximityEventPointerID

      Key to access an integer field that contains the vendor-defined ID of the pointing device.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventDeviceID

      kCGTabletProximityEventDeviceID

      Key to access an integer field that contains the system-assigned device ID.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventSystemTabletID

      kCGTabletProximityEventSystemTabletID

      Key to access an integer field that contains the system-assigned unique tablet ID.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventVendorPointerType

      kCGTabletProximityEventVendorPointerType

      Key to access an integer field that contains the vendor-assigned pointer type.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventVendorPointerSerialNumber

      kCGTabletProximityEventVendorPointerSerialNumber

      Key to access an integer field that contains the vendor-defined pointer serial number.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventVendorUniqueID

      kCGTabletProximityEventVendorUniqueID

      Key to access an integer field that contains the vendor-defined unique ID.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventCapabilityMask

      kCGTabletProximityEventCapabilityMask

      Key to access an integer field that contains the device capabilities mask.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventPointerType

      kCGTabletProximityEventPointerType

      Key to access an integer field that contains the pointer type.

      Available in OS X v10.4 and later.

    • kCGTabletProximityEventEnterProximity

      kCGTabletProximityEventEnterProximity

      Key to access an integer field that indicates whether the pen is in proximity to the tablet. The value is non-zero if the pen is in proximity to the tablet and zero when leaving the tablet.

      Available in OS X v10.4 and later.

    • kCGEventTargetProcessSerialNumber

      kCGEventTargetProcessSerialNumber

      Key to access a field that contains the event target process serial number. The value is a 64-bit long word.

      Available in OS X v10.4 and later.

    • kCGEventTargetUnixProcessID

      kCGEventTargetUnixProcessID

      Key to access a field that contains the event target Unix process ID.

      Available in OS X v10.4 and later.

    • kCGEventSourceUnixProcessID

      kCGEventSourceUnixProcessID

      Key to access a field that contains the event source Unix process ID.

      Available in OS X v10.4 and later.

    • kCGEventSourceUserData

      kCGEventSourceUserData

      Key to access a field that contains the event source user-supplied data, up to 64 bits.

      Available in OS X v10.4 and later.

    • kCGEventSourceUserID

      kCGEventSourceUserID

      Key to access a field that contains the event source Unix effective UID.

      Available in OS X v10.4 and later.

    • kCGEventSourceGroupID

      kCGEventSourceGroupID

      Key to access a field that contains the event source Unix effective GID.

      Available in OS X v10.4 and later.

    • kCGEventSourceStateID

      kCGEventSourceStateID

      Key to access a field that contains the event source state ID used to create this event.

      Available in OS X v10.4 and later.

    • kCGScrollWheelEventIsContinuous

      kCGScrollWheelEventIsContinuous

      Key to access an integer field that indicates whether a scrolling event contains continuous, pixel-based scrolling data. The value is non-zero when the scrolling data is pixel-based and zero when the scrolling data is line-based.

      Available in OS X v10.5 and later.

    Discussion

    These constants are used as keys to access certain specialized event fields when using low-level accessor functions such as CGEventGetIntegerValueField, CGEventSetIntegerValueField, CGEventGetDoubleValueField, and CGEventSetDoubleValueField.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    typealias CGEventFilterMask = UInt32

    Objective-C

    enum CGEventFilterMask { kCGEventFilterMaskPermitLocalMouseEvents = 0x00000001, kCGEventFilterMaskPermitLocalKeyboardEvents = 0x00000002, kCGEventFilterMaskPermitSystemDefinedEvents = 0x00000004, kCGEventFilterMaskPermitAllEvents = kCGEventFilterMaskPermitLocalMouseEvents | kCGEventFilterMaskPermitLocalKeyboardEvents | kCGEventFilterMaskPermitSystemDefinedEvents }; typedef uint32_t CGEventFilterMask;

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.1 and later.

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

    Declaration

    Swift

    typealias CGEventFlags = UInt64

    Objective-C

    enum _CGEventFlags { kCGEventFlagMaskAlphaShift = NX_ALPHASHIFTMASK, kCGEventFlagMaskShift = NX_SHIFTMASK, kCGEventFlagMaskControl = NX_CONTROLMASK, kCGEventFlagMaskAlternate = NX_ALTERNATEMASK, kCGEventFlagMaskCommand = NX_COMMANDMASK, kCGEventFlagMaskHelp = NX_HELPMASK, kCGEventFlagMaskSecondaryFn = NX_SECONDARYFNMASK, kCGEventFlagMaskNumericPad = NX_NUMERICPADMASK, kCGEventFlagMaskNonCoalesced = NX_NONCOALSESCEDMASK }; typedef uint64_t CGEventFlags;

    Constants

    • kCGEventFlagMaskAlphaShift

      kCGEventFlagMaskAlphaShift

      Indicates that the Caps Lock key is down for a keyboard, mouse, or flag-changed event.

      Available in OS X v10.4 and later.

    • kCGEventFlagMaskShift

      kCGEventFlagMaskShift

      Indicates that the Shift key is down for a keyboard, mouse, or flag-changed event.

      Available in OS X v10.4 and later.

    • kCGEventFlagMaskControl

      kCGEventFlagMaskControl

      Indicates that the Control key is down for a keyboard, mouse, or flag-changed event.

      Available in OS X v10.4 and later.

    • kCGEventFlagMaskAlternate

      kCGEventFlagMaskAlternate

      Indicates that the Alt or Option key is down for a keyboard, mouse, or flag-changed event.

      Available in OS X v10.4 and later.

    • kCGEventFlagMaskCommand

      kCGEventFlagMaskCommand

      Indicates that the Command key is down for a keyboard, mouse, or flag-changed event.

      Available in OS X v10.4 and later.

    • kCGEventFlagMaskHelp

      kCGEventFlagMaskHelp

      Indicates that the Help modifier key is down for a keyboard, mouse, or flag-changed event. This key is not present on most keyboards, and is different than the Help key found in the same row as Home and Page Up.

      Available in OS X v10.4 and later.

    • kCGEventFlagMaskSecondaryFn

      kCGEventFlagMaskSecondaryFn

      Indicates that the Fn (Function) key is down for a keyboard, mouse, or flag-changed event. This key is found primarily on laptop keyboards.

      Available in OS X v10.4 and later.

    • kCGEventFlagMaskNumericPad

      kCGEventFlagMaskNumericPad

      Identifies key events from the numeric keypad area on extended keyboards.

      Available in OS X v10.4 and later.

    • kCGEventFlagMaskNonCoalesced

      kCGEventFlagMaskNonCoalesced

      Indicates that mouse and pen movement events are not being coalesced.

      Available in OS X v10.4 and later.

    Discussion

    These constants specify masks for the bits in an event flags bit mask. Event flags indicate the modifier key state at the time an event is created, as well as other event-related states. Event flags are used in accessor functions such as CGEventGetFlags, CGEventSetFlags, and CGEventSourceFlagsState.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    typealias CGEventSourceStateID = UInt32

    Objective-C

    enum { kCGEventSourceStatePrivate = -1, kCGEventSourceStateCombinedSessionState = 0, kCGEventSourceStateHIDSystemState = 1 }; typedef uint32_t CGEventSourceStateID;

    Constants

    • kCGEventSourceStatePrivate

      kCGEventSourceStatePrivate

      Specifies that an event source should use a private event state table.

      Available in OS X v10.4 and later.

    • kCGEventSourceStateCombinedSessionState

      kCGEventSourceStateCombinedSessionState

      Specifies that an event source should use the event state table that reflects the combined state of all event sources posting to the current user login session.

      Available in OS X v10.4 and later.

    • kCGEventSourceStateHIDSystemState

      kCGEventSourceStateHIDSystemState

      Specifies that an event source should use the event state table that reflects the combined state of all hardware event sources posting from the HID system.

      Available in OS X v10.4 and later.

    Discussion

    A source state refers to a global event state table. These tables contain accumulated information on modifier flag state, keyboard key state, mouse button state, and related internal parameters placed in effect by posting events with associated sources.

    Two pre-existing event state tables are defined:

    • The kCGEventSourceStateCombinedSessionState table reflects the combined state of all event sources posting to the current user login session. If your program is posting events from within a login session, you should use this source state when you create an event source.

    • The kCGEventSourceStateHIDSystemState table reflects the combined state of all hardware event sources posting from the HID system. If your program is a daemon or a user space device driver interpreting hardware state and generating events, you should use this source state when you create an event source.

    Specialized applications such as remote control programs may want to generate and track event source state independent of other processes. These programs should use the kCGEventSourceStatePrivate value in creating their event source. An independent state table and unique source state ID (CGEventSourceStateID) are created to track the event source's state. This independent state table is owned by the creating event source and released with it.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Specifies any input event type.

    Declaration

    Objective-C

    #define kCGAnyInputEventType ((CGEventType)(~0))

    Constants

    • kCGAnyInputEventType

      kCGAnyInputEventType

      A constant that specifies any input event type.

      Available in OS X v10.4 and later.

    Discussion

    This constant is typically used with the function CGEventSourceSecondsSinceLastEventType to specify that you want the elapsed time since the last input event of any type.

    Import Statement

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

    Declaration

    Swift

    typealias CGEventSuppressionState = UInt32

    Objective-C

    enum CGEventSuppressionState { kCGEventSuppressionStateSuppressionInterval = 0, kCGEventSuppressionStateRemoteMouseDrag = 1, kCGNumberOfEventSuppressionStates = 2 }; typedef uint32_t CGEventSuppressionState;

    Constants

    • kCGEventSuppressionStateSuppressionInterval

      kCGEventSuppressionStateSuppressionInterval

      Specifies that certain local hardware events may be suppressed for a short interval after posting an event.

      Available in OS X v10.3 and later.

    • kCGEventSuppressionStateRemoteMouseDrag

      kCGEventSuppressionStateRemoteMouseDrag

      Specifies that certain local hardware events may be suppressed during a mouse drag operation (mouse movement with the left or only mouse button down).

      Available in OS X v10.3 and later.

    Discussion

    These constants specify the types of event suppression intervals during which an event filter is applied after posting an event.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.3 and later.

  • Constants that specify possible tapping points for events.

    Declaration

    Swift

    typealias CGEventTapLocation = UInt32

    Objective-C

    enum _CGEventTapLocation { kCGHIDEventTap = 0, kCGSessionEventTap, kCGAnnotatedSessionEventTap }; typedef uint32_t CGEventTapLocation;

    Constants

    • kCGHIDEventTap

      kCGHIDEventTap

      Specifies that an event tap is placed at the point where HID system events enter the window server.

      Available in OS X v10.4 and later.

    • kCGSessionEventTap

      kCGSessionEventTap

      Specifies that an event tap is placed at the point where HID system and remote control events enter a login session.

      Available in OS X v10.4 and later.

    • kCGAnnotatedSessionEventTap

      kCGAnnotatedSessionEventTap

      Specifies that an event tap is placed at the point where session events have been annotated to flow to an application.

      Available in OS X v10.4 and later.

    Discussion

    In addition to the three tapping points described above, an event tap may also be placed where annotated events are delivered to a specific application. For more information, see the function CGEventTapCreateForPSN.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    typealias CGEventTapOptions = UInt32

    Objective-C

    enum _CGEventTapOptions { kCGEventTapOptionDefault = 0x00000000, kCGEventTapOptionListenOnly = 0x00000001 }; typedef uint32_t CGEventTapOptions;

    Constants

    • kCGEventTapOptionDefault

      kCGEventTapOptionDefault

      Specifies that a new event tap is an active filter. (Applications targeting OS X v10.4 should use the literal value to create an active filter event tap, as this constant was omitted from the header.)

      Available in OS X v10.5 and later.

    • kCGEventTapOptionListenOnly

      kCGEventTapOptionListenOnly

      Specifies that a new event tap is a passive listener.

      Available in OS X v10.4 and later.

    Discussion

    When you create an event tap, you indicate whether it is a passive listener or active event filter. A passive listener receives events but cannot modify or divert them. An active filter may pass an event through unmodified, modify an event, or discard an event.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    typealias CGEventTapPlacement = UInt32

    Objective-C

    enum _CGEventTapPlacement { kCGHeadInsertEventTap = 0, kCGTailAppendEventTap }; typedef uint32_t CGEventTapPlacement;

    Constants

    • kCGHeadInsertEventTap

      kCGHeadInsertEventTap

      Specifies that a new event tap should be inserted before any pre-existing event taps at the same location.

      Available in OS X v10.4 and later.

    • kCGTailAppendEventTap

      kCGTailAppendEventTap

      Specifies that a new event tap should be inserted after any pre-existing event taps at the same location.

      Available in OS X v10.4 and later.

    Discussion

    Event taps may be inserted at a specified location at the head of pre-existing filters, or appended after any pre-existing filters.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Constants that specify the different types of input events.

    Declaration

    Swift

    typealias CGEventType = UInt32

    Objective-C

    enum _CGEventType { kCGEventNull = NX_NULLEVENT, kCGEventLeftMouseDown = NX_LMOUSEDOWN, kCGEventLeftMouseUp = NX_LMOUSEUP, kCGEventRightMouseDown = NX_RMOUSEDOWN, kCGEventRightMouseUp = NX_RMOUSEUP, kCGEventMouseMoved = NX_MOUSEMOVED, kCGEventLeftMouseDragged = NX_LMOUSEDRAGGED, kCGEventRightMouseDragged = NX_RMOUSEDRAGGED, kCGEventKeyDown = NX_KEYDOWN, kCGEventKeyUp = NX_KEYUP, kCGEventFlagsChanged = NX_FLAGSCHANGED, kCGEventScrollWheel = NX_SCROLLWHEELMOVED, kCGEventTabletPointer = NX_TABLETPOINTER, kCGEventTabletProximity = NX_TABLETPROXIMITY, kCGEventOtherMouseDown = NX_OMOUSEDOWN, kCGEventOtherMouseUp = NX_OMOUSEUP, kCGEventOtherMouseDragged = NX_OMOUSEDRAGGED, kCGEventTapDisabledByTimeout = 0xFFFFFFFE, kCGEventTapDisabledByUserInput = 0xFFFFFFFF }; typedef uint32_t CGEventType;

    Constants

    • kCGEventNull

      kCGEventNull

      Specifies a null event.

      Available in OS X v10.4 and later.

    • kCGEventLeftMouseDown

      kCGEventLeftMouseDown

      Specifies a mouse down event with the left button.

      Available in OS X v10.4 and later.

    • kCGEventLeftMouseUp

      kCGEventLeftMouseUp

      Specifies a mouse up event with the left button.

      Available in OS X v10.4 and later.

    • kCGEventRightMouseDown

      kCGEventRightMouseDown

      Specifies a mouse down event with the right button.

      Available in OS X v10.4 and later.

    • kCGEventRightMouseUp

      kCGEventRightMouseUp

      Specifies a mouse up event with the right button.

      Available in OS X v10.4 and later.

    • kCGEventMouseMoved

      kCGEventMouseMoved

      Specifies a mouse moved event.

      Available in OS X v10.4 and later.

    • kCGEventLeftMouseDragged

      kCGEventLeftMouseDragged

      Specifies a mouse drag event with the left button down.

      Available in OS X v10.4 and later.

    • kCGEventRightMouseDragged

      kCGEventRightMouseDragged

      Specifies a mouse drag event with the right button down.

      Available in OS X v10.4 and later.

    • kCGEventKeyDown

      kCGEventKeyDown

      Specifies a key down event.

      Available in OS X v10.4 and later.

    • kCGEventKeyUp

      kCGEventKeyUp

      Specifies a key up event.

      Available in OS X v10.4 and later.

    • kCGEventFlagsChanged

      kCGEventFlagsChanged

      Specifies a key changed event for a modifier or status key.

      Available in OS X v10.4 and later.

    • kCGEventScrollWheel

      kCGEventScrollWheel

      Specifies a scroll wheel moved event.

      Available in OS X v10.4 and later.

    • kCGEventTabletPointer

      kCGEventTabletPointer

      Specifies a tablet pointer event.

      Available in OS X v10.4 and later.

    • kCGEventTabletProximity

      kCGEventTabletProximity

      Specifies a tablet proximity event.

      Available in OS X v10.4 and later.

    • kCGEventOtherMouseDown

      kCGEventOtherMouseDown

      Specifies a mouse down event with one of buttons 2-31.

      Available in OS X v10.4 and later.

    • kCGEventOtherMouseUp

      kCGEventOtherMouseUp

      Specifies a mouse up event with one of buttons 2-31.

      Available in OS X v10.4 and later.

    • kCGEventOtherMouseDragged

      kCGEventOtherMouseDragged

      Specifies a mouse drag event with one of buttons 2-31 down.

      Available in OS X v10.4 and later.

    • kCGEventTapDisabledByTimeout

      kCGEventTapDisabledByTimeout

      Specifies an event indicating the event tap is disabled because of timeout.

      Available in OS X v10.4 and later.

    • kCGEventTapDisabledByUserInput

      kCGEventTapDisabledByUserInput

      Specifies an event indicating the event tap is disabled because of user input.

      Available in OS X v10.4 and later.

    Discussion

    These constants are used:

    Note that tablet devices may generate mouse events with embedded tablet data, or tablet pointer and proximity events. Tablet mouse events allow tablets to be used with applications that are not tablet-aware.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Specifies an event mask that represents all event types.

    Declaration

    Objective-C

    #define kCGEventMaskForAllEvents (~(CGEventMask)0)

    Constants

    • kCGEventMaskForAllEvents

      kCGEventMaskForAllEvents

      An event mask that specifies all event types.

      Available in OS X v10.4 and later.

    Discussion

    This constant is typically used with the functions CGEventTapCreate and CGEventTapCreateForPSN to register an event tap that observes all input events.

    Import Statement

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

    Declaration

    Swift

    typealias CGMouseButton = UInt32

    Objective-C

    enum _CGMouseButton { kCGMouseButtonLeft = 0, kCGMouseButtonRight = 1, kCGMouseButtonCenter = 2 }; typedef uint32_t CGMouseButton;

    Constants

    • kCGMouseButtonLeft

      kCGMouseButtonLeft

      Specifies the only mouse button on a one-button mouse, or the left mouse button on a two-button or three-button mouse.

      Available in OS X v10.4 and later.

    • kCGMouseButtonRight

      kCGMouseButtonRight

      Specifies the right mouse button on a two-button or three-button mouse.

      Available in OS X v10.4 and later.

    • kCGMouseButtonCenter

      kCGMouseButtonCenter

      Specifies the center mouse button on a three-button mouse.

      Available in OS X v10.4 and later.

    Discussion

    Quartz supports up to 32 mouse buttons. The first three buttons are specified using these three constants. Additional buttons are specified in USB order using the integers 3 to 31.

    These constants are used:

    • In the function CGEventCreateMouseEvent to specify the button that’s changing state.

    • In the function CGEventSourceButtonState to specify the button that’s being tested.

    • To specify the value of the kCGMouseEventButtonNumber event field when modifying an event.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

  • Constants used with the kCGMouseEventSubtype event field.

    Declaration

    Swift

    typealias CGEventMouseSubtype = UInt32

    Objective-C

    enum _CGEventMouseSubtype { kCGEventMouseSubtypeDefault = 0, kCGEventMouseSubtypeTabletPoint = 1, kCGEventMouseSubtypeTabletProximity = 2 }; typedef uint32_t CGEventMouseSubtype;

    Constants

    • kCGEventMouseSubtypeDefault

      kCGEventMouseSubtypeDefault

      Specifies that the event is an ordinary mouse event, and does not contain additional tablet device information.

      Available in OS X v10.4 and later.

    • kCGEventMouseSubtypeTabletPoint

      kCGEventMouseSubtypeTabletPoint

      Specifies that the mouse event originated from a tablet device, and that the various kCGTabletEvent field selectors may be used to obtain tablet-specific data from the mouse event.

      Available in OS X v10.4 and later.

    • kCGEventMouseSubtypeTabletProximity

      kCGEventMouseSubtypeTabletProximity

      Specifies that the mouse event originated from a tablet device with the pen in proximity but not necessarily touching the tablet, and that the various kCGTabletProximity field selectors may be used to obtain tablet-specific data from the mouse event. This is often used with mouse move events originating from a tablet.

      Available in OS X v10.4 and later.

    Discussion

    Tablets may generate specially annotated mouse events that contain values associated with the kCGMouseEventSubtype event field. To learn how to set these values, see the function CGEventSetIntegerValueField.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    typealias CGScrollEventUnit = UInt32

    Objective-C

    enum { kCGScrollEventUnitPixel = 0, kCGScrollEventUnitLine = 1 }; typedef uint32_t CGScrollEventUnit;

    Constants

    • kCGScrollEventUnitPixel

      kCGScrollEventUnitPixel

      Specifies that the unit of measurement is pixels.

      Available in OS X v10.5 and later.

    • kCGScrollEventUnitLine

      kCGScrollEventUnitLine

      Specifies that the unit of measurement is lines.

      Available in OS X v10.5 and later.

    Discussion

    You may pass one of these constants to the function CGEventCreateScrollWheelEvent to specify the unit of measurement for the event. The constant kCGScrollEventUnitPixel produces an event that most applications interpret as a smooth scrolling event. By default, the scale is about ten pixels per line. You can alter the scale with the function CGEventSourceSetPixelsPerLine.

    Import Statement

    import CoreGraphics

    Availability

    Available in OS X v10.5 and later.