AXUIElement.h Reference

Declared in

AXUIElement.h

Overview

Assistive applications use the functions defined in this header file to communicate with and control accessible applications running in Mac OS X.

Each accessible user interface element in an application is represented by an AXUIElementRef, which is a CFTypeRef. AXUIElementRefs (like all CFTypeRefs) can be used with all the Core Foundation polymorphic functions, such as CFRetain, CFRelease, and CFEqual.

All functions defined in this header file return kAXErrorSuccess on success. If there is some sort of system memory failure, such as the failure to allocate an object, all functions can return kAXErrorFailure. In the unlikely event that some process does not fully support the accessibility API, a function can return kAXErrorNotImplemented.

In addition, some functions can return the following error codes:

kAXErrorInvalidUIElement: The passed-in AXUIElementRef is invalid. All functions that include an AXUIElementRef parameter can return this error code.
kAXErrorIllegalArgument: At least one of the arguments is illegal (for example, NIL passed in for a pointer).
kAXErrorCannotComplete: There is a problem with messaging (such as when messaging to the server fails or when the accessible application is unresponsive or waiting for user input). All functions that perform messaging can return this error code.
kAXErrorAPIDisabled: The accessibility API is disabled. All functions that perform messaging can return this error code.

For more information on the definition and use of accessibility objects and on Mac OS X accessibility support in general, see Accessibility Overview for OS X.

Included Headers

<AvailabilityMacros.h>
<CoreFoundation/CoreFoundation.h>
<ApplicationServices/ApplicationServices.h>

Functions by Task

See the Overview section above for header-level documentation.

Notification API

Miscellaneous

Functions

AXAPIEnabled

Returns whether the accessibility API is enabled.

extern Boolean AXAPIEnabled (
   void);

Return Value

Returns TRUE if the accessibility API is currently enabled, otherwise FALSE.

Discussion

Assistive applications will not work if the accessibility API is not enabled or if the calling process is not a trusted accessibility client. Users can enable the accessibility API by checking "Enable access for assistive devices" in Universal Access Preferences.

Availability

Available in OS X v10.2 and later.

Related Sample Code

Declared In

AXUIElement.h

AXIsProcessTrusted

Returns whether the current process is a trusted accessibility client.

extern Boolean AXIsProcessTrusted (
   void)AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;

Return Value

Returns TRUE if the current process is a trusted accessibility client, FALSE if it is not.

Availability

Available in OS X v10.4 and later.

Declared In

AXUIElement.h

AXMakeProcessTrusted

Attempts to make the process represented by the specified path a trusted accessibility client.

extern AXError AXMakeProcessTrusted (
   CFStringRef executablePath)AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;

Parameters

executablePath: The path to the executable of the process to make trusted.

Return Value

An AXError that indicates success or failure.

Discussion

Use this function to make a process a trusted accessibility client. Note: The caller must be running as root to successfully call this function. In addition, the caller should relaunch the process after this function returns successfully for the trusted status to take effect.

Availability

Available in OS X v10.4 and later.

Declared In

AXUIElement.h

AXObserverAddNotification

Registers the specified observer to receive notifications from the specified accessibility object.

extern AXError AXObserverAddNotification (
   AXObserverRef observer,
   AXUIElementRef element,
   CFStringRef notification,
   void *refcon);

Parameters

observer: The observer object created from a call to AXObserverCreate.
element: The accessibility object for which to observe notifications.
notification: The name of the notification to observe.
refcon: Application-defined data passed to the callback when it is called.

Return Value

If unsuccessful, AXObserverAddNotification may return one of the following error codes, among others:

kAXErrorInvalidUIElementObserver: The observer is not a valid AXObserverRef type.
kAXErrorIllegalArgument: One or more of the arguments is an illegal value or the length of the notification name is greater than 1024.
kAXErrorNotificationUnsupported: The accessibility object does not support notifications (note that the system-wide accessibility object does not support notifications).
kAXErrorNotificationAlreadyRegistered: The notification has already been registered.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorFailure: There is some sort of system memory failure.

