# PFUIElement

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

Superclass: NSObject
Declared In: PFUIElement.h

##### 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 focused UI element in a target application. 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 string, usually beginning with the prefix "AX" as in "AXRole" or "AXPress". In a client 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 string itself. 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 Mac OS X.

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

The following new roles and subroles were introduced in Mac OS X v10.6: NSAccessibilityLevelIndicatorRole, NSAccessibilityCellRole, NSAccessibilityLayoutAreaRole, NSAccessibilityLayoutItemRole, NSAccessibilityHandleRole, NSAccessibilitySortButtonSubrole, NSAccessibilityRatingIndicatorSubrole, NSAccessibilityContentListSubrole, and NSAccessibilityDefinitionListSubrole. NSAccessibilitySortButtonRole is available but deprecated in Mac OS X v10.6. Attributes that were introduced in Mac OS X v10.6 are noted in the Attributes category.

Class Design:

Before a client application can make use of this class, the "Enable access for assistive devices" setting in the Universal Access pane of System Preferences must be turned on, or the client application must be trusted through use of the accessibility API's `AXMakeProcessTrusted()` function. Authentication may be required.

## Groups

### ACTIONS

#### Group members:

`-actions`

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

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

### NOTIFICATION UTILITIES

#### Group members:

`+descriptionForNotification:`

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

`+notifications`

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

### DEBUGGING UTILITIES

#### Group members:

`-description`

  Returns a string describing the receiver.

### NOTIFICATIONS

#### Group members:

`-notifications`

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

### ATTRIBUTE UTILITIES

#### Group members:

`-attributedStringFromAXAttributedString:`

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

`-childrenCount`

  Returns the number of children the receiver contains.

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

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

`-valuesForAttributes:`

  Returns the values of `attributes`.

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

`-setElementInfo:`

  Caches information about the receiver.

`-setElementRef:`

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

### UI ELEMENT UTILITIES

#### Group members:

`-applicationElement`

  Creates and returns a root application PFUIElement 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`.

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

`-parentPath`

  Returns an array of PFUIElement objects representing the containment hierarchy of the receiver, excluding the receiver itself.

`-path`

  Returns and array of PFUIElement objects representing the containment hierarchy of the receiver, including the receiver itself.

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

### DELEGATE ACCESSORS

#### Group members:

`-delegate`

  Returns the receiver's delegate.

`-setDelegate:`

  Sets the receiver's delegate to `object`.

### CLASS UTILITIES

#### Group members:

`-activateApplication`

  Brings the target application to the front, returning `YES` if successful.

`+isAccessEnabled`

  Class method reports whether global access for assistive devices is enabled.

`+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.

### 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 invalidated.

### ACTION UTILITIES

#### Group members:

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

## Methods

`-actions`

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

`-activateApplication`

  Brings the target application to the front, returning `YES` if successful.

`-applicationElement`

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

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

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

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

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

`+isAccessImplemented`

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

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

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

`-notifications`

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

`+notifications`

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

`-parameterizedAttributes`

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

`-parentPath`

  Returns an array of PFUIElement objects representing the containment hierarchy of the receiver, excluding the receiver itself.

`-path`

  Returns and array of PFUIElement objects representing the containment hierarchy of the receiver, including the receiver itself.

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

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

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

`-valuesForAttributes:`

  Returns the values of `attributes`.

### actions

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

    - (NSArray *)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.

### activateApplication

Brings the target application to the front, returning `YES` if successful.

    - (BOOL)activateApplication;

##### Discussion

The target application must be frontmost before some PFAssistive framework methods can be used. For example, it is necessary to make a target 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 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.

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 PFUIElement object representing the application owning the receiver.

    - (PFApplicationUIElement *)applicationElement;

##### Return Value

The receiver's PFApplicationUIElement object.

##### Discussion

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

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

### attributes

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

    - (NSArray *)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. Where a specific accessor applies to a particular kind of UI element, this document indicates the kind by referring, for example, to the "receiving window," the "receiving menu item," the "receiving stepper" or the "receiving table view or outline view." Bear in mind, however, that 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.

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. The -valueForAttribute: method automatically sends the appropriate specific attribute accessor method, if one exists for the attribute, and return 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.

### childrenCount

Returns the number of children the receiver contains.

    - (NSUInteger)childrenCount;

##### Return Value

An integer counting the receiver's children.

##### Discussion

This method counts the number of PFUIElement objects in the receiver's children array attribute value.

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

### delegate

Returns the receiver's delegate.

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

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

    - (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`.

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

    + (PFUIElement *)elementAtPoint:(NSPoint)point withDelegate:(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, 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.

    - (NSDictionary *)elementInfo;

##### Return Value

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

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

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

##### 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 or finalized.

See also -setElementRef:.

### elementsWithRole:inArray:

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

    + (NSArray *)elementsWithRole:(NSString *)role inArray:(NSArray *)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` 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 -setExists:.

### 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`.

    + (PFUIElement *)firstElementWithRole:(NSString *)role
            inArray:(NSArray *)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 *)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.

### initWithElementRef:delegate:

Initializes and returns a newly allocated PFUIElement object.

    - (id)initWithElementRef:(AXUIElementRef)uiElementRef
            delegate:(id)aDelegate;

##### 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: or -initWithPid:delegate: method, 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, 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.

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.

See also PFApplicationUIElement's -initWithPath:delegate:, -initWithPid:delegate: and -initSystemWideWithDelegate:.

### 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 will be desirable to call this method in a garbage collected environment to avoid adding time-consuming activity at collection time (and it does no harm to call it in a reference counted environment). If the client application does not call this method, it will be called automatically when the object is deallocated or finalized. It sets any delegate to `nil`, unregisters an internal destruction observer and takes care of memory management.

