« XUL Reference home [ Examples | Attributes | Properties | Methods | Related ]

The key element defines a window-global keyboard shortcut and must be placed inside a keyset element.

When a key matching the attributes on the key element is pressed, the command will be fired on the key element. The key pressed must match the key attribute (or keycode attribute) as well as the modifiers attribute in order for the key element to be activated.

For the shortcut defined using the key element to work, you must specify a command attribute (or an oncommand handler) on the key element.

To display the shortcut defined with the key element in the UI, you can use <menuitem key="key element's id" command="command id" .../>.

In order to use (non-default) key commands within specific elements, you will need to listen for key events.

More information is available in the XUL tutorial.

Attributes
command, disabled, key, keycode, keytext, modifiers, oncommand, phase

Examples

(example needed)

Attributes

command
Type: id
Set to the id of a command element that is being observed by the element.
disabled
Type: boolean
Indicates whether the element is disabled or not. If this attribute is set, the element is disabled. Disabled elements are usually drawn with grayed-out text. If the element is disabled, it does not respond to user actions, it cannot be focused, and the command event will not fire. In the case of form elements, it will not be submitted. Do not set the attribute to true, as this will suggest you can set it to false to enable the element again, which is not the case.
The disabled attribute is allowed only for form controls. Using it with an anchor tag (an <a> link) will have no effect.
The element will, however, still respond to mouse events. To enable the element, leave this attribute out entirely.
Visible controls have a disabled property which, except for menus and menuitems, is normally preferred to use of the attribute, as it may need to update additional state.
key
Type: character
The character that must be pressed. This should be set to a displayable character.
keycode
Type: string key code
For keys that do not have displayable characters, such as the Enter key or function keys, use this attribute instead of the key attribute. Valid keys are listed at Keyboard Shortcuts.
keytext
Type: string
A label for the keyboard shortcut. This text would appear next to a menuitem label if that menuitem is associated with the key element via its key attribute.
modifiers
Type: space-separated list of the values below
A list of modifier keys that should be pressed to invoke the keyboard shortcut. Multiple keys may be separated by spaces or commas. Keys will map to other keys on platforms that do not have them.
oncommand
Type: script code
This event handler is called when the command is activated. This occurs when a user selects a menu item or presses a keyboard shortcut attached to the command.
phase
Type: string
The event phase where the handler is invoked. This should be set to the value capturing to indicate during the event capturing phase or target to indicate at the target element or left out entirely for the bubbling phase.

Properties

Inherited Properties
align, , allowEvents, , boxObject, builder, , , , className, , , , , collapsed, contextMenu, controllers, database, datasources, dir, , , flex, height, hidden, id, , , left, , maxHeight, maxWidth, menu, minHeight, minWidth, , , , , , , observes, ordinal, orient, , pack, , persist, , , , ref, resource, , , , , statusText, style, ,, tooltip, tooltipText, top, width

Methods

Inherited Methods
addEventListener(), appendChild(), blur, click, cloneNode(), compareDocumentPosition, dispatchEvent(), doCommand, focus, getAttribute(), getAttributeNode(), getAttributeNodeNS(), getAttributeNS(), getBoundingClientRect(), getClientRects(), getElementsByAttribute, getElementsByAttributeNS, getElementsByClassName(), getElementsByTagName(), getElementsByTagNameNS(), getFeature, getUserData, hasAttribute(), hasAttributeNS(), hasAttributes(), hasChildNodes(), insertBefore(), isDefaultNamespace(), isEqualNode, isSameNode, isSupported(), lookupNamespaceURI, lookupPrefix, normalize(), querySelector(), querySelectorAll(), removeAttribute(), removeAttributeNode(), removeAttributeNS(), removeChild(), removeEventListener(), replaceChild(), setAttribute(), setAttributeNode(), setAttributeNodeNS(), setAttributeNS(), setUserData

Details on key, keycode, and modifiers attributes

For example, consider the following key:

<key key="r" modifiers="shift"/>

This key will only match when the Shift key is pressed as well as the R key, and no other keys. For instance, if the Shift, Control and R keys are all pressed, the key will not match.

To indiciate that a modifier key may optionally be pressed, place the word 'any' after listing the optional modifier key. For example:

<key key="r" modifiers="shift any control"/>

In this example, the shift key may or may not be pressed, while the control key must be pressed. This allows keys to match more loosely for modifier keys that aren't relevant, yet still allows specific modifiers to be required.

If the modifiers attribute is not specified, then no modifiers may be pressed for the key to match.

If neither the key or keycode attribute are used, the key element will handle all key events. However, if one of the attributes is set to an empty string, the element doesn't handle any key events. For example:

<!-- This element handles all key events -->
<key/>

<!-- These elements don't handle any key events -->
<key key="" modifiers="control"/>
<key keycode="" modifiers="control"/>

In case you want to change one of the <key>'s attributes, such as the modifiers attribute, the keyset element has to be re-added to its parent node; otherwise the new attributes won't be applied. For example:

// modify some attributes
let key = document.getElementById(KEY_ID);
key.setAttribute("modifiers", "alt shift");

// apply the changes
let keyset = document.getElementById(KEYSET_ID);
keyset.parentNode.appendChild(keyset);