The object role, state(s), properties, boundary, name, and description shall be programmatically determinable.

Rationale

Someone who is blind or visually impaired uses a computer with the aid of assistive technology (AT) such as a screen reader, screen magnifier, speech recognition or Braille display. Software must provide semantic information about the user interface objects to the AT. This is done through platform specific application programming interfaces (APIs) that programmatically expose information to the AT including name (identity), role (operation), state, boundary, properties and description of user interface objects.

The name attribute is the text string that is used to identify a user interface element to the user. For example, the label preceding an edit control, or the text of a push button function used as the name. Even non-text user interface elements, such as bitmaps, and images have a text string name that can be provided to the assistive technology.

The role provides a description of the type of user interface element and implies the behavior of the element. For example, a role of push button identifies the element as a user interface object that performs an action when activated using the Spacebar or Enter key.

The state is a description of the object's status. For example, a state of focused indicates the object has the keyboard focus.

The boundary of an object, also known as its bounds, describes the location of the object on screen. The description provides additional information about a complex object or custom widget.

In the following sample Windows dialog box, the UI element with the current focus has a role of radio button, a name of "Two" and a state reflecting checked, focused, and focusable. The AT communicates to the user that focus is currently located on the "Two" radio button that has the name "Two," and that there are three radio buttons from which to choose.

A dialog box with three radio buttons.

When the user moves focus to the edit field, the object information returned to the AT reflects a name equal to value, a role of editable text, a state reflecting focused and focusable, and the value is set to “123." In this example, there is no description. The boundary is returned through the getBounds method of each control.

The level of effort to expose object information to assistive technologies depends on how the user interface objects have been created. Standard user interface controls (or widgets) such as Windows controls or Eclipse SWT widgets (push buttons, menu bars and menu items) typically expose object information with no additional implementation needed. Custom controls can be created by building on standard controls, or can be custom drawn. Controls that build on an accessible standard control are often accessible with little effort. Custom drawn controls that are unique to the software do not share any of the standard control definitions and have no inherent accessibility; therefore, all the accessible features must be provided by the software.

Development Techniques

Note: Review the General techniques as well as other tabs applicable to your technology.  Prioritize the use of technology-specific techniques, and implement the General techniques as needed. You are always required to find, understand and implement accessible code techniques to meet the checkpoint. The documented techniques and supplements are not exhaustive; they illustrate acceptable ways to achieve the spirit of the checkpoint. If numbered, techniques are in order of preference, with recommended techniques listed first.

General techniques

Items in this section represents a technique deemed sufficient for specific circumstances.

  • Exposing the accessible attributes for role, state(s), boundary, name and other properties for all standard and custom user interface controls
  • Exposing the description programmatically when a description exists for a control

Note: For software applications, meeting the required development techniques of this checkpoint and the required development techniques of checkpoints 502.3.2 Modification of Object Information, 502.3.4 Values, and 502.3.5 Modification of Values is sufficient for meeting the required development techniques of checkpoint 4.1.2 Name, Role, Value.

Mobile Native (iOS) techniques

In addition to the General techniques, any item in this section represents a technique or combination of techniques deemed sufficient.

Note: The following examples also meet the name and role requirements in checkpoint 4.1.2 Name, Role, Value.

Using the accessibility API features of a technology to expose names and roles, to allow user-settable properties to be directly set, and to provide notification of changes

Software can extend or modify the behavior of standard iOS UI controls to create a custom control by sub-classing or super-classing the standard control. The custom control created may or may not be accessible depending on how the software modified the base control to create the appearance and behavior of the custom control. Software must verify the accessible name, role, state, and, if applicable, value are accessible. This can be done using Accessibility Inspector in the xCode development environment.

Software that creates custom controls must support the UI Accessibility Protocol to expose the object label, focus location, accessibility enabled status, value, traits (roles), and status changes. Developers should refer to the Accessibility Programming Guide for iOS.

A training module on accessibility for custom controls on iOS is available on iTunesU. Search for Stanford University Course CS193D “Developing Apps for iOS," 2010 Sessions, Lecture 18: “Accessibility on iOS: Make an App for Everyone,” guest lecturer Chris Fleizach, Apple Accessibility Development team.

Creating components using a technology that supports the accessibility API features of the user agents' target platforms to expose the names and roles, allow user-settable properties to be directly set, and provide notification of changes

When using the standard iOS controls, developers must set the accessibility attribute of the control that is used as the name of the control.

In Interface Builder, this is done by selecting the Accessibility checkbox Enabled. This is found on the Identity Inspector tab.

This can be done programmatically with the setIsAccessibilityElement and setAccessibilityLabel methods:

