
/* Create a NULL event to be filled in. ‘source’ may be NULL. */
CG_EXTERN CGEventRef CGEventCreate(CGEventSource source);
/*
* Create mouse events.
* The event source may be taken from another event, or may be
* NULL. mouseType should be one of the mouse event types.
* mouseCursorPosition should be the global coordinates the mouse
* is at for the event. For kCGEventOtherMouseDown,
* kCGEventOtherMouseDragged, and kCGEventOtherMouseUp events,
* the mouseButton parameter should indicate which button is
* changing state.
* The current implementation of the event system supports a
* maximum of thirty-two buttons. Mouse button 0 is the primary
* button on the mouse.Mouse button 1 is the secondary
* mouse button (right). Mouse button 2 is the center button, and
* the remaining buttons would be in USB device order.
*/
CG_EXTERN CGEventRef CGCreateMouseEvent(CGEventSource

	source,
	CGEventType mouseType,
	CGPoint mouseCursorPosition,
	CGButtonCount mouseButton );

/* Return the CFTypeID for CGEventRefs. */

CG_EXTERN CFTypeID CGEventGetTypeID(void);

/*

* Create keyboard events.

* The event source may be taken from another event, or may be NULL.

* Based on the virtual key code values entered,

* the appropriate key down, key up, or flags changed events are

* generated.

* All keystrokes needed to generate a character must be entered,

* including SHIFT, CONTROL, OPTION, and COMMAND 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:

* CGCreateKeyboardEvent((CGKeyCode)56, true ); // shift down

* CGCreateKeyboardEvent((CGKeyCode)6, true ); // ‘z’ down

* CGCreateKeyboardEvent((CGKeyCode)6, false ); // ‘z’ up

* CGCreateKeyboardEvent((CGKeyCode)56, false ); // ‘shift up

*/

CG_EXTERN CGEventRef CGCreateKeyboardEvent(CGEventSource

	source, CGKeyCode
	virtualKey, bool keyDown );

CG_EXTERN CGEventRef CGEventCopy(CGEventRef event);

CFRetain( ) and CFRelease( ) may be used to retain and release CGEventRefs. A set of type codes, accessor functions, and data tags are defined to permit access and modification of data within CGEventRefs.

Event Type Codes: The following enumeration describes all event types currently presented in this API.


/* Event types */
typedef enum {
/* mouse events */

kCGEventLeftMouseDown =	1,	/* left mouse-down event */
kCGEventLeftMouseUp =	2,	/* left mouse-up event */
kCGEventRightMouseDown =	3,	/* right mouse-down event */
kCGEventRightMouseUp =	4,	/* right mouse-up event */
kCGEventMouseMoved =	5,	/* mouse-moved event */

kCGEventLeftMouseDragged = 6,	/* left mouse-dragged event */
kCGEventRightMouseDragged = 7,	/* right mouse-dragged
	event */
/* keyboard events */

kCGEventKeyDown =	10,	/* key-down event */
kCGEventKeyUp =	11,	/* key-up event */

kCGEventFlagsChanged = 12,	/* flags-changed (modifier */
	/* event keys) */
/* Specialized control devices */
kCGEventScrollWheel = 22,	/* Scroll wheel input device */
kCGEventTabletPointer = 23,	/* specialized tablet pointer */
	/* event, in addition to */
	/* tablet mouse event */
kCGEventTabletProximity = 24,	/* specialized tablet prox- */
	/* imity event, in addition */
	/* to tablet mouse event */
kCGEventOtherMouseDown = 25,	/* Mouse button 2-31 down */

kCGEventOtherMouseUp = 26, /* Mouse button 2-31 up */

kCGEventOtherMouseDragged = 27	/* Drag with mouse button */
	/* 2-31 down */
} CGEventType;

Tablet devices may generate mice events with embedded tablet data, or tablet pointer and proximity events. The tablet events as mouse events allow tablets to be used with programs which are not tablet-aware.

High Level Accessor Functions: The following functions provide high level access to selected event data.


