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>