---

The Accessibility Object

An accessibility object provides to assistive applications information about the user-interface object it represents. This information includes the object’s position in the accessibility hierarchy, its position on the display, details about what it is, and what actions it can perform. In addition, an accessibility object responds to messages sent by assistive applications and sends out notifications that describe changes in its state.

This section describes the accessibility object. It describes the information an accessibility object provides and the actions it can perform and outlines the communication between accessibility objects and assistive applications.

In this section:

Attributes
Actions

Attributes

An accessibility object has many attributes associated with it. The number and kind of attributes vary depending on the type of user interface object the accessibility object represents. A few attributes are required for every accessibility object, but most are optional.

Attributes have values that assistive applications use to find out about the user interface object. For example, an assistive application gets the value of an accessibility object’s role attribute to find out what type of user interface object it represents.

Some attribute values are settable by assistive applications. An example is the value attribute in an accessibility object that represents an editable text field. When a user types in the text field, an assistive application sets the value of the value attribute to the text the user enters.

If you use standard, noncustom Cocoa or Carbon objects most of the attribute values are already in place. There are a few attribute values, however, that you must provide because they contain application-specific information, such as the description of a user interface object’s function.

The AXAttributeConstants.h file in the HIServices framework defines all the accessibility object attributes in the Mac OS X accessibility protocol. The following sections describe some of the most common required attributes, paying particular attention to the attributes for which you must provide values:

• “The Role and Role Description Attributes”

• “The Description Attribute”

• “Title Attributes”

• “Relationship Attributes”

• “Value Attributes”

The Role and Role Description Attributes

An accessibility object’s most important attribute is its role attribute. This is because the accessibility object’s role determines which other attributes the object contains and tells an assistive application how to handle it. You can think of the role as the accessibility object’s class—it defines a standard set of behaviors and capabilities to which the object conforms. For more information on the attributes associated with specific roles, see “Roles and Associated Attributes.”

The value of the role attribute is a nonlocalized string. An assistive application can programmatically test the value of the role attribute to find out what type of user interface object the accessibility object represents.

In AXRoleConstants.h (in the HIServices framework), Mac OS X defines a set standard roles that describe the vast majority of user interface object types. Although it may be tempting to define new roles for custom objects in your application, it is not recommended. An assistive application may not know how to handle an accessibility object with an arbitrary role and additional roles add unnecessary complexity to your code. Instead, you should examine the behavior of your objects and choose the standard role that best represents them.

The role description attribute contains a human-intelligible, localized string that names the accessibility object’s role. An assistive application presents this string to the user (a screen reader application, for example, speaks the string). Mac OS X defines a role description string for each role in AXRoleConstants.h, so you do not have to provide strings such as “button” or “window”. In the very unlikely event that your application needs to define a new role, however, you are responsible for providing the value of the role description attribute.

The Description Attribute

The description attribute is almost as important as the role attribute. The value of the description attribute is a human-intelligible, localized string that describes what the object does. Because it describes the application-specific function of a user interface object, the accessibility protocol cannot supply the description value. Therefore, it is essential to provide a description for all accessibility objects in your application that do not already include a title attribute (described in “Title Attributes”).

To see why the description attribute is so important, suppose your application window contains a button to left-justify text and which displays a left-pointing arrow. An assistive application can accurately identify this control as a button because it is represented by an accessibility object with the role attribute “button”. However, unless you provide an appropriate description, the assistive application has no way to know that this button left-justifies text, and therefore no way to communicate this to the user.

Title Attributes

The title attribute is required for user interface objects that include a text title in their display. For example, the title of a button is the text that appears on the button, such as the text “OK” on an OK button, and the title of a window is the text that appears in its title bar.

A user cannot change the title of such an object directly, but the title might change programmatically if the state of the object changes. For example, a Connect button’s title might change to Disconnect after a connection is made, but not because a user chose to change the button’s title. An accessibility object that represents such an object must include the title attribute and the attribute’s value must be the title string.

Many applications display static text that serves as the title for a user interface object, but that is not contained in that object. An example is the word “Search” displayed below a search field or “Address:” displayed next to a set of editable text fields. To a sighted user, the proximity of the string to the object (or objects) it describes is usually enough to imply the relationship between them. To an assistive application, however, these strings are unrelated to the objects they describe (if they are visible to the assistive application at all).

