Code considerations for accessibility

This topic describes accessibility issues when creating IBM Director console extensions.

Subtopics

Related information

Related sample code

Overview

In past releases, GUIs were typically constructed by using particular components of specific sizes which were then made visible. These GUIs typically retained their font and color settings for the duration of their visible life. Additional consideration is needed in order to meet accessibility requirements. 

The subsequent sections describe the most common areas that can be addressed by IBM Director developers as they prepare for the IBM Director Version 5.1 release. Additional items that must be addressed are contained in the checklist at:

http://www-306.ibm.com/able/guidelines/java/javatest.html

Note that while accessibility changes are required for IBM Director Version 5.1, many of the suggestions made in this section can also be used in IBM Director Version 4.2. This is helpful because it facilitates the preservation of common code and enables developers to prepare code for the accessibility requirement sooner rather than later.

Fonts

As a rule, avoid setting fonts. On a cross-platform, internationally-distributed product such as IBM Director, there is no guarantee that a specific size in a specific font family will either exist or resolve to something that will work. There are occasions where a bold font might be required. In this case, the best strategy is to get the bold font in the following manner:

    import com.tivoli.twg.console.NLSUtilities;

    Font boldFont = com.tivoli.twg.console.NLSUtilities.getBoldFont();

There are several advantages of making a bold font in this manner, beginning in IBM Director Version 4.2.

Existing code, such as:

    Font boldFont = new Font( "Dialog", Font.BOLD, 12 );
    JLabel label = new JLabel( "My Label" );
    label.setFont( boldFont ); 

    import com.tivoli.twg.console.NLSUtilities;
    JLabel label = new JLabel( "My Label" );
    label.setFont( NLSUtilities.getBoldFont() );

Testing font integrity

You should test whether your fonts are responding to accessibility changes. In IBM Director Version 5.1 complete the following steps:

  1. Start the IBM Director console
  2. Click Console Preferences -> Accessibility Preferences
  3. Change the font size to a size that is markedly different
  4. Watch your window - Font sizes should have changed 

Color

The TWGConsoleColor class, which is used by many extensions, returns ColorUIResource objects. This is important because the UI delegates update ColorUIResource objects when accessibility changes are made by the user. The UI delegates do not update simple Color objects, therefore the affected objects will not reflect the required accessibility change.

Be aware that objects using setBackground during construction might initially appear to be correct. However, if the user modifies the accessibility settings to use high contrast, they are not likely to recover their original settings when high contrast is switched off.

Dialog color

Dialogs generally open on top of panels. In order for them to stand out from the panel beneath, dialogs in IBM Director use a menu-colored background that makes them stand out from the panel-colored backgrounds. Examples of this are the "file" dialog and the "export" dialog that open when a user right-clicks on the Groups pane of the main console window and selects either Import Group or Export Group. Objects used in the construction of the dialog whose background was set, continue to display correctly when IBM Director is running in Classic mode. If, however, the user sets the accessibility display settings to turn high contrast on and then again to turn it off, the menu coloring will not restore. This is because the UI delegates do not know how these objects should be colored. For this purpose, some classes have been developed that tell the UIManager to install menu colors for commonly-used dialog objects:

These objects are in the com.tivoli.twg guilibs package. These objects are available beginning in IBM Director Version 4.2.

Toolbar color

Prior to IBM Director 4.2, com.tivoli.uif.controls.UFToolbar and com.tivoli.uif.controls.UFToolBarButton were used to create toolbars consistent with the product. These classes have been modified to behave appropriately in response to accessibility changes. Because toolbars are typically added to a panel which is then set to use the menu coloring, a com.tivoli.uif.controls.UFToolBarPanel class has been created that behaves appropriately in response to accessibility changes. All of these objects are available beginning in IBM Director Version 4.2.

Managed object "Create Device" panel color

These panels are displayed when the user right-clicks on the white space of the Group Contents pane and clicks New -> any option from the popup menu. These objects are panels that implement TWGAddMOFObjectInterface. You can use the grep command to determine whether you have such panels. The object should inherit from TWGDialogPanel rather than JPanel and construct using objects mentioned in the section on dialog color.

