Accesskey display rules

Each controls of XUL can have an accesskey which is specified by accesskey attribute or accessKey property (See accesskey attribute document for the detail). XUL elements display their accesskeys in their label automatically if it's necessary. This document describes the rules of generating a label text.

XUL elements don't display any accesskeys on Mac

XUL elements don't display any accesskeys on Mac. Because MacOS X doesn't have the conception of  accesskey function on its native widgets/applications.

Basic accesskey display rules

On non-Mac platforms, a character which is same as its accesskey is underlined. E.g., when an accesskey of "File" is 'F', the generated label will be "File".

If a label has two or more characters which are same as its accesskey, the first character of them will be underlined.

If a label doesn't have the character, XUL elements append the accesskey character with parentheses. E.g., when an accesskey of "Open" is 'A', the generated label will be "Open (A)". However, if the last character of the label is an ellipsis or a colon, the accesskey text is inserted before them. I.e., when an accesskey of "Open…" is 'A', the generated label will be "Open (A)…". And also when an accesskey of "Your Name:" is 'B', the generated label will be "Your Name (B):".

This document calls the appended text "accesskey text".

Always appends accesskey text

The basic rules are enough for Western locales. However, in some locales, e.g., Japanese localized build, its most UI labels don't have alphabets but alphabets are used to accesskey. For coherence of the labels on such localized builds, the accesskey text is always appended even if the labels have their accesskey characters. E.g., when an accesskey of "OK" is 'O' and an accesskey of "キャンセル" (means "cancel") is 'C', the labels will be "OK(O)" and "キャンセル(C)" on Japanese localized build.

XUL elements check "intl.menuitems.alwaysappendaccesskeys" pref value whether they should append accesskey text always. If the value is "true" (string), the accesskey text will be appended always. Don't change the pref value from your XUL applications.
And also Note that there are no spaces between the original labels and accesskey text in the above Japanese example. Because typically, Japanese language doesn't use spaces as word separator. This is controled by "intl.menuitems.insertseparatorbeforeaccesskeys" pref value. If the value is "true" (string), a spece will be inserted before accesskey text. Don't change the pref value from your XUL applications too.

Don't include accesskey text in labels

XUL applications should use DTD for localizable UI resource. At that time, accesskeys are specified by independent entity from their label. Be aware, this is very important thing.

When you cannot use DTD, e.g., when you need to generate some UIs dynamically, you can use .properties file or something. Then, you should provide a way for specifying accesskeys which are independent from their labels. Note that using '&' in label text is bad way. Because Japanese localizers "&Cancel" need to localize to "キャンセル(&C)". This label will be displayed as "キャンセル(C)(C)" on the localized build. So, "(C)" will be doubled. For this issue, we recommend the following format if you use .properties:

Note that APIs of nsIPromptService are using the bad way. Because the APIs are already frozen. Therefore, XUL toolkit removes accesskey text before setting the label to the buttons. However, XUL application developers should not make same mistake.

Document Tags and Contributors

 Contributors to this page: Sheppy, teoli, Masayuki
 Last updated by: Sheppy,