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.



Key Binding

Feature Owner
Chris Saari

Key bindings are convenience nodes that can be used to easily set up key event handlers on nodes without having to write the JavaScript to check for various keys being down (when those keys might even need to be different on multiple platforms).

A set of key bindings is defined using the keyset tag. It is assumed that all key bindings that occur within the keyset are bound to the parent node of the key set.

A keyset contains key nodes as its children, where each node represents a single key binding. Key nodes contain several relevant attributes: the key attribute is used to specify the primary key of the binding (e.g., the key that could potentially be used in conjunction with zero or more modifier keys). The value of this attribute is case-insensitive, so "S" means the same thing as "s".

<window ... >
  <keyset>
    <key id="saveKey" key="s"/>
    <key id="newKey" key="n"/>
  </keyset>
...
</window>

Modifier conditions can also be specified, in which case the key binding only applies if the keys represented by the modifier conditions are down at the time the primary key is triggered. There are three different attributes used to represent the modifier keys (and to provide a cross-platform abstraction): command, shift, and alt. The attribute's value is true if the modifier should be present. If the attribute is not present, then it is assumed that the modifier is not required.

For GTK, Mac, and Windows, the equivalent keys for the modifier attributes are shown below.

Modifier GTK Macintosh Windows
command control command control
alt alt option alt
shift shift shift shift
control control control control

Key nodes can have key event handlers placed on them that will fire in the context of the key node if the conditions set up on the key node are satisfied.

The four possible event handlers are keydown, keyup, and keypress, and command. command fires at the same time as keypress and is a convenience method for command nodes (see Broadcasters and Observers for details). The event handlers can be added to the key nodes through script or as attributes (onkeydown, onkeyup, onkeypress, or oncommand). The event handlers refer to the primary key in the key binding and not to the modifier keys.

<window ... >
  <keyset>
    <key id="saveKey" key="s" command="true" onkeydown="performSave()"/>
    <key id="newKey" key="n" command="true" onkeydown="openFile()"/>
  </keyset>
...
</window>