Availability

Available in OS X v10.2 and later.

Related Sample Code

iChatStatusFromApplication

Declared In

AXUIElement.h

AXObserverCreate

Creates a new observer that can receive notifications from the specified application.

extern AXError AXObserverCreate (
   pid_t application,
   AXObserverCallback callback,
   AXObserverRef *outObserver);

Parameters

application: The process ID of the application.
callback: The callback function.
outObserver: On return, an AXObserverRef representing the observer object.

Return Value

If unsuccessful, AXObserverCreate may return one of the following error codes, among others:

kAXErrorIllegalArgument: One or more of the arguments is an illegal value.
kAXErrorFailure: There is some sort of system memory failure.

Discussion

When an observed notification is received, it is passed to AXObserverCallback.

Availability

Available in OS X v10.2 and later.

Related Sample Code

iChatStatusFromApplication

Declared In

AXUIElement.h

AXObserverGetRunLoopSource

Returns the observer's run loop source.

extern CFRunLoopSourceRef AXObserverGetRunLoopSource (
   AXObserverRef observer);

Parameters

observer: The observer object (created from a call to AXObserverCreate) for which to get the run loop source.

Return Value

Returns the CFRunLoopSourceRef of the observer; NIL if you pass NIL in observer.

Discussion

The observer must be added to a run loop before it can receive notifications. Note that releasing the AXObserverRef automatically removes the run loop source from the run loop (you can also do this explicitly by calling CFRunLoopRemoveSource).

AXObserverGetRunLoopSource might be used in code in this way:

   CFRunLoopAddSource(CFRunLoopGetCurrent(), AXObserverGetRunLoopSource(observer), kCFRunLoopDefaultMode);

Availability

Available in OS X v10.2 and later.

Related Sample Code

iChatStatusFromApplication

Declared In

AXUIElement.h

AXObserverGetTypeID

Returns the unique type identifier for the AXObserverRef type.

CFTypeID AXObserverGetTypeID (
   void);

Return Value

Returns the CFTypeID of the AXObserverRef type.

Availability

Available in OS X v10.2 and later.

Declared In

AXUIElement.h

AXObserverRemoveNotification

Removes the specified notification from the list of notifications the observer wants to receive from the accessibility object.

extern AXError AXObserverRemoveNotification (
   AXObserverRef observer,
   AXUIElementRef element,
   CFStringRef notification);

Parameters

observer: The observer object created from a call to AXObserverCreate.
element: The accessibility object for which this observer observes notifications.
notification: The name of the notification to remove from the list of observed notifications.

Return Value

If unsuccessful, AXObserverRemoveNotification may return one of the following error codes, among others:

kAXErrorInvalidUIElementObserver: The observer is not a valid AXObserverRef type.
kAXErrorIllegalArgument: One or more of the arguments is an illegal value or the length of the notification name is greater than 1024.
kAXErrorNotificationUnsupported: The accessibility object does not support notifications (note that the system-wide accessibility object does not support notifications).
kAXErrorNotificationNotRegistered: This observer has not registered for any notifications.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorFailure: There is some sort of system memory failure.

Availability

Available in OS X v10.2 and later.

Declared In

AXUIElement.h

AXUIElementCopyActionDescription

Returns a localized description of the specified accessibility object's action.

extern AXError AXUIElementCopyActionDescription (
   AXUIElementRef element,
   CFStringRef action,
   CFStringRef *description);

Parameters

element: The AXUIElementRef representing the accessibility object.
action: The action to be described.
description: On return, a string containing the description of the action.

Return Value

If unsuccessful, AXUIElementCopyActionDescription may return one of the following error codes, among others:

kAXErrorActionUnsupported: The specified AXUIElementRef does not support the specified action (you will also receive this error if you pass in the system-wide accessibility object).
kAXErrorIllegalArgument: One or more of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementCopyActionNames

Returns a list of all the actions the specified accessibility object can perform.

