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

Mozilla Keyboard Planning FAQ and Cross Reference

This FAQ and cross reference will help us find unused keystrokes, look for patterns, see what has or hasn't been implemented and have consistency in our UI. We want implementers to follow this spec, so if you wish for something other than what's here, please let us know where the spec falls short. Before suggesting changes, make sure to read this entire FAQ, as it spells out our current policies and our reasons for them.

We realize it's a good idea to leave as many keystrokes open as possible, for future expandability. If you see keystroke commands in the spec that are superfluous, let us know so we can clear more space. Some hotkeys may end up being relegated to a special configuration file or preference, for the particular set of users that need them.

Contents

  1. Cross Reference
  2. Definitions
  3. Four Major Platforms
  4. Modifier Key Policies
  5. Tab Behavior
  6. Avoiding Function Keys for Crucial Roles
  7. Potentially Destructive Keys
  8. Macintosh Keyboard Differences
  9. Accesskey Conflicts
  10. Keyboard Configurability
  11. Summary for Coders
  12. Informational Links
  13. Keyboard UI Mailing List

Cross Reference

Here's an outline of all the global hot keys in Mozilla, for the browser, editor, mail-news and widgets. This document does not discuss underlined menu accelerators and the like, as those are part of i18n.

Please read the entire FAQ before recommending changes

  • Interactive frames version - only works in Gecko-based browsers. And yes, we know your keyboard looks different. Mac keyboards have don't have a Windows key, but they do have a Cmd key. Many UNIX keyboard have a Meta key.
  • No-frames version - basic reference.

Definitions

  • Key binding: a piece of data that defines the connect between a keystroke and a command.
  • Modifier: a key that is used in combination with another, such as Alt, Ctrl, Shift or Cmd (a.k.a. the Apple key).
  • Hotkey: a key with a binding that crosses widget boundaries, and can act globally in the current window.
  • Accelerator: a key who's behavior is defined locally by the widget the focus is currently in.
  • Accel key: the modifier used in conjunction with letter and number keys on a given platform for hotkey commands.
  • Shortcut: ambiguous term, could mean any kind of keystroke command. Not used in the spec.
  • Accesskey: an attribute in HTML or XUL for defining an accelator. A letter in the command name that corresponds to the accesskey is usually underline.

Four Major Platforms

We define the keyboard combinations for 4 major platform groups. Our spec currently only deals with the first three - it doesn't talk about OS/2. At some point, we may fold in the OS/2 keyboard information.

  • Windows (includes BeOS)
  • UNIX (includes Linux)
  • Mac OS
  • OS/2 (these keybindings are set by IBM)

Modifier Key Policies

What's the modifier key situation? When is Ctrl/Shift/Alt/Cmd used?

One "Accel" Key per Platform

For hotkeys, we normally use only one accelerator key per letter. On Mac we default to Cmd and on everything else we default to Ctrl. The accel letter combination can also be used with shift for a related command. When defining keystrokes in XBL, modifier="accel" is mapped to the appropriate key for that platform.

There are several reasons for this limitation of 1 accel key. First, Mac OS only offers the Cmd key for acceleration, since Alt+Letter combinations are reserved for entering special characters in text. Mac OS applications are not supposed to use the Ctrl key modifier for commands, and Mac users do a double-take when they are told to use such a key combo.

UNIX systems provide a special challenge: the need to support legacy Emacs keybindings that may conflict with Mozilla keybindings. For example, in Emacs Ctrl+A moves the caret to the beginning of a line, but in Mozilla, Accel+A is the select all command. Which should win out? In 4.7, we worked around this by having Alt as the default accelator key. However, this goes against the expectations of many newer users, as well as the default behavior of the Gnome and KDE environments. If we consider a secondary accel key key for Unix systems, we have to consider it is possibly already taken up by an Emacs key binding.

A final issue is that HTML defines the accesskey attribute, which allows page authors to define accelerators for webpages, usually indicated with underlined letters. Where possible, a modifier key should be reserved for accesskeys.

Therefore, while it may be desirable to use Alt as a secondary accel key on the Windows platform, this would leave it as the sole beneficiary of those bindings, and we would still need to find another key combination for the other two platforms. So far, it's been simpler to try finding consistent key combinations that work for all platforms at once. This means that for hotkeys, we can only assume one modifier key per letter, with and without shift.

No Ctrl key combos on Mac OS

The Mac human interface guidelines ask developers to use Cmd, not Ctrl. Using Ctrl for hotkeys would confused many Mac users. We can, however, offer Ctrl combinations for user-defined keystrokes (once we start offering keyboard configurability).

Use "Accel" key with letter and number keys, specify exact modifier for other keys

