The Navigator Event Model: Passing Events - Doc JavaScript

Passing Events

Besides returning true or false, an event processing function can also pass an event to a specific event receiver. Any object that can register event handlers is an event receiver. By calling the event handler of a specific event receiver, you can bypass the event capturing hierarchy. For instance, if you want to capture all mouse clicks in the document, except for those generated by a specific button, you can check if the event's intended target is that button. If so, simply send it to the button object via the handleEvent() method.

The handleEvent() method explicitly calls the event handler of the desired event receiver, so it takes over and handles the event immediately. For example, if you want all click events to go to the first link on the page, you could use the following event processing function:

function processClicks(e) {
  document.links[0].handleEvent(e);
}

Of course, the link must have an event handler to process the event. The following code segment shows how to put the preceding function to work:

<A HREF="...">...</A><!-- the first link in the document -->
<SCRIPT LANGUAGE="JavaScript">
<!--
function processClicks(e) {
  document.links[0].handleEvent(e);
}
function firstLink(e) {
  alert("The first link's event handler called this function.");
}
window.captureEvents(Event.CLICK);
window.onclick = processClicks;
// or put the event handler in the link's tag
// e.g., onClick="firstLink(event)"
document.links[0].onclick = firstLink;
// -->
</SCRIPT>

If you put this script in an independant HTML document (so its link is first), the firstLink() function is invoked whenever you click the mouse (in the browser area), regardless of the pointer's position. That is, you do not have to click the link directly, because the window object captures all click events and sends them to the first link's event handler, which calls the firstLink() function. Now get rid of the captureEvents() method, and the first link's event handler stops receiving events from the top-level event handler, so you'll need to click the link itself to see its event handler in action. Take another look at this script, with the addition of a single statement:

<A HREF="...">...</A>
<SCRIPT LANGUAGE="JavaScript">
<!--
function processClicks(e) {
  alert("The window's event handler called this function.");
  document.links[0].handleEvent(e);
}
function firstLink(e) {
  alert("The first link's event handler called this function.");
}
window.captureEvents(Event.CLICK);
window.onclick = processClicks;
document.links[0].onclick = firstLink;
// -->
</SCRIPT>

Even if you click the link, the window object's onclick event handler is the one that captures the click event, before it is directed to the link's onclick event handler. The reason for this behavior, which differs from most other scripting and programming environments, is a result of Navigator's event model. Events are dropped down the hierarchy, from the upper level to the lower one, so if the window object's event handler captures an event, it doesn't filter down to the intended target (the link, in our example). Back to the example. Regardless of where you click, both alert dialog boxes are generated.

Only the first event handler in the hierarchy that captures an event can cancel it. For example, in the following script, none of click events are cancelled, so when you click one of the links, the browser proceeds to the new page:

<A HREF="https://www.netscape.com/">Netscape</A><BR>
<A HREF="https://www.microsoft.com/">Microsoft</A>
<SCRIPT LANGUAGE="JavaScript">
<!--
function processClicks(e) {
  document.links[0].handleEvent(e);
}
function firstLink(e) {
  return false;
}
window.captureEvents(Event.CLICK);
window.onclick = processClicks;
document.links[0].onclick = firstLink;
// -->
</SCRIPT>

As you can see, the processClicks() function, which is associated with the first event handler (window.onclick) that captures all click events, does not return any value, so it cannot cancel an event. One way to cancel all of the click events is to return false in the body of the function. Another way is to return the value that is returned by the handleEvent() method. This method always returns the value that its event handler (its object) returns. The following script would also cancel all click events:

<A HREF="https://www.netscape.com/">Netscape</A><BR>
<A HREF="https://www.microsoft.com/">Microsoft</A>
<SCRIPT LANGUAGE="JavaScript">
<!--
function processClicks(e) {
  return document.links[0].handleEvent(e);
}
function firstLink(e) {
  return false;
}
window.captureEvents(Event.CLICK);
window.onclick = processClicks;
document.links[0].onclick = firstLink;
// -->
</SCRIPT>

Once again, remember that you can replace the statement:

document.links[0].onclick = firstLink;

with a "traditional" event handler:

<A HREF="https://www.netscape.com/"
   onClick="firstLink()">Netscape</A>

We'll discuss the differences later in the column. If you just can't wait, the equivalent event handler (attribute approach) is actually:

<A HREF="https://www.netscape.com/"
   onClick="firstLink(event)">Netscape</A>

Created: December 16, 1997
Revised: December 16, 1997

URL: https://www.webreference.com/js/column9/pass.html