PFUIElement

Conforms to:
NSCopying
Superclass:
NSObject
Declared In:

Introduction

A concrete class representing a UI element in a running application.

Discussion

A PFUIElement object represents a UI element on the screen in a running application, such as a menu, window or button. The PFApplicationUIElement subclass represents a root-level UI element—either an application or the system-wide element representing all running applications.

The PFUIElement class implements all of the functionality of the accessibility API's AXUIElementRef object. A PFApplicationUIElement subclass implements additional AXUIElementRef functionality relating to the root application element and the system-wide element. PFUIElement objects fully support the accessibility API's actions, attributes, keystrokes and notifications. A client application can get the value of a PFUIElement object's attributes, set the value of its settable attributes, and perform any actions it supports. It can send keystrokes, including keyboard shortcuts, to the target application to control its focused UI element. And, by creating a PFObserver object, it can observe any application or UI element and receive notifications when changes occur.

In this documentation, depending on context, "UI element" or "element" may refer either to a programmatic PFUIElement or PFApplicationUIElement object or to the user interface object in the running application that is represented by a PFUIElement or PFApplicationUIElement object. References to a "PFUIElement object" generally include a PFApplicationUIElement object, since the PFApplicationUIElement class is a subclass of PFUIElement.

An application's UI elements are organized in a tree-like containment hierarchy of PFUIElement objects, with the root application element on one end and leaf elements on the screen such as buttons and checkboxes on the other. A target application's hierarchy can be navigated in either direction by traversing any element's parent and children. An application's individual elements can be read by getting their attributes, and in many cases they can be controlled by setting their attributes and performing actions on them and by sending keystrokes to the application. Methods are provided to obtain the application's root element given its path or its process identification number (PID) as an entry point into the tree, or, alternatively, to read the screen to obtain the root UI element of whatever application currently has a user interface object at a specified point on the screen.

UI elements have attributes and, in many cases, actions identified by a key, a string that usually begins with the prefix "AX" as in "AXRole" or "AXPress". In a client assistive application, you normally use the NSString constants declared in the NSAccessibility informal protocol (in NSAccessibility.h, in the Cocoa AppKit framework). Alternatively, you can use the corresponding CFStringRef constants declared in the accessibility API headers and cast them to NSString*, or use the strings themselves. Some constants are omitted from NSAccessibility.h or from the accessibility API headers; if you can't find a desired constant in one of these headers, use a constant from the other header or the string itself. Note that some constants in these headers may be marked as obsolete; use only the non-obsolete constants or their string equivalents to maximize compatibility with future releases of macOS. (Most of the constants in the NSAccessibility informal protocol were deprecated in OS X Yosemite 10.10 in favor of the new formal protocols in NSAccessibilityProtocols.h. However, the deprecation was intended to apply to the way regular applications make their UI elements accessible, which is shifting from the old key-based approach to the new method-based protocol. Assistive applications should still use the key-based constants.)

Some applications, such as the Finder and Safari, implement custom UI elements with custom actions and attributes that are not part of Apple's accessibility API. This framework is written so that you can read and manipulate them as well as Apple's built-in accessibility API actions and attributes. You may be able to identify the strings used to identify custom actions and attributes by reading an application's documentation or by examining the .strings files in its application bundle. You will find it much easier, however, to use UI Browser, available from PreForm Assistive Technologies, LLC at pfiddlesoft.com/uibrowser.

Many methods return PFUIElement or PFApplicationUIElement objects. Think of these methods as factories that can be called upon to churn out these objects as often as needed, whenever needed, even if you use them only for a moment. Separate PFUIElement or PFApplicationUIElement objects representing the same UI element in the running application are interchangeable. Whether they represent the same element can be tested using -isEqual: or -isEqualToElement:. Whether the element still exists in the running application can be tested using -exists or -isDestroyed . It is prudent to test whether an element still exists before using it, because objects representing destroyed elements may be nil or may have been recycled to refer to other elements, leading to unexpected behavior.

Clients may subclass PFUIElement for applications that also subclass PFApplicationUIElement, by registering the PFUIElement subclass for the application's PID using the methods described in the discussion of PFApplicationUIElement subclassing.

Before a client application can make use of this class in OS X Mavericks 10.9 or newer, access must be granted to it using the new per-application trust mechanism in the Accessibility list in the Security & Privacy preference's Privacy pane in System Preferences. Global access and the old per-application trust mechanism no longer work in Mavericks or newer. In OS X Mountain Lion 10.8 and older, the global "Enable access for assistive devices" setting in the Accessibility (or Universal Access) pane of System Preferences must be turned on, or the client application must be made a trusted process through use of the accessibility API's AXMakeProcessTrusted() function. Authentication may be required. See +isProcessTrustedWithOptions: for details.



Groups

INITIALIZATION

Group members:

-initWithElementRef:delegate:

Initializes and returns a newly allocated PFUIElement object.

-invalidate

Invalidates this PFUIElement object when it is no longer needed.

-isValid

Reports whether this PFUIElement object has been initialized and has not been invalidated.

+UIElementWithElementRef:delegate:

Convenience class method creates and returns an initialized PFUIElement object.

 

ATTRIBUTE UTILITIES

Group members:

+attributeDefinitions

Class method returns an NSDictionary object containing information about all accessibility attributes.

-attributedStringFromAXAttributedString:

Returns an attributed string suitable for display in a text view, converted from an accessibility attributed string.

+attributesForRole:andSubrole:

Class method returns an NSArray of NSDictionary objects containing information about all accessibility attributes that may or should be supported by a UI element with the specified role and subrole.

-childrenCount

Returns the number of children the receiver contains.

-countForAttribute:

Returns the number of items in the specified attribute of the receiver if the attribute is an array.

-descriptionForAttribute:

Returns a localized string describing attribute, suitable for display or speech.

-descriptionForSubrole:

Returns a localized string describing subrole, suitable for display or speech.

-descriptionOfTypeForAttribute:

Returns a localized string describing the data type of attribute, suitable for display or speech.

-existsAttribute:

Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute.

-existsNonParameterizedAttribute:

Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute as a non-parameterized attribute.

-existsParameterizedAttribute:

Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute as a parameterized attribute.

-existsValueForAttribute:

Returns whether the UI element represented by the receiver still exists in the running application, recognizes attribute, and attribute has a value.

-isParameterizedAttribute:

Returns whether attribute is a parameterized attribute.

-isRole:

Returns whether the receiver represents a UI element whose AXRole attribute is role.

-isSettableAttribute:

Returns whether attribute can be modified.

+roleDefinitions

Class method returns an NSDictionary object containing information about all accessibility attribute roles and subroles.

-setValue:forAttribute:

Sets the value of attribute to object.

-typeForAttribute:

Returns a non-localized string for the data type of the value of attribute.

-valueForAttribute:

Returns the value of attribute.

-valueForAttribute:atIndex:

Returns the value of the item at index in the array returned by attribute.

-valueForAttribute:parameter:

Returns the value of attribute for parameter.

-valuesForAttribute:range:

Returns the values of attributes in range.

-valuesForAttributes:

Returns the values of attributes.

 

INSTANCE UTILITIES

Group members:

-activateApplication

Brings the element's application to the front, returning YES if successful or if the application was already frontmost.

 

ATTRIBUTES

Group members:

-attributes

Returns an array of the technical, non-localized names of all attributes recognized by the receiver.

-nonParameterizedAttributes

Returns the technical, non-localized names of all non-parameterized attributes recognized by the receiver.

-parameterizedAttributes

Returns the technical, non-localized names of all parameterized attributes recognized by the receiver.

 

CLASS UTILITIES

Group members:

+isAccessEnabled

Class method reports whether global access for assistive devices is enabled. DEPRECATED in OS X Mavericks 10.9.

+isAccessImplemented

Class method reports whether the accessibility API is implemented on this computer.

+isProcessTrusted

Class method reports whether the client application's process is trusted.

+isProcessTrustedWithOptions:

Class method reports whether the client application's process is trusted, optionally presenting an alert allowing the user to grant or deny access if it is not already trusted. Introduced in OS X Mavericks 10.9.

 

DEBUGGING UTILITIES

Group members:

-description

Returns a string describing the receiver.

 

UI ELEMENTS

Group members:

-elementInfo

Returns information about the receiver that was cached when the receiver was created, and that may have been modified later.

-elementRef

Returns the accessibility API AXUIElementRef opaque object that was associated with the receiver when the receiver was created.

-isDestroyed

Returns whether the element has been destroyed.

-setElementInfo:

Caches information about the receiver.

-setElementRef:

Sets the receiver's accessibility API AXUIElementRef opaque object to ref.

 

NOTIFICATIONS

Group members:

-notifications

Returns the technical, non-localized names of all notifications issued by the receiver.

 

ACTION UTILITIES

Group members:

+actionDefinitions

Class method returns an NSDictionary object containing information about all accessibility actions.

+actionsForRole:andSubrole:

Class method returns an NSArray containing the technical names of all accessibility actions that should be supported by a UI element with the specified role and subrole.

-descriptionForAction:

Returns a localized string describing action, suitable for display or speech.

-existsAction:

Returns whether the receiver still exists in the running application and can perform action.

-performAction:

Causes the receiver to perform action, returning YES if successful.

 

ACTIONS

Group members:

-actions

Returns the technical, non-localized names of all actions implemented by the receiver.

 

NOTIFICATION UTILITIES

Group members:

+descriptionForNotification:

Class method returns a localized string describing notification, suitable for display or speech.

+notificationDefinitions

Class method returns an NSDictionary object containing information about all accessibility notifications.

+notifications

Class method returns the technical, non-localized names of all notifications recognized by the accessibility API in the currently-running version of macOS.

+notificationsForRole:andSubrole:

Class method returns an NSArray containing the technical names of all accessibility notifications that should be supported by a UI element with the specified role and subrole.

 

DELEGATE ACCESSORS

Group members:

-delegate

Returns the receiver's delegate.

-setDelegate:

Sets the receiver's delegate to object.

 

UI ELEMENT UTILITIES

Group members:

-applicationElement

Creates and returns a root application UI element object representing the application owning the receiver.

-clippedRect

Returns an NSRect structure representing the origin and size of the portion of the receiver that is visible in its container.

+elementAtPoint:withDelegate:error:

Class method creates and returns a PFUIElement object representing the visible UI element located at point on the screen, no matter what application owns it.

+elementsWithRole:inArray:

Class method returns all PFUIElement objects having attribute role in array.

-exists

Returns whether the UI element represented by the receiver still exists in the running application.

+firstElementWithRole:inArray:

Class method returns the first PFUIElement object with attribute role in array.

-indexAmongLikeElementsInArray:

Returns the index of the receiver among all UI elements in array having the same role as the receiver, or NSNotFound if the receiver is not in array.

-indexPath

Returns an NSIndexPath object reflecting the accessibility hierarchy of UI elements from the root application element to and including the receiver.

-isEqualToElement:

Returns whether element and the receiver represent the same UI element in the target application.

-isSiblingOfElement:

Returns whether element and the receiver have the same parent.

-isVisibleAtPoint:

Returns whether the UI element represented by the receiver is visible at point on the screen.

-parentIndexPath

Returns an NSIndexPath object reflecting the accessibility hierarchy of UI elements from the root application element to the receiver's parent, but not the receiver itself.

-parentPath

Returns an array of PFUIElement objects reflecting the accessibility hierarchy of UI elements from the root application element to the receiver's parent, but not the receiver itself.

-path

Returns an array of PFUIElement objects reflecting the accessibility hierarchy of UI elements from the root application element to and including the receiver.

