Any relationship that a component has as a label for another component, or of being labeled by another component, shall be programmatically determinable.

Rationale

Labels give a name to an object (e.g., icon names, window titles, button labels, edit fields). The labels must be associated programmatically with the object for the assistive technology to make them available to the user.

Labels are used to describe sections of content as well as controls. In some cases, it may be unclear whether a piece of static text is a label or additional description or instructions. But whether treated as a label, a description or instructions, the requirement is the same: if labels, descriptions or instructions are present, they must be programmatically determinable.

Note: In software, programmatic determinability is best achieved through the use of accessibility services provided by platform software to enable interoperability between software and assistive technologies and accessibility features of software (from WCAG2ICT - Success Criterion 1.3.1a: Info and Relationships).

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

Where applicable, each item in this section represents a technique deemed sufficient.

  • Programmatically exposing labels
  • Programmatically exposing relationships between a control and any text or other component that provides additional information about the control such as description, instructions, grouping or identifying a required field

Mobile Native (iOS) techniques

Instructions: In addition to the General techniques, any item in this section represents a technique deemed sufficient where appropriate.

Providing a descriptive label to clarify an interactive element's purpose

Standard iOS UI elements must have a descriptive label (IBM internal use only link) attribute set.  For some UI elements, such as buttons,  you set a default label value. That default value is automatically used as the accessible, descriptive label if you enable accessibility in the accessibility inspector. Descriptive hint attributes should be provided when needed.

Custom widgets must programmatically implement the accessibilityLabel method and return a descriptive label. If needed, a descriptive hint attribute should be implemented using accessiblityHint to return a localized, descriptive hint.

Note: This technique is relevant to checkpoint 2.4.6 - Headings and Labels.

Eclipse techniques

Instructions: In addition to the General techniques, any item in this section represents a technique deemed sufficient where appropriate.

Situation A: If a label provides the name of the control

Situation B: If a label provides additional information about the control such as description, instructions, grouping or identifies a required field

Providing a label immediately before the control it describes

In software developed using Eclipse SWT, instantiating widgets and their children creates a tree hierarchy of controls and their association. A label widget created immediately before the control (text widget or combo box) is associated with the control.

Preceding label example: Form with a First and Last Name field and an OK button. The first and last name field are labeled with labels immediately preceding the input fields.

Figure 1: Rendering of label example.
 
 

Providing a label in the text of the control

For controls whose text labels the control, e.g., checkbox or radio box, provide descriptive text for the control.

Button button = new Button (shell, SWT.CHECK);

button.setText ("Provide text that describes the checkbox");

Checkbox example: A dialog with 1 checkbox with the label, Provide text that describes the checkbox.

Figure 2: Rendering of checkbox example.
 

Creating a relation between the control and text that names it, describes it or provides instructions

When additional text is provided that describes a control, a bi-directional relation must be established between the text and the control to inform assistive technologies (AT) of the relation.

Eclipse SWT Snippet 340: Tell a screen reader about updates to a non-focused descriptive area demonstrates how to define a relationship between a control and text that describes it. A relation is added to the control’s Accessible between the control and the text label that describes it. Likewise a relation is added to the text label’s Accessible to indicate that it describes the control.

textField.getAccessible().addRelation(ACC.RELATION_DESCRIBED_BY, liveLabel.getAccessible());

liveLabel.getAccessible().addRelation(ACC.RELATION_DESCRIPTION_FOR, textField.getAccessible());

To alert the AT that the description has changed, an ACC.EVENT_DESCRIPTION_CHANGED event is fired to alert the screen reader that the text field’s description has changed in the ModifyListener of the control.

textField.getAccessible().sendEvent(ACC.EVENT_DESCRIPTION_CHANGED, null);

The AT accesses the getDescription method of the control’s Accessible to get the new description, the updated live label.

A Dialog titled Description Relation Example showing a relationship between an edit field that has the value of 4 entered into it and it's live region label

Figure 3: Rendering of the example of creating a relation between the control and text that describes it.
 
 

 

Using groups to group related controls and add relations between group, labels and controls

When controls are grouped, a relation between the controls in the group and their labels must be established to inform the AT that the labels, in addition to the group label, describe the group controls.

Eclipse SWT Snippet 350: Use accessible relations to provide additional information to an AT demonstrates how to define relations between group controls and their labels. The Address group has two edit controls labeled by the labels, Street and City. A relation is defined between each control and the label that labels it and a relation is defined between each label and the controls which they label.

Additionally, a relation is formed between each control and the group declaring the control as a member of the group and that the control is labeled by the group label.

A form titled Accessible Relations with a Name edit field and a group of edit fields consisting of Street and City.

Figure 4: Rendering of the example of grouping related controls and adding relations between group, labels and controls.
 
 

Indicating which fields are required

A visible indication of which fields are required is typically accomplished using an '*' in the label of the element. To programmatically expose what fields are required to an AT, STATE_REQUIRED is returned by the getState method in the AccessibleControlListener for the field.

Dialog with form fields of First Name and Last Name. * denotes that Last Name is a required field.

Figure 5: Required file example dialog.
 
 

Windows-based (MSAA+IA2) techniques

Instructions: In addition to the General techniques, refer to the Windows techniques tab in checkpoint 502.3.1 Object Information to learn about accessibility APIs, and use the following to support Windows accessibilty.

Situation A: If a label provides the name of a control

Situation B: If a label provides additional information about the control such as description, instructions, grouping or identifies a required field


Providing a label immediately before the control it describes

When the static text immediately preceding a control, e.g. an Edit control, labels the control, provide descriptive text for the label.

Note: When using standard Windows controls or custom controls, the name of the control is returned through the get_accName method of the IAccessible interface to expose the label/name to assistive technology (AT).

Providing a label in the text of control

For controls whose text labels the control, e.g., Button control, provide descriptive text for the control.

Creating a relation between the control and text that names it, describes it or provides instructions

Define a relationship between a control and the text that describes it by defining an IAccessibleRelaton between the IAccessible2 objects for the control and the text.

Accessible relation types are defined in IA2_RELATION constant variables. Use the correlating relation types, IA2_RELATION_DESCRIBED_BY with IA2_RELATION_DESCRIPTION_FOR and IA2_RELATION_LABELLED_BY with IA2_RELATION_LABEL_FOR, to define a bidirectional relation between the control and the text that describes the control.

These relation types correspond to aria-describedby and aria-labelledby defined by the W3C WAI-ARIA Authoring Practices which differentiates between the two as follows; A label provides the user with the essence of what the object does, whereas a description is intended to provide additional detail that some users might need.

Using groups to group related controls and add relations between group, labels and controls

In Windows-based desktop applications, a group box organizes related controls and has the style BS_GROUPBOX. The group box label typically identifies how the controls contained in the group box are related.

To programmatically expose the relationship between a group box and its controls, define an IA2_RELATION_MEMBER_OF between each control's IAccessible2 object and the IAccessible2 object of the group box. Additionally, define an IA2_RELATION_LABELLED_BY on the IAccessible2 object of each control indicating that they are labelled by the group box.

Indicating which fields are required

A visible indication of which fields are required is typically accomplished using an '*' in the label of the element. To programmatically expose what fields are required to an AT, return IA2_STATE_REQUIRED  on the IAccessible2 object of the field.


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