extern AXError AXUIElementCopyActionNames (
   AXUIElementRef element,
   CFArrayRef *names);

Parameters

element: The AXUIElementRef representing the accessibility object.
names: On return, an array of actions the accessibility object can perform (empty if the accessibility object supports no actions).

Return Value

If unsuccessful, AXUIElementCopyActionNames may return one of the following error codes, among others:

kAXErrorIllegalArgument: One or both of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorFailure: There was some sort of system memory failure.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementCopyAttributeNames

Returns a list of all the attributes supported by the specified accessibility object.

extern AXError AXUIElementCopyAttributeNames (
   AXUIElementRef element,
   CFArrayRef *names);

Parameters

element: The AXUIElementRef representing the accessibility object.
names: On return, an array containing the accessibility object's attribute names.

Return Value

If unsuccessful, AXUIElementCopyAttributeNames may return one of the following error codes, among others:

kAXErrorAttributeUnsupported: The specified AXUIElementRef does not support the specified attribute.
kAXErrorIllegalArgument: One or both of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorFailure: There was a system memory failure.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementCopyAttributeValue

Returns the value of an accessibility object's attribute.

extern AXError AXUIElementCopyAttributeValue (
   AXUIElementRef element,
   CFStringRef attribute,
   CFTypeRef *value);

Parameters

element: The AXUIElementRef representing the accessibility object.
attribute: The attribute name.
value: On return, the value associated with the specified attribute.

Return Value

If unsuccessful, AXUIElementCopyAttributeValue may return one of the following error codes, among others:

kAXErrorAttributeUnsupported: The specified AXUIElementRef does not support the specified attribute.
kAXErrorNoValue: The specified attribute does not have a value.
kAXErrorIllegalArgument: One or more of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementCopyAttributeValues

Returns an array of attribute values for the accessibility object's attribute, starting at the specified index.

extern AXError AXUIElementCopyAttributeValues (
   AXUIElementRef element,
   CFStringRef attribute,
   CFIndex index,
   CFIndex maxValues,
   CFArrayRef *values);

Parameters

element: The AXUIElementRef representing the accessibility object.
attribute: The attribute name.
index: The index into the array.
maxValues: The maximum number of values you want (this may be more or less than the number of values associated with the attribute).
values: On return, the attribute values you requested. If maxValues is greater than the number of values associated with the attribute, the values array will contain values found between index and the end of the attribute's array, inclusive.

Return Value

If unsuccessful, AXUIElementCopyAttributeValues may return one of the following error codes, among others:

kAXErrorIllegalArgument: The attribute's value is not array, the index or maxValues arguments are outside the array's range, or one of the other arguments is an illegal value.
kAXErrorNoValue: The specified attribute does not have a value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Discussion

This function is useful for dealing with large arrays, for example, a table view with a large number of children.

Availability

Available in OS X v10.2 and later.

Declared In

AXUIElement.h

AXUIElementCopyElementAtPosition

Returns the accessibility object at the specified position in top-left relative screen coordinates.

extern AXError AXUIElementCopyElementAtPosition (
   AXUIElementRef application,
   float x,
   float y,
   AXUIElementRef *element);

Parameters

application: The AXUIElementRef representing the application that contains the screen coordinates (or the system-wide accessibility object).
x: The horizontal position.
y: The vertical position.
element: On return, the accessibility object at the position specified by x and y.

Return Value

If unsuccessful, AXUIElementCopyElementAtPosition may return one of the following error codes, among others:

kAXErrorNoValue: There is no accessibility object at the specified position.
kAXErrorIllegalArgument: One or more of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Discussion

This function does hit-testing based on window z-order (that is, layering). If one window is on top of another window, the returned accessibility object comes from whichever window is topmost at the specified location. Note that if the system-wide accessibility object is passed in the application parameter, the position test is not restricted to a particular application.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementCopyMultipleAttributeValues

Returns the values of multiple attributes in the accessibility object.