Testing color integrity

You should test whether your colors are responding to accessibility changes. In IBM Director Version 5.1, complete the following steps:

  1. Start the IBM Director console on a Windows system.
  2. Click Console Preferences -> Accessibility Preferences on the menu.
  3. From the colors combo box, select Windows for High Contrast Only and press OK.
  4. Open your window.
  5. On the windows task bar, click Start -> Control Panel -> Accessibility Options.
  6. Select the Display tab on the Accessibility Options dialog
  7. Select the High Contrast check box and press Apply.
  8. Watch your window; it should reflect the changes set in the Settings for High Contrast dialog that opened when you click Settings in the Accessibility Options dialog.
  9. Go back to the Accessibility Options dialog and clear the High Contrast check box and click Apply.
  10. Inspect your window; it should have returned to its original colors.

Screen readers

All windows must provide meaningful information to a screen reader. Most GUI objects available in the JDK implement the Accessible interface. Each attempts to provide the best default information possible to this interface; however, there is some information that might be set only by the developer, given the context in which the object is used. The three most important pieces of information that should be set for each control used in a window are:

In some cases, icons are used to convey information, such as product name or status. You must appropriately set the icon's Accessible information such that a visually impaired individual can learn as much from the icon as a sighted person. Because Accessible and AccessibleContext are included in both JDK1.3.1 and JDK1.4.1, it is possible to set these items in IBM Director Version 4.2 and higher.

In the next sections certain examples apply to the login dialog (see Figure 1).

Figure 1. Login Dialog

Accessible role

The roles for the ImageIcon, JLabel, JTextField and JButton are set automatically by the JDK as shown in the following example for JLabel. The creation of a new widget would require that it either inherit its accessible role from the super class, or it provide one that is meaningful to the user. 

    public AccessibleRole getAccessibleRole()
    { 
        return AccessibleRole.LABEL; 
    }

The AccessibleRole class in the JDK contains static variables for most common controls, however these roles were not sufficient to satisfy some of the console's needs. As a result, some additional accessible roles were created in a class named com.tivoli.twg.guilibs.TWGAccessibleRole. TWGAccessibleRole is packaged in DirUIL.jar and contains the following additional roles used by the console:

    /**
     * A CALENDAR_BUTTON is a button that is displayed on the scheduling calendar and is used
     * to manipulates the calendar.
     */
    public static final AccessibleRole CALENDAR_MANIPULATION_BUTTON = new TWGAccessibleRole( "TWGCalendarManipulationButtonAccessibleRole" );

    /**
     * A CALENDAR_LABEL is a label that is displayed on the scheduling calendar and is used
     * to provide scheduling calendar information.
     */ 
    public static final AccessibleRole CALENDAR_LABEL = new TWGAccessibleRole( "TWGCalendarLabelAccessibleRole" );

    /**
     * A CALENDAR_LAUNCH_BUTTON is a specially-marked button that, when pressed, opens * a scheduling calendar.
     */
    public static final AccessibleRole CALENDAR_LAUNCH_BUTTON = new TWGAccessibleRole( "TWGCalendarLaunchButtonAccessibleRole" );

    /**
     * A CALENDAR_PANEL is a panel that contains a scheduling calendar.
     */
    public static final AccessibleRole CALENDAR_PANEL = new TWGAccessibleRole( "TWGCalendarPanelAccessibleRole" );

    /**
     * A CALENDAR_SELECTION_BUTTON is a button that is displayed on the scheduling
     * calendar and is used to select
     * a date on the calendar.
     */
    public static final AccessibleRole CALENDAR_SELECTION_BUTTON = new TWGAccessibleRole( "TWGCalendarSelectionButtonAccessibleRole" );

    /**
     * A MARQUEE_PANEL is a panel that displays a scrolling message.
     */
    public static final AccessibleRole MARQUEE_PANEL = new TWGAccessibleRole( "TWGMarqueePanelAccessibleRole" );

    /**
     * A STATUS_FIELD is a label displayed on the status bar which describes the current status.
     */
    public static final AccessibleRole STATUS_FIELD = new TWGAccessibleRole( "TWGStatusFieldAccessibleRole" );

    /**
     * A STATUS_FIELD is a label displayed on the status bar which describes the current status.
     */
    public static final AccessibleRole STATUS_PANEL = new TWGAccessibleRole( "TWGStatusPanelAccessibleRole" );

    /**
     * A STATUS_INDICATOR is an icon displayed on the status bar that becomes
     * animated when a window is processing a request and is still otherwise.
     */
    public static final AccessibleRole STATUS_INDICATOR = new TWGAccessibleRole( "TWGStatusIndicatorAccessibleRole" );

    /**
     * A TABLE_HEADER is row of column headers displayed at the top of a table.
     * The table header contains a label for each column in the table.
     */
    public static final AccessibleRole TABLE_HEADER = new TWGAccessibleRole( "TWGTableHeaderAccessibleRole" );