-pid

Returns the BSD Unix process identification number (PID) of the application owning the receiver.

-setExists:

Sets whether the receiver exists in the running application to flag.

-setMessagingTimeout:

Sets the receiver's timeout to timeoutInSeconds.


Methods

+actionDefinitions

Class method returns an NSDictionary object containing information about all accessibility actions.

-actions

Returns the technical, non-localized names of all actions implemented by the receiver.

+actionsForRole:andSubrole:

Class method returns an NSArray containing the technical names of all accessibility actions that should be supported by a UI element with the specified role and subrole.

-activateApplication

Brings the element's application to the front, returning YES if successful or if the application was already frontmost.

-applicationElement

Creates and returns a root application UI element object representing the application owning the receiver.

+attributeDefinitions

Class method returns an NSDictionary object containing information about all accessibility attributes.

-attributedStringFromAXAttributedString:

Returns an attributed string suitable for display in a text view, converted from an accessibility attributed string.

-attributes

Returns an array of the technical, non-localized names of all attributes recognized by the receiver.

+attributesForRole:andSubrole:

Class method returns an NSArray of NSDictionary objects containing information about all accessibility attributes that may or should be supported by a UI element with the specified role and subrole.

-childrenCount

Returns the number of children the receiver contains.

-clippedRect

Returns an NSRect structure representing the origin and size of the portion of the receiver that is visible in its container.

-countForAttribute:

Returns the number of items in the specified attribute of the receiver if the attribute is an array.

-delegate

Returns the receiver's delegate.

-description

Returns a string describing the receiver.

-descriptionForAction:

Returns a localized string describing action, suitable for display or speech.

-descriptionForAttribute:

Returns a localized string describing attribute, suitable for display or speech.

+descriptionForNotification:

Class method returns a localized string describing notification, suitable for display or speech.

-descriptionForSubrole:

Returns a localized string describing subrole, suitable for display or speech.

-descriptionOfTypeForAttribute:

Returns a localized string describing the data type of attribute, suitable for display or speech.

+elementAtPoint:withDelegate:error:

Class method creates and returns a PFUIElement object representing the visible UI element located at point on the screen, no matter what application owns it.

-elementInfo

Returns information about the receiver that was cached when the receiver was created, and that may have been modified later.

-elementRef

Returns the accessibility API AXUIElementRef opaque object that was associated with the receiver when the receiver was created.

+elementsWithRole:inArray:

Class method returns all PFUIElement objects having attribute role in array.

-exists

Returns whether the UI element represented by the receiver still exists in the running application.

-existsAction:

Returns whether the receiver still exists in the running application and can perform action.

-existsAttribute:

Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute.

-existsNonParameterizedAttribute:

Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute as a non-parameterized attribute.

-existsParameterizedAttribute:

Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute as a parameterized attribute.

-existsValueForAttribute:

Returns whether the UI element represented by the receiver still exists in the running application, recognizes attribute, and attribute has a value.

+firstElementWithRole:inArray:

Class method returns the first PFUIElement object with attribute role in array.

-indexAmongLikeElementsInArray:

Returns the index of the receiver among all UI elements in array having the same role as the receiver, or NSNotFound if the receiver is not in array.

-indexPath

Returns an NSIndexPath object reflecting the accessibility hierarchy of UI elements from the root application element to and including the receiver.

-initWithElementRef:delegate:

Initializes and returns a newly allocated PFUIElement object.

-invalidate

Invalidates this PFUIElement object when it is no longer needed.

+isAccessEnabled

Class method reports whether global access for assistive devices is enabled. DEPRECATED in OS X Mavericks 10.9.

+isAccessImplemented

Class method reports whether the accessibility API is implemented on this computer.

-isDestroyed

Returns whether the element has been destroyed.

-isEqualToElement:

Returns whether element and the receiver represent the same UI element in the target application.

-isParameterizedAttribute:

Returns whether attribute is a parameterized attribute.

+isProcessTrusted

Class method reports whether the client application's process is trusted.

+isProcessTrustedWithOptions:

Class method reports whether the client application's process is trusted, optionally presenting an alert allowing the user to grant or deny access if it is not already trusted. Introduced in OS X Mavericks 10.9.

-isRole:

Returns whether the receiver represents a UI element whose AXRole attribute is role.

-isSettableAttribute:

Returns whether attribute can be modified.

-isSiblingOfElement:

Returns whether element and the receiver have the same parent.

-isValid

Reports whether this PFUIElement object has been initialized and has not been invalidated.

-isVisibleAtPoint:

Returns whether the UI element represented by the receiver is visible at point on the screen.

-nonParameterizedAttributes

Returns the technical, non-localized names of all non-parameterized attributes recognized by the receiver.

+notificationDefinitions

Class method returns an NSDictionary object containing information about all accessibility notifications.

-notifications

Returns the technical, non-localized names of all notifications issued by the receiver.

+notifications

Class method returns the technical, non-localized names of all notifications recognized by the accessibility API in the currently-running version of macOS.

+notificationsForRole:andSubrole:

Class method returns an NSArray containing the technical names of all accessibility notifications that should be supported by a UI element with the specified role and subrole.

-parameterizedAttributes

Returns the technical, non-localized names of all parameterized attributes recognized by the receiver.

-parentIndexPath

Returns an NSIndexPath object reflecting the accessibility hierarchy of UI elements from the root application element to the receiver's parent, but not the receiver itself.

-parentPath

Returns an array of PFUIElement objects reflecting the accessibility hierarchy of UI elements from the root application element to the receiver's parent, but not the receiver itself.

-path

Returns an array of PFUIElement objects reflecting the accessibility hierarchy of UI elements from the root application element to and including the receiver.

-performAction:

Causes the receiver to perform action, returning YES if successful.

-pid

Returns the BSD Unix process identification number (PID) of the application owning the receiver.

+roleDefinitions

Class method returns an NSDictionary object containing information about all accessibility attribute roles and subroles.

-setDelegate:

Sets the receiver's delegate to object.

-setElementInfo:

Caches information about the receiver.

-setElementRef:

Sets the receiver's accessibility API AXUIElementRef opaque object to ref.

-setExists:

Sets whether the receiver exists in the running application to flag.

-setMessagingTimeout:

Sets the receiver's timeout to timeoutInSeconds.

-setValue:forAttribute:

Sets the value of attribute to object.

-typeForAttribute:

Returns a non-localized string for the data type of the value of attribute.

+UIElementWithElementRef:delegate:

Convenience class method creates and returns an initialized PFUIElement object.

-valueForAttribute:

Returns the value of attribute.

-valueForAttribute:atIndex:

Returns the value of the item at index in the array returned by attribute.

-valueForAttribute:parameter:

Returns the value of attribute for parameter.

-valuesForAttribute:range:

Returns the values of attributes in range.

-valuesForAttributes:

Returns the values of attributes.


actionDefinitions


Class method returns an NSDictionary object containing information about all accessibility actions.

+ (NSDictionary *)actionDefinitions; 
Return Value

A dictionary containing information about all accessibility actions.

Discussion

This class method returns a dictionary containing the technical names and other features of all accessibility actions as listed in the AccessibilityDefinitions.plist file installed at /System/Library/Accessibility/AccessibilityDefinitions.plist starting with Mac OS X 10.7 (Lion). It reads information from the actions dictionary in the plist file.


actions


Returns the technical, non-localized names of all actions implemented by the receiver.

- (NSArray<NSString *> *)actions; 
Return Value

An array of NSString objects, or an empty array if the receiver does not recognize any actions.

Discussion

The accessibility API implements relatively few actions, and many UI elements do not support any actions at all. Specific applications may implement custom actions, such as the AXOpen action in the Finder, and they are included in the array returned by this method.

Sometimes performing an action and setting an attribute would achieve the same goal. In such cases, Apple generally prefers the action and makes the attribute unsettable. The prime example is checkboxes, whose value you set by sending them an AXPress action.

A client application can test whether a UI element exists and supports a specific action with -existsAction:; it can get a localized description of an action with -descriptionForAction:; and it can perform an action with -performAction:.

The following actions are supported by the accessibility API (obsolete actions are omitted):

  • AXCancel - a cancel action, such as pressing the Cancel button.

  • AXConfirm - a confirm action, such as pressing Return in a text field.

  • AXDecrement - a decrement action, such as pressing a stepper's down arrow.

  • AXIncrement - an increment action, such as pressing a stepper's up arrow.

  • AXPress - a press action, such as clicking a button or a menu.

  • AXRaise - a raise action, such as bringing a window to the front within the application.

  • AXShowMenu - a show menu user action, such as opening a pop-up button's menu or a contextual menu in a text view or text field.

  • AXShowAlternateUI - a show alternate UI action, such as causing a button to appear that is normally hidden, as when the mouse hovers over it.

  • AXShowDefaultUI - a show default UI action, such as causing a button that is normally hidden to hide, as when the mouse stops hovering over it.


actionsForRole:andSubrole:


Class method returns an NSArray containing the technical names of all accessibility actions that should be supported by a UI element with the specified role and subrole.

+ (NSArray<NSString *> *)actionsForRole:(NSString *)role 
        andSubrole:(nullable NSString *)subrole; 
Parameters
role

An NSString representing a UI element role; may be a constant from the NSAccessibility informal protocol or from AXRoleConstants.h in the accessibility API cast to NSString*, or the string itself.

subrole

An NSString representing a UI element subrole, or nil or an empty string if it has no subrole; may be a constant from the NSAccessibility informal protocol or from AXRoleConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An array of NSString objects, or an empty array if a UI element with the specified role and subrole should not support any actions.

Discussion

This class method returns an array listing all of the accessibility actions that a UI element with the specified role and subrole should support. This is general information obtained from the AccessibilityDefinitions.plist file installed at /System/Library/Accessibility/AccessibilityDefinitions.plist starting with Mac OS X 10.7 (Lion). It does not guarantee that any particular UI element does in fact support the actions.

As of OS X Mavericks 10.9, it is not known whether the role_actions array has been fully validated by Apple and is complete.


activateApplication


Brings the element's application to the front, returning YES if successful or if the application was already frontmost.

- (BOOL)activateApplication; 
Discussion

The element's application must be frontmost in order for some PFAssistive framework methods to be used. For example, it is necessary to make an application's menu visible before its menu items can be sent AXPress actions, and menus are not visible when the application is not frontmost. The accessibility API is designed to emulate the experience of a typical user, and UI elements are generally not usable when they are not visible on the screen.

If the application is not a user application, this method calls Application Services functions that were deprecated in OS X Mountain Lion 10.8 and/or OS X Mavericks 10.9 because the corresponding NSRunningApplication methods do not work with system or background applications. Deprecation warnings are suppressed during compilation.

If you call this method, it is your responsibility to return the client application to the front, if appropriate. You can call NSApplication's -activateIgnoringOtherApps: to do this.

[DELETE THIS:] If the target application is background-only, this method returns NO and the current frontmost application is not changed.


applicationElement


Creates and returns a root application UI element object representing the application owning the receiver.

- (nullable PFApplicationUIElement *)applicationElement; 
Return Value

The receiver's root appplication UI element, of class PFApplicationUIElement or a subclass, or nil if the element's PID is 0 (which would be invalid).

Discussion

It is sometimes useful to have a reference to the root application UI element as a PFApplicationUIElement or subclass object, in order to access features that are unique to that subclass of PFUIElement.

To ensure that this method returns an object of the correct class when PFApplicationUIElement is subclassed, an object of the subclass type must be created and initialized, using the PFApplicationUIElement designated initializer or any convenience initializer that calls the designated initializer, before this method is called. The designated initializer registers the subclass for the target application's PID. See the discussion of subclass support in the PFAppliationUIElement class documentation for details.