Mac OS X version 10.4 introduced two related attributes that give assistive applications information about such titles. The TitleUIElement and ServesAsTitleForUIElements attributes allow you to define the relationship between a piece of static text and the object (or objects) it describes.

The TitleUIElement attribute belongs in the accessibility object representing the object being described. The value of this attribute is the accessibility object you create to represent the static text. The ServesAsTitleForUIElements attribute belongs in the static text accessibility object you’ve created and its value is an array containing an arbitrary number of accessibility objects. This allows you to link the static text title with any number of user interface objects. Although these attributes are not required, you should provide them if your user interface includes such static text titles.

Relationship Attributes

To participate in the accessibility hierarchy, an accessibility object must include links to its immediate ancestor and descendents (if any). This helps an assistive application traverse the hierarchy. In addition, an accessibility object can express other relationships, such as between views that affect each other, but that are not linked by containment.

All accessibility objects, with the exceptions of the application-level and system-wide accessibility objects, include a parent attribute. The value of this attribute is usually the accessibility object representing the closest accessible container of the user interface object.

If a user interface object contains other accessible user interface objects, the UIElement representing it must include the children attribute. The value of this attribute is an array containing the UIElements of the accessible descendents.

Some relationships are conceptual rather than containment-based. For example, it’s not unusual for an application to display two separate views of the same or related content. One example is the Mac OS X Mail application. The Mail application’s upper view can display the subject, sender, and receive date of each message in the selected mail box. In the lower view, Mail can display the body of a message selected in the upper view. To a sighted user, the relationship between the selected message in the upper view and the message content in the lower view is apparent. To an assistive application, on the other hand, this direct relationship doesn’t exist. If an assistive application can’t express such a relationship to a blind user, for example, the user can’t jump back and forth between the related elements the way a sighted user can. Instead, such a user might have to step through all intervening controls and views to move between the message description and its content.

Mac OS X version 10.4 introduced the LinkedUIElements attribute to allow you to define such relationships. As you would expect, the UIElement of each related object should contain this attribute. The value of the attribute is an array of UIElements so you can specify one-to-one and one-to-many relationships.

Value Attributes

The optional value attribute describes the accessibility object’s state. The value might be the state of a check box or the contents of an editable text field.

The value attribute is often settable. For example, an accessibility object that represents a user-modifiable object, such as an editable text field, has a settable value attribute. This allows an assistive application to set the value of the accessibility object’s value attribute to contain the user’s input. Optionally, accessibility objects may also include attributes that define a range or set of values the object can accept, such as minimum and maximum values for a slider.

Actions

Technically, an action is an attribute of an accessibility object. However, the accessibility protocol supports actions differently from the way it supports attributes, so this chapter describes them separately.

An accessibility object can support one or more actions. An action describes how a user interacts with the user interface object the accessibility object represents. It does not describe the application-defined function of the object. This is because an assistive application is concerned with driving the user interface and the results of an action are irrelevant to it. If your application displays a print button, for example, the button’s accessibility object supports a press action, not a print action.

Because actions are generic and refer to the capabilities of user interface objects, there are only a few of them. This means that the set of actions an assistive application has to understand is small and well-defined.

In AXActionConstants.h (located in the HIServices framework), Mac OS X defines seven actions an accessibility object can support:

• Press (a button)

• Increment (the value of a scroller or slider indicator)

• Decrement (the value of a scroller or slider indicator)

• Confirm (the selection of an object)

• Cancel (a selection or action)

• Raise (a window)

• ShowMenu (display a contextual menu associated with an object)

When a user performs an action, an assistive application sends a message to the accessibility object, requesting it to perform the action. Your application should invoke the same code to carry out this action as it does when the request comes directly from your user interface.

Each action attribute has a description property. An assistive application may speak this description to tell the user what action is available for a specific object. The value of this description property is similar to the value of the role description attribute in that it is a human-intelligible, localized word or short phrase. Unlike the role description, however, the action description is not automatically supplied by the accessibility protocol. If your application creates its own accessibility objects which support actions, you must supply the appropriate action descriptions.

---