[Previous] [Next] [TOC] 

Event Model

JavaScript's event model includes several new events, an event object, and the ability to capture and handle events before they reach their intended target. This section contains the following information:

• The Event Object
• Event capturing

New events are described in the Events section.

The event Object

The event object contains properties that describe a JavaScript event, and is passed as an argument to an event handler when the event occurs. In the case of a mousedown event, for example, the event object contains the type of event (in this case "mousedown"), the x and y position of the cursor at the time of the event, a number representing the mouse button used, and a field containing the modifier keys (Control, Alt, Meta, or Shift) that were depressed at the time of the event. The properties used within the event object vary from one type of event to another. This variation is provided in the individual event descriptions.

JavaScript supports the following events. This document describes the new events, the "JavaScript Guide" describes pre-Navigator 4.0 events.

Details of the event object

Syntax

event.propertyName

Argument of

All event handlers.

Properties

The following properties are specific to an event and are passed with the event object. To learn which properties are used by an event, see the "Event object properties used" section of the individual event.

Example

The following example uses the event object to provide the type of event to the alert message.

<A HREF="http://home.netscape.com" onClick='alert("Link got an event: "
+ event.type)'>Click for link event</A>

The following example uses the event object in an explicitly called event handler.

<SCRIPT>

function fun1(e) {
   alert ("Document got an event: " + e.type);
   alert ("x position is " + e.layerX);
   alert ("y position is " + e.layerY);
   if (e.modifiers & Event.ALT_MASK)
      alert ("Alt key was down for event.");
   return true;
}

document.onmousedown = fun1;

</SCRIPT>

Event Capturing

You can now have a window or document capture and handle an event before it reaches its intended target. To accomplish this, the window, document, and layer objects have these new methods:

• captureEvents
• releaseEvents
• routeEvent
• handleEvent -- not a method of the layer object

For example, suppose you wanted to capture all click events occurring in a window.

Note: If a window with frames wants to capture events in pages loaded from different locations, you need to use captureEvents in a signed script and call enableExternalCapture.

First, you need to set up the window to capture all Click events:

window.captureEvents(Event.CLICK);

The argument to captureEvents is a property of the event object and indicates the type of event to capture. To capture multiple events, the argument is a list separated by or (|). For example:

window.captureEvents(Event.CLICK | Event.MOUSEDOWN | Event.MOUSEUP)

Next, you need to define a function that handles the event. The argument e is the event object for the event.

function clickHandler(e) {
   //What goes here depends on how you want to handle the event.
   //This is described below.
}

You have four options for handling the event:

• Return true. In the case of a link, the link is followed and no other event handler is checked. If the event cannot be canceled, this ends the event handling for that event.

function clickHandler(e) {
   return true;
}

• Return false. In the case of a link, the link is not followed. If the event is non-cancelable, this ends the event handling for that event.

function clickHandler(e) {
   return false;
}

• Call routeEvent. JavaScript looks for other event handlers for the event. If another object is attempting to capture the event (such as the document), JavaScript calls its event handler. If no other object is attempting to capture the event, JavaScript looks for an event handler for the event's original target (such as a button). The routeEvent function returns the value returned by the event handler. The capturing object can look at this return and decide how to proceed.

Note: When routeEvent calls an event handler, the event handler is activated. If routeEvent calls an event handler whose function is to display a new page, the action takes place without returning to the capturing object.

function clickHandler(e) {
   var retval = routeEvent(e);
   if (retval == false) return false;
   else return true;
}

• Call the handleEvent method of an event receiver. Any object that can register event handlers is an event receiver. This method explicitly calls the event handler of the event receiver and bypasses the capturing hierarchy. For example, if you wanted all Click events to go to the first link on the page, you could use:

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

As long as the link has an onClick handler, the link will handle any click event it receives.

Finally, you need to register the function as the window's event handler for that event:

window.onClick = clickHandler;

Example

In the following example, the window and document capture and release events:

<HTML>

<SCRIPT>

function fun1(e) {
   alert ("The window got an event of type: " + e.type + " and will call routeEvent.");
   window.routeEvent(e);
   alert ("The window returned from routeEvent.");
   return true;
}

function fun2(e) {
   alert ("The document got an event of type: " + e.type);
   return false;
}

function setWindowCapture() {
   window.captureEvents(Event.CLICK);

}

function releaseWindowCapture() {
   window.releaseEvents(Event.CLICK);
}

function setDocCapture() {
   document.captureEvents(Event.CLICK);
}

function releaseDocCapture() {
   document.releaseEvents(Event.CLICK);
}

window.onclick=fun1;
document.onclick=fun2;

</SCRIPT>

...

</HTML>