[Contents] [Previous] [Next] [Index]
JavaScript applications in the Navigator are largely event-driven. Events are actions that occur usually as a result of something the user does. For example, clicking a button is an event, as is changing a text field or moving the mouse over a link. For your script to react to an event, you define event handlers, such as onChange and onClick.
Event handling changed significantly between Navigator 3.0 and Navigator 4.0. Navigator 4.0 added:
For a good introduction to event handling in Navigator 4.0, see the article Getting Ready for JavaScript 1.2 Events in the online View Source magazine. In addition, the JavaScript technical notes contain information on programming events.
JavaScript supports the events summarized in Table 2.1.
Table 2.1 Navigator event handlers
|
Event
|
Applies to
|
Occurs when
|
Event handler
|
|---|
Abort |
images |
User aborts the loading of an image (for example by clicking a link or clicking the Stop button) |
onAbort
|
Blur |
windows and all form elements |
User removes input focus from window or form element |
onBlur
|
Change |
text fields, textareas, select lists |
User changes value of element |
onChange
|
Click |
buttons, radio buttons, checkboxes, submit buttons, reset buttons, links |
User clicks form element or link |
onClick
|
DragDrop |
windows |
User drops an object onto the browser window, such as dropping a file on the browser window |
onDragDrop
|
Error |
images, windows |
The loading of a document or image causes an error |
onError
|
Focus |
windows and all form elements |
User gives input focus to window or form element |
onFocus
|
KeyDown |
documents, images, links, text areas |
User depresses a key |
onKeyDown
|
KeyPress |
documents, images, links, text areas |
User presses or holds down a key |
onKeyPress
|
KeyUp |
documents, images, links, text areas |
User releases a key |
onKeyUp
|
Load |
document body |
User loads the page in the Navigator |
onLoad
|
MouseDown |
documents, buttons, links |
User depresses a mouse button |
onMouseDown
|
MouseMove |
nothing by default |
User moves the cursor |
onMouseMove
|
MouseOut |
areas, links |
User moves cursor out of a client-side image map or link |
onMouseOut
|
MouseOver |
links |
User moves cursor over a link |
onMouseOver
|
MouseUp |
documents, buttons, links |
User releases a mouse button |
onMouseUp
|
Move |
windows |
User or script moves a window |
onMove
|
Reset |
forms |
User resets a form (clicks a Reset button) |
onReset
|
Resize |
windows |
User or script resizes a window |
onResize
|
Select |
text fields, textareas |
User selects form element's input field |
onSelect
|
Submit |
forms |
User submits a form |
onSubmit
|
Unload |
document body |
User exits the page |
onUnload
|
Defining an Event Handler
In all versions of Navigator, you define an event handler (a JavaScript function or series of statements) to handle an event. If an event applies to an HTML tag (that is, the event applies to the JavaScript object created from that tag), then you can define an event handler for it. The name of an event handler is the name of the event, preceded by "on." For example, the event handler for the focus event is onFocus.
To create an event handler for an HTML tag, add an event handler attribute to the tag. Put JavaScript code in quotation marks as the attribute value. The general syntax is
<TAG eventHandler="JavaScript Code">
where TAG is an HTML tag, eventHandler is the name of the event handler, and JavaScript Code is a sequence of JavaScript statements.
For example, suppose you have created a JavaScript function called compute. You make Navigator call this function when the user clicks a button by assigning the function call to the button's onClick event handler:
<INPUT TYPE="button" VALUE="Calculate" onClick="compute(this.form)">
You can put any JavaScript statements as the value of the onClick attribute. These statements are executed when the user clicks the button. To include more than one statement, separate statements with semicolons (;).
Notice in the preceding example this.form refers to the current form. The keyword this refers to the current object, which is the button. The construct this.form then refers to the form containing the button. The onClick event handler is a call to the compute function, with the current form as the argument.
Be sure to alternate double quotation marks with single quotation marks. Because event handlers in HTML must be enclosed in quotation marks, you must use single quotation marks to delimit string arguments. For example:
<INPUT TYPE="button" NAME="Button1" VALUE="Open Sesame!"
onClick="window.open('mydoc.html', 'newWin')">
In general, it is good practice to define functions for your event handlers instead of using multiple JavaScript statements:
Example: Using an Event Handler
In the form shown in Figure 2.1, you can enter an expression (for example, 2+2) in the first text field, and then click the button. The second text field then displays the value of the expression (in this case, 4).
Figure 2.1 Form with an event handler
The script for this form is as follows:
<HEAD>
<SCRIPT>
<!--- Hide script from old browsers
function compute(f) {
if (confirm("Are you sure?"))
f.result.value = eval(f.expr.value)
else
alert("Please come back again.")
}
// end hiding from old browsers -->
</SCRIPT>
</HEAD>
<BODY>
<FORM>
Enter an expression:
<INPUT TYPE="text" NAME="expr" SIZE=15 >
<INPUT TYPE="button" VALUE="Calculate" onClick="compute(this.form)">
<BR>
Result:
<INPUT TYPE="text" NAME="result" SIZE=15 >
</FORM>
</BODY>
The HEAD of the document defines a single function, compute, taking one argument, f, which is a Form object. The function uses the window.confirm method to display a Confirm dialog box with OK and Cancel buttons.
If the user clicks OK, then confirm returns true, and the value of the result text field is set to the value of eval(f.expr.value). The JavaScript function eval evaluates its argument, which can be any string representing any JavaScript expression or statements.
If the user clicks Cancel, then confirm returns false and the alert method displays another message.
The form contains a button with an onClick event handler that calls the compute function. When the user clicks the button, JavaScript calls compute with the argument this.form that denotes the current Form object. In compute, this form is referred to as the argument f.
Calling Event Handlers Explicitly
In Navigator 3.0 and later releases, you can reset an event handler specified by HTML, as shown in the following example.
<SCRIPT LANGUAGE="JavaScript">
function fun1() {
...
}
function fun2() {
...
}
</SCRIPT>
<FORM NAME="myForm">
<INPUT TYPE="button" NAME="myButton"
onClick="fun1()">
</FORM>
<SCRIPT>
document.myForm.myButton.onclick=fun2
</SCRIPT>
Note that event handlers are function references, so you must assign fun2 itself, not fun2() (the latter calls fun2 and has whatever type and value fun2 returns).
Also, because the event handler HTML attributes are literal function bodies, you cannot use <INPUT onClick=fun1> in the HTML source to make fun1 the onClick handler for an input. Instead, you must set the value in JavaScript, as in the example.
Finally, because JavaScript is case-sensitive, in Navigator 3.0 you must spell event handler names in lowercase in JavaScript. In Navigator 4.0, you can also use the mixed case version of the name.
The Event Object
In Navigator 4.0, each event has an associated event object. The event object provides information about the event, such as the type of event and the location of the cursor at the time of the event. When an event occurs, and if an event handler has been written to handle the event, the event object is sent as an argument to the event handler.
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 mouse 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 in the JavaScript Reference.
Event Capturing
Typically, the object on which an event occurs handles the event. For example, when the user clicks a button, it is often the button's event handler that handles the event. Sometimes you may want the window or document object to handle certain types of events instead of leaving them for the individual parts of the document. For example, you may want the document object to handle all MouseDown events no matter where they occur in the document.
In Navigator 4.0, JavaScript's event capturing model allows you to define methods that capture and handle events before they reach their intended target. To accomplish this, the window, document, and layer objects use these event-specific methods:
As an 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. For information on signed scripts, see Chapter 7,
"JavaScript Security."
Briefly, the steps for setting up event capturing are:
- Set up the window to capture all
Click events.
- Define a function that handles the event.
- Register the function as the window's event handler for that event.
These steps are explained next.
Enable event capturing
To set up the window to capture all Click events, use a statement such as the following:
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, the following statement captures Click, MouseDown, and MouseUp events:
window.captureEvents(Event.CLICK | Event.MOUSEDOWN | Event.MOUSEUP)
Defining the event handler
Next, 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;
}
This allows the event to be completely handled by the document or window. The event is not handled by any other object, such as a button in the document or a child frame of the window.
- 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;
}
This allows you to suppress the handling of an event type. The event is not handled by any other object, such as a button in the document or a child frame of the window. You can use this, for example, to suppress the right mouse button in an application.
- 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.
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.
Registering the event handler
Finally, register the function as the window's event handler for that event:
window.onClick = clickHandler;
A complete 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>
[Contents] [Previous] [Next] [Index]
Last Updated: 11/26/97 09:25:30
Copyright © 1997
Netscape Communications Corporation