typedef uint64_t CGEventTimestamp;
typedef uint64_t CGEventFlags;
CGEventSource CGEventGetSource(CGEventRef event);
void CGEventSetSource(CGEventRef event, CGEventSource source);
CGEventType CGEventGetType(CGEventRef event);
void CGEventSetType(CGEventRef event, CGEventType type);
CGEventTimestamp CGEventGetTimestamp(CGEventRef event);
void CGEventSetTimestamp(CGEventRef event, CGEventTimestamp
timestamp);
CGPoint CGEventGetLocation(CGEventRef event);
void CGEventSetLocation(CGEventRef event, CGPoint location);
CGEventFlags CGEventGetFlags(CGEventRef event);
void CGEventSetFlags(CGEventRef event, CGEventFlags flags);

Low Level Event Accessor Functions: Additional low level functions provide access to specialized fields of the events include the following.


	intmax_t CGEventGetIntegerValueField(CGEventRef event,

CGEventField field);

double CGEventGetDoubleValueField(CGEventRef event,

CGEventField field);

CGPoint CGEventGetPointValueField(CGEventRef event,

CGEventField field);

void CGEventSetIntegerValueField(CGEventRef event,

	CGEventField field,
	intmax_t value);

void CGEventSetDoubleValueField(CGEventRef event,

	CGEventField field,
	double value);

void CGEventSetPointValueField(CGEventRef event,

	CGEventField field,
	CGPoint point);

The CGEventSetPointValueField and CGEventGetPointValueField only works on fields capable of holding point data. The other functions work on any other field in the event record, performing the appropriate type conversions and range clamping automatically.

Low Level Event Accessor Keys: Additional keys and values found in mouse events, including the OtherMouse events include the following. kCGMouseEventNumber

Key associated with an integer encoding the mouse button event number as an integer. Matching mouse-down and mouse-up events will have the same event number.

kCGMouseEventClickState

Key associated with an integer encoding the mouse button clickState as an integer. A clickState of 1 represents a single click. A clickState of 2 represents a double-click. A clickState of 3 represents a triple-click.

kCGMouseEventPressure

Key associated with a double encoding the mouse button pressure. The pressure value may range from 0 to 1.0, with 0 representing the mouse being up. This value is commonly set by tablet pens mimicking a mouse.

kCGMouseEventButtonNumber

Key associated with an integer representing the mouse button number. The left mouse button reports as button 0. A right mouse button reports asbutton 1. A middle button reports as button 2 and additional buttons report as the appropriate USB button.


	kCGMouseEventDeltaX
	kCGMouseEventDeltaY

Key associated with an integer encoding the mouse delta since the last mouse movement event.

kCGMouseEventInstantMouser

Key associated with an integer value, non-zero if the event should be ignored by the Inkwell subsystem.

kCGMouseEventSubtype

Key associated with an integer encoding the mouse event subtype as a

kCFNumberIntType.


	enum CGEventMouseSubtype {
	kCGEventMouseSubtypeDefault	= 0,
	kCGEventMouseSubtypeTabletPoint	= 1,

	kCGEventMouseSubtypeTabletProximity = 2
	};

Tablets may generate specially annotated mouse events, which will contain additional keys and values. Mouse events of subtype CGEventMouseSubtypeTabletPoint may also use the tablet accessor keys. Mouse events of subtype kCGEventMouseSubtypeTabletProximity may also use the tablet proximity accessor keys.

Additional keys and values found in keyboard events include the following. kCGKeyboardEventAutorepeat

Key associated with an integer, non-zero when this is an autorepeat of a key-down, and zero otherwise.

kCGKeyboardEventKeycode

Key associated with the integer virtual keycode of the key-down or key-up event.

kCGKeyboardEventKeyboardType

Key associated with the integer representing the keyboard type identifier.

Additional keys and values found in scroll wheel events include the following.


	kCGScrollWheelDeltaAxis1
	kCGScrollWheelDeltaAxis2
	kCGScrollWheelDeltaAxis3

Key associated with an integer value representing a change in scrollwheel position.

kCGScrollWheelEventInstantMouser

Additional keys and values found in tablet pointer events, and in mouse events containing embedded tablet event data include the following.


	kCGTabletEventPointX
	kCGTabletEventPointY
	kCGTabletEventPointZ

Key associated with an integer encoding the absolute X, Y, or Z tablet coordinate in tablet space at full tablet resolution.

kCGTabletEventPointButtons

Key associated with an integer encoding the tablet button state as a kCFNumberLongType. Bit0 is the first button, and a set bit represents a closed or pressed button.

kCGTabletEventPointPressure

