Software checklist

Software checkpoint 2.2: Object information

Provide semantic information about user interface objects. When an image represents a program element, the information conveyed by the image must also be available in text.


Rationale

Someone who is blind uses a computer with the aid of assistive technology such as a screen reader, screen magnifier or Braille display. The software must provide semantic information about the user interface object to the assistive technology. This is done through platform specific interfaces that programmatically expose information, such as the name (identity), role (operation), value (contents) and state of the user interface objects.

In the sample dialog box below, the user needs to know the focus is currently located on the radio button named "Two", there are three radio buttons to choose from, and "Two" is currently selected. The edit control named "Value" has the value of "123".

one, two, three, value:123

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 are the name. Even non-text user interface elements, such as bitmaps, and images have a text string name that is provided when queried for by the assistive technology.

The role provides a description of the type of user interface element and implicitly the behavior. A role of PUSHBUTTON identifies the element as a user interface object that performs an action when selected. The value is the content of the object. In the case of an edit control, the value is the text string contents. The state is a description of the objects current status. For example a state of SYSTEM_FOCUSED indicates the object has the keyboard focus.

The level of effort to expose this information to assistive technologies depends on how the user interface objects have been created.

Standard user interface controls (or widgets) such as the Windows (Win32) controls (push buttons, menu bars, menu items) are typically accessible with no additional support from software. Custom controls can be created by building on standard controls, or be completely unique, custom drawn. When these controls build upon an accessible base, they are often accessible with little to no additional effort by software. Custom drawn controls are unique to the software and do not share any of the standard control definitions. Custom drawn controls have no inherent accessibility; all of the accessible features must be provided by software.


Required development techniques


The following techniques are the minimum required to meet Checkpoint 2.2 from the IBM Software Accessibility Checklist:

  1. All standard user interface controls must expose the accessible attributes for name, role, and state. Value must be exposed when there is visual information contained in the control.
  2. All custom controls must expose the accessible attributes for name, role, and state. Value must be exposed when there is visual information contained in the control.

Examples for Microsoft Windows developers

1. All standard user interface controls must expose the accessible attributes for name, role, and state. Value must be exposed when there is visual information contained in the control.

Example 1

For software using standard Windows controls, no additional work is required to expose the accessible properties of the user interface objects. A detailed description of the system components can be found at the User Interface Element Reference.

2. All custom controls must expose the accessible attributes for name, role, and state. Value must be exposed when there is visual information contained in the control.

Example 2

Software can extend or modify the behavior of standard windows controls to create a custom control by subclassing, or superclassing 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 an accessibility tool.

If the control is not accessible, an accessible interface must be supported by software. This includes providing support for the WM_GETOBJECT message from the window procedure, and supplying an IAccessible interface for assistive technology (the client application) to use to query for accessible information. For more information on how to create accessible controls using the Microsoft Active Accessibility Interface, see Shortcuts for Exposing Custom User Interface Elements.

Example 3

Software that creates custom controls must create an active accessibility server to support assistive technology, the client as defined by MSAA, queries for accessible information. For more information on creating an accessible custom control, see the Developer's Guide for Active Accessibility Servers. This can be done using an accessibility tool, such as Inspect Objects.

Examples for Eclipse SWT developers

1. All standard user interface controls must expose the accessible attributes for name, role, and state. Value must be exposed when there is visual information contained in the control.

Example 4

On the Windows platform, the Eclipse SWT controls support MSAA. For text components the accessible name of the control will be set properly and no additional action is required by the application.
Non-text controls created using the org.eclipse.swt.widget.control, the accessible name must be explicitly established. In Eclipse 3.1 or later, non-text controls created using org.eclipse.swt.widget.item must explicitly set the tooltip for each item.

An accessible name is set by obtaining the Accessible object for the control using getAccessible(), and then creating an AccessibleListener. Use the getName() method to set the accessible name for the control, as shown the following example.

mycontrol.getAccessible().addAccessibleListener(
new AccessibleAdapter() {
public void getName(AccessibleEvent event) {
event.result = "Accessible name of control";
}
} );

Note: Accessible information can only be provided for SWT Controls; other widget subclasses such as menu, toolbar, tableitems can not have added accessibility support.

2. All custom controls must expose the accessible attributes for name, role, and state. Value must be exposed when there is visual information contained in the control.

Example 5

In Eclipse, when implementing a custom control you should also implement some or all of (as they apply to your control)

org.eclipse.swt.accessibility.AccessibleListener, org.eclipse.swt.accessibility.AccessibleControlListener and org.eclipse.swt.accessibility.AccessibleTextListener.

Also, the custom control can notify Active Accessibility of changes within the control using org.eclipse.swt.accessibility. Accessible methods such as setFocus(), selectionChanged(), textCaretMoved(), textChanged() and textSelectionChanged().

Examples for Java developers

See the examples to implement system settings using Java Swing.

Examples for Linux developers

The GNOME Accessibility Project is developing a suite of software services and support to make the GNOME user environment accessible. The Accessibility Framework includes an Accessibility Toolkit Application Programming Interface and an Assistive Technology Service Provider Interface. Visit the GNOME Accessibility Project for more information.

Examples for iOS developers

1. All standard user interface controls must expose the accessible attributes for name, role, and state. Value must be exposed when there is visual information contained in the control.

Example 6

When using the standard iOS controls, developers must set the accessibility attribute 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"];

2. All custom controls must expose the accessible attributes for name, role, and state. Value must be exposed when there is visual information contained in the control.

Example 7

Software can extend or modify the behavior of standard iOS UI controls to create a custom control by subclassing, or superclassing 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. (PDF, 1.2MB)

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.


Recommended development techniques

The techniques above are required; the following technique is recommended to enhance accessibility:

If a Windows application has custom controls, but does not support MSAA, the following steps can help make a control more compatible, but not fully compatible, with accessibility aids. If the custom control has its own window, you can return a descriptive string when the control is queried using the WM_GETTEXT message. For example, a control that appears as a button with the label Print could return the string "Print button" to convey both the control type and the label. The same string would be appropriate if the control looked like a button but had a graphic showing a printer rather than a text label. Likewise, a custom control that behaves like a check box could return a caption string "Printing Enabled check box, checked.

 

Required test techniques

Test the software to ensure that it complies with accessibility requirements.

Required test software

Install the following software as needed to test this checkpoint.

Test techniques

The following test techniques are required to verify this checkpoint.
Please note that each screen reader may provide object information in a different manner to the end user.


Action Result
With a screen reader active, navigate to every user interface element. (Use Tab, the Arrow keys, and any other application specific navigation keys to move to all controls and objects.)
Pass:


Fail:

Debug techniques

If the screen reader test fails for any user interface element, the problem must be debugged with an accessibility API validation tool. These techniques can be used to help determine if a problem is caused by a coding error in the application, or if it is caused by a screen reader defect.


The following techniques are required to verify this checkpoint:
Action Results for compliance
  1. Review the development techniques and insure the implementation is correct according to the development techniques.
  2. Use the API validation tool that is appropriate to your product to determine if the development techniques have been implemented properly.

Additional information on how to use the API validation tool is included with the tool.
  1. The implementation is correct according to the development techniques.

  2. The accessibility API validation tool shows that the API properties expose sufficient information as defined in the development techniques for this checkpoint.

  3. Additional instructions:
    • Report the defect to the appropriate parties (e.g., screen reader manufacturer).

    • Document the failure and defect information in the comment section for the applicable checkpoints.

©2009, 2013 IBM Corporation

Last updated August 22, 2013.