[self.myButton setIsAccessibilityElement:YES];
[self.myButton setAccessibilityLabel: @"label text for button"];

Eclipse techniques

In addition to the General techniques, any item in this section represents a technique or combination of techniques deemed sufficient.

When a label provides the name of a control, the Eclipse techniques of Situation A in checkpoint 502.3.6 Label Relationships must also be met.

Using standard interface controls (text)

For standard interface controls, for example a button or a text box, the role, state and bounds are programmatically exposed without additional coding. For standard interface controls that provide a non-empty text string, the text returned through the control’s getText method can be considered the name of the control.

Using standard interface controls (non-text)

For non-text controls created using the org.eclipse.swt.widget.Control, the accessible name must be explicitly established through the getName method of an AccessibleListener added to the control’s Accessible object. Eclipse Snippet 164 Provide text that will be spoken for an image button provides an example of a button that has a text label and an example of an image only button whose accessible name is returned through the getName method.

Implementing AccessibleListener for a control

Any control that extends org.eclipse.swt.widget.Control can be given a name and description that can be retrieved by an assistive technology. This is done by obtaining the control’s accessible object by calling Control.getAccessible, adding an AccessibleListener to the control’s Accessible object and implementing the getName and getDescription methods as shown in the following code sample.

myControl.getAccessible().addAccessibleListener (new AccessibleAdapter() {

              @Override

              public void getName (AccessibleEvent e) {

                     e.result = "My accessible control";

              }

           @Override

              public void getDescription

(AccessibleEvent e) {

                     e.result = "My accessible control description";

              }});

Implement AccessibleListener for control code sample

 

Note: An AccessibleListener can only be added to controls which extend org.eclipse.swt.widget.Control.

Implementing AccessibleListener for a control and its children

An AT may ask for the accessible name of a child item of a control. This can be determined by examining the childID of the AccessibleEvent and then calling getText on the child item.

In the following code sample, an AccessibleListener is added to the Accessible of a tree control. When an AT calls getName, the childID is examined to determine if the name of the tree or of a child tree item should be returned.

tree.getAccessible().addAccessibleListener(new AccessibleAdapter() {

              @Override

              public void getName(AccessibleEvent e) {

                     if (e.childID == ACC.CHILDID_SELF) {

                           e.result = "This is the Accessible Name for the Tree";

                     } else {

TreeItem item = (TreeItem)display.findWidget(tree, e.childID);

                           if (item != null) {

e.result = "This is the Accessible Name for the TreeItem: " + item.getText();

                           }

                     }

              }});

Implement AccessibleListener for control and its children code sample

 

This technique is further demonstrated in Eclipse Snippet 291 - Give accessible names to a tree and its tree items.

Implementing accessible interfaces for custom controls

In Eclipse, custom controls need to include some or all of the following accessible interfaces as they apply to the control:

  • org.eclipse.swt.accessibility.AccessibleListener to programmatically expose name and description, if it exists, of the custom control and its children.
  • org.eclipse.swt.accessibility.AccessibleControlListener to programmatically expose state, role and value of the custom control and its children. Refer to checkpoint 502.3.4 Values for the complete set of required development techniques for returning the value of a control.
  • The getBounds() method to programmatically expose the bounds of the custom control as screen coordinates.

Chapter 6: Custom Controls in the article Creating Accessible Applications in Eclipse - 2nd Edition provides a detailed example of how to return accessible attributes for a custom control and its children.

Notes:

  • Custom controls must expose their role through the getRole method of the AccessibleControlListener. Supported roles are defined in the org.eclipse.swt.accessibility.ACC class.
  • Custom controls must expose their state(s) through the getState method of the AccessibleControlListener. Supported states are defined in the org.eclipse.swt.accessibility.ACC class.

The W3C Core API Mappings document provides interoperable mappings of roles, states, properties and events across various accessibility APIs. These mappings ensure that controls are consistently exposed to assistive technologies. The roles and states defined by the Eclipse SWT ACC class map to a subset of the states and properties defined in the MSAA + IAccessible2 columns in the Role Mapping Table and State and Property Mapping Table. These tables can be used as a reference in identifying supported states and events for given roles.

Exposing object attributes

Implement getAttributes method of org.eclipse.swt.accessibility.AccessibleAttributeListener to expose object attributes specific to control.

  • Return attributes regarding margins, tab stops, justify, alignment and indent for text controls.
  • Return group level, group count, and group index for tree controls and their child nodes. For further details, see Eclipse bug #405244.
  • Return additional attributes not defined by the org.eclipse.swt.accessibility.AccessibleAttributeEvent in the attributes parameter that are appropriate for control. Note that the proper format for specifying attributes is "attribute:value;attribute:subattribute=subvalue,subattribute=subvalue;"

