Checkpoint 502.3.5 Modification of Values

Any values associated with an object that can be set by the user shall be capable of being set programmatically, including through assistive technology.

Rationale

In addition to knowing the name, role, state, boundary, properties and description of an object (as covered in 502.3.1 Object Information), it is important for the user to understand the current value and range of values available for a user input control (as covered in 502.3.4 Values). Any values that can be set by the user, the user should be able to set those programmatically, including through assistive technology.

For example, when a user interacts with a spinner widget to be able to select a desired value from a list of values, it is important for the user to know the currently selected value, the minimum and the maximum values. In order to communicate these values to the user, they must be programmatically available to an AT. Any values that can be set by the user must be capable of being set programmatically, including through an assistive technology.

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

Any item in this section represents a technique deemed sufficient.

  • If a value of a user interface control can be set by the user, allowing the value to be set programmatically including through assistive technology

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

Mobile Native (iOS) techniques

Instructions: In addition to the General techniques, the Mobile Native iOS techniques in this section represent a technique or combination of techniques deemed sufficient.

Note: The first two examples below also meet the value requirement 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 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.

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"];
 

Exposing minimum and maximum values where applicable

Different controls provide different options to expose value-related information.

Picker: Because picker values contain strings, the only information that can be exposed is the number of components.

Page control: Minimum value is 0, maximum value is the total number of pages -1.

Progress view: Minimum and maximum value should be set. By default, the minimum is 0, the maximum is 1.0. Progress views are accessible by default.

Stepper: By default, the minimum value is 0, the maximum value is 100.

Eclipse techniques

Instructions: Any item in this section represents a technique or combination of techniques deemed sufficient.

Implementing AccessibleValueListener

Some user interface controls represent one of a range of values, for example, a spinner widget as pictured in Figure 1. The user sets the current value by selecting it from a range of values spanning the range from minimum to maximum allowed value.

Screenshot of spinner widget

Figure 1 A spinner widget that programmatically returns a minimum value of 1, maximum of 100 and a current value of 50.
 
For these user interface controls which represent one of a range of numerical values, add an org.eclipse.swt.accessibility.AccessibleValueListener to the Accessible of the control and implement getCurrentValue, getMinimumValue and getMaximumValue and setCurrentValue methods as outlined in the Eclipse code example for an accessible spinner widget.
/*
        * Add an AccessibleValueListener to the spinner widget
        * to get and set its current value and
        * to get its minimum and maximum values.
        */
       spinner.getAccessible().addAccessibleValueListener(
               new AccessibleValueAdapter() {
 
               @Override
              public void getCurrentValue(AccessibleValueEvent e) {
                     e.value = new Integer(spinner.getSelection());
              }
 
              @Override
              public void getMinimumValue(AccessibleValueEvent e) {
                     e.value = new Integer(spinner.getMinimum());
              }
 
              @Override
              public void getMaximumValue(AccessibleValueEvent e) {
                     e.value = new Integer(spinner.getMaximum());
              }
 
              @Override
              public void setCurrentValue(AccessibleValueEvent e) {
                     spinner.setSelection(e.value.intValue());
              }
});

 

Implementing AccessibleValueListener for corresponding numerical values

Often times a control has an array of available text values that programmatically correspond to a numerical value, for example, the months of a Gregorian calendar correspond to the numbers 1 through 12. The month picker widget pictured in Figure 2 allows the user to select 1 of 12 months by selecting the text value of the desired month from a drop down list.

Screenshot of month picker dialog

Figure 2 A month picker where the months of the year correspond to the values 1 thru 12.
 
Add an org.eclipse.swt.accessibility.AccessibleValueListener to the Accessible of the control and implement getCurrentValue, getMinimumValue and getMaximumValue and setCurrentValue methods as outlined in the following Eclipse code example for a control that has numerical values corresponding to the months of a calendar.
final Combo combo = new Combo (shell, SWT.READ_ONLY);
combo.setItems(new String[] { "January", "February", "March", "April", "May", "June", "July", "August", "September", "October",  "November", "December" });
combo.setText(combo.getItem(3)); //Set selection to April
/*
 * Add an AccessibleValueListener to the month picker combo widget
 * to get and set its current numerical value and to get its minimum and maximum numerical values.
 */
combo.getAccessible().addAccessibleValueListener(
     new AccessibleValueAdapter() {
 
          @Override
          public void getCurrentValue(AccessibleValueEvent e) {
              e.value = new Integer(combo.getSelectionIndex()+1);
          }
 
          @Override
          public void getMinimumValue(AccessibleValueEvent e) {
              e.value = new Integer(1);
          }
 
          @Override
          public void getMaximumValue(AccessibleValueEvent e) {
              e.value = new Integer(combo.getItemCount());
          }
 
          @Override
          public void setCurrentValue(AccessibleValueEvent e) {
              combo.select(e.value.intValue()-1);
          }
});

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.

 

Implementing IAccessibleValue

For user interface controls that represent one of a range of numerical values, implement IAccessibleValue and implement its getCurrentValue, getMinimumValue and getMaximumValue and setCurrentValue methods.

Implementing IAccessibleValue for corresponding numerical values

Often times a control has an array of available text values that programmatically correspond to a numerical value, for example, the months of a Gregorian calendar correspond to the numbers 1 through 12. The month picker widget pictured in Figure 3 allows the user to select 1 of 12 months by selecting the text value of the desired month from a grid.

 

Screenshot of Month picker dialog

Figure 3 Month picker from Windows Change date and time settings dialog
Implement IAccessibleValue and implement its getCurrentValue, getMinimumValue and getMaximumValue and setCurrentValue methods to programmatically expose the numerical values that correspond to the text values displayed.

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