Deprecated Quartz Event Services Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

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

CGEventGetSource

Returns a Quartz event source created from an existing Quartz event. (Available in OS X v10.4 through OS X v10.4. Use CGEventCreateSourceFromEvent instead.)

CGEventSourceRef CGEventGetSource (
   CGEventRef event
);
Availability
  • Available in OS X v10.4 through OS X v10.4.
  • Deprecated in OS X v10.4.
Declared In
CGEvent.h

Deprecated in OS X v10.6

CGEnableEventStateCombining

Enables or disables the merging of actual key and mouse state with the application-specified state in a synthetic event. (Deprecated in OS X v10.6.)

CGError CGEnableEventStateCombining (
   boolean_t doCombineState
);
Parameters
doCombineState

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

Return Value

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

Discussion

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

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

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
CGRemoteOperation.h

CGInhibitLocalEvents

Turns off local hardware events in the current session. (Deprecated in OS X v10.6.)

CGError CGInhibitLocalEvents (
   boolean_t doInhibit
);
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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
CGRemoteOperation.h

CGPostKeyboardEvent

Synthesizes a low-level keyboard event on the local machine. (Deprecated in OS X v10.6.)

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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
CGRemoteOperation.h

CGPostMouseEvent

Synthesizes a low-level mouse-button event on the local machine. (Deprecated in OS X v10.6.)

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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
CGRemoteOperation.h

CGPostScrollWheelEvent

Synthesizes a low-level scrolling event on the local machine. (Deprecated in OS X v10.6.)

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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
CGRemoteOperation.h

CGSetLocalEventsFilterDuringSuppressionState

Filters local hardware events from the keyboard and mouse during the short interval after a synthetic event is posted. (Deprecated in OS X v10.6.)

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.

Availability
  • Available in OS X v10.1 and later.
  • Deprecated in OS X v10.6.
Declared In
CGRemoteOperation.h

CGSetLocalEventsSuppressionInterval

Sets the time interval in seconds that local hardware events are suppressed after posting a synthetic event. (Deprecated in OS X v10.6.)

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.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
CGRemoteOperation.h