Key associated with a double encoding the tablet pen pressure. 0 represents no pressure, and 1.0 represents maximum pressure.


	kCGTabletEventTiltX
	kCGTabletEventTiltY

Key associated with a double encoding the tablet pen tilt. 0 represents no tilt, and 1.0 represents maximum tilt.

kCGTabletEventRotation

Key associated with a double encoding the tablet pen rotation.

kCGTabletEventTangentialPressure

Key associated with a double encoding the tangential pressure on the device. 0 represents no pressure, and 1.0 represents maximum pressure.

kCGTabletEventDeviceID

Key associated with an integer encoding the system-assigned unique device ID.


	kCGTabletEventVendor1
	kCGTabletEventVendor2
	kCGTabletEventVendor3

Key associated with an integer containing vendor-specified values.

Additional keys and values found in tablet proximity events, and in mouse events containing embedded tablet proximity data:

kCGTabletProximityEventVendorID

Key associated with an integer encoding the vendor-defined ID, typically the USB vendor ID.

kCGTabletProximityEventTabletID

Key associated with an integer encoding the vendor-defined tablet ID, typically the USB product ID.

kCGTabletProximityEventPointerID

Key associated with an integer encoding the vendor-defined ID of the pointing device.

kCGTabletProximityEventDeviceID

Key associated with an integer encoding the system-assigned device ID.

kCGTabletProximityEventSystemTabletID

Key associated with an integer encoding the system-assigned unique tablet ID.

kCGTabletProximityEventVendorPointerType

Key associated with an integer encoding the vendor-assigned pointer type.

kCGTabletProximityEventVendorPointerSerialNumber

Key associated with an integer encoding the vendor-defined pointer serial number.

kCGTabletProximityEventVendorUniqueID

Key associated with an integer encoding the vendor-defined unique ID.

kCGTabletProximityEventCapabilityMask

Key associated with an integer encoding the device capabilities mask.

kCGTabletProximityEventPointerType

Key associated with an integer encoding the pointer type.

kCGTabletProximityEventEnterProximity

Key associated with an integer, non-zero when pen is in proximity to the tablet, and zero when leaving the tablet.

Registering an Event Tap: A function registers an event tap, taking a pointer to the program's tap function (also referred to as a callback routine or function) and an arbitrary reference to be passed to the tap function, and returning a CFMachPortRef the program can add to the appropriate run loop using CFRunLoopAddSource( ) Taps may be placed at the point where HIDSystem events enter the server, at the point where HIDSystem and remote control events enter a session, at the point where events have been annotated to flow to a specific application, or at the point where events are delivered to the application. Taps may be inserted at a specified point at the head of pre-existing filters, or appended after any pre-existing filters. Taps may be passive event listeners, or active filters. An active filter may pass an event through unmodified, modify an event, or discard an event. When a tap is registered, it identifies the set of events to be observed with a mask, and indicates if it is a passive or active event filter. Multiple event type bitmasks may be OR'ed together. Releasing the CFMachPortRef will release the tap. The CGEventTapProxy is an opaque reference to state within the client application associated with the tap. The tap function may pass this reference to other functions, such as the event-posting routines.


/* Possible tapping points for events */
typedef enum {
kCGHIDEventTap,
kCGSessionEventTap,
kCGAnnotatedSessionEventTap
} CGEventTap;
typedef enum {
kCGHeadInsertEventTap,
kCGTailAppendEventTap
} CGEventTapPlacement;
enum {
kCGEventTapOptionListenOnly = 0x00000001
};
typedef uint32_t CGEventTapOptions;
#define CGEventMaskBit(eventType) (1ULL << (eventType))
typedef uint64_t CGEventMask;
typedef void * CGEventTapProxy;
/*
* The callback is passed a proxy for the tap, the event type, the
* incoming event, and the refcon the callback was registered with.
* The function should return the (possibly modified) passed in event,
* a newly constructed event, or NULL if the event is to be deleted.
* The CGEventRef passed into the callback is retained by the calling
* code, and is released after the callback returns and the data is
* passed back to the event system. If a different event is returned
* by the callback function, then that event will be released by the
* calling code along with the original event, after the event data
* has been passed back to the event system.
* If an event tap is set to be listen-only, then the returned value,
* if not NULL, is released without being passed back to the event
* system.
*/
typedef void (*CGEventTapCallBack)(CGEventTapProxy proxy,

	CGEventType type, CGEventRef event,
	void refcon, CGEventRef pEventOut);