attributeDefinitions


Class method returns an NSDictionary object containing information about all accessibility attributes.

+ (NSDictionary *)attributeDefinitions; 
Return Value

A dictionary containing information about all accessibility attributes.

Discussion

This class method returns a dictionary containing the technical names and other features of all accessibility attributes as listed in the AccessibilityDefinitions.plist file installed at /System/Library/Accessibility/AccessibilityDefinitions.plist starting with Mac OS X 10.7 (Lion). It reads information from the attributes dictionary in the plist file.


attributedStringFromAXAttributedString:


Returns an attributed string suitable for display in a text view, converted from an accessibility attributed string.

- (NSAttributedString *)
        attributedStringFromAXAttributedString:(NSAttributedString *)AXAttributedString; 
Parameters
AXAttributedString

An NSAttributedString with accessibility text attributes, returned by the -AXAttributedStringForRange: parameterized attribute method.

Return Value

An NSAttributedString object with standard Cocoa text system attributes.

Discussion

The attributed string returned by this method is a standard text system attributed string suitable for display in a text view based on NSTextStorage. It is converted from an accessibility text attributed string passed to it from the -AXAttributedStringForRange: parameterized attribute method. The conversion is lossy, as described below.

Use this method only when you wish to display a reasonable facsimile of the accessibility attributed string. For an assistive application, use the accessibility attributed string and its attributes, instead.

An accessibility text attributed string is an NSAttributedString in the sense that it has a dictionary of attributes and responds to NSAttributedString methods. However, its attributes, declared in AXTextAttributedString.h, differ from the standard text system attributes, and it therefore cannot be used for display without first converting it using this method. An accessibility text attributed string omits many appearance-related attributes of a standard text system attributed string that do not convey meaningful information in the accessibility context, so an attributed string returned by this method may not look identical to the original attributed string in the target application. For example, baseline offset, kerning and ligature information is omitted, and double strikethroughs are not distinguished from single strikethroughs. Other standard text system attributes are included, such as foreground and background color, superscript and subscript, underline, strikethrough, shadow, link, and text attachment. An accessibility text attributed string also includes some attributes that are not recognized by the standard text system, namely, natural language, replacement string, and misspelled string, three list item attributes introduced in OS X El Capitan 10.11, the text alignment attribute introduced in macOS Sierra 10.12, and the language, custom and annotation attributes introduced in macOS High Sierra 10.13.


attributes


Returns an array of the technical, non-localized names of all attributes recognized by the receiver.

- (NSArray<NSString *> *)attributes; 
Return Value

An array of NSString objects, or an empty array if the receiver does not recognize any attributes.

Discussion

Cocoa and Carbon target applications respond differently to this method. In general, Carbon target applications return only those attributes that are implemented by the receiving UI element, and all such attributes therefore have a value. Cocoa target applications return all attributes implemented in the receiver's class, whether or not a particular attribute for a particular UI element has a value. In cases where an attribute is not implemented, or is implemented but does not contain a value, the PFUIElement accessor method for that attribute returns nil. In all cases, an empty string is considered a valid attribute value.

The preferred and most efficient way to get or set the value of an attribute of the receiver is to send one of the specific attribute accessor messages, such as -AXRole declared in the Attributes category. The names of these accessor methods are identical to the technical, non-localized attribute strings declared in the accessibility API and returned by this method, including the "AX" prefix. The accessor methods are convenient to use and descriptive when you know the name of the attribute you want to access. The PFAssistive framework implements accessor methods for all attributes declared in the Cocoa and Carbon accessibility APIs (except those marked obsolete).

While many specific attribute accessor methods apply to almost any kind of UI element, others apply only to particular kinds of UI elements. In addition, applications are free to implement new kinds of UI elements and new attributes. Apple encourages developers to minimize the number of new attributes by reusing existing attributes for analogous new purposes wherever appropriate. As time goes by, therefore, existing attributes may apply to more and more kinds of UI elements. When in doubt, test the return value of an attribute for nil or an empty value, or use one of the -exists... methods. For specific usage information regarding individual attributes, consult the "Accessibility (ApplicationServices/HIServices) Reference" and the "Carbon Accessibility Reference" in the Xcode Documentation window, and the AccessibilityDefinitions.plist file at /System/Library/Accessibility/AccessibilityDefinitions.plist.

Another way to get or set the value of a non-parameterized attribute of the receiver is to send the generic messages -valueForAttribute: and -setValue:forAttribute:. They use key-value coding with keys generated by -nonParameterizedAttributes. They can be used instead of the specific accessor methods described above to get any non-parameterized attribute value using its NSAccessibility informal protocol constant, its accessibility API string constant cast to NSString*, or the attribute string itself. You must always use these two generic methods when you don't know which attribute you need, for example, when iterating over a list of attributes, and when a specific attribute accessor method is not implemented here. The -valueForAttribute: method automatically sends the appropriate specific attribute accessor method, if one exists for the attribute, and returns an object of the appropriate type. It even returns the value of a non-parameterized attribute that is not covered by a specific accessor method, including attributes added to the accessibility API in the future or implemented in another application like the Finder or Safari, because the framework implements the Cocoa key-value coding fallback methods using whatever attribute strings you provide.

This method also returns the parameterized attribute strings if the receiver is a text area or a text field. However, you cannot obtain or set the value of parameterized attributes using key-value coding in this version of the framework. For these, you must use the specific parameterized attribute accessor methods.

A few applications may not expose the AXChildren attribute in the list of attributes for some custom elements, even though these applications may in fact support the AXChildren attribute. The accessibility API may not expose the AXChildren attribute on behalf of these applications, as it used to do. Pursuant to Apple's recommendation, this method therefore always includes the AXChildren attribute in the list for all UI elements. The PFAssistive framework will always return a value for this attribute for elements that support them.

See also -nonParameterizedAttributes and -parameterizedAttributes.


attributesForRole:andSubrole:


Class method returns an NSArray of NSDictionary objects containing information about all accessibility attributes that may or should be supported by a UI element with the specified role and subrole.

+ (NSArray<NSDictionary *> *)attributesForRole:(NSString *)role 
        andSubrole:(nullable NSString *)subrole; 
Parameters
role

An NSString representing a UI element role; may be a constant from the NSAccessibility informal protocol or from AXRoleConstants.h in the accessibility API cast to NSString*, or the string itself.

subrole

An NSString representing a UI element subrole, or nil or an empty string if it has no subrole; may be a constant from the NSAccessibility informal protocol or from AXRoleConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An array of NSDictionary objects, or an empty array if a UI element with the specified role and subrole should not support any attributes.

Discussion

This class method returns an array of dictionaries containing the technical names and other features of all of the accessibility attributes that a UI element with the specified role and subrole may or should support. In addition to the technical name of the attribute and the associated role, a dictionary item discloses whether the attribute is required, whether it may or should be settable, and the data types of the values in the returned array. This is general information obtained from the AccessibilityDefinitions.plist file installed at /System/Library/Accessibility/AccessibilityDefinitions.plist. It reads information from the role_attributes array and the attributes dictionary in the plist file. It does not guarantee that any particular UI element does in fact support the listed attributes.

Each dictionary returned in the array has keys "attribute" (NSString, technical name of the attribute), "required" (NSNumber with BOOL value, NO if attribute is optional or YES if attribute is required), "role" (NSString), "settable" (NSString, "NO" if attribute must not be settable, "YES" if attribute may optionally be settable, or "REQUIRED" if attribute must be settable), and "types" (NSArray of NSStrings). The "required" field may be omitted if the attribute is not required.

As of OS X Mavericks 10.9, the attributes and role_attributes arrays are believed to have been fully validated by Apple and are complete. However, Apple does not appear to be updating the AccessibilityDefinitions.plist file since then.


childrenCount


Returns the number of children the receiver contains.

- (NSUInteger)childrenCount; 
Return Value

An integer counting the receiver's children.

Discussion

This method returns the number of PFUIElement objects in the receiver's children array attribute value, or 0 if it has no children.

See also -countForAttribute:.


clippedRect


Returns an NSRect structure representing the origin and size of the portion of the receiver that is visible in its container.

- (NSRect)clippedRect; 
Return Value

An NSRect structure representing the intersection of the element's visible rectangle and the rectangle of its smallest ancestor.

Discussion

Returns an NSRect representing the intersection of the element's rectangle visible on the screen and the rectangle of its smallest ancestor. If the two rectangles don't overlap, the returned rectangle has its origin at {0.0, 0.0} and a size of {0.0, 0.0}. This method is useful because some elements are sized larger than their containing elements, such as a text view in a scroll view. Use the result to determine what part of the receiver, if any, is currently scrolled into view.

A drawer is treated as an independent element because its parent window occupies a different screen position.


countForAttribute:


Returns the number of items in the specified attribute of the receiver if the attribute is an array.

- (NSUInteger)countForAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing an attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An integer counting the receiver's attributes.

Discussion

Returns the number of items in the specified attribute of the receiver if the attribute is an array, or 0 if attribute is not an array, doesn't exist, or has no value. A return value of 0 can therefore represent either an empty array or an error.

See also -childrenCount.


delegate


Returns the receiver's delegate.

- (nullable id <PFUIElementDelegate>)delegate; 
Return Value

The receiver's delegate, an object of any type, or nil if it has no delegate.

Discussion

-PFUIElementWasDestroyed: and -PFUIElementReportError: are the only available delegate methods, which are optional. They are declared in the PFUIElementDelegate protocol.

See also -setDelegate:.


description


Returns a string describing the receiver.

- (NSString *)description; 
Return Value

An NSString object.

Discussion

The returned string is formatted as a property list showing the values for the receiver's AXDescription, AXHelp, AXRole, AXRoleDescription and AXSubrole attributes. In client code, call NSLog and pass in the element to see this information in the Xcode run log and debug console log.


descriptionForAction:


Returns a localized string describing action, suitable for display or speech.

- (nullable NSString *)descriptionForAction:(NSString *)action; 
Parameters
action

An NSString representing an action; may be a constant from the NSAccessibility informal protocol or from AXActionConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An NSString object, or nil if action can't be performed by the receiver.

Discussion

These action descriptions are provided by Apple's accessibility API.

It is possible for a target application to return an empty description string (as does the AXOpen action in Finder 10.3 and newer). It is up to the client to deal with this, perhaps by supplying a localizable string in a strings file in its bundle or by substituting the technical action name.


descriptionForAttribute:


Returns a localized string describing attribute, suitable for display or speech.

- (NSString *)descriptionForAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing an attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An NSString object, an empty string if the receiver does not implement attribute.

Discussion

These attribute descriptions are unique to the PFAssistive framework; Apple's accessibility API has no equivalent. The key-value pairs are defined in the PFAttributeDescriptions.strings file in the PFAssistive framework bundle.

It may be possible for a target application to return an empty description string. It is up to the client to deal with this, perhaps by supplying a localizable string in a strings file in its bundle or by substituting the technical attribute name.


descriptionForNotification:


Class method returns a localized string describing notification, suitable for display or speech.

+ (NSString *)descriptionForNotification:(NSString *)notification; 
Parameters
notification

An NSString representing a notification; may be a constant from the NSAccessibility informal protocol or from AXNotificationConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An NSString object.

Discussion

These notification descriptions are unique to the PFAssistive framework; Apple's accessibility API has no equivalent. The key-value pairs are defined in the PFNotificationDescriptions.strings file in the PFAssistive framework bundle.

