Table of Contents | Previous | Next | Index

## Chapter 3
Event Handlers

This chapter contains the event handlers that are used with client-side objects in JavaScript to evoke particular actions. For general information on event handlers, see the Client-Side JavaScript Guide. The following table summarizes the event handlers. 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`.

Table 3.1 Event handlers

Event | Event handler | Description
--- | --- | ---
    Abort
    onAbort
| Executes JavaScript code when the user aborts the loading of an image.
    Blur
    onBlur
| Executes JavaScript code when a form element loses focus or when a window or frame loses focus.
    Change
    onChange
| Executes JavaScript code when a `Select`, `Text`, or `Textarea` field loses focus and its value has been modified
    Click
    onClick
| Executes JavaScript code when an object on a form is clicked.
    DblClick
    onDblClick
| Executes JavaScript code when the user double-clicks a form element or a link.
    DragDrop
    onDragDrop
| Executes JavaScript code when the user drops an object onto the browser window, such as dropping a file.
    Error
    onError
| Executes JavaScript code when the loading of a document or image causes an error.
    Focus
    onFocus
| Executes JavaScript code when a window, frame, or frameset receives focus or when a form element receives input focus.
    KeyDown
    onKeyDown
| Executes JavaScript code when the user depresses a key.
    KeyPress
    onKeyPress
| Executes JavaScript code when the user presses or holds down a key.
    KeyUp
    onKeyUp
| Executes JavaScript code when the user releases a key.
    Load
    onLoad
| Executes JavaScript code when the browser finishes loading a window or all frames within a `FRAMESET` tag.
    MouseDown
    onMouseDown
| Executes JavaScript code when the user depresses a mouse button.
    MouseMove
    onMouseMove
| Executes JavaScript code when the user moves the cursor.
    MouseOut
    onMouseOut
| Executes JavaScript code each time the mouse pointer leaves an area (client-side image map) or link from inside that area or link.
    MouseOver
    onMouseOver
| Executes JavaScript code once each time the mouse pointer moves over an object or area from outside that object or area.
    MouseUp
    onMouseUp
| Executes JavaScript code when the user releases a mouse button.
    Move
    onMove
| Executes JavaScript code when the user or script moves a window or frame.
    Reset
    onReset
| Executes JavaScript code when a user resets a form (clicks a Reset button).
    Resize
    onResize
| Executes JavaScript code when a user or script resizes a window or frame.
    Select
    onSelect
| Executes JavaScript code when a user selects some of the text within a text or textarea field.
    Submit
    onSubmit
| Executes JavaScript code when a user submits a form.
    Unload
    onUnload
| Executes JavaScript code when the user exits a document.

## onAbort

Executes JavaScript code when an abort event occurs; that is, when the user aborts the loading of an image (for example by clicking a link or clicking the Stop button).

Event handler for | `Image`
Implemented in | JavaScript 1.1

#### Syntax

    onAbort="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.

#### Examples

In the following example, an `onAbort` handler in an `Image` object displays a message when the user aborts the image load:

    <IMG NAME="aircraft" SRC="f15e.gif"
       onAbort="alert('You didn\'t get to see the image!')">

#### See also

`event`, `onError`, `onLoad`

## onBlur

Executes JavaScript code when a blur event occurs; that is, when a form element loses focus or when a window or frame loses focus.

Event handler for | `Button`, `Checkbox`, `FileUpload`, `Layer`, `Password`, `Radio`, `Reset`, `Select`, `Submit`, `Text`, `Textarea`, `window`
Implemented in | JavaScript 1.0 JavaScript 1.1: event handler of `Button`, `Checkbox`, `FileUpload`, `Frame`, `Password`, `Radio`, `Reset`, `Submit`, and `window`

#### Syntax

    onBlur="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Description

The `blur` event can result from a call to the `window.blur` method or from the user clicking the mouse on another object or window or tabbing with the keyboard. For windows, frames, and framesets, `onBlur` specifies JavaScript code to execute when a window loses focus. A frame's `onBlur` event handler overrides an `onBlur` event handler in the `BODY` tag of the document loaded into frame.

> NOTE: In JavaScript 1.1, on some platforms placing an `onBlur` event handler in a `FRAMESET` tag has no effect.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.

#### Examples

Example 1: Validate form input. In the following example, `userName` is a required text field. When a user attempts to leave the field, the `onBlur` event handler calls the `required` function to confirm that `userName` has a legal value.

    <INPUT TYPE="text" VALUE="" NAME="userName"
       onBlur="required(this.value)">

Example 2: Change the background color of a window. In the following example, a window's `onBlur` and `onFocus` event handlers change the window's background color depending on whether the window has focus.

    <BODY BGCOLOR="lightgrey"
       onBlur="document.bgColor='lightgrey'"
       onFocus="document.bgColor='antiquewhite'">

Example 3: Change the background color of a frame. The following example creates four frames. The source for each frame, `onblur2.html` has the `BODY` tag with the onBlur and `onFocus` event handlers shown in Example 1. When the document loads, all frames are light grey. When the user clicks a frame, the `onFocus` event handler changes the frame's background color to antique white. The frame that loses focus is changed to light grey. Note that the `onBlur` and `onFocus` event handlers are within the `BODY` tag, not the `FRAME` tag.

    <FRAMESET ROWS="50%,50%" COLS="40%,60%">
    <FRAME SRC=onblur2.html NAME="frame1">
    <FRAME SRC=onblur2.html NAME="frame2">
    <FRAME SRC=onblur2.html NAME="frame3">
    <FRAME SRC=onblur2.html NAME="frame4">
    </FRAMESET>

The following code has the same effect as the previous code, but is implemented differently. The `onFocus` and `onBlur` event handlers are associated with the frame, not the document. The `onBlur` and `onFocus` event handlers for the frame are specified by setting the `onblur` and `onfocus` properties.

    <SCRIPT>
    function setUpHandlers() {
       for (var i = 0; i < frames.length; i++) {
          frames[i].onfocus=new Function("document.bgColor='antiquewhite'")
          frames[i].onblur=new Function("document.bgColor='lightgrey'")
       }
    }
    </SCRIPT>

    <FRAMESET ROWS="50%,50%" COLS="40%,60%" onLoad=setUpHandlers()>
    <FRAME SRC=onblur2.html NAME="frame1">
    <FRAME SRC=onblur2.html NAME="frame2">
    <FRAME SRC=onblur2.html NAME="frame3">
    <FRAME SRC=onblur2.html NAME="frame4">
    </FRAMESET>

Example 4: Close a window. In the following example, a window's `onBlur` event handler closes the window when the window loses focus.

    <BODY onBlur="window.close()">
    This is some text
    </BODY>

#### See also

`event`, `onChange`, `onFocus`

## onChange

Executes JavaScript code when a change event occurs; that is, when a `Select`, `Text`, or `Textarea` field loses focus and its value has been modified.

Event handler for | `FileUpload`, `Select`, `Text`, `Textarea`
Implemented in | JavaScript 1.0 event handler for `Select`, `Text`, and `Textarea` JavaScript 1.1: added as event handler of `FileUpload`

#### Syntax

    onChange="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Description

Use `onChange` to validate data after it is modified by a user.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.

#### Examples

In the following example, `userName` is a text field. When a user changes the text and leaves the field, the onChange event handler calls the `checkValue` function to confirm that `userName` has a legal value.

    <INPUT TYPE="text" VALUE="" NAME="userName"
       onChange="checkValue(this.value)">

#### See also

`event`, `onBlur`, `onFocus`

## onClick

Executes JavaScript code when a click event occurs; that is, when an object on a form is clicked. (A click event is a combination of the MouseDown and MouseUp events).

Event handler for | `Button`, `document`, `Checkbox`, `Link`, `Radio`, `Reset`, `Submit`
Implemented in | JavaScript 1.0 JavaScript 1.1: added the ability to return false to cancel the action associated with a click event

#### Syntax

    onClick="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
When a link is clicked, `layerX`, `layerY`, `pageX`, `pageY`, `screenX`,`screenY` | Represent the cursor location at the time the event occurred.
    which
| Represents 1 for a left-mouse click and 3 for a right-mouse click.
    modifiers
| Contains the list of modifier keys held down when the event occurred.

#### Description

For checkboxes, links, radio buttons, reset buttons, and submit buttons, `onClick` can return false to cancel the action normally associated with a `click` event. For example, the following code creates a link that, when clicked, displays a confirm dialog box. If the user clicks the link and then chooses cancel, the page specified by the link is not loaded.

    <A HREF = "http://home.netscape.com/"
       onClick="return confirm('Load Netscape home page?')">
    Netscape</A>

If the event handler returns false, the default action of the object is canceled as follows:

- Buttons--no default action; nothing is canceled

- Radio buttons and checkboxes--nothing is set

- Submit buttons--form is not submitted

- Reset buttons--form is not reset

> NOTE: In JavaScript 1.1, on some platforms, returning false in an `onClick` event handler for a reset button has no effect.

#### Examples

Example 1: Call a function when a user clicks a button. Suppose you have created a JavaScript function called `compute`. You can execute the `compute` function when the user clicks a button by calling the function in the onClick event handler, as follows:

    <INPUT TYPE="button" VALUE="Calculate" onClick="compute(this.form)">

In the preceding example, the keyword `this` refers to the current object; in this case, the Calculate button. The construct `this.form` refers to the form containing the button. For another example, suppose you have created a JavaScript function called `pickRandomURL` that lets you select a URL at random. You can use `onClick` to specify a value for the `HREF` attribute of the `A` tag dynamically, as shown in the following example:

    <A HREF=""
       onClick="this.href=pickRandomURL()"
       onMouseOver="window.status='Pick a random URL'; return true">
    Go!</A>

In the above example, `onMouseOver` specifies a custom message for the browser's status bar when the user places the mouse pointer over the Go! anchor. As this example shows, you must return true to set the `window.status` property in the `onMouseOver` event handler. Example 2: Cancel the checking of a checkbox. The following example creates a checkbox with `onClick`. The event handler displays a confirm that warns the user that checking the checkbox purges all files. If the user chooses Cancel, `onClick` returns false and the checkbox is not checked.

    <INPUT TYPE="checkbox" NAME="check1" VALUE="check1"
       onClick="return confirm('This purges all your files. Are you sure?')"> Remove files

#### See also

`event`

## onDblClick

Executes JavaScript code when a DblClick event occurs; that is, when the user double-clicks a form element or a link.

Event handler for | `document`, `Link`
Implemented in | JavaScript 1.2

#### Syntax

    onDblClick="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

> NOTE: `DblClick` is not implemented on the Macintosh.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    layerX, layerY,
    pageX, pageY,
    screenX, screenY
| Represent the cursor location at the time the event occurred.
    which
| Represents 1 for a left-mouse double-click and 3 for a right-mouse double-click.
    modifiers
| Contains the list of modifier keys held down when the event occurred.

#### Examples

The following example opens an alert dialog box when a user double-clicks a button:

    <form>
    <INPUT Type="button" Value="Double Click Me!"
              onDblClick="alert('You just double clicked me!')">
    </form>

#### See also

`event`

## onDragDrop

Executes JavaScript code when a DragDrop event occurs; that is, when the user drops an object onto the browser window, such as dropping a file.

Event handler for | `window`
Implemented in | JavaScript 1.2

#### Syntax

    onDragDrop="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    data
| Returns an Array of Strings containing the URLs of the dropped objects.
    modifiers
| Contains the list of modifier keys held down when the event occurred.
    screenX,
    screenY
| Represent the cursor location at the time the event occurred.

#### Security

Getting the `data` property of the DragDrop event requires the `UniversalBrowserRead` privilege. For information on security, see the Client-Side JavaScript Guide.

#### Description

The `DragDrop` event is fired whenever a system item (file, shortcut, and so on) is dropped onto the browser window using the native system's drag and drop mechanism. The normal response for the browser is to attempt to load the item into the browser window. If the event handler for the `DragDrop` event returns true, the browser loads the item normally. If the event handler returns false, the drag and drop is canceled.

#### See also

`event`

## onError

Executes JavaScript code when an error event occurs; that is, when the loading of a document or image causes an error.

Event handler for | `Image`, `window`
Implemented in | JavaScript 1.1

#### Syntax

    onError="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Description

An error event occurs only when a JavaScript syntax or runtime error occurs, not when a browser error occurs. For example, if you try set `window.location.href='notThere.html'` and `notThere.html` does not exist, the resulting error message is a browser error message; therefore, `onError` would not intercept that message. However, an error event is triggered by a bad URL within an `IMG` tag or by corrupted image data. `window.onerror` applies only to errors that occur in the window containing `window.onerror`, not in other windows. `onError` can be any of the following:

- null to suppress all JavaScript error dialogs. Setting `window.onerror` to null means your users won't see JavaScript errors caused by your own code.

- The name of a function that handles errors (arguments are message text, URL, and line number of the offending line). To suppress the standard JavaScript error dialog, the function must return true. See Example 3 below.

- A variable or property that contains null or a valid function reference.

If you write an error-handling function, you have three options for reporting errors:

- Trace errors but let the standard JavaScript dialog report them (use an error handling function that returns false or does not return a value)

- Report errors yourself and disable the standard error dialog (use an error handling function that returns true)

- Turn off all error reporting (set the onError event handler to null)

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.

#### Examples

Example 1: Null event handler. In the following `IMG` tag, the code `onError="null"` suppresses error messages if errors occur when the image loads.

    <IMG NAME="imageBad1" SRC="corrupt.gif" ALIGN="left" BORDER="2"
       onError="null">

Example 2: Null event handler for a window. The `onError` event handler for windows cannot be expressed in HTML. Therefore, you must spell it all lowercase and set it in a `SCRIPT` tag. The following code assigns null to the `onError` handler for the entire window, not just the `Image` object. This suppresses all JavaScript error messages, including those for the `Image` object.

    <SCRIPT>
    window.onerror=null
    </SCRIPT>
    <IMG NAME="imageBad1" SRC="corrupt.gif" ALIGN="left" BORDER="2">

However, if the `Image` object has a custom `onError` event handler, the handler would execute if the image had an error. This is because `window.onerror=null` suppresses JavaScript error messages, not `onError` event handlers.

    <SCRIPT>
    window.onerror=null
    function myErrorFunc() {
       alert("The image had a nasty error.")
    }
    </SCRIPT>
    <IMG NAME="imageBad1" SRC="corrupt.gif" ALIGN="left" BORDER="2"
       onError="myErrorFunc()">

In the following example, `window.onerror=null` suppresses all error reporting. Without `onerror=null`, the code would cause a stack overflow error because of infinite recursion.

    <SCRIPT>
    window.onerror = null;
    function testErrorFunction() {
       testErrorFunction();
    }
    </SCRIPT>
    <BODY onload="testErrorFunction()">
    test message
    </BODY>

Example 3: Error handling function. The following example defines a function, `myOnError`, that intercepts JavaScript errors. The function uses three arrays to store the message, URL, and line number for each error. When the user clicks the Display Error Report button, the `displayErrors` function opens a window and creates an error report in that window. Note that the function returns true to suppress the standard JavaScript error dialog.

    <SCRIPT>
    window.onerror = myOnError

    msgArray = new Array()
    urlArray = new Array()
    lnoArray = new Array()

    function myOnError(msg, url, lno) {
       msgArray[msgArray.length] = msg
       urlArray[urlArray.length] = url
       lnoArray[lnoArray.length] = lno
       return true
    }

    function displayErrors() {
       win2=window.open('','window2','scrollbars=yes')
       win2.document.writeln('<B>Error Report</B><P>')

       for (var i=0; i < msgArray.length; i++) {
          win2.document.writeln('<B>Error in file:</B> ' + urlArray[i] + '<BR>')
          win2.document.writeln('<B>Line number:</B> ' + lnoArray[i] + '<BR>')
          win2.document.writeln('<B>Message:</B> ' + msgArray[i] + '<P>')
       }
       win2.document.close()
    }
    </SCRIPT>

    <BODY onload="noSuchFunction()">
    <FORM>
    <BR><INPUT TYPE="button" VALUE="This button has a syntax error"
       onClick="alert('unterminated string)">

    <P><INPUT TYPE="button" VALUE="Display Error Report"
       onClick="displayErrors()">
    </FORM>

This example produces the following output:

    Error Report

    Error in file: file:///c%7C/temp/onerror.html
    Line number: 34
    Message: unterminated string literal

    Error in file: file:///c%7C/temp/onerror.html
    Line number: 34
    Message: missing ) after argument list

    Error in file: file:///c%7C/temp/onerror.html
    Line number: 30
    Message: noSuchFunction is not defined

Example 4: Event handler calls a function. In the following `IMG` tag, `onError` calls the function `badImage` if errors occur when the image loads.

    <SCRIPT>
    function badImage(theImage) {
       alert('Error: ' + theImage.name + ' did not load properly.')
    }
    </SCRIPT>
    <FORM>
    <IMG NAME="imageBad2" SRC="orca.gif" ALIGN="left" BORDER="2"
       onError="badImage(this)">
    </FORM>

#### See also

`event`, `onAbort`, `onLoad`

## onFocus

Executes JavaScript code when a focus event occurs; that is, when a window, frame, or frameset receives focus or when a form element receives input focus.

Event handler for | `Button`, `Checkbox`, `FileUpload`, `Layer`, `Password`, `Radio`, `Reset`, `Select`, `Submit`, `Text`, `Textarea`, `window`
Implemented in | JavaScript 1.0 JavaScript 1.1: event handler of `Button``,` `Checkbox``,` `FileUpload``, Frame,` `Password``,` `Radio``,` `Reset``,` `Submit``,` and `window` JavaScript 1.2: event handler of `Layer`

#### Syntax

    onFocus="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Description

The focus event can result from a `focus` method or from the user clicking the mouse on an object or window or tabbing with the keyboard. Selecting within a field results in a select event, not a focus event. `onFocus` executes JavaScript code when a focus event occurs. A frame's `onFocus` event handler overrides an `onFocus` event handler in the `BODY` tag of the document loaded into frame. Note that placing an alert in an `onFocus` event handler results in recurrent alerts: when you press OK to dismiss the alert, the underlying window gains focus again and produces another focus event.

> NOTE: In JavaScript 1.1, on some platforms, placing an `onFocus` event handler in a `FRAMESET` tag has no effect.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.

#### Examples

The following example uses an `onFocus` handler in the `valueField` `Textarea` object to call the `valueCheck` function.

    <INPUT TYPE="textarea" VALUE="" NAME="valueField"
       onFocus="valueCheck()">

See also the examples for `onBlur`.

#### See also

`event`, `onBlur`, `onChange`

## onKeyDown

Executes JavaScript code when a KeyDown event occurs; that is, when the user depresses a key.

Event handler for | `document`, `Image`, `Link`, `Textarea`
Implemented in | JavaScript 1.2

#### Syntax

    onKeyDown="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    layerX, layerY,
    pageX, pageY,
    screenX, screenY
| For an event over a window, these represent the cursor location at the time the event occurred. For an event over a form, they represent the position of the form element.
    which
| Represents the ASCII value of the key pressed. To get the actual letter, number, or symbol of the pressed key, use the `String.fromCharCode` method. To set this property when the ASCII value is unknown, use the `String.charCodeAt` method.
    modifiers
| Contains the list of modifier keys held down when the event occurred.

#### Description

A `KeyDown` event always occurs before a `KeyPress` event. If `onKeyDown` returns false, no `KeyPress` events occur. This prevents `KeyPress` events occurring due to the user holding down a key.

#### Examples

The following example uses the `blockA` function to evaluate characters entered from the keyboard in the `textentry` text box. If a user enters either "a" or "A", the function returns false and the text box does not display the value.

    <form name="main">
       <input name="textentry" type=text size=10 maxlength=10>
    </form>

    <script>
    function blockA(e) {
            var keyChar = String.fromCharCode(e.which);
            if (keyChar == 'A' || keyChar == 'a')
                    return false;
    }

    document.main.textentry.onkeydown = blockA;
    </script>

In the function, the `which` property of the event assigns the ASCII value of the key the user presses to the `keyChar` variable. The `if` statement evaluates `keyChar` and returns false for the specified characters.

#### See also

`event`, `onKeyPress`, `onKeyUp`

## onKeyPress

Executes JavaScript code when a KeyPress event occurs; that is, when the user presses or holds down a key.

Event handler for | `document`, `Image`, `Link`, `Textarea`
Implemented in | JavaScript 1.2

#### Syntax

    onKeyPress="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    layerX, layerY,
    pageX, pageY,
    screenX, screenY
| For an event over a window, these represent the cursor location at the time the event occurred. For an event over a form, they represent the position of the form element.
    which
| Represents the ASCII value of the key pressed. To get the actual letter, number, or symbol of the pressed key, use the `String.fromCharCode` method. To set this property when the ASCII value is unknown, use the `String.charCodeAt` method.
    modifiers
| Contains the list of modifier keys held down when the event occurred.

#### Description

A `KeyPress` event occurs immediately after a `KeyDown` event only if `onKeyDown` returns something other than false. A `KeyPress` event repeatedly occurs until the user releases the key. You can cancel individual `KeyPress` events.

#### Examples

In this example, the `captureEvents` method catches keyboard input and the `onKeyPress` handler calls the `blockA` function to examine the keystrokes. If the keystrokes are "a" or "z", the function scrolls the Navigator window.

    function blockA(e) {
            var keyChar = String.fromCharCode(e.which);
            if (keyChar == 'A' || keyChar == 'a')
                    self.scrollBy(10,10);

            else if(keyChar == 'Z' || keyChar == 'z')
                    self.scrollBy(-10,-10);

            else    return false;
    }
    document.captureEvents(Event.KEYPRESS);
    document.onkeypress = blockA;

#### See also

`event`, `onKeyDown`, `onKeyUp`

## onKeyUp

Executes JavaScript code when a KeyUp event occurs; that is, when the user releases a key.

Event handler for | `document`, `Image`, `Link`, `Textarea`
Implemented in | JavaScript 1.2

#### Syntax

    onKeyUp="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    layerX, layerY,
    pageX, pageY,
    screenX, screenY
| For an event over a window, these represent the cursor location at the time the event occurred. For an event over a form, they represent the position of the form element.
    which
| Represents the ASCII value of the key pressed. To get the actual letter, number, or symbol of the pressed key, use the `String.fromCharCode` method. To set this property when the ASCII value is unknown, use the `String.charCodeAt` method.
    modifiers
| Contains the list of modifier keys held down when the event occurred.

#### Examples

In this example, the `captureEvents` method catches keyboard input and the `onKeyUp` handler calls the `Key_Up` function. An alert method within the function opens a dialog box to display the value of the keystroke.

    function Key_Up(e) {
            var keyChar = String.fromCharCode(e.which);
            alert("Hold '" + keyChar +"' again for me, okay?");
    }
    document.onkeyup=Key_Up;
    document.captureEvents(Event.KEYUP);

#### See also

`event`

## onLoad

Executes JavaScript code when a load event occurs; that is, when the browser finishes loading a window or all frames within a `FRAMESET` tag.

Event handler for | `Image`, `Layer`, `window`
Implemented in | JavaScript 1.0 JavaScript 1.1: event handler of `Image`

#### Syntax

    onLoad="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Description

Use the `onLoad` event handler within either the `BODY` or the `FRAMESET` tag, for example, <`BODY onLoad="...">`. In a `FRAMESET` and `FRAME` relationship, an `onLoad` event within a frame (placed in the `BODY` tag) occurs before an `onLoad` event within the `FRAMESET` (placed in the `FRAMESET` tag). For images, the `onLoad` event handler indicates the script to execute when an image is displayed. Do not confuse displaying an image with loading an image. You can load several images, then display them one by one in the same `Image` object by setting the object's `src` property. If you change the image displayed in this way, `onLoad` executes every time an image is displayed, not just when the image is loaded into memory. If you specify an `onLoad` event handler for an `Image` object that displays a looping GIF animation (multi-image GIF), each loop of the animation triggers the `onLoad` event, and the event handler executes once for each loop. You can use the `onLoad` event handler to create a JavaScript animation by repeatedly setting the `src` property of an `Image` object. See `Image` for information.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    width, height
| For an event over a window, but not over a layer, these represent the width and height of the window.

#### Examples

Example 1: Display message when page loads. In the following example, the onLoad event handler displays a greeting message after a Web page is loaded.

    <BODY onLoad="window.alert("Welcome to the Brave New World home page!")>

Example 2: Display alert when image loads. The following example creates two `Image` objects, one with the `Image` constructor and one with the `IMG` tag. Each `Image` object has an `onLoad` event handler that calls the `displayAlert` function, which displays an alert. For the image created with the `IMG` tag, the alert displays the image name. For the image created with the `Image` constructor, the alert displays a message without the image name. This is because the onLoad handler for an object created with the `Image` constructor must be the name of a function, and it cannot specify parameters for the `displayAlert` function.

    <SCRIPT>
    imageA = new Image(50,50)
    imageA.onload=displayAlert
    imageA.src="cyanball.gif"

    function displayAlert(theImage) {
       if (theImage==null) {
          alert('An image loaded')
       }
       else alert(theImage.name + ' has been loaded.')
    }
    </SCRIPT>

    <IMG NAME="imageB" SRC="greenball.gif" ALIGN="top"
       onLoad=displayAlert(this)><BR>

Example 3: Looping GIF animation. The following example displays an image, `birdie.gif`, that is a looping GIF animation. The onLoad event handler for the image increments the variable `cycles`, which keeps track of the number of times the animation has looped. To see the value of `cycles`, the user clicks the button labeled Count Loops.

    <SCRIPT>
    var cycles=0
    </SCRIPT>
    <IMG ALIGN="top" SRC="birdie.gif" BORDER=0
       onLoad="++cycles">
    <INPUT TYPE="button" VALUE="Count Loops"
       onClick="alert('The animation has looped ' + cycles + ' times.')">

Example 4: Change GIF animation displayed. The following example uses an onLoad event handler to rotate the display of six GIF animations. Each animation is displayed in sequence in one `Image` object. When the document loads, `!anim0.html` is displayed. When that animation completes, the onLoad event handler causes the next file, `!anim1.html`, to load in place of the first file. After the last animation, `!anim5.html`, completes, the first file is again displayed. Notice that the `changeAnimation` function does not call itself after changing the `src` property of the `Image` object. This is because when the `src` property changes, the image's `onLoad` event handler is triggered and the `changeAnimation` function is called.

    <SCRIPT>
    var whichImage=0
    var maxImages=5

    function changeAnimation(theImage) {
       ++whichImage
       if (whichImage <= maxImages) {
          var imageName="!anim" + whichImage + ".gif"
          theImage.src=imageName
       } else {
          whichImage=-1
          return
       }
    }
    </SCRIPT>

    <IMG NAME="changingAnimation" SRC="!anim0.gif" BORDER=0 ALIGN="top"
       onLoad="changeAnimation(this)">

See also the examples for `Image`.

#### See also

`event`, `onAbort`, `onError`, `onUnload`

## onMouseDown

Executes JavaScript code when a MouseDown event occurs; that is, when the user depresses a mouse button.

Event handler for | `Button`, `document`, `Link`
Implemented in | JavaScript 1.2

#### Syntax

    onMouseDown="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    layerX, layerY,
    pageX, pageY,
    screenX, screenY
| Represent the cursor location at the time the `MouseDown` event occurred.
    which
| Represents 1 for a left-mouse-button down and 3 for a right-mouse-button down.
    modifiers
| Contains the list of modifier keys held down when the `MouseDown` event occurred.

#### Description

If `onMouseDown` returns false, the default action (entering drag mode, entering selection mode, or arming a link) is canceled. Arming is caused by a `MouseDown` over a link. When a link is armed it changes color to represent its new state.

#### Examples

This example lets users move an image on an HTML page by dragging it with the mouse. Your HTML code defines the image and positions it in a layer called `container1`. In your JavaScript code, event handlers set the position properties of `container1` as users drag the image, creating the animation. Using style sheets, the image is initially defined and positioned as follows:

    <HEAD>
    <STYLE type="text/css">
       #container1 { position:absolute; left:200; top:200}
    </STYLE>
    </HEAD>

    <BODY>
    <P ID="container1">
    <img src="backgrnd.gif" name="myImage" width=96 height=96>
    </P>
    </BODY>

In the previous HTML code, the `ID` attribute for the `P` element which contains the image is set to `container1`, making `container1` a unique identifier for the paragraph and the image. The `STYLE` tag creates a layer for `container1` and positions it. The following JavaScript code defines `onMouseDown`, `onMouseUp`, and `onMouseMove` event handlers:

    <SCRIPT>
    container1.captureEvents(Event.MOUSEUP|Event.MOUSEDOWN);
    container1.onmousedown=DRAG_begindrag;
    container1.onmouseup=DRAG_enddrag;
    var DRAG_lastX, DRAG_lastY, DRAG_dragging;
    function DRAG_begindrag(e) {
            if (e.which == 1) {
                    window.captureEvents(Event.MOUSEMOVE);
              window.onmousemove=DRAG_drag;
                    DRAG_lastX=e.pageX;
                    DRAG_lastY=e.pageY;
                    DRAG_dragging=true;
                    return false;
            }
            else {
                    /*Do any right mouse button processing here*/
                    return true;
            }
    }
    function DRAG_enddrag(e) {
            if (e.which == 1) {
                    window.releaseEvents(Event.MOUSEMOVE);
              window.onmousemove=null
                    DRAG_dragging=false;
                    return false;
            }
            else {
                    /*Do any right mouse button processing here*/
                    return true;
            }
    }
    function DRAG_drag(e) {
            if (DRAG_dragging) {
                    /*This function called only if MOUSEMOVEs are captured*/
                    moveBy(e.pageX-DRAG_lastX, e.pageY-DRAG_lastY);
                    DRAG_lastX = e.pageX;
                    DRAG_lastY = e.pageY;
                    return false;
            }
            else {
                    return true;
            }
    }
    </SCRIPT>

In the previous code, the `captureEvents` method captures `MouseUp` and `MouseDown` events. The `DRAG_begindrag` and `DRAG_enddrag` functions are respectively called to handle these events. When a user presses the left mouse button, the `DRAG_begindrag` function starts capturing `MouseMove` events and tells the `DRAG_drag` function to handle them. It then assigns the value of the `MouseDown` event's `pageX` property to `DRAG_lastX`, the value of the `pageY` property to `DRAG_lastY`, and `true` to `DRAG_dragging`. The `DRAG_drag` function evaluates `DRAG_dragging` to make sure the `MouseMove` event was captured by `DRAG_begindrag`, then it uses the `moveBy` method to position the object, and reassigns values to `DRAG_lastX` and `DRAG_lastY`. When the user releases the left mouse button, the `DRAG_enddrag` function stops capturing `MouseMove` events. `DRAG_enddrag` then makes sure no other functions are called by setting `onmousemove` to `Null` and `DRAG_dragging` to `false`.

#### See also

`event`

## onMouseMove

Executes JavaScript code when a MouseMove event occurs; that is, when the user moves the cursor.

Event handler for | None
Implemented in | JavaScript 1.2

#### Syntax

    onMouseMove="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event of

Because mouse movement happens so frequently, by default, `onMouseMove` is not an event of any object. You must explicitly set it to be associated with a particular object.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    layerX, layerY,
    pageX, pageY,
    screenX, screenY
| Represent the cursor location at the time the `MouseMove` event occurred.

#### Description

The `MouseMove` event is sent only when a capture of the event is requested by an object. For information on events, see the Client-Side JavaScript Guide.

#### Examples

See the examples for `onMouseDown`.

#### See also

`event`, `document.captureEvents`

## onMouseOut

Executes JavaScript code when a MouseOut event occurs; that is, each time the mouse pointer leaves an area (client-side image map) or link from inside that area or link.

Event handler for | `Layer`, `Link`
Implemented in | JavaScript 1.1

#### Syntax

    onMouseOut="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Description

If the mouse moves from one area into another in a client-side image map, you'll get `onMouseOut` for the first area, then `onMouseOver` for the second. `Area` tags that use `onMouseOut` must include the `HREF` attribute within the `AREA` tag. You must return true within the event handler if you want to set the `status` or `defaultStatus` properties with `onMouseOver`.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    layerX, layerY,
    pageX, pageY,
    screenX, screenY
| Represent the cursor location at the time the `MouseOut` event occurred.

#### Examples

See the examples for `Link`.

#### See also

`event`, `onMouseOver`

## onMouseOver

Executes JavaScript code when a MouseOver event occurs; that is, once each time the mouse pointer moves over an object or area from outside that object or area.

Event handler for | `Layer`, `Link`
Implemented in | JavaScript 1.0 JavaScript 1.1: event handler of `Area`

#### Syntax

    onMouseOver="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Description

If the mouse moves from one area into another in a client-side image map, you'll get `onMouseOut` for the first area, then `onMouseOver` for the second. `Area` tags that use `onMouseOver` must include the `HREF` attribute within the `AREA` tag. You must return true within the event handler if you want to set the `status` or `defaultStatus` properties with `onMouseOver`.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    layerX, layerY,
    pageX, pageY,
    screenX, screenY
| Represent the cursor location at the time the `MouseOver` event occurred.

#### Examples

By default, the `HREF` value of an anchor displays in the status bar at the bottom of the browser when a user places the mouse pointer over the anchor. In the following example, `onMouseOver` provides the custom message "Click this if you dare."

    <A HREF="http://home.netscape.com/"
       onMouseOver="window.status='Click this if you dare!'; return true">
    Click me</A>

See `onClick` for an example of using `onMouseOver` when the `A` tag's `HREF` attribute is set dynamically. See also the examples for `Link`.

#### See also

`event`, `onMouseOut`

## onMouseUp

Executes JavaScript code when a MouseUp event occurs; that is, when the user releases a mouse button.

Event handler for | `Button`, `document`, `Link`
Implemented in | JavaScript 1.2

#### Syntax

    onMouseUp="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    layerX, layerY,
    pageX, pageY,
    screenX, screenY
| Represent the cursor location at the time the `MouseUp` event occurred.
    which
| Represents 1 for a left-mouse-button up and 3 for a right-mouse-button up.
    modifiers
| Contains the list of modifier keys held down when the `MouseUp` event occurred.

#### Description

If `onMouseUp` returns false, the default action is canceled. For example, if `onMouseUp` returns false over an armed link, the link is not triggered. Also, if `MouseUp` occurs over an unarmed link (possibly due to `onMouseDown` returning false), the link is not triggered.

> NOTE: Arming is caused by a `MouseDown` over a link. When a link is armed it changes color to represent its new state.

#### Examples

See the examples for `onMouseDown`.

#### See also

`event`

## onMove

Executes JavaScript code when a move event occurs; that is, when the user or script moves a window or frame.

Event handler for | `window`
Implemented in | JavaScript 1.2

#### Syntax

    onMove="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    screenX,
    screenY
| Represent the position of the top-left corner of the window or frame.

#### Examples

In this example, the `open_now` function creates the `myWin` window and captures `Move` events. The `onMove` handler calls another function which displays a message when a user moves `myWin`.

    function open_now(){
        var myWin;
        myWin=window.open("","displayWindow","width=400,height=400,menubar=no,
                            location=no,alwaysRaised=yes");
        var text="<html><head><title>Test</title></head>"
            +"<body bgcolor=white><h1>Please move this window</h1></body>"
            +"</html>";
        myWin.document.write(text);
        myWin.captureEvents(Event.MOVE);
        myWin.onmove=fun2;
    }

    function fun2(){
        alert("Hey you moved me!");
        this.focus(); //'this' points to the current object
    }

#### See also

`event`

## onReset

Executes JavaScript code when a reset event occurs; that is, when a user resets a form (clicks a Reset button).

Event handler for | `Form`
Implemented in | JavaScript 1.1

#### Syntax

    onReset="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Examples

The following example displays a `Text` object with the default value "CA" and a reset button. If the user types a state abbreviation in the `Text` object and then clicks the reset button, the original value of "CA" is restored. The form's onReset event handler displays a message indicating that defaults have been restored.

    <FORM NAME="form1" onReset="alert('Defaults have been restored.')">
    State:
    <INPUT TYPE="text" NAME="state" VALUE="CA" SIZE="2"><P>
    <INPUT TYPE="reset" VALUE="Clear Form" NAME="reset1">
    </FORM>

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.

#### See also

`event`, `Form.reset`, `Reset`

## onResize

Executes JavaScript code when a resize event occurs; that is, when a user or script resizes a window or frame.

Event handler for | `window`
Implemented in | JavaScript 1.2

#### Syntax

    onResize="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.
    width, height
| Represent the width and height of the window or frame.

#### Description

This event is sent after HTML layout completes within the new window inner dimensions. This allows positioned elements and named anchors to have their final sizes and locations queried, image `SRC` properties can be restored dynamically, and so on.

#### Examples

In this example, the `open_now` function creates the `myWin` window and captures `Resize` events. The `onResize` handler calls the `alert_me` function which displays a message when a user resizes `myWin`.

    function open_now(){
        var myWin;
        myWin=window.open("","displayWin","width=400,height=300,resizable=yes,
                                        menubar=no,location=no,alwaysRaised=yes");
        var text="<html><head><title>Test</title></head>"
               +"<body bgcolor=white><h1>Please resize me</h1></body>"
               +"</html>";
        myWin.document.write(text);
        myWin.captureEvents(Event.RESIZE);
        myWin.onresize=alert_me;
    }

    function alert_me(){
        alert("You resized me! \nNow my outer width: " + this.outerWidth +
            "\n and my outer height: " +this.outerHeight);
        this.focus();
    }

#### See also

`event`

## onSelect

Executes JavaScript code when a select event occurs; that is, when a user selects some of the text within a text or textarea field.

Event handler for | `Text`, `Textarea`
Implemented in | JavaScript 1.0

#### Syntax

    onSelect="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.

#### Examples

The following example uses `onSelect` in the `valueField` `Text` object to call the `selectState` function.

    <INPUT TYPE="text" VALUE="" NAME="valueField" onSelect="selectState()">

#### See also

`event`

## onSubmit

Executes JavaScript code when a submit event occurs; that is, when a user submits a form.

Event handler for | `Form`
Implemented in | JavaScript 1.0

#### Syntax

    onSubmit="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Security

Submitting a form to a `mailto:` or `news:` URL requires the `UniversalSendMail` privilege. For information on security, see the Client-Side JavaScript Guide.

#### Description

You can use `onSubmit` to prevent a form from being submitted; to do so, put a `return` statement that returns false in the event handler. Any other returned value lets the form submit. If you omit the `return` statement, the form is submitted.

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.

#### Examples

In the following example, `onSubmit` calls the `validate` function to evaluate the data being submitted. If the data is valid, the form is submitted; otherwise, the form is not submitted.

    <FORM onSubmit="return validate(this)">
    ...
    </FORM>

See also the examples for `Form`.

#### See also

`event`, `Submit`, `Form.submit`

## onUnload

Executes JavaScript code when an unload event occurs; that is, when the user exits a document.

Event handler for | `window`
Implemented in | JavaScript 1.0

#### Syntax

    onUnload="handlerText"

#### Parameters

    handlerText
| JavaScript code or a call to a JavaScript function.

#### Description

Use `onUnload` within either the `BODY` or the `FRAMESET` tag, for example, `<BODY onUnload="...">`. In a frameset and frame relationship, an `onUnload` event within a frame (placed in the `BODY` tag) occurs before an `onUnload` event within the frameset (placed in the `FRAMESET` tag).

#### Event properties used

Property | Description
--- | ---
    type
| Indicates the type of event.
    target
| Indicates the object to which the event was originally sent.

#### Examples

In the following example, `onUnload` calls the `cleanUp` function to perform some shutdown processing when the user exits a Web page:

    <BODY onUnload="cleanUp()">

#### See also

`onLoad` For general information on event handlers, see the Client-Side JavaScript Guide. For information about the `event` object, see `event`.

Table of Contents | Previous | Next | Index

Last Updated: 05/28/99 12:01:01

Copyright (c) 1999 Netscape Communications Corporation