/* Return the a CFMachPortRef for the event tap. */

CG_EXTERN CFMachPortRef CGEventTapCreate(CGEventLocation

	tap, CGEventTapPlacement place,
	CGEventTapOptions options,
	CGEventMask eventsOfInterest,
	CGEventTapCallBack callback,
	void * refcon );

Events being routed to individual applications may be tapped using another function. CGEventTapCreateForPSN( )will report all events being routed to the specified application.


	/* Return the CFMachPortRef for an event tap for the specified
	* process. */
	#include <HIServices/Processes.h>
	CG_EXTERN CFMachPortRef

CGEventTapCreateForPSN(ProcessSerialNumber

	*psn, CGEventTapPlacement place,
	CGEventTapOptions options,
	CGEventMask eventsOfInterest,
	CGEventTapCallBack callback,
	void * refcon );

Posting New Events: A function to post events from a tap is provided. The events are posted to the same points that an event returned from an event tap would be posted to. If an event tap posts new events, the new events enter the system before the event returned by the tap enters the system. This order may be changed by explicitly posting the filtered event along with new events in the desired order, and then returning NULL from the callback. Events posted into the system will be seen by all taps placed after the tap posting the event.


/* Post an event from the event tap into the event stream. */
CG_EXTERN void CGEventTapPostEvent(CGEventTapProxy proxy,

	CGEventRef event );

Functions to post events into the system at various points are provided. Each event posted by these functions enters the system at a point immediately before any taps instantiated for that point, and will pass through any such taps. This mechanism permits an external process to establish an event routing policy, for example, by tapping events at the kCGAnnotatedSessionEventTap and then posting the events to the desired PSN.


/* Post an event from the event tap into the event stream. */
CG_EXTERN void CGPostEvent(CGEventTapLocation tap,

CGEventRef event );

/* Post an event from the event tap into the event stream

* for a specific application. */

CG_EXTERN void CGPostEventToPSN(ProcessSerialNumber *psn,

	CGEventRef event );

Typical Usage as an Event Monitor: This sample code demonstrates the use of this API in the context of a simple event monitor.


#include <ApplicationServices/ApplicationServices.h>
#include <stdlib.h>
#include <unistd.h>
static const char * eventType[ ] =
{
“NullEvent”, “LMouseDown”, “LMouseUp”, “RMouseDown”,
“RMouseUp”, “MouseMoved”, “LMouseDragged”,
“RMouseDragged”, “MouseEntered”, “MouseExited”,
“KeyDown”, “KeyUp”, “FlagsChanged”, “Kitdefined”,
“SysDefined”, “AppDefined”, “Timer”, “CursorUpdate”,
“Journaling”, “Suspend”, “Resume”, “Notification”,
“ScrollWheel”, “TabletPointer”, “TabletProximity”,
“OtherMouseDown”, “OtherMouseUp”, “OtherMouseDragged”
};
static CGEventRef eventCallback(CGEventTapProxy proxy,

	CGEventType type, CGEventRef event,
	void *refcon)

{

if (type < (sizeof eventType / sizeof eventType[0]) )

printf(“%s\n”, eventType[type] );

else

printf(“Event Type 0x%x\n”, type);

CFMachPortRef eventPort;

CFRunLoopSourceRef eventSrc;

CFRunLoopRef runLoop;

runLoop = CFRunLoopGetCurrent( );

if (runLoop == NULL )

printf(“No run loop?\n” );

/*

* Create an event tap.

* The tap listens for annotated session events, the

* last tap point before events are sent to applications.

*/

eventPort = CGCreateEventTap(kCGAnnotatedSessionEventTap,

	kCGHeadInsertEventTap,
	kCGEventTapOptionListenOnly,
	kCGEventMaskForAllEvents,
	eventCallback,
	NULL );

if (eventPort == NULL )

{

printf(“NULL event port\n” );

exit(1 );

}

/* Make an event source for our event tap port */

eventSrc = CFMachPortCreateRunLoopSource(NULL, eventPort, 0);

if (eventPort == NULL )

printf(“No event run loop src?\n” );

/* Listen for events on our event tap port */

CFRunLoopAddSource(runLoop, eventSrc,

kCFRunLoopDefaultMode);

/* Go log events. Never returns. */