Checkpoint 502.3.9: Modification of Text

Text that can be set by the user shall be capable of being set programmatically, including through assistive technology.

Rationale

Users depend on Assistive Technology (AT) to relay programmatic information to them about text content and attributes. If text is editable, AT users also need the ability to create, interact with, and modify text content. Some AT, such as speech recognition programs, provide the user with the ability to cut, copy, paste, insert and set the attributes of the text. This functionality to modify and create new text must be made programmatically available to the AT.

Note: The selection and manipulation of text involves considerations for several checkpoints. Depending on circumstances, such as whether text is static, read-only or fully editable, similar techniques may be cited by each of a set of checkpoints. These are:

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

Each item in this section represents a technique deemed sufficient.

  • When the rich text is editable, programmatically exposing the ability to cut, copy, paste, insert and set the attributes of the text

Mobile Native (iOS) techniques

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

Making sure text contents, text attributes, and the boundary of text rendered to the screen are programmatically determinable

The text and text attributes of UIKit Text Fields and Text Views are exposed without needing additional code. Boundaries are determined by the view coordinates. Text attributes can be changed in the attributedText instance property.

Eclipse techniques

Instructions: In addition to the General techniques, the Eclipse techniques in this section represent a combination of techniques deemed sufficient.

Implementing setTextAttributes method in the AccessibleEditableTextListener

Eclipse provides the org.eclipse.swt.custom.StyledText widget, an editable user interface object that displays lines of text. Applications that utilize this widget will receive accessibility coverage for this checkpoint "at no additional cost."  However, if the application provides the ability to set text attributes in the text widget, the setTextAttributes method in the AccessibleEditableTextListener must be implemented  to programmatically expose the setting of text attributes to assistive technology. Other custom editors and text-based widgets, need to implement additional interfaces to be made accessible.

If the application offers editing of text attributes and other styles on the StyledText, it is necessary to implement setTextAttributes
to programmatically expose the setting of the text attributes to assistive technology. The following is a code snippet from IBM Accessibility Education, Creating Accessible Applications in Eclipse - 12.2 AccessibleEditableTextTest.  It provides a good overview of how the implementation is coordinated.

StyledText text = new StyledText(shell, SWT.SINGLE | SWT.BORDER);

text.setText("Sets a text into StyledText widget");

text.getAccessible().addAccessibleAttributeListener( new AccessibleAttributeAdapter() {

      public void getTextAttributes(AccessibleTextAttributeEvent e) {

            valueField.setText("getTextAttributes" + e);

      }

});

text.getAccessible().addAccessibleEditableTextListener(new AccessibleEditableTextAdapter() {

      public void setTextAttributes(AccessibleTextAttributeEvent e) {

            valueField.setText("setAttributes " + e);

            TextStyle textStyle = e.textStyle;

if (textStyle != null) {

                  /*

                   * Copy all of the TextStyle fields into the new

                   * StyleRange.

                   */

                  StyleRange style = new StyleRange(textStyle);

                  /*

                   * Create new graphics resources because the old

                   * ones are only valid during the event.

                   */

                  if (textStyle.font != null)

                        style.font = new Font(display, textStyle.font

                                    .getFontData());

                  if (textStyle.foreground != null)

                        style.foreground = new Color(display,

                                    textStyle.foreground.getRGB());

                  if (textStyle.background != null)

                        style.background = new Color(display,

 textStyle.background.getRGB());

                  if (textStyle.underlineColor != null)

                        style.underlineColor = new Color(display,

                                    textStyle.underlineColor.getRGB());

                  if (textStyle.strikeoutColor != null)

                        style.strikeoutColor = new Color(display,

                                    textStyle.strikeoutColor.getRGB());

                  if (textStyle.borderColor != null)

                        style.borderColor = new Color(display,

                                    textStyle.borderColor.getRGB());

                  /* Set the StyleRange into the StyledText. */

                  style.start = e.start;

                  style.length = e.end - e.start;

                  text.setStyleRange(style);

                  e.result = ACC.OK;

            } else {

   text.setStyleRanges(e.start, e.end - e.start, null,

                              null);

            }

      }

});

 
Implementing AccessibleEditableTextListener

For text widgets, standard and custom, that provide editing, selection, styling, copying, pasting, spell checking and/or language support, additional interfaces must be implemented as outlined below. Refer to checkpoint 502.3.8 Text for full details on exposing these text widgets to assistive technology. The following technique outlines the steps to modify the text widget and the text attributes.

The org.eclipse.swt.accessibility.AccessibleEditableTextListener interface complements the AccessibleTextListener and AccessibleTextExtendedListener interfaces and provides clipboard level functionality for text areas. Since read only text areas can support copy functionality, this interface is not limited to editable text.

For all text areas, implement the copyText method. For editable text areas, implement methods to cutText, pasteText and replaceText methods.

Implement the method setTextAttributes to allow the attributes of a range of text to be set. Text attributes can be applied on a character by character basis as defined in the IA2 Text Attributes Specification which defines the formatting of the text attributes string. Attributes that are applied to an entire paragraph are defined in the IA2 Object Attributes Specification. Eclipse maps many of the text attributes to styles in org.eclipse.swt.graphics.TextStyle and org.eclipse.swt.graphics.FontData while object level attributes are exposed through org.eclipse.swt.accessibility.AccessibleAttributeEvent.

Windows-based (MSAA+IA2) techniques

Instructions: In addition to the General techniques, the Windows-based techniques in this section represent a combination of techniques deemed sufficient. Refer to the Windows techniques tab in checkpoint 502.3.1 Object Information to learn about accessibility APIs.

Implementing IAccessibleEditableText for editable text

First, refer to checkpoint 502.3.8 Text for full details on exposing text widgets to assistive technology. This technique outlines the steps to modify the text widget and the text attributes.

The IAccessibleEditableText interface complements the IAccessibleText interface and provides clipboard level functionality for text areas.

For editable text areas, implement methods to cutText, deleteText, insertText, pasteText and replaceText.

Implement the method setAttributes to allow the attributes of a range of text to be set. The setAttributes method takes a startOffset and endOffset defining the range of text to update along with a pointer to a BSTR defining the set of attributes. Text attributes can be applied on a character by character basis as defined in the IA2 Text Attributes Specification which defines the formatting of the attributes string. Attributes that are applied to an entire paragraph are defined in the IA2 Object Attributes Specification. For example, if there was a spelling error in the text, return IA2_STATE_INVALID_ENTRY and invalid:<”spelling”> as a text attribute (not an object attribute.)


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