User Interface Specification:
GNOME 2.x Keyboard Accessibility Status Applet

Introduction

Overview of Functionality

In GNOME 2.0, the Keyboard Accessibility Preferences window allows the user to set various keyboard accessibility properties.  These include the standard AccessX features Mouse Keys, Sticky Keys, Slow Keys and Bounce Keys.

• Mouse Keys allows the user to move the mouse pointer and emulate pressing, releasing, clicking or double-clicking mouse buttons using only the numeric keypad on the keyboard.
• Sticky Keys allows the user to input keyboard combinations (for example, Ctrl-Alt-Del) by pressing the keys sequentially rather than simultaneously.
• Slow Keys prevents a key from registering until it has been held for a short length of time.
  
• Bounce Keys filters out any repeated presses of the same key for a short time after the first keypress.
  

The status indicator described by this spec provides a dynamic on-screen indication of the state of whichever of these three AccessX features are enabled at any given time. For example:

Fig 1. Mockup of status indicator applet in use on a horizontal panel (blue area represents desktop): Mouse Keys indicator (first icon), Sticky Keys indicator (next four icons), Slow Keys indicator (showing Slow Keys is enabled), and Bounce Keys indicator (showing Bounce Keys is disabled).

Context

The status indicator is a GNOME 2.x panel applet, which the user adds to their panel by right-clicking the panel, and selecting Add to Panel->Utility->Keyboard Accessibility Status.  (Or should we push for an Accessibility category on the Add to Panel menu?  Are there likely to be any other accessibility applets in future?)

The status indicator provides similar information to the status windows available in the CDE version of AccessX.

The source code will ideally live in the gnome-applets module in GNOME cvs.

References

• Chema Celorio's Sticky Keys applet
• Joergen Scheibengruber's Lock Keys (Toggle Keys) applet

who should be credited appropriately if parts of their code are re-used.

User View

Description of the Users

AccessX is aimed at users with physical disabilities that would otherwise prevent them from using a normal PC keyboard effectively.  This status indicator applet is primarily aimed at the same audience.

A small, secondary audience might include users with keyboards that do not have LED lock indicators (or whose indicators have broken), for whom Toggle Keys may be useful, and users whose mouse is malfunctioning or temporarily disconnected, for whom Mouse Keys may be useful.

User Model

The applet displays a graphical representation of a three-button mouse and the keyboard's modifier keys.  For localization reasons, however, symbols are used to represent all the modifier keycaps, rather than the wording that may actually appear on the user's keyboard.

The status indicator does now allow any direct manipulation of its icons, it is a read-only display.  However, by double-clicking any part of the applet, the user can open the GNOME Keyboard Accessibility preferences window to configure their AccessX preferences.

Scenario

(Note: In this scenario, the steps that the <whatever unit> implements are shown in normal text, and the external steps are shown in italics.)

<Recommended: Tell a brief story in which user(s) solve a realistic problem with this unit. Do include some context: other units that the user uses before, during, and after this unit. Distinguish between the steps that are covered by this unit versus external steps, by using italics for the external steps. Do not include a detailed keystroke-by-keystroke account, but a give a higher-level description of a realistic set of chronological steps.>

<Nice to have: Significant branches in the storyline, illustrating common alternate paths and/or common things that can go wrong.>

<Nice to have: Give references to more detailed user profiles and scenarios in other files, if you prepared them.>

System-Wide UI Impact

Panel Menu

The Add to Panel menu is posted when the user right-clicks any panel's background. This will require a new Keyboard Accessibility Status item added to its Utility sub-menu.

Fig 2. Position of menu item for launching the status indicator

Control Center

The Accessibility capplet could also be modified to include a show/hide status applet checkbox, but the mechanics of that are unlikely to be pleasant and is probably best avoided as long as the status indicator is implemented as an applet rather than a status tray icon.

Detailed Spec

The applet consists of three status indicators:

• mouse keys indicator, containing a single icon
• sticky keys indicator, containing four icons
• toggle keys indicator, containing three icons 

