Routing Events: Event Capturing (Netscape)

As in archery, when you fire an event you typically want it to hit its target. We've already looked at all of the possible targets, called "target elements", so now let's consider how an event reaches its target.

As if an arrow launching from a bow, an event is launched as the result of an occurrence -- either a user action or an internal change to the state of the page. The event, which you might picture now hurtling through the air, needs to hit a target. That target, as we've seen, is the element in the place where the occurences, well, occurred!

Put once again into plain English, if a Click event occurs over a button element then that button element becomes the target. If a Resize event happens to the window then the window becomes the target. And so on.

The above should succinctly describe all of the concepts we've seen so far, including the tables galore. What if, though, we could re-route an event so that it does not immediately hit its target element? What if we could route an event towards a different target? Or what if we could send an event on a detour to a different target and then onto its original target? It's all very exciting and all somewhat true.

Netscape Navigator supports "Event Capturing", or the ability to intercept events before they reach their target and potentially re-route or even cancel them. To begin, we must enable event capturing at one or more of three possible "levels": the window, the document, or the layer.

Capturing and Releasing the Event

Only these three objects -- window, document, and layer -- have the ability to intercept events which occur within their jurisdiction. Even among these three objects there is a pecking order:

1. window -->
2. document -->
3. layer

An event will always be captured by the highest capture-enabled object in this pecking order first. Therefore, if we have enabled event capturing at both the document and window levels, an event will first be captured by the window. From there we may choose to route the event elsewhere, such as down a level, which we'll see shortly.

You must specify which events you wish to capture as parameters to the captureEvents() method of the capturing object. Events are specified as type properties of the event object. For example, to capture only the Click event at the window level:

window.captureEvents(Event.CLICK);

Notice the capitalization used in the parameter: "Event" is capitalized and the event type is in all capitals. This is strictly necessary in the captureEvents() call (Navigator can be a finicky kitty).

Perhaps we'd like to capture a MouseDown and MouseUp event at the document level:

document.captureEvents(Event.MOUSEDOWN | Event.MOUSEUP);

Here we use the "or" (|) operator to separate a list of multiple events. Once the captureEvents() call has been made, all events matching the captured type will be handled by the registered event handler for the capturing object. Put another way, "what happens to a Click event when it is being captured by the window object?"

Good question! A Click event occurs somewhere on the page while event capturing is in effect for this event at the window level. The window, then, must have a defined event handler to account for this scenario. Thus, you must also define an event handler function to take over the interception -- this function may perform a wide variety of tasks so we'll simply rely on a placeholder example:

function windowHandleClick(evt)
{ ...JavaScript statements...
return BOOLEAN }

This event handler function must be registered as the event handler for a Click event at the window object:

window.onclick=windowHandleClick;

Notice that the last statement of the event handler function returns a boolean value, meaning true or false. Were this return value set to false then certain targets, such as links and form submit elements, would not proceed after windowHandleClick() completes; otherwise, they would proceed normally (the link would be followed, the form would be submitted).

Remember that once you set event capturing to begin it stays in effect for that event until you release capturing. You can stop capturing any event at any level at any time with the releaseEvents() call. Simply:

window.releaseEvents(Event.CLICK);

Once released, this event reverts to its normal behavior -- that is, triggering at its original target element.

The following brief example pulls together the event capturing concepts seen thus far -- this simple page contains a single button. Event capturing of the Click event is enabled at the window level. Should this event occur, an event handler for the window is executed which pops up a message. As it stands, the onClick event handler for the button itself will never execute because the intercepting window object does nothing to return control to the button (we'll change that in the next example).

<html> <head> <script language="JavaScript"> function windowHandleClick(evt) { alert("I have just handled a "+evt.type+" event!"); return true; } window.captureEvents(Event.CLICK); window.onclick=windowHandleClick; </script> <body> <form> <input type="button" name="button1" value="Click me!" onClick="location='newpage.html';"> </form> </body> </html>

Grand Unified Table: Events and Supported Properties of the Event Object
Events in JavaScript: An Inside Look
Routing Events: Event Redirection (Netscape)