Accessible name

The accessible name is a localized String that designates the purpose of the object. For some controls, the JDK provides a default. JLabel provides its label text. JButton provides its button text. Thus the screen reader simply reads the text in the labels to the left of each JTextField in the login dialog example (Figure 1). The name of the JTextField controls is subject to the context in which they are used; consequently these need to be set by the programmer. This was done as follows for the server name JTextField:

    JTextField serverNameEdit.getAccessibleContext().setAccessibleName(
                    TWGMainGUI.getProductInfo().getProductServerName()
                    ); 

In the case of the login dialog (Figure 1), the Accessible Name for each text field is the same as the label preceding it.

Accessible description

The accessible description is a short localized String describing the purpose of the object. For example, in the case of a Cancel button on the Login dialog, the accessible description might read "Cancel the login and close dialog box." The accessible description is set by default in very few cases. It should be checked by the developer and explicitly set if not appropriate. This was done as follows for the server name JTextField:

        String[] strarray = new String[1];
        strarray[0] = TWGMainGUI.getProductInfo().getProductServerName();
        String serverAccessibilityDesc = NLSUtilities.getNLSString(
                                                          viewResourcesName, viewResources,
                                                          "TWGServerAccessibleDesc" );
        if ( serverAccessibilityDesc != null )
        {
                    userPmtsDesc[0] = MessageFormat.format( serverAccessibilityDesc, strarray );
        }
        serverNameEdit.getAccessibleContext().setAccessibleDescription(
                             userPmtsDesc[0]
                              );

The accessible description of the server name JTextField reads as follows in English:

"Enter your IBM Director Server name."

Accessible description for icons

Classes that display images such as ImageIcon have an AccessibleContext. Icon descriptions can be set using AccessibleContext. The description is a String that should convey to the visually impaired user all significant information conveyed to a sighted individual. ImageIcon provides the setDescription() method for this purpose. The following code was used to set the icon description for the Login dialog (see Figure 1). The description will read "IBM Director."

        ImageIcon loginIcon = new ImageIcon( image );
        loginIcon.setDescription( TWGMainGUI.getProductInfo().getFullProductName() );

Creating new widgets

If a new widget is created, it must implement Accessible and its AcessibleContext must be fully implemented according to the information supplied in the JDK.

Checking accessible information

A useful utility for verifying that accessibility information has been appropriately set for GUI components is JavaFerret. JavaFerret is included with the Java Access Bridge. It is available for download from Sun Microsystems at the following URL:

http://java.sun.com/products/accessbridge/

JavaFerret tracks mouse movement, focus, and other events and then displays accessibility information about the component in view in a small window.

To install JavaFerret for use with IBM Director complete the following steps:

  1. Download JavaFerret from the URL listed previously and unzip it into the root directory; it will unzip into directory AccessBridge-1.1_GA
  2. Copy the following files into %DirectorRootDir%\Director\jre\lib\ext:
    • X:\AccessBridge-1.1\installer\installerFiles\jaccess1_4.jar
    • X:\AccessBridge-1.1\installer\installerFiles\access-bridge.jar
    • X:\AccessBridge-1.1\installer\installerFiles\*.dll
  3. Add the following line to the accessibility.properties file located in IBM\Director\jre\lib:
    • assistive_technologies=com.sun.java.accessibility.AccessBridge
  4. Add the AccessBridge directory to your path, for example: 
     set PATH=X:\AccessBridge-1.1_GA;%PATH%