For simplicity of interaction and to reduce clutter on the panel, each indicator is only shown only if the corresponding AccessX feature is enabled in the Keyboard Accessibility preferences dialog.

Depending on the size and orientation of the panel, and the characteristics of the current theme, the three indicators may be arranged on one of four ways. See Layout and Resize Behaviour below for details of the four layouts and when each layout should be used.

General Interaction

The user can right-click each of the three indicators to pop up a context menu relevant to that indicator.  Each of the three indicators must be individually-focusable to allow equivalent keyboard navigation.  However, individual icons within each indicator are not individually focusable.

None of the three indicators respond to a single left-click, they are for information only.

Double-clicking any of the indicators opens the Keyboard Accessibility preferences window.

Layout and Resize Behavior

The Mouse Keys icon is always drawn to fit the height or width of the panel (depening on whether the panel is horizontal or vertical), and scaled proportionately in the other direction. It is therefore always the same size as any launchers on the same panel.

For horizontal panels, if panel height >= twice the gtk-small-toolbar icon height for the current theme, the Slow, Bounce and Sticky indicators are split over two rows, with each row's height being half the panel height:

Otherwise, the indicators are shown in a single horizontal row, with a small gap between adjacent indicators:

For vertical panels, if panel width >= twice the gtk-small-toolbar icon width for the current theme, the Slow, Bounce and Sticky Keys indicators are split over two columns, with each column's width being half the panel width.

Otherwise, the indicators are shown in a single vertical column, with a small gap between adjacent indicators:

Each indicator extends as close as possible to the top and/or bottom of a horizontal panel, or to the left and/or right of vertical panel, whilst still allowing its focus indicator to be drawn at the correct width for the current theme.

When an AccessX feature with a corresponding indicator is turned off, the indicator's "disabled" icon is shown.  So, for example, with all four features turned off, this is how the applet would appear in each of the four layouts described above:

Tab Order

Initial focus: Mouse Keys indicator.
Tab order: Mouse Keys, Sticky Keys, Slow Keys, Bounce Keys.

Focus indicator style and width respects the current gtk theme.

Remember that within an applet, focus is moved around with the arrow keys, not the Tab key. Tab moves focus on to the next object on the panel.

Tooltips

The tooltip for the top-level applet window is:

Actions

Content to Cover in Online Help

<Stuff that it's important to call out in the docs. Particularly user confusions that can be foreseen.>

Selection, Dragging, and other Direct Manipulation

User can move the applet by clicking and dragging any part of the applet with the middle mouse button.

Double-clicking any part of the applet opens the Keyboard Accessibility Preferences window.

Mouse Keys Indicator

The mouse keys indicator is a single icon that serves three purposes:

1. It shows whether Mouse Keys is enabled or disabled.
2. A marker in the icon shows which mouse button is the Mouse Keys default (i.e the one that will be pressed or clicked when the user presses the '5', '0'  or '.' keys on the numeric keypad)
3. The correpsonding button in the icon is highlighted while any mouse button is pressed (via Mouse Keys or a connected pointing device).

Mouse Keys Enabled

A single icon representing a mouse is shown, with a dot on the relevant button indicating which button is the Mouse Keys default:

Fig 4. Three instances of the Mouse Keys indicator, showing appearance when button 1, button 2 or button 3 is the default, respectively.

The relevant button is highlighted while the corresponding mouse button is pressed, whether that be using Mouse Keys or on a pointing device attached to the system:

Fig 5. Three instances of the Mouse Keys indicator, showing appearance when button 1, button 2 or button 3 are pressed, respectively.

Note that when the default button is pressed, the default button indicator is still shown, inverted.  It remains inverted until the button is released again.

To best support the correct display of "chorded" inputs (i.e. pressing two or more mouse buttons simultaneously), the Mouse Keys icon are composited from the icons provided.  For example, the first icon in figure 5 above is composited of:

See also Open Issues.