In our spec, the Accel key is the key that can change between Ctrl, Alt or Cmd, thus changing what modifier is used with different letters. For all other keys (numbers, function keys, navigation keys and editing keys like Delete and backspace), our spec says exactly what modifier is used in each command combination. For example, Alt+Left always means "Go to previous page in history". For Ctrl+ combos, we general say Ctrl/Cmd(Mac), to show that Ctrl is used on Windows and UNIX for this command, and Cmd is used on the Mac.

No Ctrl+Alt combinations

On international keyboards Ctrl+Alt is used to access accents and other special characters. Even UK keyboards have 6 Ctrl+Alt keystrokes (11 if you count upper case): á, é, í, ó, ú (acute accentuated vowels) and EUR (Euro currency symbol Ctrl+Alt+4).

In addition, Ctrl+Alt+Letter combos are traditionally reserved on Windows for defining user application startup hotkeys. This isn't set in stone, so if we really start running out of keys, perhaps we can change this policy. For now, consistency is a good thing, and we don't need them.

Try to group related functions together on the same key

For example, we try to reserve Accel+Shift+Letter for commands that are related to Accel+Letter, where possible. This makes our interface more elegant, and makes the hotkeys easier to remember.

Avoid modified punctuation keys

Many keyboards from around the world don't support the punctuation you might expect (some don't even have semicolon!). You also can't assume that two punctuation characters are on two different keys. For example, comma may be on a different key from period, or may be on the same key. Also, a punctuation key may be shifted on some keyboards and unshifted on others, and a binding which specifies an unshifted key won't work if shift is pressed (and vice versa). So, while some of our hotkeys can be reassigned by the i18n team, it's a good idea to use punctuation combos for non-essential things, so that we don't lose much if the key isn't available. Here's a set of international keyboard layout diagrams.

Emacs editor bindings always go on Ctrl

Emacs bindings are currently available only on the UNIX platform. On some letters, there is an accel binding, and a ctrl(unix) binding. When these two bindings conflict (as in Ctrl-A or Ctrl-H), the emacs binding wins. Most of the time, the bindings will follow focus, so e.g. if the focus is in an editing field, the editing binding will be used, if the focus is in the browser content area, the browser binding will be used. More information on this in the open issue below.

Open Issue: The default UNIX accel key is Ctrl

The default accel key was Alt in Netscape 4.7. A good reason for keeping Ctrl is to be consistent with Gnome and KDE. A good reason for making it Alt, is that more of the Emacs key bindings are then available for use. Reasonable people disagree on this issue. To learn how to switch your accel key, see the customizing document. It may be desirable to build a pre-made keyboard configuration file for users who want pure-Emacs style control. Akkana Peck has reopened this issue. If you feel strongly either way, please email mozilla-accessibility@mozilla.org with your preference.

Macintosh Keyboard Differences

Not all Macintosh keyboards are the same. For example, older macs may not have any function keys at all, newer Macs have F1-F12, very few have F13-F15 (F13-F15 are usually labelled Print Screen, Break etc on PCs). When function keys are present, Mac OS allow users to define their actions (macros). For these reasons we want to avoid the only key binding for a feature being on a function key. If the feature is important or common, it must have an alternative means of activation.

Some Macs are missing keys like "insert" or "end" or "pageup" or "del". The Backspace key is labelled "delete" and represented in menus by an icon, "enter" is a key on the numeric keypad and the key PC users call "enter" is labelled "return". Some have separate "help" keys while others have "help" on the "insert" key. Some have a "clear" key. The layout of keys like Insert, Delete, Home, End, etc. may be different from keyboard to keyboard. That's just the US English keyboards: in other words, the fewer assumptions you make, the happier the users will be.

Mac OS does not have a built in way of walking through the menubar with the keyboard. Mac OS reserves Alt (Option), and Alt+Shift letter combinations for inserting special characters and those required by non-English languages.

Open Issue: Should keys that OS X has taken over be replaced?

As of OS X, Cmd+M and Cmd+H are taken over by the system for the "mimimize windows" and "hide window" commands. Mozilla and Netscape 4.7 used these for "new mail" and "history". We've even heard that Cmd+M now crashes Mozilla under Mac OS X. Are these commands now and forever relegated to using the mouse with pull down menus on Mac? Should we invent new keys for those commands in OS X? Should we make an exception in this case and use Ctrl? We need an avid Mac user who loves keyboard commands to step forward on issues like this.

Another important fact is that we're already going against platform UI guidelines with our Accel+N behavior. The standard on Windows and Mac OS is for Accel+N to open a new document or window of the appropriate kind, depending on the application. For example, Accel+N should open a new browser window in Navigator, a new empty document in Composer, a new message composition in Mailnews and a new card in the address book. Users would use the Accel+digit hotkeys if they wanted a keyboard command to jump straight to a different application.

  • The argument against change, is that we'll be changing what people are already used to. Perhaps we should have done it this way from the start, but what happens if we change these common things right under our users' feet?
  • The argument for change, is that it's better to do the right thing now, than to assign some strange keystroke for new message compose for Mac users, onlu to possibly change it later. We should follow platform standards, and get rid of our strange use of Accel+N.