To use JavaFerret:

  1. Start the IBM Director Console, and run JavaFerret.exe located in the AccessBridge directory.
  2. When JavaFerret opens, use the JavaEvents menu to select what events to track.
  3. Selecting either Track Mouse Events or Track Focus Events is useful. For this example, select Track Mouse Events.
  4. Using the mouse, hover over different areas and components of the IBM Director GUI. Notice that the information in the JavaFerret window changes as the mouse pointer moves from component to component. 

JavaFerret provides a great deal of information, including AccessibleContext information such as name, description, and role. JavaFerret is not bug-free; therefore it might be necessary in some cases to use another screen reader utility to check AccessibleContext information, such as IBM's Self-Voicing Runtime Environment (SVRE).

Overall window layout considerations

To be accessible, windows should respond to font size changes. You should rely on the standard layout managers wherever possible and allow the window to size itself. While layouts can be tested only with the IBM Director Version 5.1 release, it is frequently the case that the solution for the IBM Director Version 5.1 release will also work in the IBM Director Version 4.2 release, permitting common source code.

Testing window layout integrity

To test whether your window layouts are responding to accessibility changes using IBM Director Version 5.1, complete the following steps:

  1. Start the IBM Director console on a Windows system.
  2. Click Console Preferences -> Accessibility Preferences on the menu.
  3. From the Colors combo box, select Windows for High Contrast Only and click OK.
  4. Now open your window.
  5. On the windows task bar, click Start -> Control Panel -> Accessibility Options; the Accessibility Options dialog opens.
  6. Click on Settings and select a different font size
  7. Select the Display tab, select the High Contrast check box and click Apply.
  8. Watch your window; it should reflect the changes made in the Settings For High Contrast dialog that came up when you chose Settings in the Accessibility Options dialog. Does the window make a good appearance and function properly? All window objects should be visible, readable and functional. If the change makes the window too large for the screen, a scroll bar should be displayed to permit access to all parts of the window.
  9. Return to the Accessibility Options Dialog and clear the High Contrast check box and click Apply.
  10. Try this with all available font sizes to be sure the window works correctly in all cases.

New worst-case test scenario

Previously, defects would be reported when dialogs did not work under low-resolution display settings, 800x600. In IBM Director Version 5.1 and beyond, the new worst-case test scenario is 800x600 using extra large fonts. If the dialog content was large using 800x600 in previous releases, it will be even larger using 800x600 and extra large fonts in IBM Director Version 5.1. Ensure that the window employs scroll bars where required.

Flashing objects

Text and objects that flicker or flash can cause epileptic seizures in susceptible individuals, particularly if the flash has a high intensity and is within certain frequency ranges. This includes text or graphics that flash on and off, or that repeatedly change between different images on the screen.

Because IBM Director 5.1 is an accessible product, it is best to avoid using elements that flash or flicker. If you must use flashing elements, follow these guidelines:

The following techniques are recommended to enhance accessibility:

Timed responses

Some users might have difficulty reading or responding to information if that information is displayed briefly or requires a quick response time. It is important to avoid any timed responses in IBM Director panels.

Information conveyed by color

Color can be most useful in highlighting actions for a visual display; however, if a user cannot identify or distinguish colors they will not be able to make use of the information. The software needs to provide another way of making the information available. For example, asking users to click the green button is not useful if they cannot distinguish the green button from other buttons on the screen. Instead put a label Submit on the green button and ask users to click the Submit button. Consequently, the green is an enhancement to the visual display and the Submit label provides the information to users who cannot identify or distinguish colors.

For IBM Director 5.1, the following guidelines are the best ways to handle the situation:

Set the focus

Even if the software provides keyboard access in order for users to navigate the software, this is not sufficient information if the user does not know their current location. Keyboard users must be able to see the current focus point to know what action to take. To illustrate this, imagine typing if you could not see the caret (insertion bar). Assistive technologies (for example, screen reader, screen magnifier) need to know the position and contents of the visual focus indicator, in order to describe, magnify, or manipulate the object for the user.