Mouse Keys Disabled

Tooltips

Enabled

When Mouse Keys is enabled in the Keyboard Accessibility Preferences window, the tooltip for Mouse Keys indicator is:

Mouse Keys
Default Button: <n> [(Locked)]

Example:

Mouse Keys
Default Button: 1

Example:

Note: the default Mouse Keys button is "locked" when the user presses the "." (period) key on the keypad.  It is unlocked again when the user presses "+", "5" or "0" key on the keypad (release, click, and double-click respectively), or clicks or double-clicks the corresponding button on a connected input device.

Is a locked default button also unlocked when you choose a different default button?  Need to check.  If not, it's probably possible to have more than one button locked at a time, so tooltip format will need to change.

Disabled

When Mouse Keys is disabled in the Keyboard Accessibility Preferences window, the tooltip for Mouse Keys indicator is:

Mouse Keys Disabled

Actions

[Enable | Disable] Mouse Keys    (depending on whether feature is currently turned off or on respectively)
--------
Preferences                           (opens GNOME Keyboard Accessibility Preferences window with Mouse tab frontmost)
Help
About
--------
Remove from Panel
Move

Sticky Keys Indicator

Sticky Keys Enabled

The sticky keys indicator displays four icons, showing the latched/locked status of the Shift, Ctrl, Alt and Meta keys.  A latched modifier only affects the next (non-modifier) keypress, and a locked modifier affects all subsequent keypresses until it is unlocked again.  When Sticky Keys is active, a modifier is latched by pressing it once, and locked by pressing it twice in succession.

The icons are always shown in the following order (left to right, or top to bottom, depending on the applet orientation):

• Shift
• Ctrl
• Alt
• Meta

See also Open Issues for note about Super and Meta keys.

When locked or latched, Shift is always shown in the first position, Ctrl in the second position, Alt in the third position and Meta in the fourth position. Placeholder icons are shown for the keys that are not locked or latched, so that the applet still has some graphical presence on the panel even when no keys are locked or latched and Mouse Keys is switched off.

Examples:

User types...	Effect	Sticky Keys Indicator shows...
Shift	Shift latched
Ctrl, then Shift, then Shift	Shift locked, Ctrl latched
Ctrl, then Shift, then Shift, then Ctrl	Shift locked, Ctrl locked
Shift, then Meta, then Alt	Shift latched, Alt latched, Meta latched

Sticky Keys Disabled

Tooltips

Enabled

When Sticky Keys is enabled in the Keyboard Accessibility Preferences window, the tooltip for the Sticky Keys indicator is:

Sticky Keys
Latched: [[Shift][,][Ctrl][,][Alt ][,][Meta] | None] ; Locked: [Shift][,][Ctrl ][,][Alt][,][Meta] | None.

Example:

Sticky Keys
Latched: Shift, Alt; Locked: None

Disabled

When Sticky Keys is disabled in the Keyboard Accessibility Preferences window, the tooltip for Sticky Keys indicator is:

Sticky Keys Disabled

Actions

Bounce Keys Indicator

Bounce Keys Enabled

Bounce Keys Disabled

Tooltips

When Bounce Keys is disabled in the Keyboard Accessibility Preferences window, the tooltip for Bounce Keys indicator is:

     Bounce Keys [Enabled | Disabled]

When Bounce Keys is disabled, the tooltip is:

Actions

Slow Keys Indicator

Slow Keys Enabled

Slow Keys Disabled

Tooltips

When Slow Keys is disabled in the Keyboard Accessibility Preferences window, the tooltip for Slow Keys indicator is:

When Bounce Keys is disabled, the tooltip is:

Actions

Usability Measurement

Usability Goals

<Describe the usability goals for this unit. Refer to the classes of users described in the User View section. This will typically be couched as "<user-type-n> can perform <task-n> in time <n> with <what help and other support>, with <how much trouble>." Goals like this can focus on learning (first-time experience) or on more practiced performance.>

Usability Testing

