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.

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 made a trusted process 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.

+UIElementWithElementRef:delegate:

Convenience class method creates and returns an initialized PFUIElement object.

 

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.

+UIElementWithElementRef:delegate:

Convenience class method creates and returns an initialized PFUIElement object.

-valueForAttribute:

Returns the value of attribute.

-valueForAttribute:atIndex:

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

-valueForAttribute:parameter:

Returns the value of attribute for parameter.

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


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: , -initWithURL:delegate: , -initWithBundleIdentifier:delegate: or -initWithPid:delegate: method, or their corresponding convenience factory methods, when you want to browse an application's UI elements from its root application element without reading the screen;

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

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

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

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

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

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


invalidate


Invalidates this PFUIElement object when it is no longer needed.

- (void)invalidate; 
Discussion

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

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


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


UIElementWithElementRef:delegate:


Convenience class method creates and returns an initialized PFUIElement object.

+ (PFUIElement *)UIElementWithElementRef:(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 object, or nil if the target application is not running or the UI element does not exist in the target application's user interface.

Discussion

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

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


valueForAttribute:


Returns the value of attribute.

- (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: Monday, July 19, 2010