PFUIElement(Attributes)

Extends Class:
Declared In:

Introduction

A category on PFUIElement for attribute properties and methods.

Discussion

The Attributes category on PFUIElement includes two kinds of attributes: nonparameterized attributes and parameterized attributes.

The nonparameterized attributes are declared as properties. To use them, you send a key message to their receivers (where key is the property name, such as AXRole to read the "AXRole" attribute), just as you would use a getter accessor method. They take no parameters, and they return an Objective-C object. To set those that are settable, you send a setKey: message to their receivers passing an Objective-C object (where setKey: incorporates the property name, such as setAXValue: to set the "AXValue" attribute), just as you would use a setter accessor method.

The parameterized attributes are implemented as methods. You send them to a receiver with a parameter, and the value returned depends on the value of the parameter.

The accessor methods specified by the properties in the Attributes category on PFUIElement return UI element attribute values for attributes having the same name as the property. All attributes declared in the AXAttributeConstants.h and NSAccessibility.h headers are included (except where they are marked obsolete). Note that some attributes appear in only one of those headers.

Individual properties are named according to the string value of the attribute, not its constant name in the AXAttributeConstants.h or NSAccessibility.h header. They are classified approximately the same as in AXAttributeConstants.h, which differs in minor ways from the classification in NSAccessibility.h. Classification of attributes is for ease of understanding only and has no functional significance. It can be misleading, because Apple encourages developers to use existing attribute names for custom objects where possible, and they may therefore be used for new purposes.

The properties in this category are mostly for convenience. Instead of using them, you can send -valueForAttribute: and -setValue:forAttribute: with the appropriate accessibility API constant from AXAttributeConstants.h (cast to NSString*) or NSAccessibility.h. These two methods use key-value coding to find and send one of these properties by name or, if it is not found, to fall back on a private method that calls the accessibility API directly. The net effect is that the framework will always find all attributes, even new attributes that are added to the accessibility API in future versions of macOS and custom attributes that are implemented by other applications such as the Finder and Safari. You must send -valueForAttribute: and -setValue:forAttribute: instead of a specific property when you don't know in advance which attribute to use, for example, when using a list of attributes obtained from the -nonParameterizedAttributes method.

There is a slight efficiency advantage in sending an accessor message instead of using the -valueForAttribute: and -setValue:forAttribute: methods. Either technique will execute any special code, such as bug fixes, that is included in a particular accessor method.

All attribute values are Objective-C objects returned autoreleased.

See -attributes for information regarding the use of the attribute properties.