<Describe the usability testing that is planned for this unit. It's fine if this unit is included with other units in one larger test. After the test has occurred, include pointers to the test plan and the report in the References section, and describe them briefly here.>

Required Graphics

Icons

Note: most of these icons are just placeholders for now... final icons will be added as they are developed.

Graphic	Description	Status
	Mousekeys, used as basis for compositing	<not yet requested>
	Mousekeys button 1 default indicator	<not yet requested>
	Mousekeys button 2 default indiicator	<not yet requested>
	Mousekeys button 3 default indicator	<not yet requested>
	Mousekeys button 1 default indicator when pressed	<not yet requested>
	Mousekeys button 2 default indicator when pressed	<not yet requested>
	Mousekeys button 3 default indicator when pressed	<not yet requested>
	Mousekeys button 1 pressed	<not yet requested>
	Mousekeys button 2 pressed	<not yet requested>
	Mousekeys button 3 pressed	<not yet requested>
	Shift latched	<not yet requested>
	Shift locked	<not yet requested>
	Ctrl latched	<not yet requested>
	Ctrl locked	<not yet requested>
	Alt latched	<not yet requested>
	Alt locked	<not yet requested>
	Meta latched	<not yet requested>
	Super latched (if required?)	<not yet requested>
	Super locked (if required?)	<not yet requested>
?	Hyper latched (if required?)	<not yet requested>
?	Hyper locked (if required?)	<not yet requested>
	Key neither locked or latched	<not yet requested>
	MouseKeys disabled
	StickyKeys disabled	<not yet requested>
	SlowKeys enabled	<not yet requested>
	SlowKeys disabled	<not yet requested>
	BounceKeys enabled	<not yet requested>
	BounceKeys disabled	<not yet requested>

At a minimum, High Contrast Inverse and Low Contrast versions of these icons will also be required. (The standard icons will hopefully double as the High Contrast icons, eliminating the need for a special set of those.)

If theming is done using libgnome icon theming rather than gtk stock icon theming, provision of additional hand-drawn 16x16 versions may be desirable, depending on how the applet looks on smaller panels.

Notes

Alternative Proposals

Main issue was whether to implement as status notification icons rather than an applet.  Rejected for now because:

- This is really a whole bunch of status indicators that need to be grouped together; the status tray isn't really designed for that.
- Status indicator area may or may not be fully accessible/keynavigable in time for 2.4 anyway.

In Joergen's orginal Lock Keys applet, the icons have a 3D effect to look more like actual keys. However, I felt this made them look too "clickable", so I'd suggest a flatter look like the one I've used in the mockups here.

Open Issues

• What other keys does Sticky Keys need to track?  On Wintel boxes, the Windows key is sometimes mapped to Super rather than Meta, do we need to cater for that too?  What about Hyper?  Does XKB's Sticky Keys feature support all these?

• Do we need to be able to control the visibility of the indicators separately from the on/off state of the features themselves?  I was hoping not, because that would mean I'd have to design a Preferences dialog as well :)

• If the user's mouse is set to left-handed in the Mouse Preferences, pressing the left button on a connected mouse is going to light the right-hand button on the Mouse Keys icon, and vice versa, which seems rather confusing.  But if we swap the buttons around on the icon as well, pressing B1 using Mouse Keys is going to light the right-hand button, which might be equally confusing for a keyboard-only user, who might not even know his mouse preferences have been set to left-handed.  Not immediately clear what the best solution is here.  Possible factors include:

• how many people we think are going to be using Mouse Keys only vs. the number who might be using Mouse Keys in conjunction with an attached input device.  If the MouseKeys-only audience is significantly larger (and I'm guessing it is, not swapping the buttons around on the icon is probably fine.
  

• left-handed Mouse Keys users might actually prefer the Mouse Keys mouse icon to behave as if they were using a left-handed mouse, in which case we'd need to swap the icons.
  

Of course we could make this a preference, but right now this applet has no preferences of its own, and it would be nice to keep it that way :)