You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

Accessible Toolkit Checklist

What needs to be done when building new toolkits

Original author: Aaron Leventhal

Please contact the Mozilla Accessibility Community with questions or feedback.

The Work

When implementing a new toolkit it's important to:

  • Implement standard keyboard behavior, which can vary from platform to platform.
  • Expose your UI - a way for assistive technologies such as screen readers, screen magnifiers and voice dictation software to understand your software.
  • Provide theme compatibility with the operating system, at least as an option. Some low vision users will be running your software with high contrast or large font themes.
  • Go beyond section 508. Implement true usability for everyone, and make your toolkit follow the guidelines for each platform.

The Approaches

There are two basic kinds of toolkits, which each provide different challenges when implementing accessibility:

  • Native widget toolkits, like Eclipse and wxWidgets, already have some accessibility built-in. These toolkits wrap the widgets implemented by the OS with a consistent API for each platform. Since the individual widgets predominately come from the operating system, they already implement standard keyboard commands and follow the operating system's visual theme. Also, assistive technologies already understand native widgets so it is only necessary to implement Microsoft Active Accessibility (MSAA) API support for custom controls. However, be aware that the wrapping layer will introduce accessibility bugs, and thus you will need to test extensively and fill in the holes. You will also need to provide a way for custom and owner drawn controls to easily accessibility API support, as wxWidgets does. There will be custom and owner drawn controls -- there always are. For example, lists of checkboxes are implemented in Windows with images of checked and unchecked checkboxes.
  • Owner drawn toolkits, like XUL and Flash's Flex UI framework use few or no native widgets. These toolkits need to have accessibility implemented from the ground up, and get nothing for free in terms of keyboard, API or OS-theme support. In this case, adding a complete or even a partial accessibility solution is major work, and will require more than one full time person as well as cooperation from Windows assistive technology vendors when parts of your MSAA solution isn't working. Often these kinds of toolkits don't use a separate window for each control; in that case remember to generate a unique 32 bit child ID for each control so that the MSAA event system can call back for the right IAccessible for each event.

The Checklist

This checklist is currently only for Microsoft Windows, but should be expanded to include information about Linux and OS X. It is maintained by the Mozilla Accessibility Community. Contributions are welcome.

