ADC Home > Reference Library > Reference > User Experience > Accessibility > Accessibility (ApplicationServices/HIServices) Reference
|
AXUIElement.h |
Includes: | <AvailabilityMacros.h> <CoreFoundation/CoreFoundation.h> <ApplicationServices/ApplicationServices.h> |
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
kAXErrorIllegalArgument
kAXErrorCannotComplete
kAXErrorAPIDisabled
API
- AXObserverAddNotification
Registers the specified observer to receive notifications from the specified accessibility object.
- AXObserverCallback
- AXObserverCreate
Creates a new observer that can receive notifications from the specified application.
- AXObserverGetRunLoopSource
Returns the observer's run loop source.
- AXObserverGetTypeID
Returns the unique type identifier for the AXObserverRef type.
- AXObserverRef
- AXObserverRemoveNotification
Removes the specified notification from the list of notifications the observer wants to receive from the accessibility object.
Returns whether the accessibility API is enabled.
Returns whether the current process is a trusted accessibility client.
Attempts to make the process represented by the specified path a trusted accessibility client.
Registers the specified observer to receive notifications from the specified accessibility object.
Creates a new observer that can receive notifications from the specified application.
Returns the observer's run loop source.
Returns the unique type identifier for the AXObserverRef type.
Removes the specified notification from the list of notifications the observer wants to receive from the accessibility object.
Returns a localized description of the specified accessibility object's action.
Returns a list of all the actions the specified accessibility object can perform.
Returns a list of all the attributes supported by the specified accessibility object.
Returns the value of an accessibility object's attribute.
Returns an array of attribute values for the accessibility object's attribute, starting at the specified index.
Returns the accessibility object at the specified position in top-left relative screen coordinates.
Returns the values of multiple attributes in the accessibility object.
Returns a list of all the parameterized attributes supported by the specified accessibility object.
Returns the value of an accessibility object's parameterized attribute.
Creates and returns the top-level accessibility object for the application with the specified process ID.
Returns an accessibility object that provides access to system attributes.
Returns the count of the array of an accessibility object's attribute value.
Returns the process ID associated with the specified accessibility object.
Returns the unique type identifier for the AXUIElementRef type.
Returns whether the specified accessibility object's attribute can be modified.
Requests that the specified accessibility object perform the specified action.
Posts keys to the specified application.
Sets the accessibility object's attribute to the specified value.
Sets the timeout value used in the accessibility API.
AXAPIEnabled |
Returns whether the accessibility API is enabled.
extern Boolean AXAPIEnabled ();
Returns TRUE if the accessibility API is currently enabled, otherwise FALSE.
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.
AXIsProcessTrusted |
Returns whether the current process is a trusted accessibility client.
extern Boolean AXIsProcessTrusted ();
Returns TRUE if the current process is a trusted accessibility client, FALSE if it is not.
AXMakeProcessTrusted |
Attempts to make the process represented by the specified path a trusted accessibility client.
extern AXError AXMakeProcessTrusted ( CFStringRef executablePath);
executablePath
The path to the executable of the process to make trusted.
An AXError that indicates success or failure.
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.
AXObserverAddNotification |
Registers the specified observer to receive notifications from the specified accessibility object.
extern AXError AXObserverAddNotification ( AXObserverRef observer, AXUIElementRef element, CFStringRef notification, void *refcon);
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.
If unsuccessful, AXObserverAddNotification
may return one of the following error codes, among others:
kAXErrorInvalidUIElementObserver
kAXErrorIllegalArgument
kAXErrorNotificationUnsupported
kAXErrorNotificationAlreadyRegistered
kAXErrorCannotComplete
kAXErrorFailure
AXObserverCreate |
Creates a new observer that can receive notifications from the specified application.
extern AXError AXObserverCreate ( pid_t application, AXObserverCallback callback, AXObserverRef *outObserver);
application
The process ID of the application.
callback
The callback function.
outObserver
On return, an AXObserverRef representing the observer object.
If unsuccessful, AXObserverCreate
may return one of the following error codes, among others:
kAXErrorIllegalArgument
kAXErrorFailure
When an observed notification is received, it is passed to AXObserverCallback.
AXObserverGetRunLoopSource |
Returns the observer's run loop source.
extern CFRunLoopSourceRef AXObserverGetRunLoopSource ( AXObserverRef observer);
observer
The observer object (created from a call to AXObserverCreate) for which to get the run loop source.
Returns the CFRunLoopSourceRef of the observer; NIL if you pass NIL in observer
.
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);
AXObserverGetTypeID |
Returns the unique type identifier for the AXObserverRef type.
CFTypeID AXObserverGetTypeID ( void);
Returns the CFTypeID of the AXObserverRef type.
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);
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.
If unsuccessful, AXObserverRemoveNotification
may return one of the following error codes, among others:
kAXErrorInvalidUIElementObserver
kAXErrorIllegalArgument
kAXErrorNotificationUnsupported
kAXErrorNotificationNotRegistered
kAXErrorCannotComplete
kAXErrorFailure
AXUIElementCopyActionDescription |
Returns a localized description of the specified accessibility object's action.
extern AXError AXUIElementCopyActionDescription ( AXUIElementRef element, CFStringRef action, CFStringRef *description);
element
The AXUIElementRef representing the accessibility object.
action
The action to be described.
description
On return, a string containing the description of the action.
If unsuccessful, AXUIElementCopyActionDescription
may return one of the following error codes, among others:
kAXErrorActionUnsupported
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
kAXErrorCannotComplete
kAXErrorNotImplemented
AXUIElementCopyActionNames |
Returns a list of all the actions the specified accessibility object can perform.
extern AXError AXUIElementCopyActionNames ( AXUIElementRef element, CFArrayRef *names);
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).
If unsuccessful, AXUIElementCopyActionNames
may return one of the following error codes, among others:
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
kAXErrorFailure
kAXErrorCannotComplete
kAXErrorNotImplemented
AXUIElementCopyAttributeNames |
Returns a list of all the attributes supported by the specified accessibility object.
extern AXError AXUIElementCopyAttributeNames ( AXUIElementRef element, CFArrayRef *names);
element
The AXUIElementRef representing the accessibility object.
names
On return, an array containing the accessibility object's attribute names.
If unsuccessful, AXUIElementCopyAttributeNames
may return one of the following error codes, among others:
kAXErrorAttributeUnsupported
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
kAXErrorFailure
kAXErrorCannotComplete
kAXErrorNotImplemented
AXUIElementCopyAttributeValue |
Returns the value of an accessibility object's attribute.
extern AXError AXUIElementCopyAttributeValue ( AXUIElementRef element, CFStringRef attribute, CFTypeRef *value);
element
The AXUIElementRef representing the accessibility object.
attribute
The attribute name.
value
On return, the value associated with the specified attribute.
If unsuccessful, AXUIElementCopyAttributeValue
may return one of the following error codes, among others:
kAXErrorAttributeUnsupported
kAXErrorNoValue
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
kAXErrorCannotComplete
kAXErrorNotImplemented
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);
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.
If unsuccessful, AXUIElementCopyAttributeValues
may return one of the following error codes, among others:
kAXErrorIllegalArgument
index
or maxValues
arguments are outside the array's range, or one of the other arguments is an illegal value.kAXErrorNoValue
kAXErrorInvalidUIElement
kAXErrorCannotComplete
kAXErrorNotImplemented
This function is useful for dealing with large arrays, for example, a table view with a large number of children.
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);
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.
If unsuccessful, AXUIElementCopyElementAtPosition
may return one of the following error codes, among others:
kAXErrorNoValue
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
kAXErrorCannotComplete
kAXErrorNotImplemented
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.
AXUIElementCopyMultipleAttributeValues |
Returns the values of multiple attributes in the accessibility object.
extern AXError AXUIElementCopyMultipleAttributeValues ( AXUIElementRef element, CFArrayRef attributes, AXCopyMultipleAttributeOptions options, CFArrayRef *values);
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.
If unsuccessful, AXUIElementCopyMultipleAttributeValues
may return one of the following error codes, among others:
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
kAXErrorCannotComplete
kAXErrorNotImplemented
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.
AXUIElementCopyParameterizedAttributeNames |
Returns a list of all the parameterized attributes supported by the specified accessibility object.
extern AXError AXUIElementCopyParameterizedAttributeNames ( AXUIElementRef element, CFArrayRef *names);
element
The AXUIElementRef representing the accessibility object.
names
On return, an array containing the accessibility object's parameterized attribute names.
If unsuccessful, AXUIElementCopyParameterizedAttributeNames
may return one of the following error codes, among others:
kAXErrorAttributeUnsupported
or kAXErrorParameterizedAttributeUnsupported
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
kAXErrorFailure
kAXErrorCannotComplete
kAXErrorNotImplemented
AXUIElementCopyParameterizedAttributeValue |
Returns the value of an accessibility object's parameterized attribute.
extern AXError AXUIElementCopyParameterizedAttributeValue ( AXUIElementRef element, CFStringRef parameterizedAttribute, CFTypeRef parameter, CFTypeRef *result);
element
The AXUIElementRef representing the accessibility object.
parameterizedAttribute
The parameterized attribute.
parameter
The parameter.
result
On return, the value of the parameterized attribute.
If unsuccessful, AXUIElementCopyParameterizedAttributeValue
may return one of the following error codes, among others:
kAXErrorAttributeUnsupported
or kAXErrorParameterizedAttributeUnsupported
kAXErrorNoValue
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
kAXErrorCannotComplete
kAXErrorNotImplemented
AXUIElementCreateApplication |
Creates and returns the top-level accessibility object for the application with the specified process ID.
extern AXUIElementRef AXUIElementCreateApplication ( pid_t pid);
pid
The process ID of an application.
The AXUIElementRef representing the top-level accessibility object for the application with the specified process ID.
AXUIElementCreateSystemWide |
Returns an accessibility object that provides access to system attributes.
extern AXUIElementRef AXUIElementCreateSystemWide ( void);
The AXUIElementRef representing the system-wide accessibility object.
This is useful for things like finding the focused accessibility object regardless of which application is currently active.
AXUIElementGetAttributeValueCount |
Returns the count of the array of an accessibility object's attribute value.
extern AXError AXUIElementGetAttributeValueCount ( AXUIElementRef element, CFStringRef attribute, CFIndex *count);
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.
If unsuccessful, AXUIElementGetAttributeValueCount
may return one of the following error codes, among others:
kAXErrorIllegalArgument
kAXErrorAttributeUnsupported
kAXErrorInvalidUIElement
kAXErrorCannotComplete
kAXErrorNotImplemented
AXUIElementGetPid |
Returns the process ID associated with the specified accessibility object.
extern AXError AXUIElementGetPid ( AXUIElementRef element, pid_t *pid);
element
The AXUIElementRef representing an accessibility object.
pid
On return, the process ID associated with the specified accessibility object.
If unsuccessful, AXUIElementGetPid
may return one of the following error codes, among others:
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
AXUIElementGetTypeID |
Returns the unique type identifier for the AXUIElementRef type.
extern CFTypeID AXUIElementGetTypeID ( void);
Returns a CFTypeID representing the AXUIElementRef type.
AXUIElementIsAttributeSettable |
Returns whether the specified accessibility object's attribute can be modified.
extern AXError AXUIElementIsAttributeSettable ( AXUIElementRef element, CFStringRef attribute, Boolean *settable);
element
The AXUIElementRef representing the accessibility object.
attribute
The attribute name.
settable
On return, a Boolean value indicating whether the attribute is settable.
If unsuccessful, AXUIElementIsAttributeSettable
may return one of the following error codes, among others:
kAXErrorCannotComplete
kAXErrorIllegalArgument
kAXErrorAttributeUnsupported
kAXErrorNoValue
kAXErrorInvalidUIElement
kAXErrorNotImplemented
If you receive a kAXErrorCannotComplete
error from this function, you might want to repeat the request or change the timeout value.
AXUIElementPerformAction |
Requests that the specified accessibility object perform the specified action.
extern AXError AXUIElementPerformAction ( AXUIElementRef element, CFStringRef action);
element
The AXUIElementRef representing the accessibility object.
action
The action to be performed.
If unsuccessful, AXUIElementPerformAction
may return one of the following error codes, among others:
kAXErrorActionUnsupported
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
kAXErrorCannotComplete
kAXErrorNotImplemented
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).
AXUIElementPostKeyboardEvent |
Posts keys to the specified application.
extern AXError AXUIElementPostKeyboardEvent ( AXUIElementRef application, CGCharCode keyChar, CGKeyCode virtualKey, Boolean keyDown);
application
The AXUIElementRef representing the application (or the system-wide accessibility object).
keyChar
virtualKey
keyDown
If unsuccessful, AXUIElementPostKeyboardEvent
may return one of the following error codes, among others:
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
kAXErrorFailure
kAXErrorCannotComplete
kAXErrorNotImplemented
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.
AXUIElementSetAttributeValue |
Sets the accessibility object's attribute to the specified value.
extern AXError AXUIElementSetAttributeValue ( AXUIElementRef element, CFStringRef attribute, CFTypeRef value);
element
The AXUIElementRef representing the accessibility object.
attribute
The attribute name.
value
The new value for the attribute.
If unsuccessful, AXUIElementSetAttributeValue
may return one of the following error codes, among others:
kAXErrorIllegalArgument
kAXErrorAttributeUnsupported
kAXErrorInvalidUIElement
kAXErrorCannotComplete
kAXErrorNotImplemented
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.
AXUIElementSetMessagingTimeout |
Sets the timeout value used in the accessibility API.
extern AXError AXUIElementSetMessagingTimeout ( AXUIElementRef element, float timeoutInSeconds);
element
The AXUIElementRef representing an accessibility object.
timeoutInSeconds
The number of seconds for the new timeout value.
If unsuccessful, AXUIElementSetMessagingTimeout
may return one of the following error codes, among others:
kAXErrorIllegalArgument
kAXErrorInvalidUIElement
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.
AXCopyMultipleAttributeOptions |
typedef UInt32 AXCopyMultipleAttributeOptions;
AXObserverCallback |
typedef void ( *AXObserverCallback)( AXObserverRef observer, AXUIElementRef element, CFStringRef notification, void *refcon);
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
AXObserverRef |
typedef struct __AXObserver *AXObserverRef;
An AXObserverRef is a CFType. Like all CFTypes, they are reference counted (CFRetain, CFRelease).
AXUIElementRef |
A structure used to refer to an accessibility object.
typedef const struct __AXUIElement *AXUIElementRef;
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.
kAXCopyMultipleAttributeOptionStopOnError |
enum { kAXCopyMultipleAttributeOptionStopOnError = 0x1 };
Pass this option to AXUIElementCopyMultipleAttributeValues to force the function to stop when it gets an error.
|
Last Updated: 2008-08-07