It may be possible for a target application to return an empty description string. It is up to the client to deal with this, perhaps by supplying a localizable string in a strings file in its bundle or by substituting the technical notification name.


descriptionForSubrole:


Returns a localized string describing subrole, suitable for display or speech.

- (NSString *)descriptionForSubrole:(NSString *)subrole; 
Parameters
subrole

An NSString representing a subrole; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An NSString object, an empty string if the receiver does not implement attribute.

Discussion

These attribute descriptions are unique to the PFAssistive framework; Apple's accessibility API has no equivalent. The key-value pairs are defined in the PFSubroleDescriptions.strings file in the PFAssistive framework bundle.

It may be possible for a target application to return an empty description string. It is up to the client to deal with this, perhaps by supplying a localizable string in a strings file in its bundle or by substituting the technical subrole name.


descriptionOfTypeForAttribute:


Returns a localized string describing the data type of attribute, suitable for display or speech.

- (nullable NSString *)descriptionOfTypeForAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing an attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An NSString object, an empty string if the receiver does not implement attribute, or nil if attribute does not exist or has no value.

Discussion

These type descriptions are unique to the PFAssistive framework; Apple's accessibility API has no equivalent. The key-value pairs are defined in the PFTypeDescriptions.strings file in the PFAssistive framework bundle.

This method returns a string for the structured types point, size, rect, and range when appropriate. It may return a string for an unknown type or nil if attribute does not exist or has no value.

In the case of non-parameterized attributes, this method gets the attribute's value first and then determines the type of the attribute.

For a non-localized string identifying the data type of attribute, use -typeForAttribute:.


elementAtPoint:withDelegate:error:


Class method creates and returns a PFUIElement object representing the visible UI element located at point on the screen, no matter what application owns it.

+ (nullable instancetype)elementAtPoint:(NSPoint)point 
        withDelegate:(nullable id)delegate error:(NSError **)error; 
Parameters
point

An NSPoint structure using top-left relative screen coordinates.

delegate

An object that may implement the optional -PFUIElementWasDestroyed: or -PFUIElementReportError: delegate method. May be nil.

error

An indirect reference to an NSError object describing the error if the result is nil. Pass NULL if you don't care about the error.

Return Value

The PFUIElement object at point, or nil if an error occurred.

Discussion

Use this method to read the screen based on the current location of the mouse in top-left relative screen coordinates, or any other point of interest. This method can be the foundation of any screen reader application.

In Cocoa, the mouse location can be obtained at any time in bottom-left relative screen coordinates, regardless of the current event or pending events, using NSEvent's +mouseLocation class method. You must convert it to the accessibility API's top-left relative screen coordinates before passing it to this method. To avoid having to convert the coordinates, you can use Carbon's HIGetMousePosition() function, in HIToolkit's CarbonEventsCore framework, which returns top-left relative screen coordinates. It is available in 64-bit applications as well as 32-bit applications.

Get the root application element that owns the returned UI element by sending -applicationElement to it. Navigate the accessibility containment hierarchy in either direction using -AXParent and -AXChildren.

Use the PFApplicationUIElement instance method -elementAtPoint: instead of this class method to get a PFUIElement object representing the UI element visible at point on the screen belonging to a specific application.

See -initWithElementRef:delegate: for important information regarding the creation of UI element objects.


elementInfo


Returns information about the receiver that was cached when the receiver was created, and that may have been modified later.

- (nullable NSDictionary *)elementInfo; 
Return Value

An NSDictionary object using NSString constants from the NSAccessibility informal protocol as keys. May be nil.

Discussion

When the UI element represented by the receiver is destroyed, the receiver can no longer be queried by the accessibility API for valid data about it (except for its process identification number, or PID). Any information about it that must survive its destruction therefore has to be cached when it is created. See -elementRef for information regarding destroyed UI elements.

The role and, if available, the subrole, role description and title of the receiver are automatically cached when a new PFUIElement or PFAppplicationUIElement object is created. Note that the title may have changed by the time the UI element is destroyed. To make the cached title useful, a client application can update the cache at any time by sending -setElementInfo: with an appropriate dictionary entry. To retrieve these values from the dictionary returned by this method, or to set them, use as keys the NSAccessibility informal protocol string constants NSAccessibilityRoleAttribute, NSAccessibilityRoleDescriptionAttribute, NSAccessibilitySubroleAttribute, and NSAccessibilityTitleAttribute, or their counterparts in AXAttributeConstants.h in the accessibility API cast to NSString*, or the strings themselves.

If the client has registered to observe the root application element or the receiver for accessibility notifications, the client's callback method will always receive the affected element, even when observing NSAccessibilityUIElementDestroyedNotification. However, you must treat a destroyed element as invalid; do not pass it as a parameter to methods that call accessibility API functions. You can nevertheless use a destroyed element with -pid, and with -isEqual: and -isEqualToElement: to manage any element cache you maintain. Note that attempting to pass a destroyed UI element in an accessibility API function is not guaranteed to return an accessibility API error.

This method will return valid information about a destroyed element that was cached when the receiver was created, as described above, with one exception: If the observed element differs from the affected element (typically, when observing the root application element), this method will return nil if the element was destroyed. It is the client's responsibility to cache information about the receiver if it will be needed in this situation.

If you added key-value pairs of your own to the dictionary, you can retrieve the information from the dictionary returned by this method using the keys you added.

See also -setElementInfo:.


elementRef


Returns the accessibility API AXUIElementRef opaque object that was associated with the receiver when the receiver was created.

- (nullable AXUIElementRef)elementRef; 
Return Value

An opaque accessibility API object representing a UI element in the target application. The object is returned CFRetained and will be CFReleased when the PFUIElement object with which it is associated is deallocated. Do not CFRelease it yourself unless you CFRetain it yourself. May be nil if the PFUIElement object has not yet been initialized.

Discussion

The AXUIElementRef object returned by this method can be used with accessibility API functions, passed to the -initWithElementRef:delegate: method to create another PFUIElement object representing the same UI element, or passed to the -setElementRef: method for a PFUIElement object that was initialized with a nil uiElementRef parameter.

The returned AXUIElementRef object may represent a UI element that no longer exists in the running application. In that case, you should not call any accessibility API function on it except to get its process identification number (PID) or to test it for equality with another AXUIElementRef ofject. It can always be used to test cached AXUIElementRef objects using CFEqual(); for example, to decide whether to remove them from the cache. For this reason, -isEqual: and -isEqualToElement: can also be used with destroyed UI elements.

You should CFRetain the returned object if you want to ensure that it persists while you are using it even after the UI element represented by the receiver is destroyed. If you do CFRetain it, CFRelease it when you are done with it. An AXUIElementRef object returned by this method is already CFRetained once, but it will be CFReleased by the framework when the PFUIElement object with which it is associated is deallocated.

See also -setElementRef:.


elementsWithRole:inArray:


Class method returns all PFUIElement objects having attribute role in array.

+ (NSArray<__kindof PFUIElement *> *)elementsWithRole:(NSString *)role 
        inArray:(NSArray<__kindof PFUIElement *> *)array; 
Parameters
role

an NSString representing an accessibility API role; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

array

An array of PFUIElement objects.

Return Value

An array of PFUIElement objects with attribute role, or an empty array if none exists in array.

Discussion

Use this method to return, for example, all of an element's children that are buttons.

This method does a flat search in array; it does not search nested elements such as grandchildren.

See also +firstElementWithRole:inArray:.


exists


Returns whether the UI element represented by the receiver still exists in the running application.

- (BOOL)exists; 
Discussion

Returns YES if the UI element represented by the receiver still exists in the running application. Use this method to test, for example, whether an application's window is still open. This method is very fast, so it can and should be called liberally.

This method is important because the AXUIElementRef object associated with the receiver may be invalid if the UI element it represents has been destroyed; that is, if it no longer exists in the running application. A UI element can be destroyed under many circumstances, not all of them obvious. The accessibility API defines existence in terms of an element's availability in the user interface, rather than its programmatic availability. For example, a window UI element is destroyed when its application is hidden, even if the window object still exists in memory. To be prudent, you should not call any accessibility API function on a UI element that might have been destroyed without first sending it this message.

You can, however, always safely get a destroyed UI element's -pid, and you can always test destroyed PFUIElement objects for equality using -isEqual: or -isEqualToElement:. You can also get information that was cached when a destroyed PFUIElement object was created, by sending -elementInfo to it.

Due to the design of the accessibility API, some UI elements do not issue NSAccessibilityUIElementDestroyedNotification notifications when the UI element containing them is destroyed, such as a Cocoa window's title and grow area elements. This method depends on this notification internally, so it will report that such elements still exist in the running application, although Apple advises that all UI elements descended from a destroyed element should nevertheless be considered destroyed. One way to deal with this issue is to explicitly mark all contained UI elements as destroyed when their container is destroyed, by sending -setExists: to each of them with flag passed as NO. If this technique is not adopted, a prudent client should always anticipate that a PFUIElement object it is accessing might not exist, in case this method returns an incorrect result. There is no better way to deal with this issue; using an accessibility API function to access a destroyed UI element is not guaranteed to return an error because AXUIElementRef objects are recycled and therefore might refer to another valid UI element.

A client can observe when a UI element is destroyed by calling -setDelegate: to set itself as PFUIElement's delegate and implementing the -PFUIElementWasDestroyed: delegate method, or by registering with NSNotificationCenter to observe PFUIElementWasDestroyedNotification. As noted above, some elements do not issue a notification when their container is destroyed.

For other issues relating to UI elements that have been destroyed, see the -PFUIElementWasDestroyed: delegate method.

See also -isDestroyed , which is the antonym of -exists, and -setExists: , which can be used to mark children of a destroyed element as destroyed by passing NO.


existsAction:


Returns whether the receiver still exists in the running application and can perform action.

- (BOOL)existsAction:(NSString *)action; 
Parameters
action

An NSString representing an action; may be a constant from the NSAccessibility informal protocol or from AXActionConstants.h in the accessibility API cast to NSString*, or the string itself.

Discussion

Returns YES if the receiver still exists in the running application and can perform action.

Use this method to test, for example, whether a button element exists and supports the AXPress action.


existsAttribute:


Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute.

- (BOOL)existsAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing an attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Discussion

Returns YES if the UI element represented by the receiver still exists in the running application and recognizes attribute.

Use this method to test, for example, whether a button UI element has a subrole attribute and might therefore be a close, minimize, or zoom button. Note that some UIElements have attributes with NULL values, such as 0, or an empty string.

See also -existsNonParamterizedAttribute:, -existsParameterizedAttribute:, and -existsValueForAttribute:.


existsNonParameterizedAttribute:


Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute as a non-parameterized attribute.

- (BOOL)existsNonParameterizedAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing a non-parameterized attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Discussion

Returns YES if the UI element represented by the receiver still exists in the running application and recognizes attribute as a non-parameterized attribute.

See also -existsAttribute:, -existsParameterizedAttribute:, and -existsValueForAttribute:.


existsParameterizedAttribute:


Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute as a parameterized attribute.

- (BOOL)existsParameterizedAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing a parameterized attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Discussion

Returns YES if the UI element represented by the receiver still exists in the running application and recognizes attribute as a parameterized attribute.

See also -existsAttribute:, -existsNonParameterizedAttribute:, and -existsValueForAttribute:.


existsValueForAttribute:


Returns whether the UI element represented by the receiver still exists in the running application, recognizes attribute, and attribute has a value.

- (BOOL)existsValueForAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing a non-parameterized attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Discussion

