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 handler element. If both are specified, the attribute wins. In both cases the JavaScript body is compiled just before execution; code that does not depend on the context of the event should be factored into normal Javascript file. (Note that there is a possibility that this may change in the future.)
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.
The 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 shift and control. For more details, see the XBL Element Reference for <handler>.
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 charcode and 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.]