PFUIElement |
A concrete class representing a UI element in a running application.
Superclass: NSObject
Declared In: PFUIElement.h
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.
Returns the technical, non-localized names of all actions implemented by the receiver.
Returns an array of the technical, non-localized names of all attributes recognized by the receiver.
Returns the technical, non-localized names of all non-parameterized attributes recognized by the receiver.
Returns the technical, non-localized names of all parameterized attributes recognized by the receiver.
Class method returns a localized string describing notification, suitable for display or speech.
Class method returns the technical, non-localized names all notifications recognized by the accessibility API in the currently-running version of Mac OS X.
Returns a string describing the receiver.
Returns the technical, non-localized names of all notifications issued by the receiver.
Returns an attributed string suitable for display in a text view, converted from an accessibility attributed string.
Returns the number of children the receiver contains.
Returns a localized string describing attribute, suitable for display or speech.
Returns a localized string describing subrole, suitable for display or speech.
Returns a localized string describing the data type of attribute, suitable for display or speech.
Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute.
Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute as a non-parameterized attribute.
Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute as a parameterized attribute.
Returns whether the UI element represented by the receiver still exists in the running application, recognizes attribute, and attribute has a value.
Returns whether attribute is a parameterized attribute.
Returns whether the receiver represents a UI element whose AXRole attribute is role.
Returns whether attribute can be modified.
Sets the value of attribute to object.
Returns a non-localized string for the data type of the value of attribute.
Returns the value of attribute.
Returns the value of the item at index in the array returned by attribute.
Returns the value of attribute for parameter.
Returns the values of attributes.
Returns information about the receiver that was cached when the receiver was created, and that may have been modified later.
Returns the accessibility API AXUIElementRef opaque object that was associated with the receiver when the receiver was created.
Caches information about the receiver.
Sets the receiver's accessibility API AXUIElementRef opaque object to ref.
Creates and returns a root application PFUIElement object representing the application owning the receiver.
Returns an NSRect structure representing the origin and size of the portion of the receiver that is visible in its container.
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.
Class method returns all PFUIElement objects having attribute role in array.
Returns whether the UI element represented by the receiver still exists in the running application.
Class method returns the first PFUIElement object with attribute role in array.
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.
Returns whether element and the receiver represent the same UI element in the target application.
Returns whether element and the receiver have the same parent.
Returns whether the UI element represented by the receiver is visible at point on the screen.
Returns an array of PFUIElement objects representing the containment hierarchy of the receiver, excluding the receiver itself.
Returns and array of PFUIElement objects representing the containment hierarchy of the receiver, including the receiver itself.
Returns the BSD Unix process identification number (PID) of the application owning the receiver.
Sets whether the receiver exists in the running application to flag.
Sets the receiver's timeout to timeoutInSeconds.
Returns the receiver's delegate.
Sets the receiver's delegate to object.
Brings the target application to the front, returning YES if successful.
Class method reports whether global access for assistive devices is enabled.
Class method reports whether the accessibility API is implemented on this computer.
Class method reports whether the client application's process is trusted.
Initializes and returns a newly allocated PFUIElement object.
Invalidates this PFUIElement object when it is no longer needed.
Reports whether this PFUIElement object has been invalidated.
Returns a localized string describing action, suitable for display or speech.
Returns whether the receiver still exists in the running application and can perform action.
Causes the receiver to perform action, returning YES if successful.
Returns the technical, non-localized names of all actions implemented by the receiver.
Brings the target application to the front, returning YES if successful.
Creates and returns a root application PFUIElement object representing the application owning the receiver.
Returns an attributed string suitable for display in a text view, converted from an accessibility attributed string.
Returns an array of the technical, non-localized names of all attributes recognized by the receiver.
Returns the number of children the receiver contains.
Returns an NSRect structure representing the origin and size of the portion of the receiver that is visible in its container.
Returns the receiver's delegate.
Returns a string describing the receiver.
Returns a localized string describing action, suitable for display or speech.
Returns a localized string describing attribute, suitable for display or speech.
Class method returns a localized string describing notification, suitable for display or speech.
Returns a localized string describing subrole, suitable for display or speech.
Returns a localized string describing the data type of attribute, suitable for display or speech.
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.
Returns information about the receiver that was cached when the receiver was created, and that may have been modified later.
Returns the accessibility API AXUIElementRef opaque object that was associated with the receiver when the receiver was created.
Class method returns all PFUIElement objects having attribute role in array.
Returns whether the UI element represented by the receiver still exists in the running application.
Returns whether the receiver still exists in the running application and can perform action.
Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute.
Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute as a non-parameterized attribute.
Returns whether the UI element represented by the receiver still exists in the running application and recognizes attribute as a parameterized attribute.
Returns whether the UI element represented by the receiver still exists in the running application, recognizes attribute, and attribute has a value.
Class method returns the first PFUIElement object with attribute role in array.
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.
Initializes and returns a newly allocated PFUIElement object.
Invalidates this PFUIElement object when it is no longer needed.
Class method reports whether global access for assistive devices is enabled.
Class method reports whether the accessibility API is implemented on this computer.
Returns whether element and the receiver represent the same UI element in the target application.
Returns whether attribute is a parameterized attribute.
Class method reports whether the client application's process is trusted.
Returns whether the receiver represents a UI element whose AXRole attribute is role.
Returns whether attribute can be modified.
Returns whether element and the receiver have the same parent.
Reports whether this PFUIElement object has been invalidated.
Returns whether the UI element represented by the receiver is visible at point on the screen.
Returns the technical, non-localized names of all non-parameterized attributes recognized by the receiver.
Returns the technical, non-localized names of all notifications issued by the receiver.
Class method returns the technical, non-localized names all notifications recognized by the accessibility API in the currently-running version of Mac OS X.
Returns the technical, non-localized names of all parameterized attributes recognized by the receiver.
Returns an array of PFUIElement objects representing the containment hierarchy of the receiver, excluding the receiver itself.
Returns and array of PFUIElement objects representing the containment hierarchy of the receiver, including the receiver itself.
Causes the receiver to perform action, returning YES if successful.
Returns the BSD Unix process identification number (PID) of the application owning the receiver.
Sets the receiver's delegate to object.
Caches information about the receiver.
Sets the receiver's accessibility API AXUIElementRef opaque object to ref.
Sets whether the receiver exists in the running application to flag.
Sets the receiver's timeout to timeoutInSeconds.
Sets the value of attribute to object.
Returns a non-localized string for the data type of the value of attribute.
Returns the value of attribute.
Returns the value of the item at index in the array returned by attribute.
Returns the value of attribute for parameter.
Returns the values of attributes.
actions |
Returns the technical, non-localized names of all actions implemented by the receiver.
- (NSArray *)actions;
An array of NSString objects, or an empty array if the receiver does not recognize any actions.
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;
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;
The receiver's PFApplicationUIElement object.
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;
AXAttributedStringAn NSAttributedString with accessibility text attributes, returned by the -AXAttributedStringForRange: parameterized attribute method.
An NSAttributedString object with standard Cocoa text system attributes.
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;
An array of NSString objects, or an empty array if the receiver does not recognize any attributes.
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;
An integer counting the receiver's children.
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;
An NSRect structure representing the intersection of the element's visible rectangle and the rectangle of its smallest ancestor.
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;
The receiver's delegate, an object of any type, or nil if it has no delegate.
-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;
An NSString object.
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;
actionAn 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.
An NSString object, or nil if action can't be performed by the receiver.
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;
attributeAn 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.
An NSString object, an empty string if the receiver does not implement attribute.
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;
notificationAn 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.
An NSString object.
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;
subroleAn 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.
An NSString object, an empty string if the receiver does not implement attribute.
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;
attributeAn 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.
An NSString object, an empty string if the receiver does not implement attribute.
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;
pointAn NSPoint structure using top-left relative screen coordinates.
delegateAn object that may implement the optional -PFUIElementWasDestroyed: or -PFUIElementReportError: delegate method. May be nil.
errorAn indirect reference to an NSError object describing the error if the result is nil. Pass NULL if you don't care about the error.
The PFUIElement object at point, or nil if an error occurred.
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;
An NSDictionary object using NSString constants from the NSAccessibility informal protocol as keys.
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;
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.
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;
rolean 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.
arrayAn array of PFUIElement objects.
An array of PFUIElement objects with attribute role, or an empty array if none exists in array.
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;
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;
actionAn 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.
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;
attributeAn 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.
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;
attributeAn 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.
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;
attributeAn 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.
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;
attributeAn 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.
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;
rolean 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.
arrayAn array of PFUIElement objects.
The first PFUIElement object with attribute role, or nil if none exists in array.
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;
arrayAn array of PFUIElement objects.
The receiver's index among like elements in array, or NSNotFound if the receiver is not in array.
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;
uiElementRefAn opaque accessibility API object representing a UI element in the target application.
aDelegateAn object that may implement the optional -PFUIElementWasDestroyed: or -PFUIElementReportError: delegate method. May be nil.
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.
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;
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;
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;
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;
elementA PFUIElement or PFApplicationUIElement object to be tested for equality with the receiver.
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;
attributeAn 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.
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;
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
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;
roleAn 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.
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;
attributeAn 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.
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;
elementA PFUIElement or PFApplicationUIElement object to be compared with the receiver.
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;
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;
pointAn NSPoint structure representing a point on the screen in top-left relative screen coordinates.
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;
An array of NSString objects, or an empty array if the receiver does not recognize any non-parameterized attributes.
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;
An NSArray of NSString objects. All UI elements issue some notifications.
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;
An array of NSString objects.
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;
An array of NSString objects, or an empty array if the receiver does not recognize any parameterized attributes.
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;
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.
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;
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.
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;
actionAn 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.
YES if the action was successfully performed; NO, if not.
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;
An integer, or 0 if an error occurred.
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;
objectAn object of any type, or nil to remove an existing delegate.
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;
infoAn NSDictionary object using NSString constants from the NSAccessibility informal protocol as keys.
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;
refAn opaque accessibility API object representing a UI element in the target application.
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;
flagYES if the receiver exists in the running application; NO, if not.
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;
timeoutInSecondsA float representing a number of seconds.
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;
objectAn object of any appropriate type.
attributeAn 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.
YES if the value was successfully set; NO, if not.
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
See also -valueForAttribute:.
typeForAttribute: |
Returns a non-localized string for the data type of the value of attribute.
- (NSString *)typeForAttribute:(NSString *)attribute;
attributeAn 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.
An NSString object describing the data type of attribute.
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;
attributeAn 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.
An object of an appropriate type, or nil if attribute is a parameterized attribute.
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;
attributeAn 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.
indexThe index of the desired value in the array.
An object of an appropriate type, or nil if index is not in the range of the array returned by attribute.
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;
attributeAn 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.
parameterAn object of the type required by the parameterized attribute.
An object of an appropriate type, or nil if attribute is a non-parameterized attribute.
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;
attributesAn 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.
An array of objects of any type.
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