Event Objects

When an event occurs in Netscape 4, the browser creates an Event object and passes it to the handler. Some interesting properties of Event objects are listed in Table 11-6.

The way the Event object is passed to the handler is a bit subtle. If the handler is defined as an (X)HTML attribute, the Event object is implicitly accessible to script in the text of the attribute through the event identifier. For example, the following script shows the user the x coordinate of the click:

<<a href="index.html" onclick="alert('Click at ' + event.screenX);">>
Click me!<</a>>

Because the implicitly available event identifier is only available within the text of the event handler attribute, any functions JavaScript invokes won’t have access to it. You need to pass it to them manually. The following code illustrates the common mistake of forgetting to do so:

<<script type="text/javascript">>
<<!--
function myHandler() 
{
  alert("Event type: " + event.type);
}
//-->>
<</script>>
<<a href="#" onclick="myHandler(); return false;">>Click me!<</a>>

You should see an error like

if you check your JavaScript console. To fix the problem, pass the Event manually:

<<script type="text/javascript">>
<<!--
function myHandler(event) 
{
  alert("Event type: " + event.type);
}
//-->>
<</script>>
<<a href="#" onclick="myHandler(event); return false;">>Click me!<</a>>

The result is as expected:

Since there would otherwise be no way to access the Event object in handlers bound to objects via JavaScript, the Event object is always passed to such functions as an argument. So if a function bound as an event handler with JavaScript wishes to access the Event object, the function must be declared as accepting an argument (though it does not necessarily have to call it an “event”). For example, to show the x coordinate of a click event attached to a link, you could use

<<a href="index.html">>Click me!<</a>>
<<script type="text/javascript">>
<<!-- 
function handleIt(e) 
{
  alert("Click at " + e.screenX);
}
document.links[0].onclick = handleIt;
//-->>
<</script>>

Event Capture

Under Netscape 4 the Window, Document, and Layer objects are afforded the opportunity to “capture” events before they are processed by their intended targets. This capability is useful when you want to handle a bunch of events for a document in one place. You might have a series of form buttons and wish to handle clicks on them with one function, so you could define a click handler for the Document in order to do so. You’d then use the contents of the Event object the handler is passed to determine which button was clicked, and carry out whatever processing is necessary.

To set up event capturing, use the captureEvents() method of Window, Document, or Layer. The argument to this method is a bitmask indicating which events the object is to capture. Like the constants used with the modifiers property, these bitmasks are defined as static properties of the Event object. The supported constants, which are case-sensitive, are listed in Table 11-7.

To capture all click events at the Document level, you could use a script like the one shown here:

<<script type="text/javascript">>
<<!--
function docClick(e) 
{
  alert("Someone clicked on this document");
}
// Only try to capture events if it is Netscape 4
if (document.layers) 
{
  document.captureEvents(Event.CLICK);
  document.onclick = docClick;
}
//-->>
<</script>>

To capture more than one event, you should bitwise OR ( | ) the desired event masks together. For example, to capture all click, dblClick, and blur events you might use

document.captureEvents(Event.CLICK | Event.DBLCLICK | Event.BLUR);

Turning off event capture is carried out analogously. You invoke the releaseEvents() method of the appropriate object, passing the bitmask of the events to release as the argument. To turn off event capturing of blur and click events at the Document level, you use

document.releaseEvents(Event.BLUR | Event.CLICK);

Event Propagation and Routing

Because Netscape propagates events top-down, handlers at a higher level in the document’s object tree always have the opportunity to handle an event before those at a lower level. If you have instructed the Window and the Document to capture click events, for example, the Window will capture the event because it is higher up the document object hierarchy.

Sometimes, however, a handler at a higher level might wish to not handle a particular event. For example, you might be capturing all clicks at the Document level in order to handle all button clicks in a single place. But the handler might receive a click event that wasn’t on a button, and therefore you may wish the event to continue on its journey to its intended target (a link, for example).

To let an event proceed along down the hierarchy, a handler invokes the routeEvent() method with the event it is processing as the argument. As an example, consider that you might want to process clicks in a special manner if the user has the ALT key depressed.

You might capture clicks at the Window level, examine the Event, and pass it along to be handled by lower-level handlers if the ALT key isn’t depressed.

function handleClicks(event) 
{
   if (event.modifiers & Event.ALT_MASK) 
   {
            // do something special because they have ALT depressed
   }
   else 
      routeEvent(event);
}
window.captureEvents(Event.CLICK);
window.onclick = handleClicks;

An occasionally useful aspect of routeEvent() is that it returns the value that the handler eventually processing the object returns. Because of this, handlers higher up the hierarchy can keep tabs on what happened to an event after it was passed on. They can modify their behavior according to whether the eventual target returned true or false.

At times, programmers find it necessary to send an event directly to a particular object, skipping down over intervening objects in the hierarchy or “sideways” to an object on another branch. Netscape 4 allows this with use of the handleEvent() method. This method is invoked as a property of the object to which the event is to be sent and takes the event itself as an argument. The target object’s appropriate event handler is immediately invoked as if it were the original target of the event. For example, to capture all form submissions and send them to the last form on the page for processing, you might use

function handleSubmits(event) 
{     
 document.forms[document.forms.length - 1].handleEvent(event);
}
window.captureEvents(Event.SUBMIT);
window.onsubmit = handleSubmits;