Current and future Tab key behavior in the content window

Currently, Tab navigates through all links and form elements in a page

Avoiding function keys for crucial roles

Avoid using function keys for important functionality, or provide other equivalents on Mac OS. This is because the Macintosh generally reserves function keys for user defined actions. Some Mac keyboards have no function keys at all.

Potentially Destructive Keys

Certain keystroke combinations are reportedly often hit by mistake by users intending to type something else. Those keys should only invoke undoable or non-destructive actions

Here's our current list of easy-to-mistype keystrokes:

  • Modified Enter
  • Modified Space

Keys that are easily hit by accident should not invoke an immediate, undoable, destructive action. For example, if Ctrl+Enter was used for immediate mail send, someone might send a rude email before having the chance to edit it. To get around this, we will have Ctrl+Enter bring up a dialog "Send mail now?" with a checkbox that lets the user avoid the extra question in the future.

Accesskey Conflicts

Web pages can use the accesskey attribute to define keyboard accelerators for their page. For example, on www.microsoft.com/enable, pressing Alt+S initiates a site search. However, Alt+S is also supposed to pull down the Search menu in Mozilla's menu bar.

At this point in time, our solution will be the same as Internet Explorer's. If there is a conflict, the web page's accesskey will get the key. If a user specifically wants to go to the main menu, they will type the menu access key first (normally Alt by itself), then the letter corresponding to the accesskey (such as S for search).

Right now we have disabled Alt as the menu access key in UNIX, because Alt+click can have meaning. To get around this, we need to fix the Alt menu access code to check for a click.

Keyboard Configurability

It is now possible to build your own keyboard configuration. We still need to fix some places where Mozilla hard codes specific keys, for example the TAB key is hard coded for link and form navigation in nsEventStateManager.cpp. There are a number of other keys that are defined in the chrome, but are packed away in .jar files. We don't have a solution for changing those easily yet, either.

At some point, we may get someone to build a keyboard configuration front-end. For now, our solution is to have the user edit text files. We can also provide some pre-build keyboard configuration files (any volunteers?). For example, someone may provide bindings for Emacs, Opera or Lynx users. Opera and Lynx have quite a few single keystroke commands in the browser. Single key bindings are great for users that have a great deal of difficulty typing. It also necessitates the use of a "leave form controls" key.

It is possible to allow users to associate javascripts with a key. This would allow users to match a favorite URL to a specific key. We would especially love to see someone come up with an easy way for end-users to create macros in Mozilla.

See the customizing document to learn how to use keyboard configurability.

Summary for Coders

For key combos using letter and number keys, the main cross reference table often lists accel as a modifier. If you use "accel" in XBL Mozilla will automatically choose the right key for you, even if the user changes it in their preferences. For other keys, (function keys, punctuation, etc.) we explicitly say "Ctrl(Win+Unix) or Cmd(Mac)" to indicate this will always be the key used, even if "accel" is otherwise redefined by the user. Even in this case, we still prefer "Command" over "Control" on the Mac because "Control" is used for context menus and very few end user programs use it as a modifier key.

Modifier Keys Demystified

Modifier key names in Mozilla and on major platforms
Mozilla XBLWindowsUnixMac
shiftShiftShiftShift
controlCtrlCtrlControl
altAltAltOption
meta
Windows Key
(unavailable)
 Meta
Command
(Apple Key)
accelCtrlCtrl or AltCommand

Keyboard Coding Rules

  • Never hardcode keynames. Use string bundles. This is also essential for localization, so there is no excuse.
  • Avoid making important features available only on non-alphanumeric keys (punctuation, numbers and function keys), these might not be present or easy to type on Mac or non-US keyboards.
  • For combos using letter or number keys, use "accel" or "shift,accel" in XBL.
  • For other key combos be explicit: use "ctrl", "alt" and "shift" on Windows and Unix; use "meta", "alt" and "shift" in the Mac keybindings file.

Key Bindings Files

Key bindings are defined in many places in Mozilla. Hopefully you'll be able to find what you want in the list below, or by using LXR. Be sure to read the customizing document.

Content area bindings

Task-specific bindings

Widget bindings

Informational Links

Keyboard UI Mailing List

Please discuss general keyboard issues on the Mozilla-Accessibility mailing list. We really want people to follow the keyboard plan, so if you see Bugzilla bugs that differ from the plan, please point it out on the bug and in the mailing list.

Maintained by Aaron Leventhal and Sarah Liberman.