Note: Text controls may require additional attributes. These requirements are outlined in the required development techniques for checkpoint 502.3.8 Text.

Defining an AccessibleContext

The conventional approach to exposing name, role, state and description is to add an AccessibleListener and an AccessibleControlListener to the Accessible of a Control. This can become tedious.  An alternate solution is to define an AccessibleContext. Section 6.3 of the article Creating Accessible Applications in Eclipse - 2nd Edition outlines the details of creating an AccessibleContext.

Resources:

Creating Accessible Applications in Eclipse - 2nd Edition

IAccessible2 Object Attributes Specification

Core Accessibility API Mappings 1.1

Windows-based (MSAA+IA2) techniques

For software using standard Windows UI controls, no additional work is required to expose the Active Accessibility (MSAA) properties, including role, state, name, and description. However, these properties are limited to the older IAccessible interface and may need the use of a complementary accessible interface. For example, a custom control may need to expose additional accessibility properties which are available through IAccessible2 interfaces. Legacy software applications may be extended to use the IAccessible2 interfaces.

Applications created with the Windows Presentation Foundation (WPF), using UI Automation as the accessibility interface, will return additional information which is not available for legacy Windows applications. Therefore, the following techniques are not used for UI Automation. For information outlining the difference between MSAA and UIA, refer to the Microsoft article UI Automation and Microsoft Active Accessibility.

For legacy applications that use Active Accessibility (MSAA), a detailed description of the system-provided user interface elements can be found in the User Interface Element Reference. Drill into each element type to view accessibility properties and methods.

Instructions: In addition to the General techniques, use the following to support Windows accessibilty. All links point to Microsoft unless otherwise indicated.

Implementing IAccessible, IAccessible2 and IServiceProvider for custom Windows controls

Software can extend or modify the behavior of standard Windows controls to create a custom control by sub-classing, or super-classing the standard control. All custom controls, at a minimum, must provide the IAccessible, IAccessible2 and IServiceProvider interfaces and all objects must support the IAccessible2::uniqueID property.

Refer to the IAccessible2 Implementation Guide for full details on providing IAccessible, IAccessible2 and IServiceProvider interfaces as well information about the IAccessible2::uniqueID property.

For more information on how to implement IAccessible for custom controls using the Microsoft Active Accessibility Interface, refer to Shortcuts for Exposing Custom User Interface Elements. The MSDN page, Exposing Additional Information Not Covered by IAccessible Interface, provides further details on using QueryService to expose additional interfaces for an IAccessible object, i.e., IAccessible2 interfaces.

Notes:

  • IAccessible2::role method returns both MSAA roles and IAccessible2 roles for convenience. However, IAccessible2 roles should NOT be returned through the IAccessible::get_accRole method.
  • IAccessible2 enabled applications should return the closest MSAA role or ROLE_SYSTEM_CLIENT through the IAccessible::get_accRole method in addition to the IAccessible2 role to provide backward compatibility to Assistive Technologies that are not enabled for IAccessible2.
  • IA2States are returned through the IAccessible2::states parameter of the IAccessible2 object while MSAA states are returned through the get_accState method of the IAccessible object.

Creating an Active Accessibility server and IAccessibleApplication

Software that creates custom controls must create an Active Accessibility server to support assistive technology, the client, as defined by MSAA, and queries for accessible information. For more information on creating an accessible custom control, see the Developer's Guide for Active Accessibility Servers. For a concrete example of how Mozilla implements an MSAA server, see the article, Implementing a Microsoft Active Accessibility (MSAA) Server: Practical Tips for Developers and How Mozilla Does It.

In addition, software that creates custom controls must implement IAccessibleApplication to return application information to assistive technologies (AT). Servers must provide access to the IAccessibleApplication interface via QueryService from any object so that ATs can easily determine specific information about the application such as its name or version.

Exposing object attributes

Return the attributes of a control through the attributes member function of the IAccessible2 object.

Note: Text controls may require additional attributes. These requirements are outlined in the required development techniques for checkpoint 502.3.8 Text.

Implementing getBounds for standard and custom controls

Boundary information is returned by the operating system through the appropriate getBounds method for standard and custom controls. Typically, no additional coding is necessary.

Resources:


Most links in this checklist reside outside ibm.com at the Web Content Accessibility Guidelines (WCAG) 2.0. W3C Recommendation 11 December 2008: http://www.w3.org/TR/WCAG20/

Copyright © 1994-2017 World Wide Web Consortium, (Massachusetts Institute of Technology, European Research Consortium for Informatics and Mathematics, Keio University, Beihang University). All Rights Reserved.

Copyright © 2001, 2017 IBM Corporation