extern AXError AXUIElementCopyMultipleAttributeValues (
   AXUIElementRef element,
   CFArrayRef attributes,
   AXCopyMultipleAttributeOptions options,
   CFArrayRef *values)AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;

Parameters

element: The AXUIElementRef representing the accessibility object.
attributes: An array of attribute names.
options: A value that tells AXUIElementCopyMultipleAttributeValues how to handle errors.
values: On return, an array in which each position contains the value of the attribute that is in the corresponding position in the passed-in attributes array (or CFNull). If options = 0, the values array can contain an AXValueRef of type kAXValueAXErrorType in the corresponding position. If options = kAXCopyMultipleAttributeOptionStopOnError, this function will return immediately when it gets an error.

Return Value

If unsuccessful, AXUIElementCopyMultipleAttributeValues may return one of the following error codes, among others:

kAXErrorIllegalArgument: One of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Discussion

If the specified AXUIElementRef does not support an attribute passed in the attributes array, the returned array can contain an error or CFNull at the corresponding position.

Availability

Available in OS X v10.4 and later.

Declared In

AXUIElement.h

AXUIElementCopyParameterizedAttributeNames

Returns a list of all the parameterized attributes supported by the specified accessibility object.

extern AXError AXUIElementCopyParameterizedAttributeNames (
   AXUIElementRef element,
   CFArrayRef *names)AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;

Parameters

element: The AXUIElementRef representing the accessibility object.
names: On return, an array containing the accessibility object's parameterized attribute names.

Return Value

If unsuccessful, AXUIElementCopyParameterizedAttributeNames may return one of the following error codes, among others:

kAXErrorAttributeUnsupported or kAXErrorParameterizedAttributeUnsupported: The specified AXUIElementRef does not support the specified parameterized attribute.
kAXErrorIllegalArgument: One or both of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorFailure: There was some sort of system memory failure.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Availability

Available in OS X v10.3 and later.

Declared In

AXUIElement.h

AXUIElementCopyParameterizedAttributeValue

Returns the value of an accessibility object's parameterized attribute.

extern AXError AXUIElementCopyParameterizedAttributeValue (
   AXUIElementRef element,
   CFStringRef parameterizedAttribute,
   CFTypeRef parameter,
   CFTypeRef *result)AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER;

Parameters

element: The AXUIElementRef representing the accessibility object.
parameterizedAttribute: The parameterized attribute.
parameter: The parameter.
result: On return, the value of the parameterized attribute.

Return Value

If unsuccessful, AXUIElementCopyParameterizedAttributeValue may return one of the following error codes, among others:

kAXErrorAttributeUnsupported or kAXErrorParameterizedAttributeUnsupported: The specified AXUIElementRef does not support the specified parameterized attribute.
kAXErrorNoValue: The specified parameterized attribute does not have a value.
kAXErrorIllegalArgument: One or more of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Availability

Available in OS X v10.3 and later.

Declared In

AXUIElement.h

AXUIElementCreateApplication

Creates and returns the top-level accessibility object for the application with the specified process ID.

extern AXUIElementRef AXUIElementCreateApplication (
   pid_t pid);

Parameters

pid: The process ID of an application.

Return Value

The AXUIElementRef representing the top-level accessibility object for the application with the specified process ID.

Availability

Available in OS X v10.2 and later.

Related Sample Code

iChatStatusFromApplication

Declared In

AXUIElement.h

AXUIElementCreateSystemWide

Returns an accessibility object that provides access to system attributes.

extern AXUIElementRef AXUIElementCreateSystemWide (
   void);

Return Value

The AXUIElementRef representing the system-wide accessibility object.

Discussion

This is useful for things like finding the focused accessibility object regardless of which application is currently active.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementGetAttributeValueCount

Returns the count of the array of an accessibility object's attribute value.

extern AXError AXUIElementGetAttributeValueCount (
   AXUIElementRef element,
   CFStringRef attribute,
   CFIndex *count);

Parameters

element: The AXUIElementRef representing the accessibility object.
attribute: The attribute name.
count: On return, the size of the array that is the attribute's value.

