AXAttributeConstants.h

Overview

Each UIElement has a set of attributes that assistive applications use to get information about the UIElement. The list of attributes vary depending on the type of UIElement. The value of some attributes can be changed, while others cannot. For example, changing the "value" attribute of a slider changes the slider's setting.

Attribute values are stored as Core Foundation types, CFTypeRefs, and are reference counted (CFRetain/CFRelease). Some attributes have a particular type associated with them. For example, the "title" attribute, if defined, always has a string value, regardless of the type of UIElement from which it is obtained. A UIElement's "value" attribute, however, varies with the UIElement. For example, a text field's value is a string whereas a checkbox's value is a boolean. You need to explictly test the returned objects, using the CFGetTypeID function, for what type they really are.

Finally, some attribute values hold simple structures, such as CGPoint and CGRect, instead of regular CFTypes. These are still passed between the target and assistive application as CFTypeRefs, but they merely wrap an encoded version of the structure. You need to use the functions AXValueCreate and AXValueGetValue to convert between the structures and CFTypeRefs. Each supported structure has an AXValueType associated with it. The AXValueGetType function returns the AXValueType of the structure contained within a CFTypeRef.

Groups

Value

Attributes

Group members:

kAXValueAttribute

Informational

Attributes

Group members:

kAXDescriptionAttribute

kAXHelpAttribute

kAXRoleAttribute

Identifies the basic type of an element.

kAXRoleDescriptionAttribute

Required for all elements. Even in the worst case scenario where an element cannot figure out what its basic type is, it can still supply the value "unknown".

kAXSubroleAttribute

More specifically identifies the type of an element beyond the basic type provided by kAXRoleAttribute.

kAXTitleAttribute

#defines

#define kAXDescriptionAttribute CFSTR("AXDescription") 

Discussion

A localized, human-readable string that indicates an element's purpose in a way that is slightly more specific than the kAXRoleDescriptionAttribute, but which is less wordy than the kAXHelpAttribute. Typically, the description should an adjective or short phrase that describes the element's usage. For example, the description of a slider in a font panel might be "font size". The string should be all lower-case and contain no punctuation.

Recommended for all elements because it gives the user a concise indication of an element's purpose.

Writable:

No

Value:

A localized, human-readable CFStringRef

#define kAXHelpAttribute CFSTR("AXHelp") 

Discussion

A localized, human-readable CFStringRef that offers help content for an element. This is often the same information that would be provided in a help tag for the element.

Recommended for any element that has help data available.

Writable:

No

Value:

A localized, human-readable CFStringRef

Identifies the basic type of an element.

#define kAXRoleAttribute CFSTR("AXRole") 

Discussion

Required for all elements. Even in the worst case scenario where an element cannot figure out what its basic type is, it can still supply the value kAXUnknownRole.

Writable:

No

Value:

A CFStringRef of one of the role strings defined in this header, or a new role string of your own invention. The string should not be localized, and it does not need to be human-readable. Instead of inventing new role strings, see if a custom element can be identified by an existing role string and a new subrole. See kAXSubroleAttribute.

Carbon Accessorization Notes:

If your HIObjectClass or Carbon Event handler provides the kAXRoleAttribute, it must also provide the kAXRoleDescriptionAttribute.

Required for all elements. Even in the worst case scenario where an element cannot figure out what its basic type is, it can still supply the value "unknown".

#define kAXRoleDescriptionAttribute CFSTR("AXRoleDescription") 

Discussion

A localized, human-readable string that an assistive application can present to the user as an explanation of an element's basic type or purpose. Examples would be "push button" or "secure text field". The string's language should match the language of the app that the element lives within. The string should be all lower-case and contain no punctuation.

Two elements with the same kAXRoleAttribute and kAXSubroleAttribute should have the same kAXRoleDescriptionAttribute.

Writable:

No

Value:

A localized, human-readable CFStringRef

Carbon Accessorization Notes:

The HIObjectClass or Carbon Event handler that provides the AXRole and/or AXSubrole for an element is the one that must also handle the AXRoleDescription attribute. If an HIObjectClass or Carbon Event handler does not provide either the AXRole or AXSubrole, it must not provide the AXRoleDescription.

More specifically identifies the type of an element beyond the basic type provided by kAXRoleAttribute.

#define kAXSubroleAttribute CFSTR("AXSubrole") 

Discussion

Required only when an element's kAXRoleAttribute alone doesn't provide an assistive application with enough information to convey the meaning of this element to the user.

An example element that offers the kAXSubroleAttribute is a window's close box. Its kAXRoleAttribute value is kAXButtonRole and its kAXSubroleAttribute is kAXCloseButtonSubrole. It is of role kAXButtonRole because it offers no additional actions or attributes above and beyond what other kAXButtonRole elements provide; it was given a subrole in order to allow an assistive app to communicate the close box's semantic difference to the user.

Writable:

No

Value:

A CFStringRef of one of the subrole strings defined in this header, or a new subrole string of your own invention. The string should not be localized, and it does not need to be human-readable.

Carbon Accessorization Notes:

If your HIObjectClass or Carbon Event handler provides the kAXSubroleAttribute, it must also provide the kAXRoleDescriptionAttribute.

#define kAXTitleAttribute CFSTR("AXTitle") 

Discussion

The localized, human-readable string that is displayed as part of the element's normal visual interface. For example, an OK button's kAXTitleElement is the string "OK", and a menu item's kAXTitleElement is the text of the menu item.

Required if the element draws a string as part of its normal visual interface.

Writable:

No

Value:

A localized, human-readable CFStringRef

#define kAXValueAttribute CFSTR("AXValue") 

Discussion

A catch-all attribute that represents a user modifiable setting of an element. For example, the contents of an editable text field, the position of a scroll bar thumb, and whether a check box is checked are all communicated by the kAXValueAttribute of their respective elements.

Required for many user manipulatable elements, or those whose value state conveys important information.

Writable:

Generally yes. However, it does not need to be writable if some other form of direct manipulation is more appropriate for causing a value change. For example, a kAXScrollBar's kAXValueAttribute is writable because it allows an efficient way for the user to get to a specific position in the element being scrolled. By contrast, a kAXCheckBox's kAXValueAttribute is not settable because underlying functionality of the check box widget relies on it being clicked on; therefore, it changes its own kAXValueAttribute appropriately in response to the kAXPressAction.

Required for many user manipulatable elements, or those whose value state conveys important information.

Value:

Varies, but will always be the same type for a given kind of element. Each role that offers kAXValueAttribute will specify the type of data that will be used for its value.

Did this document help you? Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.