Returns YES if the UI element represented by the receiver still exists in the running application, if it recognizes attribute, and if attribute has a value. The attribute argument must be a non-parameterized attribute.

A value such as 0 or an empty string is considered a valid value for a UI element's attribute, but nil is not.


firstElementWithRole:inArray:


Class method returns the first PFUIElement object with attribute role in array.

+ (nullable instancetype)firstElementWithRole:(NSString *)role 
        inArray:(NSArray<__kindof PFUIElement *> *)array; 
Parameters
role

an NSString describing an accessibility API role; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

array

An array of PFUIElement objects.

Return Value

The first PFUIElement object with attribute role, or nil if none exists in array.

Discussion

Use this method to test whether, for example, an application's children include any windows or a window's children include any scroll areas.

This method does a flat search in array; it does not search nested elements such as grandchildren.

See also +elementsWithRole:inArray:.


indexAmongLikeElementsInArray:


Returns the index of the receiver among all UI elements in array having the same role as the receiver, or NSNotFound if the receiver is not in array.

- (NSUInteger)indexAmongLikeElementsInArray:(NSArray<__kindof PFUIElement *> *)array; 
Parameters
array

An array of PFUIElement objects.

Return Value

The receiver's index among like elements in array, or NSNotFound if the receiver is not in array.

Discussion

This method does a flat search in array; it does not search nested elements such as grandchildren.

The returned index is zero-based. For AppleScript GUI Scripting compatibility, add 1 to the index returned by this method because AppleScript indexes are one-based. UI elements whose role is "AXUnknown" should not be indexed with this method, but instead with NSArray's -indexOfObject: for compatibility with GUI Scripting.

The indexes of windows represent their front-to-back ordering.


indexPath


Returns an NSIndexPath object reflecting the accessibility hierarchy of UI elements from the root application element to and including the receiver.

- (nullable NSIndexPath *)indexPath; 
Return Value

An NSIndexPath object starting with 0, the index of the root PFApplicationUIElement object. Returns an empty NSIndexPath object with length of 0 if the receiver has been destroyed in the running application.

Discussion

The returned index path represents the path from the root application element to and including the receiver in the target application's UI element containment hierarchy. Use -parentIndexPath to obtain an index path that excludes the receiver.

If the receiver has been destroyed in the running application, the returned index path is empty.

The root application element's index defaults to 0 because there is only one root application element in an application. For clients that wish to use index paths for combined management of multiple applications, the rootIndex property of PFApplicationUIElement can be set to any integer value. In that case, it is the client's responsibility to manage the root application indexes.

Any index in the returned indexPath object may be NSNotFound. This usually indicates a mismatch error in the target application's accessibility hierarchy, where an element is not a child of its own parent. For this reason, when using an indexPath returned by this method to obtain the element it represents, it is essential to test for out-of-range errors. This is done, for example, in -[PFApplicationUIElement elementAtIndexPath:].

Use the PFApplicationUIElement method -elementAtIndexPath: to obtain the PFUIElement object at the generated index path.


initWithElementRef:delegate:


Initializes and returns a newly allocated PFUIElement object.

- (nullable instancetype)initWithElementRef:(nullable AXUIElementRef)uiElementRef 
        delegate:(nullable id)aDelegate NS_DESIGNATED_INITIALIZER; 
Parameters
uiElementRef

An opaque accessibility API object representing a UI element in the target application.

aDelegate

An object that may implement the optional -PFUIElementWasDestroyed: or -PFUIElementReportError: delegate method. May be nil.

Return Value

An initialized PFUIElement or PFApplicationUIElement object, or nil if the target application is not running or the UI element does not exist in the target application's user interface.

Discussion

This is the designated initializer for the PFUIElement class. Use it to initialize a newly-allocated PFUIElement object with uiElementRef, an opaque accessibility API AXUIElementRef object.

The uiElementRef argument may be obtained by sending -elementRef to any valid PFUIElement or PFApplicationUIElement object, or by calling any of several accessibility API functions. You may pass nil, but then you are responsible for calling -setElementRef: with a uiElementRef object and -setElementInfo: before you use the new PFUIElement object.

The object passed in the aDelegate argument, if it implements the optional -PFUIElementWasDestroyed: delegate method, is automatically registered to receive PFUIElementWasDestroyedNotification when the UI element represented by the new PFUIElement object is destroyed (for example, when a window closes). Pass nil if you don't need to know when the element is destroyed.

Although this is the designated initializer for the PFUIElement class, a client application normally creates and initializes a new PFUIElement object in one of the four ways listed here, instead of allocating a new PFUIElement object and sending it the -initWithElementRef:delegate: message:

  1. with PFUIElement's +elementAtPoint:withDelegate:error: class method or PFApplicationUIElement's -elementAtPoint: instance method, when you want to browse an application's UI elements from a leaf element by reading the screen;

  2. with PFApplicationUIElement's -initWithPath:delegate: , -initWithURL:delegate: , -initWithBundleIdentifier:delegate: or -initWithPid:delegate: method, or their corresponding convenience factory methods, when you want to browse an application's UI elements from its root application element without reading the screen;

  3. with PFApplicationUIElement's -initSystemWideWithDelegate: method, or its corresponding convenience factory method, when you want to use the system-wide UI element to access the active application's elements; or

  4. with any of several methods, such as -applicationElement, -AXParent and -AXChildren, that return a PFUIElement object or an array of PFUIElement objects related to a given element, when you already have a PFUIElement object and can use it as the receiver.

This method is nevertheless handy when you need to create a temporary UI element object; for example, an object representing a known UI element in order to test it for equality with a cached element using -isEqualToElement:. You can allocate as many UI elements as you like in this way, as often as you like, and initialize each of them with -initWithElementRef:delegate:. Typically, in this situation, you get the uiElementRef argument from an existing or newly-created element by sending it -elementRef, but you can also get it directly by calling any of several accessibility API functions.

This method may return a PFApplicationUIElement object, substituting it for the PFUIElement object that was initially allocated. You must therefore always follow the convention of allocating and initializing a UI element object in a single statement in this form: [[PFUIElement alloc] initWithElementRef:myElementRef delegate:MyObject].

All PFUIElement objects except a PFApplicationUIElement object use internal mechanisms to learn when they are destroyed in the target application's user interface (for example, when a window closes), even if the client application does not register to observe PFUIElementWasDestroyedNotification or implement the -PFUIElementWasDestroyed: delegate method. Use -exists to determine whether a PFUIElement object currently exists in the user interface. When an element is initialized, it caches information about itself that can still be accessed after the element is destroyed. See the -PFUIElementWasDestroyed: delegate method and -elementInfo for details.

Clients may subclass PFUIElement for applications that also subclass PFApplicationUIElement, by registering the PFUIElement subclass for the application's PID using the methods described in the discussion of PFApplicationUIElement subclassing. Subclasses of PFUIElement must override its designated initializer or provide a new initializer that calls its designated initializer.

IMPORTANT: if you use -initWithElementRef:delegate: to create a new PFUIElement object to represent a UI element that has already been destroyed (for example, in response to a notification that it has been destroyed), the cached information in the newly-created object may be invalid. You should therefore substitute known good elementInfo, which you can obtain from the elementInfo that was cached in the destroyed PFUIElement object when it was initially created.


invalidate


Invalidates this PFUIElement object when it is no longer needed.

- (void)invalidate; 
Discussion

Optionally call this method when the client application is finished with this PFUIElement object.

It is desirable to call this method to avoid adding time-consuming activity at dealloc time. If the client application does not call this method, it is called automatically when the object is deallocated. It sets any delegate to nil, unregisters an internal destruction observer and takes care of memory management.

Invalidation is not related to -exists or -isDestroyed , which report the existence or nonexistence of the underlying UI element in the running application. Invalidation applies only to a specific instance of PFUIElement. PFUIElement objects representing destroyed and nonexistent elements can still be used for equality tests and the like, but invalidated PFUIElement objects cannot.

NOTE: PFAssistive Framework does not support garbage collected clients.

See also -isValid.


isAccessEnabled


Class method reports whether global access for assistive devices is enabled. DEPRECATED in OS X Mavericks 10.9.

+ (BOOL)isAccessEnabled; 
Discussion

This method is deprecated in OS X Mavericks 10.9 and newer because Apple has deprecated the function on which it relies, AXAPIEnabled() in AXUIElement.h, because global accessibility is no longer available. See +isProcessTrustedWithOptions: for information on the new trust features that take its place in Mavericks.

In OS X Mountain Lion 10.8 and earlier, returns YES if global access for assistive devices is enabled in the Accessibility (or Universal Access) pane of System Preferences. (Testing indicates that, though deprecated in Mavericks, this method returns the same value in Mavericks as +isProcessTrusted and +isProcessTrustedWithOptions: .)

In OS X Mountain Lion 10.8 and earlier, global access for assistive devices is enabled manually in the Accessibility (or Universal Access) pane of System Preferences. It can also be enabled programmatically using AppleScript by setting the UI elements enabled property in System Events or the GUI Scripting enabled property in AppleScript Utility. System Events and AppleScript Utility are scriptable faceless background applications. Enabling this setting requires user authentication whether done manually or by AppleScript. Apple removed the global access setting from System Preferences in OS X Mavericks 10.9 and replaced it with application-specific settings in the Accessibility list in the Security & Privacy preference's Privacy pane. The UI elements enabled and GUI Scripting enabled properties are now read-only.

Global access for assistive devices is turned off by default in OS X Mountain Lion 10.8 or earlier, and client applications therefore cannot use the methods of the PFAssistive framework unless they arrange to turn it on. Assistive applications commonly instruct the user to turn access on manually in System Preferences. One technique is to send the isAccessEnabled message in a client application's -awakeFromNib or similar method and, if the result is NO, present an alert explaining how the user can turn the setting on. Applications optionally open System Preferences to the appropriate pane for the user. A more user-friendly technique is to enable access for assistive devices for the user with an embedded AppleScript command using Scripting Bridge. For this to work, the developer of an assistive application has to use the sdef and sdp tools to generate a System Events.h header file, which is added to the project before compiling. The SBApplication.framework has to be linked. Here is an action method that toggles the state of the setting in OS X Mountain Lion 10.8 or earlier:

 - (IBAction)enableAccessAllAction:(id)sender {
     SystemEventsApplication *systemEventsApp
              = [SBApplication applicationWithBundleIdentifier:@"com.apple.systemevents"];
     if ([systemEventsApp isRunning]) {
         [systemEventsApp activate]; // so authentication dialog opens frontmost
         [systemEventsApp setUIElementsEnabled:[PFUIElement isAccessEnabled] ? NO : YES];
     }
     [sender setState:[PFUIElement isAccessEnabled] ? NSOnState : NSOffState];
 } 
 

The most sophisticated technique is to ask the user to make the assistive application alone "trusted." This is complicated for the developer in OS X Mountain Lion 10.8 or earlier because it requires an embedded helper application with root privileges and an embedded helper application to relaunch the application. It is much easier in OS X Mavericks 10.9 or later, where it requires no helper applications. See +isProcessTrustedWithOptions: for information about making a apecific client application trusted in Mavericks.

Now that global access for assistive devices has been eliminated in OS X Mavericks 10.9, the meaning of the System Events UI element enabled property and the AppleScript Utilities GUI Scripting enabled property have changed. They used to mean that global access was enabled for all applications, including the System Events application which supports GUI Scripting. These AppleScript properties and this isAccessEnabled method always returned the same result. Now, in OS X Mavericks 10.9 or later, isAccessEnabled is deprecated because global access no longer exists, but the UI elements enabled property of System Events and the GUI Scripting enabled property of AppleScript Utility return true for an assistive application that is trusted in the Accessibility list in the Security & Privacy preference's Privacy pane.

