Checkpoint 502.3.14: Event Notification

Notification of events relevant to user interactions, including but not limited to changes in the component’s state(s), value, name, description, or boundary, shall be available to assistive technology.

Rationale

In addition to providing semantic information about user interface objects to Assistive Technology (AT), a software application must alert the AT when events occur that cause changes to the user interface objects. These events include when:

  • focus changes
  • the caret moves
  • selection changes
  • components are added to the page/screen
  • a component's state(s), value, name, description or boundary has changed

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.

  • Programmatically notifying assistive technologies (AT) of events relevant to user interactions, including but not limited to changes in the component’s state(s), value, name, description, or boundary

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 that is deemed sufficient for meeting this checkpoint.

Note: Example 1 of this checkpoint is also included in the Checkpoint 1.3.1 - Info and Relationships.

Set the accessibility, label, hint, and trait of UI elements

Native UI elements have accessibility properties built in. You must enable and provide the content for the applicable accessibility properties. At a minimum, you should set isAccessibleElement = YES to enable the accessibility and set the label to a meaningful text string. Trait is already set, and is rarely changed unless you create a custom control. Provide a hint, if needed. Refer to Accessibility Programming Guide for iOS for Apple's style instructions on creating good labels and hints.

self.button.isAccessibilityElement = YES;
self.button.label = @”Confirm”;
self.button.hint = @”Completes the transaction.”

Custom widgets implement UIAccessibility protocol. Methods on the protocol include: isAccessibilityElement to return YES; accessibilityLabel to return an appropriate label; accessibilityTrait to return the closest trait; and optionally, accessibilityHint to return a localized hint. In the following code, a custom widget that allows the user to select the angle of rotation implements the needed methods.

- (BOOL)isAccessibilityElement
{
   return YES;
}

- (NSString*)accessibilityLabel
{
   return @"Angle";
}

- (NSString*)accessibilityHint
{
   return @"Adjusts the angle of rotation";
}

- (UIAccessibilityTraits)accessibilityTraits
{
   return UIAccessibilityTraitAdjustable;

}

Eclipse techniques

Instructions: The Eclipse techniques in this section represent a technique or combination of techniques deemed sufficient for meeting this checkpoint.

Use standard SWT interface controls

For most standard SWT controls, such as a button or text box, Eclipse uses the accessible native controls of the platform. For this reason, accessibility functions provided by the platform are available for free to the user. As a rule of thumb, accessible events are sent to Assistive Technology (AT) through the functions of the native control when standard controls are used.

However, some native controls, such as a Table, are not fully accessible and require further programming by the developer to fully expose accessibility information.

Return events through org.eclipse.swt.accessibility.Accessible.sendEvent method for custom controls

Send  event specific information via the sendEvent method of the Accessible object of the custom control along with the corresponding org.eclipse.swt.accessibility.ACC event constant.

For example, the following code shows the sendEvent method being invoked on the Accessible object of a toggle control with the EVENT_STATE_CHANGED flag, type of state, and new state value as arguments to the method to indicate a change in selection.

toggle.getAccessible().sendEvent(ACC.EVENT_STATE_CHANGED, new int[]{ACC.STATE_SELECTED,       
toggle.getSelection()?1:0});

The org.eclipse.swt.accessibility.ACC  class defines constants for all accessible events that notify changes to custom controls. These events should be sent as messages through the sendEvent method of the Accessible object.

Return events through helper methods of org.eclipse.swt.accessibility.Accessible class for custom controls

In addition to the sendEvent method, the org.eclipse.swt.accessibility.Accessible class provides helper methods to send events for focus changes, caret movement, text and text selection changes on custom widgets. The following examples demonstrate how to invoke these helper methods.

Notify when there is a caret movement

This example demonstrates how an Accessible client is notified of caret movements as demonstrated in the org.eclipse.swt.custom.StyledText widget. 

void sendAccessibleTextCaretMoved() {
    if (caretOffset != accCaretOffset) {
        accCaretOffset = caretOffset;
        getAccessible().textCaretMoved(caretOffset);
    }
}

Notify when focus changes on a custom control

The following code snippet as demonstrated in AccessibleBarChartExample.java in the SWT Examples, calls the setFocus helper method on the Accessible object to send a message to the accessible client when focus changes on a custom control.

if (change) {
    redraw();
    getAccessible().setFocus(selectedItem);
    getAccessible().selectionChanged();
}

Notify when text changes on a custom control

The following example demonstrated by the org.eclipse.swt.custom.StyledText widget sends a message to the accessible clients when text changes on a StyledText custom control.

void sendAccessibleTextChanged(int start, int newCharCount, int replaceCharCount) {
    Accessible accessible = getAccessible();
    if (replaceCharCount != 0) {
        accessible.textChanged(ACC.TEXT_DELETE, start, replaceCharCount);
    }
    if (newCharCount != 0) {
        accessible.textChanged(ACC.TEXT_INSERT, start, newCharCount);
    }
}

Notify when text selection changes on a custom control

The following example demonstrated by the org.eclipse.swt.custom.StyledText widget sends a message to the accessible clients when text selection changes on a StyledText custom control.

void sendSelectionEvent() {
    //getAccessible().textSelectionChanged();
    getAccessible().sendEvent(ACC.EVENT_TEXT_SELECTION_CHANGED, null);
    Event event = new Event();
    event.x = selection.x;
    event.y = selection.y;
    notifyListeners(SWT.Selection, event);
}

 

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.

Use standard UI controls

The Windows system generates WinEvents for all HWND-based controls when it creates, destroys, moves, resizes or performs an action on an HWND-based control. The Microsoft Active Accessibility (MSAA) run-time provides IAccessible proxies for all standard UI controls.

Generate WinEvents for custom controls

Server applications must generate WinEvents for custom controls for which they have implemented IAccessible. Server applications must call the the NotifyWinEvent function to broadcast the event. The system will then call into registered callback functions of listening clients. The clients can then ask the server for the IAccessible object associated with the event.

The MSDN page on System-level and Object-level events further explains the responsibility of the server to generate appropriate WinEvents. The constant values used in the WinEvent parameters are defined on the Event Constants page.

The CustomAccServer sample provides an example of implementing a custom control by an Active Accessibility Server including generation of WinEvents for the custom control.

For example, if a server wants to notify listening clients that a custom control received focus, it calls NotifyWinEvent and passes EVENT_OBJECT_FOCUS as a parameter. The system then calls the registered clients' callback functions that handle the focus event.

Generate IA2 Events for custom controls for events not covered by WinEvents

The IAccessible2 API specifies an enum IA2EventID which defines the event ids generated by accessibility servers for IAccessible2 objects. These event ids identify events not defined in the WinEvent constants.

The sendEvent method in org.eclipse.swt.accessibility.Accessible class demonstrates that these events are still generated via a call to the NotifyWinEvent function.

COM.NotifyWinEvent (COM.IA2_EVENT_TEXT_REMOVED, control.handle, COM.OBJID_CLIENT, eventChildID());

Notes:


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