More Event Handlers

In this section, the event object is examined and additional events are described.

The Event Object

Each event handler has a single argument which holds an event object. In the attribute form of event listener, this event is an implied argument to the script code which can be refered to using the name 'event'. In the addEventListener form, the first argument to the listener function will be the event object. The event object has a number of properties which can be examined during an event. The full list can be found in the object reference.

We already saw the event's target property is the last section. It holds a reference to the element where the event occured. A similar property currentTarget holds the element that is currently having its event listeners handled. In the example below, currentTarget is always the vbox, whereas target would be the specific element, either the button or checkbox, that was activated.

<vbox oncommand="alert(event.currentTarget.tagName);">
  <button label="OK"/>
  <checkbox label="Show images"/>
</vbox>

Recall that the capturing phase occurs before the bubbling phase, so any capturing listeners will trigger before any bubbling listeners. If a capturing event stops the event propagation, none of the later capturing listeners, nor any of the bubbling listeners will ever receive notification about the events. To stop event propagation, call the event object's stopPropagation method, as in the following example.

<hbox id="outerbox">
  <button id="okbutton" label="OK"/>
</hbox>

<script>
function buttonPressed(event)
{
  alert('Button was pressed!');
}

function boxPressed(event)
{
  alert('Box was pressed!');
  event.stopPropagation();
}

var button = document.getElementById("okbutton");
button.addEventListener('command',buttonPressed,true);

var outerbox = document.getElementById("outerbox");
outerbox.addEventListener('command',boxPressed,true);
</script>

Here, an event listener has been added to the button and another event listener has been added to the box. The stopPropagation method has been called in the box's listener, so the button's listener never gets called. If this call was removed, both listeners would be called and both alerts would appear.

If no event handlers have been registered for an event, then after completing the capturing and bubbling phases, the element will handle the event in a default way. What will happen depends on the event and the type of element. For example, the 'popupshowing' event is sent to a popup just before it is displayed. The default action is to display the popup. If the default action is prevented, the popup will not be displayed. The default action can be prevented with the event object's preventDefault method, as in the example below.

<button label="Types" type="menu">
  <menupopup onpopupshowing="event.preventDefault();">
    <menuitem label="Glass"/>
    <menuitem label="Plastic"/>
  </menupopup>
</button>

Alternatively, for attribute event listeners, you can just return false from the code. Note that preventing the default action is not the same as stopping event propagation with the stopPropagation method. Even if the default action has been prevented, the event will still continue to propagate. Similarly, calling the stopPropagation method won't prevent the default action. You must call both methods to stop both from occuring.

Note that once propagation or the default action has been prevented, neither may be re-enabled again for that event.

The following sections list some of the events that may be used. A full list is provided in the event reference.

Mouse Events

There are several events which can be used to handle mouse specific actions, listed in the following table:

There are also a set of drag related events, which occur when the user holds down a mouse button and drags the mouse around. Those events are described in a later section on drag and drop.

When a mouse button event occurs, a number of additional properties are available to determine which mouse buttons were pressed and the location of the mouse pointer. The event's button property can be used to determine which button was pressed, where possible values are 0 for the left button, 1 for the right button and 2 for the middle button. If you've configured your mouse differently, these values may be different.

The detail property holds the number of times the button has been clicked quickly in sequence. This allows you to check for single, double or triple clicks. Of course, if you just want to check for double clicks, you can also use the dblclick event instead. The click event will be fired once for the first click, again for the second click, and again for the third click, but the dblclick event will only be fired once for a double click.

The button and detail properties only apply to the mouse button related events, not mouse movement events. For the mousemove event, for example, both properties will be set to 0.

However, all mouse events will be supplied with properties that hold the coordinates of the mouse position where the event occured. There are two sets of coordinates. The first is the screenX and screenY properties and are relative to the top left corner of the screen. The second set, clientX and clientY, are relative to the top left corner of the document. Here is an example which displays the current mouse coordinates:

<script>

function updateMouseCoordinates(event)
{
  var text = "X:" + event.clientX + " Y:" + event.clientY;
  document.getElementById("xy").value = text;
}
</script>

<label id="xy"/>
<hbox width="400" height="400" onmousemove="updateMouseCoordinates(event);"/>

In this example, the size of the box has been set explicity so the effect is easier to see. The event handler gets the clientX and clientY properties and creates a string from them. This string is then assigned to the value property of the label. Note that the event argument must be passed to the updateMouseCoordinates function. If you move the mouse quickly across the border of the box, you might notice that the coordinates don't generally stop right at 400. This is because the mousemove events occur at intervals depdending on the speed at which the mouse moves and the mouse is usually moved some distance past the border by the time the next event fires. Obviously, it would be much too inefficient to send a mousemove event for every pixel the mouse is moved.

You will often want to get the coordinates of an event relative to the element where the element occured rather than the entire window. You can do this by subtracting the element's position from the event position, as in the following code.

var element = event.target;
var elementX = event.clientX - element.boxObject.x;
var elementY = event.clientY - element.boxObject.y;

XUL elements have a box object that can be retrieved using the boxObject property. We'll learn more about the box object in a later section, but it holds information pertaining to how the element is displayed, including the x and y position of the element. In this example code, these coordinates are subtracted from the event coordinates to get the event position relative to the element.

Load Events

The load event is sent to the document (the window tag) once the XUL file has finished loading and just before the content is displayed. This event is commonly used to initialize fields and perform other tasks that need to be done before the user can use the window. You should use a load event to do these kinds of things as opposed to adding script at the top level outside a function. This is because the XUL elements may not have loaded or fully initialized yet, so some things may not work as expected. To use a load event, place an onload attribute on the window tag. Call code within the load handler which will initialize the interface as necessary.

There is also an unload event which is called once the window has closed, or in a browser context, when the page is switched to another URL. You can use this event to save any changed information, for example.

(Next) Next, we'll find out how to add keyboard shortcuts.

Examples: 6.2.1 6.2.2 6.2.3 6.2.4