See also +isAccessImplemented, +isProcessTrusted and +isProcessTrustedWithOptions:.


isAccessImplemented


Class method reports whether the accessibility API is implemented on this computer.

+ (BOOL)isAccessImplemented; 
Discussion

Returns YES if the accessibility API is implemented on this computer. This method should always return YES because the accessibility API was introduced in Mac OS X 10.2 (Jaguar), so there is no longer any reason to call it.

See also +isAccessEnabled, +isProcessTrusted and +isProcessTrustedWithOptions:.


isDestroyed


Returns whether the element has been destroyed.

- (BOOL)isDestroyed; 
Discussion

Returns YES if this PFUIElement object has been destroyed (for example, a window has closed).

See also -exists , which is the antonym of -isDestroyed, and -setExists:, which can be used to mark children of a destroyed element as destroyed by passing NO.


isEqualToElement:


Returns whether element and the receiver represent the same UI element in the target application.

- (BOOL)isEqualToElement:(PFUIElement *)element; 
Parameters
element

A PFUIElement or PFApplicationUIElement object to be tested for equality with the receiver.

Discussion

Returns YES if element represents the same UI element in the target application that the receiver represents.

This method tests whether two PFUIElement objects represent the same UI element in the running application. This works even if the UI elements represented by either or both elements no longer exist in the running application.

Use this method for efficiency if you know that element is a PFUIElement or PFApplicationUIElement object. Otherwise, use -isEqual:.


isParameterizedAttribute:


Returns whether attribute is a parameterized attribute.

- (BOOL)isParameterizedAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing a parameterized attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Discussion

Returns YES if attribute is a parameterized attribute.

If attribute is not a parameterized attribute, it is a non-parameterized attribute. See -existsAttribute: for details.


isProcessTrusted


Class method reports whether the client application's process is trusted.

+ (BOOL)isProcessTrusted; 
Discussion

A "trusted" process is an application that has been granted access to the computer to monitor or control other applications using the accessibility features of macOS. It is known as an "asssistive" application, especially if it is designed to facilitate the use of the computer by persons with disabilities. An application is untrusted by default, and a client application cannot use the accessibility methods of the PFAssistive framework until the user grants access to make it a trusted process. Access is typically granted to an assistive application when it is first run or when its accessibility features are first needed. User authentication is required. See +isProcessTrustedWithOptions: for details about making a process trusted and testing its status.

This method returns YES if the client application's process is trusted in Mac OS X 10.4 (Tiger) and newer. In OS X Mavericks 10.9 or later, it can be used interchangeably with +isProcessTrustedWithOptions: using either a parameter value of nil or a parameter value of an NSDictionary object with a value of YES for the AXTrustedCheckOptionPrompt key, to test the application's accessibility status without presenting the built-in system alert giving the user an option to grant or deny access.

See also +isAccessImplemented, +isAccessEnabled and +isProcessTrustedWithOptions:.


isProcessTrustedWithOptions:


Class method reports whether the client application's process is trusted, optionally presenting an alert allowing the user to grant or deny access if it is not already trusted. Introduced in OS X Mavericks 10.9.

+ (BOOL)isProcessTrustedWithOptions:(nullable NSDictionary *)options; 
Parameters
options

An NSDictionary object. Set the value associated with the kAXTrustedCheckOptionPrompt key to YES to present an alert offering to grant or deny access if access is not already allowed.

Discussion

A "trusted" process is an application that has been granted access to the computer to monitor or control other applications using the accessibility features of macOS. It is known as an "asssistive" application, especially if it is designed to facilitate the use of the computer by persons with disabilities. An application is untrusted by default, and a client application cannot use the accessibility methods of the PFAssistive framework until the user grants access to make it a trusted process. Access is typically granted to an assistive application when it is first run or when its accessibility features are first needed. User authentication is required.

Until OS X Mavericks 10.9, a user could grant access to all assistive applications at once on a global basis instead of relying on a per-application trust mechanism. Global access was granted manually by selecting the "Enable access for assistive devices" setting in the Accessibility (or, formerly, Universal Access) pane of System Preferences. Global access could also be granted programmatically using AppleScript by setting to true the UI elements enabled property of System Events or the GUI Scripting enabled property of AppleScript Utility, both of which were read-write properties.

