7.6. Event Handling

Event handlers are attributes that listen for events. They intercept events raised by certain user actions, such as button clicks. When intercepted, control is given to the application to carry out some functionality.

Mouse and keyboard actions are included in these events. XBL uses all events that are available on an element in XUL and calls them by their name, minus the on prefix. Thus, for example, the onmouseclick event handler becomes mouseclick in XBL. Refer to Appendix C for a full list of these events, which also describes the difference between XUL and XBL event handling.

The <handler> element contains a single event. Sets of individual <handler> elements need to be included in a <handlers> element. The event that sets off the action is contained in the event attribute.

<handlers>
  <handler event="mousedown" action="dumpString('hello', 'there!')" />
</handlers>

This code uses the action attribute to point to script that is executed when the event is triggered. The alternative way to set up the actions is to put the executable script between the handler tags, like you can with the XUL <script> element. If you use this "embedded" syntax, wrap your script in a CDATA section so it gets interpreted and executed properly:

<handlers>
  <handler event="mousedown">
    <![CDATA[
      var list = document.getElementById('someElement');
      list.setAttribute('style', 'display:block;');
    ]]>
  </handler>
</handlers>

You cannot use both inline and external scripts in an XBL event handler. If this instance does occur, the action attribute is used. Like code decisions in other contexts, which one you use depends on whether you want to reuse the code. In our experience, using inline scripts is best in most circumstances unless useful code libraries can be accessed in external scripts.

7.6.1. The Time and Venue

Event handlers in XBL allow for fine-tuning, using built-in attributes that control when, where, and how they are executed. Events are not limited to bindings. They can be registered with other UI elements that pre-empt behavior when, for example, a create or load event occurs. This registration occurs when using the attachto attribute.

<handler event="create" attachto="window" action="returnNode( )">

The handler is designed to update the list in the binding when the application is loaded up and the window shows. Other possible values for attachto are document and element.

//FIXME did we loose content here?

The attachto feature is disabled for Mozilla 1.0, but it is included here for completeness and to highlight XBL's full capabilities.

Another nice feature of event handlers in XBL is the existence of extra modifiers on mouse and key events using the modifiers and the key or keycode attributes. The value is a list of one or more modifier keys separated by a comma. The most common combination is the use of the alt, control, or shift modifiers. The key codes have special identifiers like VK_INSERT and VK_UP.

<handler event="keypress" modifiers="control, alt" keycode="VK_UP" action="goUp( )">

Finally, when talking about event handlers, the phase attribute allows you to control the point in the event's lifecycle when the code is to be executed.

<handler event="mouseup" phase="capturing" action="goUp( )">

The possible values are bubbling (the default), targeting, and capturing.

Here is an example of a handler implementation that fills a tooltip when the popup element displaying it is shown:

<handler event="popupshowing">
  <![CDATA[
    var label = "";
    var tipNode = document.tooltipNode;
    if (tipNode && tipNode.hasAttribute("tooltiptext"))
      this.label = tipNode.getAttribute("tooltiptext");
  ]]>
</handler>

This event handler first checks that the current popup is in fact a tooltip via the document's tooltipNode property and then extracts the text from it. This text is assigned to the binding's label, which will propagate via inheritance to the text display content widget used in the binding, which could be a label or description element.