When editing, the caret or insertion bar is the visual focus. As a visually impaired user moves the focus with the arrow keys, a screen reader must know the position of that focus so that it can echo the current character, word, or line. Similarly, as a user tabs around a dialog, a screen magnifier needs to follow the visual focus.

While this is a requirement for IBM Director Version 5.1 and beyond, it should also be included in IBM Director Version 4.2.

Respect Keyboard accessibility features

The Windows operating system, CDE/Motif UNIX systems, Linux, and others have a set of accessibility options that enable users with disabilities to customize system-wide keyboard settings to improve accessibility. For example, a Windows user with limited hand use might not be able to press multiple keystroke sequences, such as Ctrl+Alt+Delete simultaneously. Setting the StickyKeys option enables the user to press and release the keys individually to invoke the required function. For example, the user can press and release the Shift key five times, then Ctrl, then Alt, then Delete to restart the Windows operating system.

Keyboard accessibility options make it possible for people with a variety of limited-hand-use disabilities to use their computer. If the application software interferes with these options, some users might find their application unusable.

On Windows systems, the Accessibility Options are customized using the Control Panel settings. On UNIX systems, they are part of the AccessX package.

As a minimum, the following requirements should be considered in IBM Director Version 5.1 and beyond:

Windows

CDE/motif

Considerations



Solving problems with button arrows

 

There are places in the product where “Back” and “Next” buttons are used to guide the user through a process.  Examples of this can be seen in the cfgdb tool, and in the Software Distribution.  In the case of the cfgdb tool,  >” and “<” served as arrows in the 4.x releases of IBM Director.  While this did not present a color problem, it sounded bad when the SVRE was used.  The SVRE would read “Next greater-than” and “Back less-than”.  At first it seemed a simple solutin to replace these with the arrow gif files used in Software Distribution and provide these ImageIcons with Accessible Descriptions.  This presented a color problem.  Many of the high-contrast color combinations use black backgrounds which hid the black icons from view.  Additionally, the icons were intended to match the color of the text which was assigned a different color for the high contrast.  To solve this problem we created the following classes which draw the arrow using the text color so that it matches the print.  This icon was intended for use with text.  The classes are as follows:

 

            com.tivoli.twg.guilibs.LeftArrowButtonIcon

            com.tivoli.twg.guilibs.RightArrowButtonIcon

 

These classes provide their own Accessible Icon Descriptions and are employed n the latest IBM Director 5.1 build.  An example of their use follows:

 

// create the back button

BackButton = new JButton( this.getBundleString( "BackButton" ) );

BackButton.setIcon( new LeftArrowButtonIcon() );

BackButton.getAccessibleContext().setAccessibleDescription( this.getBundleString( “BackButtonAccessibleDesc” ) );

 

// Next Button

NextButton = new JButton( this.getBundleString( "NextButton" ) );

NextButton.setHorizontalTextPosition(TWGDbUFButton.LEFT);

NextButton.setIcon( new RightArrowButtonIcon() );    NextButton.getAccessibleContext().setAccessibleDescription(this.getBundleString("NextButtonAccessibleDesc"));

 

 

Testing color integrity

 

To test whether your windows are responding to accessibility changes using IBM Director 5.1, do the following:

    

1.      Bring up the IBM Director console on a Windows system.

2.      Select from menu: Console Preferences | Accessibility Preferences

3.      From the Colors combo box, select “Windows for High Contrast Only” and press OK.

4.      Now bring up your window.

5.      On the windows task bar, select Start | Control Panel | Accessibility Options.

6.      The Accessibility Options dialog appears.

7.      Select the “Display” tab, check the “High Contrast” box and press “Apply”

8.      Watch your window.  It should reflect the changes set in the “Settings For High Contrast” Dialog that comes up when you press the “Settings” in the Accessibility Options dialog.

9.      Now go back to the Accessibility Options Dialog and remove the check from the “High Contrast” box and press “Apply.”

10.  Check your window.  Has it returned to its original colors?  It should have.  