Return Value

If unsuccessful, AXUIElementGetAttributeValueCount may return one of the following error codes, among others:

kAXErrorIllegalArgument: The attribute's value is not an array or one of the other arguments is an illegal value.
kAXErrorAttributeUnsupported: The specified AXUIElementRef does not support the specified attribute.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementGetPid

Returns the process ID associated with the specified accessibility object.

extern AXError AXUIElementGetPid (
   AXUIElementRef element,
   pid_t *pid);

Parameters

element: The AXUIElementRef representing an accessibility object.
pid: On return, the process ID associated with the specified accessibility object.

Return Value

If unsuccessful, AXUIElementGetPid may return one of the following error codes, among others:

kAXErrorIllegalArgument: One or more of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementGetTypeID

Returns the unique type identifier for the AXUIElementRef type.

extern CFTypeID AXUIElementGetTypeID (
   void);

Return Value

Returns a CFTypeID representing the AXUIElementRef type.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementIsAttributeSettable

Returns whether the specified accessibility object's attribute can be modified.

extern AXError AXUIElementIsAttributeSettable (
   AXUIElementRef element,
   CFStringRef attribute,
   Boolean *settable);

Parameters

element: The AXUIElementRef representing the accessibility object.
attribute: The attribute name.
settable: On return, a Boolean value indicating whether the attribute is settable.

Return Value

If unsuccessful, AXUIElementIsAttributeSettable may return one of the following error codes, among others:

kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way (often due to a timeout).
kAXErrorIllegalArgument: One or more of the arguments is an illegal value.
kAXErrorAttributeUnsupported: The specified AXUIElementRef does not support the specified attribute.
kAXErrorNoValue: The specified attribute does not have a value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Discussion

If you receive a kAXErrorCannotComplete error from this function, you might want to repeat the request or change the timeout value.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementPerformAction

Requests that the specified accessibility object perform the specified action.

extern AXError AXUIElementPerformAction (
   AXUIElementRef element,
   CFStringRef action);

Parameters

element: The AXUIElementRef representing the accessibility object.
action: The action to be performed.

Return Value

If unsuccessful, AXUIElementPerformAction may return one of the following error codes, among others:

kAXErrorActionUnsupported: The specified AXUIElementRef does not support the specified action (you will also receive this error if you pass in the system-wide accessibility object).
kAXErrorIllegalArgument: One or more of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way or the application has not yet responded.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Discussion

It is possible to receive the kAXErrorCannotComplete error code from this function because accessible applications often need to perform some sort of modal processing inside their action callbacks and they may not return within the timeout value set by the accessibility API. This does not necessarily mean that the function has failed, however. If appropriate, your assistive application can try to call this function again. Also, you may be able to increase the timeout value (see AXUIElementSetMessagingTimeout).

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementPostKeyboardEvent

Posts keys to the specified application.

extern AXError AXUIElementPostKeyboardEvent (
   AXUIElementRef application,
   CGCharCode keyChar,
   CGKeyCode virtualKey,
   Boolean keyDown);

Parameters

application: The AXUIElementRef representing the application (or the system-wide accessibility object).
keyChar
virtualKey
keyDown

Return Value

If unsuccessful, AXUIElementPostKeyboardEvent may return one of the following error codes, among others:

kAXErrorIllegalArgument: One or more of the arguments is an illegal value.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorFailure: There is some sort of system memory failure.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Discussion

This is similar to CGPostKeyboardEvent (which synthesizes a low-level keyboard event on the local machine), but it allows you to specify the target application as opposed to always sending the events to the active application. If the system-wide accessibility object is passed in the application parameter, the event is sent to the active application.

You can only pass in the system-wide or application AXUIElementRef.

Availability

Available in OS X v10.2 and later.

Declared In

AXUIElement.h

AXUIElementSetAttributeValue

Sets the accessibility object's attribute to the specified value.