General

  1. Dialogs/windows/general
    1. Escape key cancels dialogs and refocuses the previously focused on the parent window.
    2. Alt+F4 closes windows, similar to Escape but even works on dialogs without Cancel button
    3. Alt+space opens window menu with Restore, Move, Size, Minimize, Maximize, Close
    4. The Move and Size options must be usable with the arrow keys on the keyboard
    5. In windows, initial focus goes to first focusable widget that is not a clickable tabbed property sheet label
    6. Making tab order definable. Default tab order should be in document order.
    7. Tab order must wrap, not have invisible items in tab order
    8. Dynamically added items must not corrupt the tab cycle or make it disorderly
    9. Tab cycle must be identical backwards and forwards
    10. The F6 and Shift+F6 key combinations should cycle through panes in a window
    11. Making focus visible on any widget, and focus must always be visible
    12. Shift+F10 or context menu key should work like right click on focused item, and context menu should show just under and to the right of the current focus. On Mac OS X, ctrl+space is used to bring up the context menu.
    13. Most widgets (like checkboxes) can have a label outside of themselves, which should focus the widget when clicked on, or when its mnemonic is pressed. The system should require these labels to be created/associated with each widget, not as a separate static text with no tie to the widget. The MSAA support needs to know what label goes with what widget.
    14. MSAA support: expose window with ROLE_DIALOG, unless it's already the standard dialog window class #32770. If you don't, some screen readers won't automatically read the dialog when it receives focus. Expose status bars with ROLE_STATUSBAR, unless they already use the standard window class msctls_statusbar32. Make sure that parent-child relationships are exposed correctly in each window's MSAA tree
  2. General MSAA support
    1. Focus events
    2. Handling event callbacks, which requires a unique ID for each non-windowed child of every widget that can be focused or have any other event associated with it. For example, a unique child ID would be required for each tree item
      • Supporting the most important basic IAccessible events
      • get_accParent: Get the parent of an IAccessible.
      • get_accChildCount: Get the number of children of an IAccessible.
      • get_accChild: Get the child of an IAccessible.
      • get_accName: Get the "name" of the IAccessible, for example the name of a button, checkbox or menu item. This is one reason why a label must be created together with each widget, rather than separately.
      • get_accValue: Get the "value" of the IAccessible, for example a number in a slider, a URL for a link, the text a user entered in a field.
      • get_accRole: Get an enumerated value representing what this IAccessible is used for, for example. is it a link, static text, editable text, a checkbox, or a table cell, etc.
      • get_accState: a 32 bit field representing possible on/off states, such as focused, focusable, selected, selectable, visible, protected (for passwords), checked, etc.
      • get_accKeyboardShortcut: What is the keyboard shortcut for this IAccessible (underlined alt+combo mnemonic)
      • get_accFocus: Which child is focused?
      • get_accSelection: Which children of this item are selected?
      • accLocation: Get the x,y coordinates, and the height and width of this IAccessible node.
      • accNavigate: Navigate to the first/last child, previous/next sibling, up, down, left or right from this IAccessible. [important, but no need to implement up/down/left/right]
      • accDoDefaultAction: Perform the action described by get_accDefaultAction.
    3. Supporting the basic MSAA states on every item: unavailable, focused, readonly, offscreen, focusable
    4. To avoid extra work, utilize implementing an MSAA Server
  3. Mnemonics
    1. Ability to define in XML for any widget with a text label (via attribute or a preceding char in label)
    2. Automatically define mnemonics for all standard common dialogs (like Yes/No confirmations and Retry/Exit error dialogs)
    3. Support mnemonics in dialogs created via method calls
    4. Layout engine - drawing underline under correct letter
    5. Events - making keystrokes do the right thing
    6. MSAA support, via IAccessible's get_accKeyboardShortcut
  4. Support for MS Windows settings
    1. When high contrast checkbox is set (in accessibility control panel, SPI_GETHIGHCONTRAST), or when user selects a "Native" skin option in your software, then get all look and feel from current OS skin.
    2. The high contrast theme can be toggled dynamically with LeftAlt+LeftShift+printscreen
    3. Expose the SPI_GETSCREENREADER flag to XML/scripts so that apps can alter behavior
    4. Use system highlight color where possible for item selection, but never use that exact color in more than 1 place at a time, otherwise screen reader will read everything with that color whenever highlight changes
    5. Pay attention to SPI_GETCARETWIDTH for the correct width of the caret
    6. Pay attention to 'route mouse pointer to default button' setting
    7. It's possible that the user wants mnemonics hidden except when the alt key is pressed. This can be supported through SPI_GETKEYBOARDCUES and SPI_GETMENUUNDERLINES

Simple widgets

  1. Buttons
    1. Tab, arrow, unmodified letter mnemonics
    2. Require and support text labels for buttons with images, can be same as tooltip
    3. Space key activates button
    4. Enter key activates focused button (thus current button, not default button shows dark border when a different button is focused)
    5. When button has a popup available by clicking on it, the Enter key or space bar should also activate the popup
    6. Toolbars and toolbar buttons are not focusable, but we should expose the tooltip. If possible, make the tooltip automatically append text for the keyboard shortcut associated with it.
    7. MSAA support, including the haspopup state
  2. Default buttons
    1. Ability to define in XML
    2. Enter key fires it, but not when another widget has focus that needs the Enter key
    3. Layout engine - drawing dark border dynamically when the currently focused widget does not need the Enter key
    4. Events - making keystrokes do the right thing
    5. MSAA support (default state)
  3. Links
    1. Enter key activates link (thus default button no longer shows dark border when link is focused)
    2. MSAA support, including linked and traversed states, and accessible value that holds destination URL
  4. Text fields - single and multiple line
    1. It's probably best to use native widgets for these, otherwise accessibility support will be quite difficult
    2. Tab should always focus the next item, not insert a tab, unless there's a really good reason and another way to navigate
    3. Always use system selection color, otherwise screen reader won't read the text
    4. Make sure the caret is never blinking when focus is not in text field
    5. Handle standard editing keys, such as arrow keys, home, end, pageup, pagedown, ctrl+left/right, shifted keys for selection, delete, ctrl+delete, backspace, ctrl+backspace, ctrl+a, ctrl+b, ctrl+c, ctrl+i, ctrl+u, ctrl+x, ctrl+v, ctrl+[shift]+z
    6. In multiline text field, Enter key inserts new line (thus default button no longer shows dark border when multiline text field is focused)
    7. In autocomplete text fields, make sure the autocomplete popup doesn't receive actual or MSAA focus unless an up/down arrow is pressed, and don't use the default system highlight color in the list itself unless it really has focus
    8. In autocomplete text fields, make sure that the delete or backspace key removes all auto completed selected text.
    9. In autocomplete text fields, make sure that the left or right arrow closes the popup and starts moving through the text letter by letter
    10. MSAA support, including accessible value that holds text, protected for password fields and readonly for read-only fields
  5. Checkboxes
    1. Space bar to toggle
    2. MSAA support, including checkbox state and statechange event
  6. Sliders
    1. Keyboard support for moving slider: arrow keys, home, end, PgUp, PgDn
    2. MSAA support including ROLE_SLIDER, accessible value, value change events
  7. Progress bars
    1. MSAA support including accessible name, value, name and value change events