Accessible description for task icons

Task Icons are provided by the Console Extension which exists at the Server level.  The TWGTask object on the Server creates TWGImageSet objects.  The TWGImageSet object is “shadowed” up to the Console as a TWGConImageSet.  If an NLS bundle name has been associated with the TWGImageSet at the Server level, TWGConImageSet will construct an icon description key from the icon name, load the named NLS bundle and search the bundle for the value of this key.  If a value is located, it will be assigned to the Icon and can be seen using Javaferret. 

Using the Process Management Extension as an example:

AccessibleSelection information:

Selection Count: 1

Name of Selection #0: Process Management

Description of Selection #0: Process Manager Icon | Process Management

Role of Selection #0: Label

States of Selection #0:

Task Icon Descriptions can also be seen under “Accessible Icons” in the JavaFerret when the mouse is moved over an area where the task’s name and/or icon are used.

How this is accomplished in Process Management:

# The ResourceBundle property specifies the resource bundle containing any

# NLS translatable items for the task.  Any text strings for the task are

# specified as the key that should be retrieved from this resource bundle to

# obtain the locale specific version of the string.

#

ResourceBundle = com.tivoli.twg.procman.ProcManResources

# Help file for process manager main panel

helpTopicsMapping       = /com/tivoli/twg/procman/TWGProcManHelp

#-------------------------------------------------------------------------------

# Icon properties define all the GIFs that can be used to represent the task on

# the console GUI.  Each of these properties specifies the path and file name

# for an icon file.  The large versions is used in the task pane of the console.

# The small version is used in the toolbar or list views.  The drag/drop version

# is used as the icon that is displayed as a task object is being dragged.

#

Icon.Large              = /com/tivoli/twg/procman/images/prcmgr32.gif

Icon.Large.Selected     = /com/tivoli/twg/procman/images/prcmgr32.gif

Icon.Small              = /com/tivoli/twg/procman/images/prcmgr16.gif

Icon.Small.Selected     = /com/tivoli/twg/procman/images/prcmgr16.gif

Icon.Toolbar            = /com/tivoli/twg/procman/images/prcmgr24.gif

 

   public final void setImageSet(String iconNames[]) throws TWGTaskException {

      if (iconNames.length != TWGDefaultTask.iconKeys.length) {

         throw new TWGTaskException("iconNames.length must be "+TWGDefaultTask.iconKeys.length);

      }

      try {

          if( (resourceBundle != null) && (resourceBundle.length() > 0) ) {

              TWGImageSet imgset = TWGImageSet.FindImageSet(iconNames,resourceBundle);

              imageSetID = imgset.ObjectID();

              String rb = imgset.getResourceBundle();

              // if this TWGImageSet is a persistant object from a previous install, it might

              // not have a resourceBundle associated with it, so we must save this persistant

              // object with this new change

              if( rb == null )

              {

                  imgset.setResourceBundle( resourceBundle );

                  imgset.save();

              }

          }

          else {

              imageSetID = TWGImageSet.FindImageSet(iconNames).ObjectID();

          }

         setSaveRequired();

         UpdateShadowVersion();

      } catch (InvalidObjectIDException ioid) {

         TWGRas.error(TWGRas.TASK, "TWGTask.TWGsetImageSet: Error finding/creating TWGImageSet", ioid);

         throw new TWGTaskException("Error finding/creating TWGImageSet", ioid);

      } catch (TWGPersistentObjectSaveException pose) {

         TWGRas.error(TWGRas.TASK, "TWGTask.TWGsetImageSet: Error during persistant object save", pose);

         throw new TWGTaskException("Error during persistant object save", pose);

      }

   }

The Process Manager NLS properties file contains the key that TWGConImageSet will construct from the gif file name and attempt to find in the procman.nls file which is used to generate the ProcManResources Bundle:

# Icon Descriptions

image.desc.com.tivoli.twg.procman.images.prcmgr16.gif=Process Manager Icon

image.desc.com.tivoli.twg.procman.images.prcmgr24.gif=Process Manager Icon

image.desc.com.tivoli.twg.procman.images.prcmgr32.gif=Process Manager Icon