Per-application access was introduced by Apple in Mac OS X 10.4 (Tiger) to move away from the global on/off model, which was judged to be too broad and insecure. Initially, assistive applications could be made trusted on a per-application basis only programmatically by calling the AXMakeProcessTrusted() function. However, per-application trust was difficult to implement, and very few applications did so because global access was readily available. (One application that did implement per-application trust was PFiddlesoft's own UI Browser.) As a result, Apple removed the global access mechanism in OS X Mavericks 10.9, and the previous programmatic per-application trust mechanism was replaced at the same time by a new, simpler trust mechanism. An existing assistive application that relies on global access or on the old trust mechanism must now be granted access using the new Mavericks trust mechanism, and developers may need to revise their user interfaces. The "Enable access for assistive devices" setting no longer exists in System Preferences, and the AXIsAccessEnabled() function is deprecated. The AXMakeProcessTrusted() function is also deprecated. In addition, Apple made the UI elements enabled property of the System Events application's AppleScript terminology dictionary and the GUI Scripting enabled property of AppleScript Utility's dictionary read-only. As a result, assistive applications and GUI Scripting scripts may no longer set these properties to true to turn on global access.

In Mavericks, making an assistive application trusted requires a user to add the application to the new Accessibility list in the Security & Privacy preference's Privacy pane in System Preferences and select the application's checkbox. The application can be added to the list manually by dropping its application icon into the list after authenticating to unlock the preference pane, and the application's checkbox is selected to make it trusted. The application can be added to the list programmatically by calling this isProcessTrustedWithOptions: method, which covers the new AXIsProcessTrustedWithOptions() function introduced in OS X Mavericks 10.9. Passing in a properly configured options dictionary presents an alert giving the user the option to open System Preferences or to deny access, and if the user clicks the Open System Preferences button the application is added to the list automatically. For compiled GUI Scripting scripts, the application running the script must now be added to the Accessibility list; use the AppleScript current application command to learn its identity). For GUI Scripting applets, the applet itself must now be added to the list.

Either of the following statements can be used to create the options dictionary to be passed in as the parameter to this method. Passing in the first dictionary adds the application to the Accessibility list and presents the built-in system alert. Passing in nil or the second dictionary adds the application to the Accessibility list without presenting an alert.

NSDictionary *withAlertOption = [NSDictionary dictionaryWithObject:[NSNumber numberWithBool:YES] forKey:(NSString *)kAXTrustedCheckOptionPrompt];
 
NSDictionary *withoutAlertOption = [NSDictionary dictionaryWithObject:[NSNumber numberWithBool:NO] forKey:(NSString *)kAXTrustedCheckOptionPrompt];

This method enables an application to determine whether it is trusted using the new Security & Privacy preference mechanism. It returns YES if the client application's process is trusted. It returns NO if the application is not trusted, and it optionally presents an alert with buttons to deny access or to open the Accessibility list in the Security & Privacy preference's Privacy pane in System Preferences. If the user clicks the Open System Preferences button, the system opens the Security & Privacy preference's Privacy pane and selects the Accessibility list, and it automatically adds the application to the list. The application's checkbox must be selected to grant access to the application. Thereafter, access can be granted or denied at any time by selecting or deselecting its checkbox. Unlike the old trust mechanism, the change takes effect without requiring the application to be relaunched. Authentication is required to unlock the Security & Privacy preference pane before any changes can be made. The method is asynchronous; it returns its result based on the application's current accessibility status, and then it presents the optional alert allowing the user to change its status. The alert is presented if the options dictionary is passed to this method with a value of YES for the kAXTrustedCheckOptionPrompt key and the application is not already trusted using the new mechanism.

An assistive application can register to observe the "com.apple.accessibility.api" distributed notification posted by System Preferences to learn when the user grants or denies access. This notification is especially helpful when using the optional alert presented by this method, because the alert provides no way to learn which button the user clicked or what happened after the user clicked the Open System Preferences button. A suggested pattern for responding to the notification is to do it in two stages. First capture the application's old or "before" accessibility status in -applicationDidFinishLaunching:, and then in the next iteration of the run loop after the notification is received compare it to the application's new accessibility status. If the status has changed, then it is the assistive application's accessibility status that the user altered. This technique is necessary because the "com.apple.accessibility.api" notification is posted for every change in the Accessibility list, and its object and userInfo accessors do not report the identity of the affected application or its "before" status. The changed status apparently does not take effect until the next iteration of the run loop after the notification is received. Note that the "before" accessibility status cannot be reliably obtained when the notification is received because distributed notifications are asynchronous and can be delayed. Call this method or +isProcessTrusted in the first stage to get the "before" status, and then call the other method using performSelector:withObject:afterDelay: passing 0 in the parameter labeled withDelay:.

If this method is called under OS X Mountain Lion 10.8 or earlier, it ignores the options parameter and returns YES if the process is trusted or if global access is enabled, because before Mavericks either setting allows the client application to monitor or control other applications using accessibility features. If called in Mountain Lion or older, it should not be used to distinguish between global access and per-application trust; instead, call +isAccessEnabled or +isProcessTrusted to test those settings separately.

See also +isAccessImplemented , +isAccessEnabled and +isProcessTrusted.


isRole:


Returns whether the receiver represents a UI element whose AXRole attribute is role.

- (BOOL)isRole:(NSString *)role; 
Parameters
role

An NSString representing an accessibility API role attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Discussion

Returns YES if the receiver represents a UI element whose AXRole attribute has a value of role.

This method tests whether the receiver's role string is equal to the string provided in the role argument. It tests the receiver's cached elementInfo, so it returns the correct result even if the receiver has been destroyed.


isSettableAttribute:


Returns whether attribute can be modified.

- (BOOL)isSettableAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing an attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Discussion

Returns YES if attribute can be modified.

This method tests whether attribute is marked as settable in the accessibility API. Some UI elements report that an attribute is settable when in fact it is not.


isSiblingOfElement:


Returns whether element and the receiver have the same parent.

- (BOOL)isSiblingOfElement:(PFUIElement *)element; 
Parameters
element

A PFUIElement or PFApplicationUIElement object to be compared with the receiver.

Discussion

Returns YES if element is a sibling of the receiver; that is, if they have the same parent.

This method works even if the UI elements represented by either or both elements no longer exist in the running application.

Two root application objects are never considered siblings.


isValid


Reports whether this PFUIElement object has been initialized and has not been invalidated.

- (BOOL)isValid; 
Discussion

Returns YES if this PFUIElement object has been initialized and has not been invalidated.

See also -invalidate.


isVisibleAtPoint:


Returns whether the UI element represented by the receiver is visible at point on the screen.

- (BOOL)isVisibleAtPoint:(NSPoint)point; 
Parameters
point

An NSPoint structure representing a point on the screen in top-left relative screen coordinates.

Discussion

Returns YES if the UI element represented by the receiver is visible at point on the screen; that is, its window is not obscured by another application's window at point.

If the UI element represented by the receiver is not visible at point because another application's window is in front of it, then PFUIElement's +elementAtPoint:withDelegate:error: class method cannot read it by its location on the screen; it can only read the visible UI element of the frontmost application's window at point. The PFApplicationUIElement's -elementAtPoint: instance method reads the UI element represented by the receiver even if it is not visible.

See +elementAtPoint:withDelegate:error: for information about how to obtain the mouse pointer's current position on the screen.


nonParameterizedAttributes


Returns the technical, non-localized names of all non-parameterized attributes recognized by the receiver.

- (NSArray<NSString *> *)nonParameterizedAttributes; 
Return Value

An array of NSString objects, or an empty array if the receiver does not recognize any non-parameterized attributes.

Discussion

All elements should return at least one non-parameterized attribute, AXRole. However, if the receiver does not support the accessibility API, this method returns an empty array.

See also -attributes and -parameterizedAttributes.


notificationDefinitions


Class method returns an NSDictionary object containing information about all accessibility notifications.

+ (NSDictionary *)notificationDefinitions; 
Return Value

A dictionary containing information about all accessibility notifications.

Discussion

This class method returns a dictionary containing the technical names and other features of all accessibility notifications as listed in the AccessibilityDefinitions.plist file installed at /System/Library/Accessibility/AccessibilityDefinitions.plist starting with Mac OS X 10.7 (Lion). It reads information from the notifications dictionary in the plist file.


notifications


Returns the technical, non-localized names of all notifications issued by the receiver.

- (NSArray<NSString *> *)notifications; 
Return Value

An NSArray of NSString objects. All UI elements issue some notifications.

Discussion

The accessibility API does not include a function to return the notifications issued by a UI element, so the list returned by this method is arbitrary and is only as current as the version of macOS existing when this framework was last updated.

The notifications returned by this method are based on the class of the receiver. The root application element reports all notifications that may be issued by any element in the application. Other elements report all notifications that might be appropriate to the nature and function of that element. Notifications returned by this method should be considered candidates until a particular application is tested. The only notifications that this method excludes are those that are plainly inappropriate for a particular element, such as menu notifications in the case of a window element, and window notififications in the case of a menu or menu item element. Note that, as of OS X Mavericks 10.9, custom UI elements that do not inherit from NSView, NSWindow or NSCell can issue notifications. The role_nofitications array in the AccessibilityDefinitions.plist file installed at /System/Library/Accessibility/AccessibilityDefinitions.plist still has not been fully validated by Apple and is incomplete.

Apple discourages application developers from inventing new notifications, but there is no guarantee that they will not do so. The list returned by this method does not include any custom notifications implemented by third-party applications. If a client application must know of newer notifications or custom notifications implemented by other applications, it is the client's responsibility to provide them. An example of a user interface for letting users add new notifications is the Notifications pane in the Preferences window for UI Browser, an application from PFiddlesoft.

The PFAssistive framework handles registration to observe notifications in the PFObserver class in PFObserver.h. In general, it is best to register to receive notifications on the root application UI element of the target application, because this guarantees that all notifications will be received from all UI elements affected by a user's activity in the user interface, even as to elements that don't yet exist at registration time. It might be sensible to register for notifications on a particular element if registering on the application element floods the client application with irrelevant notifications.

Use the class method +notifications to get an array of all notifications recognized in the accessibility API.

The following notifications are supported by the accessibility API (obsolete notifications are omitted):

  • AXAnnouncementRequested - Returns the announcement requested by the application and its priority. (Mavericks)

  • AXApplicationActivated - Returns the application UI element for the activated application.

  • AXApplicationDeactivated - Returns the application UI element for the deactivated application.

  • AXApplicationHidden - Returns the application UI element for the hidden application.

  • AXApplicationShown - Returns the application UI element for the shown application.

  • AXCreated - Sent when a window is shown.

  • AXDrawerCreated - Returns the drawer that was created.

  • AXElementBusyChanged - Returns the UI element whose busy state has changed. (Yosemite)

  • AXFocusedUIElementChanged - Returns the UI element that acquired keyboard focus, or the application UI element if no UI element has focus.

  • AXFocusedWindowChanged - Returns the window that acquired keyboard focus, or the application UI element if there is no focused window.

  • AXHelpTagCreated - Returns the Help tag that was created.

  • AXLayoutChanged - Optionally returns an array of UI elements that have been shown, hidden or changed by user action such as hovering a mouse somewhere. (Mavericks)

  • AXMainWindowChanged - Returns the window that became main, or the application UI element if there is no main window.

  • AXMenuClosed - Returns the menu that closed.

  • AXMenuItemSelected - Returns the menu item that was selected.

  • AXMenuOpened - Returns the menu that opened.

  • AXMoved - Sent when an element has moved.

  • AXResized - Sent when an element has resized.

  • AXRowCollapsed - Sent when an outline view's row collapses. (Snow Leopard)

  • AXRowCountChanged - Sent when a table's row count changes.

  • AXRowExpanded - Sent when an outline view's row expands. (Snow Leopard)

  • ASSelectedCellsChanged - Send when a cell-based table's cell selection changes. (Snow Leopard)

  • AXSelectedChildrenChanged - Sent when a different subset of an element's children is selected.

  • AXSelectedChildrenMoved - Sent when an element's children move. (Snow Leopard)

  • AXSelectedColumnsChanged - Sent when a different set of a table's columns is selected.

  • AXSelectedRowsChanged - Sent when a different set of a table's rows is selected.

  • AXSelectedTextChanged - Sent when different text is selected.

  • AXSheetCreated - Returns the sheet that was created.

  • AXTitleChanged - Sent when an element's title has changed.

  • AXUnitsChanged - Sent when units of measurement change. (Snow Leopard)

  • AXUIElementDestroyed - Returns the UI element that was destroyed, such as a window that closed. The returned PFUIElement object is not valid except to compare it to another PFUIElement object for equality.

  • AXValueChanged - Returns the UI element whose value was modified.

  • AXWindowCreated - Returns the window that was created.

  • AXWindowDeminiaturized - Returns the window that was maximized from the Dock.

  • AXWindowMiniaturized - Returns the window that was minimized to the Dock.

  • AXWindowMoved - Returns the window that was moved (after it was moved).

  • AXWindowResized - Returns the window that was resized (after it was resized).


notifications


Class method returns the technical, non-localized names of all notifications recognized by the accessibility API in the currently-running version of macOS.

+ (NSArray<NSString *> *)notifications; 
Return Value

An array of NSString objects.

Discussion

The accessibility API does not include a function to return all available notifications, so the list returned by this method is only as current as the version of macOS existing when this framework was last updated.

Use the instance method -notifications to get an array of notifications that might be issued by a specific UI element.


notificationsForRole:andSubrole:


Class method returns an NSArray containing the technical names of all accessibility notifications that should be supported by a UI element with the specified role and subrole.

+ (NSArray<NSString *> *)notificationsForRole:(NSString *)role 
        andSubrole:(nullable NSString *)subrole; 
Parameters
role

An NSString representing a UI element role; may be a constant from the NSAccessibility informal protocol or from AXRoleConstants.h in the accessibility API cast to NSString*, or the string itself.

subrole

An NSString representing a UI element subrole, or nil or an empty string if it has no subrole; may be a constant from the NSAccessibility informal protocol or from AXRoleConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An array of NSString objects, or an empty array if a UI element with the specified role and subrole should not support any notifications.

Discussion

This class method returns an array listing all of the accessibility notifications that a UI element with the specified role and subrole should support. This is general information obtained from the AccessibilityDefinitions.plist file installed at /System/Library/Accessibility/AccessibilityDefinitions.plist starting with Mac OS X 10.7 (Lion). It does not guarantee that any particular UI element does in fact support the notifications.

As of OS X Mavericks 10.9, the role_nofitications array still has not been fully validated by Apple and is incomplete.


parameterizedAttributes


Returns the technical, non-localized names of all parameterized attributes recognized by the receiver.

- (NSArray<NSString *> *)parameterizedAttributes; 
Return Value

An array of NSString objects, or an empty array if the receiver does not recognize any parameterized attributes.

Discussion

Parameterized attributes exist for text areas, text fields, cell-based tables, and layout areas. If the receiver does not recognize any parameterized attributes, this method returns an empty array.

See also -attributes and -nonParameterizedAttributes.


parentIndexPath


Returns an NSIndexPath object reflecting the accessibility hierarchy of UI elements from the root application element to the receiver's parent, but not the receiver itself.

- (nullable NSIndexPath *)parentIndexPath; 
Return Value

An NSIndexPath object starting with the index of the root PFApplicationUIElement object. Returns nil if the receiver has been destroyed in the running application.

Discussion

The returned index path represents the path from the root application element to and including the receiver's parent in the target application's UI element containment hierarchy. Use -indexPath to obtain an index path that includes the receiver itself.

If the receiver has been destroyed in the running application, the returned value is nil. If the receiver is the root application element, which has no parent, the returned index path is empty.

The root application element's index defaults to 0 because there is only one root application element in an application. For clients that wish to use index paths for combined management of multiple applications, the rootIndex property of PFApplicationUIElement can be set to any integer value. In that case, it is the client's responsibility to manage the root application indexes.

Any index in the returned indexPath object may be NSNotFound. This usually indicates a mismatch error in the target application's accessibility hierarchy, where an element is not a child of its own parent. For this reason, when using an indexPath returned by this method to obtain the element it represents, it is essential to test for out-of-range errors. This is done, for example, in -[PFApplicationUIElement elementAtIndexPath:].

Use the PFApplicationUIElement method -elementAtIndexPath: to obtain the PFUIElement object at the generated index path.


parentPath


Returns an array of PFUIElement objects reflecting the accessibility hierarchy of UI elements from the root application element to the receiver's parent, but not the receiver itself.

- (NSArray<__kindof PFUIElement *> *)parentPath; 
Return Value

An array of PFUIElement objects starting with the root PFApplicationUIElement object. The array is empty if the UI element represented by the receiver is the root application element or has been destroyed in the running application.

Discussion

The returned array represents the path from the root application element to and including the receiver's parent in the target application's UI element containment hierarchy. Use -path to obtain an array that includes the receiver itself.

If the receiver is the root application element or has been destroyed in the running application, the returned array is empty. Otherwise, the first item in the array is a PFApplicationUIElement object.


path


Returns an array of PFUIElement objects reflecting the accessibility hierarchy of UI elements from the root application element to and including the receiver.

- (nullable NSArray<__kindof PFUIElement *> *)path; 
Return Value

An array of PFUIElement objects starting with the root PFApplicationUIElement object. The result is nil or the array contains only the receiver if it has been destroyed in the running application.

Discussion

The returned array represents the path from the root application element to and including the receiver in the target application's UI element containment hierarchy. Use -parentPath to obtain an array that excludes the receiver.

If the receiver has been destroyed in the running application, the returned array is empty or contains only the receiver, which is an orphaned PFUIElement object. Otherwise, the first item in the array is a PFApplicationUIElement object.


performAction:


Causes the receiver to perform action, returning YES if successful.

- (BOOL)performAction:(NSString *)action; 
Parameters
action

An NSString representing an action; may be a constant from the NSAccessibility informal protocol or from AXActionConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

YES if the action was successfully performed; NO, if not.

Discussion

This method causes the receiver to perform action as if the user had performed it directly, such as clicking a button, returning YES if successful. The target application should support undo and redo and behave in every other respect as if the user had used the keyboard or mouse to perform the action.


pid


Returns the BSD Unix process identification number (PID) of the application owning the receiver.

- (pid_t)pid; 
Return Value

An integer, or 0 if an error occurred.

Discussion

It is sometimes useful to know the process identification number of the application owning the receiver. For example, it can be used with a variety of Carbon functions to access information not otherwise readily available in Cocoa. 0 is never a valid PID.

The PID returned by this method can be used even if the receiver has been destroyed in the running application (for example, a window has closed).

See also PFApplicationUIElement's -pidNumber, which returns the PID as a Cocoa NSNumber object.


roleDefinitions


Class method returns an NSDictionary object containing information about all accessibility attribute roles and subroles.

+ (NSDictionary *)roleDefinitions; 
Return Value

A dictionary containing information about all accessibility attribute roles and subroles.

Discussion

This class method returns a dictionary containing the technical names and other features of all accessibility attribute roles and subroles as listed in the AccessibilityDefinitions.plist file installed at /System/Library/Accessibility/AccessibilityDefinitions.plist starting with Mac OS X 10.7 (Lion). It reads information from the roles dictionary in the plist file. Subrole strings are in the form role:subrole.


setDelegate:


Sets the receiver's delegate to object.

- (void)setDelegate:(nullable id <PFUIElementDelegate>)object; 
Parameters
object

An object of any type, or nil to remove an existing delegate.

Discussion

The delegate must adopt the PFUIElementDelegate formal protocol to receive delegate messages.

The delegate methods, both of which are optional, are declared in the PFUIElementDelegate protocol. If it is implemented by the delegate, a delegate method is automatically called when the UI element represented by the receiver is destroyed in the user interface or an error is reported. The delegate must adopt the PFUIElementDelegate formal protocol to receive delegate messages.

The only available delegate messages are -PFUIElementWasDestroyed: and -PFUIElementReportError:, which are optional. If the delegate implements the PFUIElementWasDestroyed: delegate method, it is automatically registered to receive PFUIElementWasDestroyedNotification. Other objects can register to observe that notification, as well.

See the -PFUIElementWasDestroyed: delegate method for important information about detecting when a UI element is destroyed in the running application's user interface.

See also -delegate.


setElementInfo:


Caches information about the receiver.

- (void)setElementInfo:(nullable NSDictionary *)info; 
Parameters
info

An NSDictionary object using NSString constants from the NSAccessibility informal protocol as keys.

Discussion

See -elementInfo for details regarding the information that is cached. This message is sent automatically when a new PFUIElement or PFApplicationUIElement object is created. You can send it again if, for example, you want to update the receiver's cached title when the UI element's title changes.

You can add key-value pairs of your own to the dictionary before sending this method, if you want to cache additional information about the receiver. In that case, you can retrieve the information from the dictionary returned by -elementInfo using the keys you added.

See also -elementInfo.


setElementRef:


Sets the receiver's accessibility API AXUIElementRef opaque object to ref.

- (void)setElementRef:(AXUIElementRef)ref; 
Parameters
ref

An opaque accessibility API object representing a UI element in the target application.

Discussion

Use this method to finish initializing the receiver if nil was passed to the -initWithElementRef:delegate: method when the receiver was created. You should call -setElementInfo: at the same time.

See -initWithElementRef:delegate: for information about how to obtain AXUIElementRef objects to use with this method.

See also -elementRef.


setExists:


Sets whether the receiver exists in the running application to flag.

- (void)setExists:(BOOL)flag; 
Parameters
flag

YES if the receiver exists in the running application; NO, if not.

Discussion

If flag is passed as NO, the -exists method thereafter reports that the receiver has been destroyed. This method does not actually destory the receiver, and it does not send PFUIElementWasDestroyedNotification. Use it only to mark elements as destroyed when their container has been destroyed.

Due to the design of the accessibility API, some UI elements do not issue NSAccessibilityUIElementDestroyedNotification when the UI element containing them is destroyed, such as a Cocoa window's title and grow area elements. Apple advises that all UI elements descended from a destroyed element should nevertheless be considered destroyed.

This method enables a client to mark any UI element as destroyed in response to notification that an ancestor has been destroyed. If this technique is not adopted, a prudent client should always anticipate that a PFUIElement object it is accessing might not exist, in case -exists returns an incorrect result. There is no better way to deal with this issue; using an accessibility API function to access a destroyed UI element is not guaranteed to return an error because AXUIElementRef objects are recycled and therefore might refer to another valid UI element.

IMPORTANT: If flag is passed as NO, it is the client's responsibility to unregister this element for all notifications by sending -unregisterForAllNotificationsFromElement: to all relevant observers. Since by definition this element did not post a notification when it was destroyed, it is also the client's responsibility to ensure that all other PFUIElement objects representing the same UI Element are marked as destroyed.

There should be no reason to pass flag as YES.

See also -exists.


setMessagingTimeout:


Sets the receiver's timeout to timeoutInSeconds.

- (void)setMessagingTimeout:(float)timeoutInSeconds; 
Parameters
timeoutInSeconds

A float representing a number of seconds.

Discussion

Pass 0.0 to set the timeout to the default global timeout for the target application.

If the receiver is the root application UI element, this method sets the global timeout for all UI elements in the target application.

When any accessibility call fails to work within the timeout period, a kAXErrorCannotComplete error is generated.


setValue:forAttribute:


Sets the value of attribute to object.

- (BOOL)setValue:(id)object forAttribute:(NSString *)attribute; 
Parameters
object

An object of any appropriate type.

attribute

An NSString representing a non-parameterized attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

YES if the value was successfully set; NO, if not.

Discussion

This method sets the value of attribute to object if attribute is a non-parameterized attribute, returning YES if successful. It always returns NO if attribute is a parameterized attribute.

Use this method to set the value of a non-parameterized attribute in the general case, when you don't know which attribute you will receive. Also use this method when this framework does not include, or you prefer not to use, a specific attribute accessor method, when this framework does not implement a specific attribute accessor method, or when attribute is a custom application attribute.

It is your responsibility to ensure that object is an object of an appropriate type for attribute and, in the case of objects of type point, size, rect, and range, that the values that object encodes make sense for attribute (for example, that windows are on screen, have positive width and height values, and are within the limits of the macOS window server).

This method uses key-value coding to send the appropriate specific attribute accessor method, if it is implemented, falling back to a private generic method if a specific attribute accessor method is not implemented for attribute.

Some applications mark attributes as settable when in fact they cannot be modified, and it is possible that this method will return YES even if the value of the attribute was not successfully set. It is the client's responsibility to deal with such false positives, if necessary, perhaps by testing the value of the attribute after setting it to see if the value was successfully changed. We don't perform such a test here because it is relatively expensive.

See also -valueForAttribute:.


typeForAttribute:


Returns a non-localized string for the data type of the value of attribute.

- (nullable NSString *)typeForAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing an attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An NSString object describing the data type of attribute, or nil if attribute does not exist or has no value.

Discussion

Returns a non-localized string for the data type of the value of attribute.

These type identifiers are unique to the PFAssistive framework; Apple's accessibility API has no equivalent. They are used for program control in the PFAssistive framework, and a client application can use them in a similar fashion, for example, as table column identifiers. According to AccessibilityDefinitions.plist, he possible strings are "array", "attributed string", "Boolean", "data", "number", "point", "range", "rect", "size", "string", "UIElement" and "URL". It appears that "date" is also a possible value. This method returns "unknown" if it cannot determine the type. This method does not return "text marker" or "text marker range" because they are marked as private in AccessibilityDefinitions.plist.

This method returns a string for the structured types point, size, rect, and range when appropriate. It may return a string for an unknown type or nil if attribute does not exist or has no value.

In the case of non-parameterized attributes, this method gets the attribute's value first and then determines its type.

For a localized string describing the data type of attribute, use -descriptionOfTypeForAttribute:.


UIElementWithElementRef:delegate:


Convenience class method creates and returns an initialized PFUIElement object.

+ (nullable instancetype)UIElementWithElementRef:(nullable AXUIElementRef)uiElementRef 
        delegate:(nullable id)aDelegate; 
Parameters
uiElementRef

An opaque accessibility API object representing a UI element in the target application. May be nil.

aDelegate

An object that may implement the optional -PFUIElementWasDestroyed: or -PFUIElementReportError: delegate method. May be nil.

Return Value

An initialized PFUIElement object, or nil if the target application is not running or the UI element does not exist in the target application's user interface.

Discussion

Use this convenience method to create and return an initialized PFUIElement object with uiElementRef, an opaque accessibility API AXUIElementRef object.

See the designated initializer, -initWithElementRef:delegate: for important information about creating new UI element objects.


valueForAttribute:


Returns the value of attribute.

- (nullable id)valueForAttribute:(NSString *)attribute; 
Parameters
attribute

An NSString representing a non-parameterized attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An object of an appropriate type, or nil if attribute is a parameterized attribute.

Discussion

Returns the value of attribute as an object of an appropriate type.

Use this method to get the value of a non-parameterized attribute in the general case, when you don't know which attribute you will receive. Also use this method when this framework does not include, or you prefer not to use, a specific attribute accessor method, when this framework does not implement a specific attribute accessor method, or when attribute is a custom application attribute.

This method uses key-value coding to send the appropriate specific attribute accessor method, if it is implemented, falling back to a private generic method if a specific attribute accessor method is not implemented for attribute.

The attribute parameter should be a non-parameterized attribute. See -typeForAttribute: for a list of recognized attribute value types.

See also -setValue:forAttribute:.


valueForAttribute:atIndex:


Returns the value of the item at index in the array returned by attribute.

- (nullable id)valueForAttribute:(NSString *)attribute 
        atIndex:(NSUInteger)index; 
Parameters
attribute

An NSString representing an array attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

index

The index of the desired value in the array.

Return Value

An object of an appropriate type, or nil if index is not in the range of the array returned by attribute.

Discussion

Returns the value of the item at index in the array returned by attribute.

Use this method to get an object at any index in the value of an array attribute.

The attribute parameter should be an array attribute.

See -typeForAttribute: for a list of recognized attribute value types.


valueForAttribute:parameter:


Returns the value of attribute for parameter.

- (nullable id)valueForAttribute:(NSString *)attribute 
        parameter:(id)parameter; 
Parameters
attribute

An NSString representing a parameterized attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

parameter

An object of the type required by the parameterized attribute.

Return Value

An object of an appropriate type, or nil if attribute is a non-parameterized attribute.

Discussion

Returns the value of attribute for parameter.

Use this method to get the value of a parameterized attribute in the general case, when you don't know which attribute you will receive.

The attribute parameter should be a parameterized attribute.

See -typeForAttribute: for a list of recognized attribute value types.


valuesForAttribute:range:


Returns the values of attributes in range.

- (nullable NSArray *)valuesForAttribute:(NSString *)attribute 
        range:(NSRange)range; 
Parameters
attribute

An NSString representing an array attribute; may be a constant from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An array of objects of any type.

Discussion

Returns the values of attribute in range.

Use this method to get multiple objects at once for the non-parameterized attributes in the attribute array, restricted to range. It is not an error if the length of range exceeds the number of array elements remaining from the location of range; instead, the returned array will contain the remaining array elements.

Use this method instead of AXChildren when the attribute array is very large, in order to process the array in small pieces. For example, this method can bring in a small number of array elements in order to make them visible in increments when a table view is scrolled.

The attribute parameter should be an array of non-parameterized attributes.


valuesForAttributes:


Returns the values of attributes.

- (nullable NSArray *)valuesForAttributes:(NSArray<NSString *> *)attributes; 
Parameters
attributes

An NSArray of NSStrings representing non-parameterized attributes; may be constants from the NSAccessibility informal protocol or from AXAttributeConstants.h in the accessibility API cast to NSString*, or the string itself.

Return Value

An array of objects of any type.

Discussion

Returns the values of attributes.

Use this method to get multiple objects at once for the non-parameterized attributes in the attributes array. This method has performance advantages over getting attributes individually.

The attributes parameter should be an array of non-parameterized attributes.