Event handlers are defined using
handler elements. A handler specifies what event it is listening for using the
event attribute. The handler contains script that is executed when an event flows to the object the handler is attached to and if that event matches all of the criteria specified by the handler.
The most basic handler specifies the event to listen for and an action to take when the handler fires. This action can be specified either using an
action attribute or by specifying the script as a child of the
Handlers are attached to the bound element, and they are registered by default for bubbling events. This means that
<handler event="click" action="foo()"/>
is analogous to
onclick="foo()" defined on the bound element.
phase attribute specifies the phase of event flow that the handler is registered for. The default value is
bubbling, which means that the event handler will fire during the bubbling phase. The other possible values are
target, which means the handler will only fire if
event.originalTarget is the same as the target to which the handler is attached, and
capturing, which indicates the handler should fire during the capturing phase of event flow.
XBL event handlers always fire last, after all other event handlers at the same position in the event flow. Since XBL handlers usually constitute the default actions for a widget, this allows authors in the bound document to write events that potentially suppress the default actions taken by the XBL handlers.
Within an XBL inheritance chain, event handlers always fire first on the derived binding and then on the base binding in the chain. A derived handler then has a way of preventing the event from flowing to its base binding handlers.
Mouse and key handlers have certain additional properties that are supported by XBL. Additional attributes can be used to impose a filter on the event handler. When a filter is imposed, additional conditions must be met before the event handler will fire.
For both mouse and key events, modifier keys can be specified using the
modifiers attribute. This attribute is a comma-separated list of modifier keys that must be down at the time the key or mouse event occurs in order for the handler to execute. Examples of common keys in the list are
control. For more details, see the XBL Element Reference for
In addition, mouse events can specify the
button and the
clickcount. This allows XBL authors to easily define handlers for right-click, or for left double-click, without having to write script on the same handler to differentiate those cases.
Key events support the
keycode attributes. When set, the corresponding fields in the
event object must match for the event to fire.
[Editor's Note: Should we have section on error-handling? Probably.]