extern AXError AXUIElementSetAttributeValue (
   AXUIElementRef element,
   CFStringRef attribute,
   CFTypeRef value);

Parameters

element: The AXUIElementRef representing the accessibility object.
attribute: The attribute name.
value: The new value for the attribute.

Return Value

If unsuccessful, AXUIElementSetAttributeValue may return one of the following error codes, among others:

kAXErrorIllegalArgument: The value is not recognized by the accessible application or one of the other arguments is an illegal value.
kAXErrorAttributeUnsupported: The specified AXUIElementRef does not support the specified attribute.
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.
kAXErrorCannotComplete: The function cannot complete because messaging has failed in some way.
kAXErrorNotImplemented: The process does not fully support the accessibility API.

Discussion

You can send and receive many different CFTypeRefs using the accessibility API. These include all CFPropertyListRef types, AXUIElementRef, AXValueRef, AXTextMarkerRef, AXTextMarkerRangeRef, CFNullRef, CFAttributedStringRef, and CRURLRef.

Availability

Available in OS X v10.2 and later.

Related Sample Code

UIElementInspector

Declared In

AXUIElement.h

AXUIElementSetMessagingTimeout

Sets the timeout value used in the accessibility API.

extern AXError AXUIElementSetMessagingTimeout (
   AXUIElementRef element,
   float timeoutInSeconds)AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;

Parameters

element: The AXUIElementRef representing an accessibility object.
timeoutInSeconds: The number of seconds for the new timeout value.

Return Value

If unsuccessful, AXUIElementSetMessagingTimeout may return one of the following error codes, among others:

kAXErrorIllegalArgument: One or more of the arguments is an illegal value (timeout values must be positive).
kAXErrorInvalidUIElement: The AXUIElementRef is invalid.

Discussion

Pass the system-wide accessibility object (see AXUIElementCreateSystemWide) if you want to set the timeout globally for this process. Setting the timeout on another accessibility object sets it only for that object, not for other accessibility objects that are equal to it.

Setting timeoutInSeconds to 0 for the system-wide accessibility object resets the global timeout to its default value. Setting timeoutInSeconds to 0 for any other accessibility object makes that element use the current global timeout value.

Availability

Available in OS X v10.4 and later.

Declared In

AXUIElement.h

Callbacks

See the Overview section above for header-level documentation.

AXObserverCallback

typedef void ( *AXObserverCallback)(
   AXObserverRef observer,
   AXUIElementRef element,
   CFStringRef notification,
   void *refcon);

Parameters

observer: An AXObserverRef object to observe the notifications.
element: The accessibility object.
notification: The name of the notification to observe.
refcon: Application-defined data specified when registering the observer for notification

Availability

Available in OS X v10.2 and later.

Declared In

AXUIElement.h

Data Types

See the Overview section above for header-level documentation.

AXCopyMultipleAttributeOptions

typedef UInt32 AXCopyMultipleAttributeOptions;

Availability

Available in OS X v10.4 and later.

Declared In

AXUIElement.h

AXObserverRef

typedef struct __AXObserver *AXObserverRef;

Discussion

An AXObserverRef is a CFType. Like all CFTypes, they are reference counted (CFRetain, CFRelease).

Availability

Available in OS X v10.2 and later.

Declared In

AXUIElement.h

AXUIElementRef

A structure used to refer to an accessibility object.

typedef const struct __AXUIElement *AXUIElementRef;

Discussion

An accessibility object provides information about the user interface object it represents. This information includes the object's position in the accessibility hierarchy, its position on the display, details about what it is, and what actions it can perform. Accessibility objects respond to messages sent by assistive applications and send notifications that describe state changes.

Availability

Available in OS X v10.2 and later.

Declared In

AXUIElement.h

Constants

See the Overview section above for header-level documentation.

kAXCopyMultipleAttributeOptionStopOnError

enum {
   kAXCopyMultipleAttributeOptionStopOnError = 0x1
};

Discussion

Pass this option to AXUIElementCopyMultipleAttributeValues to force the function to stop when it gets an error.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.