Invalidation is not related to -exists, which reports 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: This version of PFAssistive Framework does not support garbage collected clients.

See also -isValid.

### isAccessEnabled

Class method reports whether global access for assistive devices is enabled.

    + (BOOL)isAccessEnabled;

##### Discussion

Returns `YES` if global access for assistive devices is enabled in the Universal Access pane of System Preferences. In Mac OS X 10.5 Leopard, this setting is also available as the GUI Scripting setting in AppleScript Utility.

Enabling global access for assistive devices is usually done manually, although it can also be done using an AppleScript command addressed to AppleScript Utility. AppleScript Utility is scriptable in Leopard, and it is a scriptable faceless background application in Mac OS X 10.6 Snow Leopard. Enabling this setting requires user authentication.

Access for assistive devices is turned off by default, 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 on one of these settings manually. One technique is to send the `isAccessEnabled` message in a client application's `-awakeFromNib` method and, if the result is `NO`, present an alert explaining how the user can turn the setting on.

A more user-friendly technique is to enable access for assistive devices for the user with an AppleScript command using Scripting Bridge. For this to work, the developer of an assistive application must use the sdef and sdp tools to generate a System Events.h header file, which must be added to the project before compiling. The SBApplication.framework must be linked. Here is an action method that toggles the state of the setting:

     - (IBAction)setAccessAllAction:(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 trusted. See +isProcessTrusted for information about making a client application trusted.

See also -isAccessImplemented and -isProcessTrusted.

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

See also -isAccessEnabled and -isProcessTrusted.

### 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

Returns `YES` if the client applicatiion's process is trusted

A trusted process is typically an assistive application that was made trusted by the user when it was installed or first run. This feature is part of Apple's movement away from the global on/off model of the Universal Access pane of System Preferences and AppleScript Utility, toward a per-application security model. Individual assistive applications may be labeled as trusted in order to make use of the accessibility API without turning on access globally for all applications.

A process is untrusted by default, and client applications typically cannot use the methods of the PFAssistive framework unless they arrange to enable access for assistive devices. See +isAccessEnabled for information about enabling access for assistive devices.

Assistive applications can use the trusted process technique to avoid forcing the user to enable access for all applications globally, which might be viewed as a security risk in sensitive environments. However, Apple's GUI Scripting technology for AppleScript requires that access be enabled globally, so an assistive application related to GUI Scripting should allow the user to enable global access.

For an assistive application to become trusted, it must present an authorization dialog and then run a small embedded helper application as root to call the `AXMakeProcessTrusted()` function. The assistive application can use the SFAuthorization framework to present the dialog. The application should first call `isProcessTrusted` to test whether it is already trusted. Then, if it is not and if the user successfully authenticates, it should run the helper application to call the AXMakeProcessTrusted() function, passing in the path to the target application's executable. The assistive application must then be terminated and relaunched for its new trusted status to take effect. The helper application should be placed in the Resources subfolder in the assistive application's bundle.

Note that the PFAssistive framework cannot be embedded in an assistive application's bundle. For security reasons, Apple prevents embedded frameworks from using the accessibility API. An assistive application must use an installer package, instead, to install the application and to install the framework in /Library/Frameworks/.

The PFAssistive framework does not implement a Cocoa wrapper method for the `AXMakeProcessTrusted()` function, because it would not be prudent to run an assistive application as root. Instead, it is the developer's responsibility to implement a small helper application, give it root privileges, obtain user authorization, and terminate and relaunch the assistive application.

See also -isAccessImplemented and -isAccessEnabled.

### 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 invalidated.

    - (BOOL)isValid;

##### Discussion

Returns `YES` if this PFUIElement object has 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, not obscured by another application's UI element.

If the UI element represented by the receiver is not visible because another application's UI element is in front of it, then PFUIElement's +elementAtPoint:withDelegate:error: class method cannot read it by its location on the screen. The PFApplicationUIElement's -elementAtPoint: instance method can read it 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 *)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.

### notifications

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

    - (NSArray *)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 Mac OS X 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.

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 PreForm UI Browser's Preferences.

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

- 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.
- 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.
- 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 all notifications recognized by the accessibility API in the currently-running version of Mac OS X.

    + (NSArray *)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 Mac OS X 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.

### parameterizedAttributes

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

    - (NSArray *)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.

### parentPath

Returns an array of PFUIElement objects representing the containment hierarchy of the receiver, excluding the receiver itself.

    - (NSArray *)parentPath;

##### Return Value

An array of PFUIElement objects starting with the root PFApplicationUIElement object, or an empty array if the UI element represented by the receiver has been destroyed in the target 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 array is not empty, its first item is a PFApplicationUIElement object.

### path

Returns and array of PFUIElement objects representing the containment hierarchy of the receiver, including the receiver itself.

    - (NSArray *)path;

##### Return Value

An array of PFUIElement objects starting with the root PFApplicationUIElement object. 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 contains only the receiver, which is now an orphan. 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.

### setDelegate:

Sets the receiver's delegate to `object`.

    - (void)setDelegate:(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:(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 Mac OS X 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 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`.

    - (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`.

##### 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. The possible strings are "array", "Boolean", "number", "point", "range", "rect", "size", "string", "UIElement", "unknown" and "URL".

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

### valueForAttribute:

Returns the value of `attribute`.

    - (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`.

    - (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`.

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

### valuesForAttributes:

Returns the values of `attributes`.

    - (NSArray *)valuesForAttributes:(NSArray *)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.

Last Updated: Wednesday, May 19, 2010