Grouped navigation widgets

  1. Menus
    1. Arrow keys, Enter, Escape
    2. Alt alone enters main menu
    3. After leaving menus, focus is restored to where it was
    4. Modified and unmodified mnemonics
    5. MSAA support (including focus events, menu start and end events, radio and checkbox menu items)
  2. Static text and Group boxes
    1. MSAA support
  3. Radio groups
    1. Only the selected radio button is in the tab order
    2. The other radio buttons can be selected and focused with up/down arrow.
    3. The focused radio button is always selected, and vice versa
    4. Keyboard and MSAA support must still work correctly when radio button labels have textfields, combo boxes or other controls as part of their prompts.
    5. MSAA support, including checkbox state and statechange event
  4. Tab panels
    1. Ctrl+[shift]+tab or Ctrl+PgUp/PgDn to switch tabs
    2. Tabs can be focused, and then left/right arrow to switch
    3. First click on a tab switches to it, second click focuses it
    4. MSAA support. Note, you can use the accessible description to expose the current tab position, such as "3 of 5" in order to provide ease of access for the user. The "of" will be parsed out by the assistive technology, so don't localize it.
  5. Lists and combo boxes
    1. When a list is tabbed to, select the first item if nothing else is already selected
    2. F4, Alt+down or alt+up toggle a combo box open and closed
    3. Escape closes combo box if it was open (be careful not to have it cancel entire dialog)
    4. Up/down arrow key navigation. Shift+up and shift+down move and extend the selection.
    5. Typing letter or several letters to navigate (same letter goes to each item starting with that, different letters go to first item starting with that entire string).
    6. Multiple selection is possible with Ctrl+arrow to move focus without selecting, then space to select item, shift+space to select to current point or control+space to toggle selection of current item
    7. Shift+F10 or context menu key to bring up context menu for current item. Generate a context menu event. On Mac OS X, ctrl+space is used to bring up the context menu.
    8. Space bar toggles checkboxes
    9. For listboxes, use owner drawn list items to show a different highlight color when the list is not focused. If you don't the list focus will not be apparent, and screen readers may read the selected list item when they shouldn't. For unfocused lists, use a lighter color highlight to show a non-focused state. For autocomplete lists, use the system color offset by 1, so that it looks active but the list items don't get echoed while they user's trying to simply type and edit.
    10. MSAA support, including accessible selection, selectable, multiselectable and extselectable states, and statechange events for checkbox children
  6. Trees
    1. When a tree view is tabbed to, select the first item if nothing else is already selected
    2. Up/down arrow key navigation
    3. Left arrow to first collapse a branch, then move to parent
    4. Right arrow to first expand a branch, then move to first child
    5. Multiple selection is possible with Ctrl+arrow to move focus without selecting, then space to select item, shift+space to select to current point or control+space to toggle selection of current item
    6. Typing letter or several letters to navigate (similar to list support for this)
    7. Shift+F10 or context menu key to bring up context menu for current item (On OS X ctrl+space is used to bring up context menu).
    8. Space bar toggles checkboxes
    9. The enter key should activate an item if double clicking would do so
    10. MSAA support, including accessible selection, exposing current level and position in list, alternative text for informative or interactive images, selectable, multiselectable and extselectable states, statechange events for expanding/collapsing and toggling of checkbox children. Note, you can use the accessible description to expose the current tree view level and position, such as "L3, 6 of 9" in order to provide ease of access for the user. The "L" and "of" will be parsed out by the assistive technology, so don't localize it.
    11. Mac OS X difference: option+left and option+right should do deep expand/collapse
    12. Mac OS X difference: user should be able to select multiple rows and expand them with one keystroke. After the expansion, the multiple (now discontiguous) selection should remain.