Mac Developer Library

Developer

AXUIElement.h Reference

Options
Deployment Target:

On This Page
Language:

AXUIElement.h Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import ApplicationServices

Objective-C

@import ApplicationServices;

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 Programming Guide for OS X.

Included Headers

  • <AvailabilityMacros.h>

  • <CoreFoundation/CoreFoundation.h>

  • <ApplicationServices/ApplicationServices.h>

Functions

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

    Declaration

    Swift

    func AXObserverAddNotification(_ observer: AXObserver!, _ element: AXUIElement!, _ notification: CFString!, _ refcon: UnsafeMutablePointer<Void>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func AXObserverCreate(_ application: pid_t, _ callback: AXObserverCallback, _ outObserver: UnsafeMutablePointer<Unmanaged<AXObserver>?>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Creates a new observer that can receive notifications with an information dictionary from the specified application.

    Declaration

    Swift

    func AXObserverCreateWithInfoCallback(_ application: pid_t, _ callback: AXObserverCallbackWithInfo, _ outObserver: UnsafeMutablePointer<Unmanaged<AXObserver>?>) -> AXError

    Objective-C

    AXError AXObserverCreateWithInfoCallback ( pid_t application, AXObserverCallbackWithInfo 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, AXObserverCreateWithInfoCallback 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 AXObserverCallbackWithInfo.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.9 and later.

  • Returns the observer's run loop source.

    Declaration

    Swift

    func AXObserverGetRunLoopSource(_ observer: AXObserver!) -> Unmanaged<CFRunLoopSource>!

    Objective-C

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Returns the unique type identifier for the AXObserverRef type.

    Declaration

    Swift

    func AXObserverGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID AXObserverGetTypeID ( void );

    Return Value

    Returns the CFTypeID of the AXObserverRef type.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func AXObserverRemoveNotification(_ observer: AXObserver!, _ element: AXUIElement!, _ notification: CFString!) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • AXAPIEnabled AXAPIEnabled (OS X v10.9)

    Returns whether the accessibility API is enabled.

    Declaration

    Objective-C

    Boolean AXAPIEnabled ( void );

    Return Value

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

  • Returns whether the current process is a trusted accessibility client.

    Declaration

    Swift

    func AXIsProcessTrusted() -> Boolean

    Objective-C

    Boolean AXIsProcessTrusted ( void );

    Return Value

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

  • Returns whether the current process is a trusted accessibility client.

    Declaration

    Swift

    func AXIsProcessTrustedWithOptions(_ options: CFDictionary!) -> Boolean

    Objective-C

    Boolean AXIsProcessTrustedWithOptions ( CFDictionaryRef options );

    Parameters

    options

    A dictionary of options, or NULL to specify no options. The following options are available:

    KEY: kAXTrustedCheckOptionPrompt VALUE: ACFBooleanRef indicating whether the user will be informed if the current process is untrusted. This could be used, for example, on application startup to always warn a user if accessibility is not enabled for the current process. Prompting occurs asynchronously and does not affect the return value.

    Return Value

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.9 and later.

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

    Declaration

    Objective-C

    AXError AXMakeProcessTrusted ( CFStringRef executablePath );

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.4 and later.

    Deprecated in OS X v10.9.

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

    Declaration

    Swift

    func AXUIElementCopyActionDescription(_ element: AXUIElement!, _ action: CFString!, _ description: UnsafeMutablePointer<Unmanaged<CFString>?>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func AXUIElementCopyActionNames(_ element: AXUIElement!, _ names: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func AXUIElementCopyAttributeNames(_ element: AXUIElement!, _ names: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func AXUIElementCopyAttributeValue(_ element: AXUIElement!, _ attribute: CFString!, _ value: UnsafeMutablePointer<Unmanaged<AnyObject>?>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func AXUIElementCopyAttributeValues(_ element: AXUIElement!, _ attribute: CFString!, _ index: CFIndex, _ maxValues: CFIndex, _ values: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func AXUIElementCopyElementAtPosition(_ application: AXUIElement!, _ x: Float, _ y: Float, _ element: UnsafeMutablePointer<Unmanaged<AXUIElement>?>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Returns the values of multiple attributes in the accessibility object.

    Declaration

    Swift

    func AXUIElementCopyMultipleAttributeValues(_ element: AXUIElement!, _ attributes: CFArray!, _ options: AXCopyMultipleAttributeOptions, _ values: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> AXError

    Objective-C

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

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func AXUIElementCopyParameterizedAttributeNames(_ element: AXUIElement!, _ names: UnsafeMutablePointer<Unmanaged<CFArray>?>) -> AXError

    Objective-C

    AXError AXUIElementCopyParameterizedAttributeNames ( AXUIElementRef element, CFArrayRef *names );

    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

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func AXUIElementCopyParameterizedAttributeValue(_ element: AXUIElement!, _ parameterizedAttribute: CFString!, _ parameter: AnyObject!, _ result: UnsafeMutablePointer<Unmanaged<AnyObject>?>) -> AXError

    Objective-C

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

    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

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func AXUIElementCreateApplication(_ pid: pid_t) -> Unmanaged<AXUIElement>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Returns an accessibility object that provides access to system attributes.

    Declaration

    Swift

    func AXUIElementCreateSystemWide() -> Unmanaged<AXUIElement>!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func AXUIElementGetAttributeValueCount(_ element: AXUIElement!, _ attribute: CFString!, _ count: UnsafeMutablePointer<CFIndex>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Returns the process ID associated with the specified accessibility object.

    Declaration

    Swift

    func AXUIElementGetPid(_ element: AXUIElement!, _ pid: UnsafeMutablePointer<pid_t>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Returns the unique type identifier for the AXUIElementRef type.

    Declaration

    Swift

    func AXUIElementGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID AXUIElementGetTypeID ( void );

    Return Value

    Returns a CFTypeID representing the AXUIElementRef type.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

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

    Declaration

    Swift

    func AXUIElementIsAttributeSettable(_ element: AXUIElement!, _ attribute: CFString!, _ settable: UnsafeMutablePointer<Boolean>) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Requests that the specified accessibility object perform the specified action.

    Declaration

    Swift

    func AXUIElementPerformAction(_ element: AXUIElement!, _ action: CFString!) -> AXError

    Objective-C

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Posts keys to the specified application.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.9.

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

    Declaration

    Swift

    func AXUIElementSetAttributeValue(_ element: AXUIElement!, _ attribute: CFString!, _ value: AnyObject!) -> AXError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Sets the timeout value used in the accessibility API.

    Declaration

    Swift

    func AXUIElementSetMessagingTimeout(_ element: AXUIElement!, _ timeoutInSeconds: Float) -> AXError

    Objective-C

    AXError AXUIElementSetMessagingTimeout ( AXUIElementRef element, float timeoutInSeconds );

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

Callbacks

  • Declaration

    Swift

    typealias AXObserverCallback = CFunctionPointer<((AXObserver!, AXUIElement!, CFString!, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • Declaration

    Swift

    typealias AXObserverCallbackWithInfo = CFunctionPointer<((AXObserver!, AXUIElement!, CFString!, CFDictionary!, UnsafeMutablePointer<Void>) -> Void)>

    Objective-C

    typedef void ( *AXObserverCallbackWithInfo)( AXObserverRef observer, AXUIElementRef element, CFStringRef notification, CFDictionaryRef info, void *refcon);

    Parameters

    observer

    An AXObserverRef object to observe the notifications.

    element

    The accessibility object.

    notification

    The name of the notification to observe.

    info

    The coresponding notification information.

    refcon

    Application-defined data specified when registering the observer for notification

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.9 and later.

Data Types

See the Overview section above for header-level documentation.

  • Declaration

    Swift

    typealias AXCopyMultipleAttributeOptions = UInt32

    Objective-C

    typedef UInt32 AXCopyMultipleAttributeOptions;

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Swift

    typealias AXObserverRef = AXObserver

    Objective-C

    typedef struct __AXObserver *AXObserverRef;

    Discussion

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

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

  • A structure used to refer to an accessibility object.

    Declaration

    Swift

    typealias AXUIElementRef = AXUIElement

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ApplicationServices;

    Swift

    import ApplicationServices

    Availability

    Available in OS X v10.2 and later.

Constants

See the Overview section above for header-level documentation.