Table of Contents | Previous | Next | Index

# Image

An image on an HTML form.

Client-side object |
Implemented in | JavaScript 1.1 JavaScript 1.2: added `handleEvent` method

#### Created by

The `Image` constructor or the `IMG` tag. The JavaScript runtime engine creates an `Image` object corresponding to each `IMG` tag in your document. It puts these objects in an array in the `document.images` property. You access an `Image` object by indexing this array. To define an image with the `IMG` tag, use standard HTML syntax with the addition of JavaScript event handlers. If specify a value for the `NAME` attribute, you can use that name when indexing the `images` array. To define an image with its constructor, use the following syntax:

    new Image([width,] [height])

#### Parameters

    width

The image width, in pixels.

    height

The image height, in pixels.

#### Event handlers

- `onAbort`
- `onError`
- `onKeyDown`
- `onKeyPress`
- `onKeyUp`
- `onLoad`

To define an event handler for an `Image` object created with the `Image` constructor, set the appropriate property of the object. For example, if you have an `Image` object named `imageName` and you want to set one of its event handlers to a function whose name is `handlerFunction`, use one of the following statements:

    imageName.onabort = handlerFunction
    imageName.onerror = handlerFunction
    imageName.onkeydown = handlerFunction
    imageName.onkeypress = handlerFunction
    imageName.onkeyup = handlerFunction
    imageName.onload = handlerFunction

`Image` objects do not have `onClick`, `onMouseOut`, and `onMouseOver` event handlers. However, if you define an `Area` object for the image or place the `IMG` tag within a `Link` object, you can use the `Area` or `Link` object's event handlers. See `Link`.

#### Description

The position and size of an image in a document are set when the document is displayed in the web browser and cannot be changed using JavaScript (the `width` and `height` properties are read-only for these objects). You can change which image is displayed by setting the `src` and `lowsrc` properties. (See the descriptions of `Image.src` and `Image.lowsrc`.) You can use JavaScript to create an animation with an `Image` object by repeatedly setting the `src` property, as shown in Example 4 below. JavaScript animation is slower than GIF animation, because with GIF animation the entire animation is in one file; with JavaScript animation, each frame is in a separate file, and each file must be loaded across the network (host contacted and data transferred). The primary use for an `Image` object created with the `Image` constructor is to load an image from the network (and decode it) before it is actually needed for display. Then when you need to display the image within an existing image cell, you can set the `src` property of the displayed image to the same value as that used for the previously fetched image, as follows.

    myImage = new Image()
    myImage.src = "seaotter.gif"
    ...
    document.images[0].src = myImage.src

The resulting image will be obtained from cache, rather than loaded over the network, assuming that sufficient time has elapsed to load and decode the entire image. You can use this technique to create smooth animations, or you could display one of several images based on form input.

#### Property Summary

Property | Description
--- | ---

    border

Reflects the `BORDER` attribute.

    complete

Boolean value indicating whether the web browser has completed its attempt to load the image.

    height

Reflects the `HEIGHT` attribute.

    hspace

Reflects the `HSPACE` attribute.

    lowsrc

Reflects the `LOWSRC` attribute.

    name

Reflects the `NAME` attribute.

    src

Reflects the `SRC` attribute.

    vspace

Reflects the `VSPACE` attribute.

    width

Reflects the `WIDTH` attribute.

#### Method Summary

Method | Description
--- | ---

    handleEvent

Invokes the handler for the specified event.

In addition, this object inherits the `watch` and `unwatch` methods from `Object`.

#### Examples

Example 1: Create an image with the `IMG` tag. The following code defines an image using the `IMG` tag:

    <IMG NAME="aircraft" SRC="f15e.gif" ALIGN="left" VSPACE="10">

The following code refers to the image:

    document.aircraft.src='f15e.gif'

When you refer to an image by its name, you must include the form name if the image is on a form. The following code refers to the image if it is on a form:

    document.myForm.aircraft.src='f15e.gif'

Example 2: Create an image with the Image constructor. The following example creates an `Image` object, `myImage`, that is 70 pixels wide and 50 pixels high. If the source URL, `seaotter.gif`, does not have dimensions of 70x50 pixels, it is scaled to that size.

    myImage = new Image(70, 50)
    myImage.src = "seaotter.gif"

If you omit the width and height arguments from the `Image` constructor, `myImage` is created with dimensions equal to that of the image named in the source URL.

    myImage = new Image()
    myImage.src = "seaotter.gif"

Example 3: Display an image based on form input. In the following example, the user selects which image is displayed. The user orders a shirt by filling out a form. The image displayed depends on the shirt color and size that the user chooses. All possible image choices are preloaded to speed response time. When the user clicks the button to order the shirt, the `allShirts` function displays the images of all the shirts.

    <SCRIPT>
    shirts = new Array()
    shirts[0] = "R-S"
    shirts[1] = "R-M"
    shirts[2] = "R-L"
    shirts[3] = "W-S"
    shirts[4] = "W-M"
    shirts[5] = "W-L"
    shirts[6] = "B-S"
    shirts[7] = "B-M"
    shirts[8] = "B-L"

    doneThis = 0
    shirtImg = new Array()

    // Preload shirt images
    for(idx=0; idx < 9; idx++) {
       shirtImg[idx] = new Image()
       shirtImg[idx].src = "shirt-" + shirts[idx] + ".gif"
    }

    function changeShirt(form)
    {
       shirtColor = form.color.options[form.color.selectedIndex].text
       shirtSize = form.size.options[form.size.selectedIndex].text

       newSrc = "shirt-" + shirtColor.charAt(0) + "-" + shirtSize.charAt(0) + ".gif"
       document.shirt.src = newSrc
    }

    function allShirts()
    {
       document.shirt.src = shirtImg[doneThis].src
       doneThis++
       if(doneThis != 9)setTimeout("allShirts()", 500)
       else doneThis = 0

       return
    }

    </SCRIPT>

    <FONT SIZE=+2><B>Netscape Polo Shirts!</FONT></B>

    <TABLE CELLSPACING=20 BORDER=0>
    <TR>
    <TD><IMG name="shirt" SRC="shirt-W-L.gif"></TD>

    <TD>
    <FORM>
    <B>Color</B>
    <SELECT SIZE=3 NAME="color" onChange="changeShirt(this.form)">
    <OPTION> Red
    <OPTION SELECTED> White
    <OPTION> Blue
    </SELECT>

    <P>
    <B>Size</B>
    <SELECT SIZE=3 NAME="size" onChange="changeShirt(this.form)">
    <OPTION> Small
    <OPTION> Medium
    <OPTION SELECTED> Large
    </SELECT>

    <P><INPUT type="button" name="buy" value="Buy This Shirt!"
       onClick="allShirts()">
    </FORM>

    </TD>
    </TR>
    </TABLE>

Example 4: JavaScript animation. The following example uses JavaScript to create an animation with an `Image` object by repeatedly changing the value the `src` property. The script begins by preloading the 10 images that make up the animation (`image1.gif`, `image2.gif`, `image3.gif`, and so on). When the `Image` object is placed on the document with the `IMG` tag, `image1.gif` is displayed and the `onLoad` event handler starts the animation by calling the `animate` function. Notice that the `animate` 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 `animate` function is called.

    <SCRIPT>
    delay = 100
    imageNum = 1

    // Preload animation images
    theImages = new Array()
    for(i = 1; i < 11; i++) {
       theImages[i] = new Image()
       theImages[i].src = "image" + i + ".gif"
    }

    function animate() {
       document.animation.src = theImages[imageNum].src
       imageNum++
       if(imageNum > 10) {
          imageNum = 1
       }
    }

    function slower() {
       delay+=10
       if(delay > 4000) delay = 4000
    }

    function faster() {
       delay-=10
       if(delay < 0) delay = 0
    }
    </SCRIPT>

    <BODY BGCOLOR="white">

    <IMG NAME="animation" SRC="image1.gif" ALT="[Animation]"
       onLoad="setTimeout('animate()', delay)">

    <FORM>
       <INPUT TYPE="button" Value="Slower" onClick="slower()">
       <INPUT TYPE="button" Value="Faster" onClick="faster()">
    </FORM>
    </BODY>

See also the examples for the `onAbort`, `onError`, and `onLoad` event handlers.

#### See also

`Link`, `onClick`, `onMouseOut`, `onMouseOver`

## border

A string specifying the width, in pixels, of an image border.

Property of | `Image`
Read-only |
Implemented in | JavaScript 1.1

#### Description

The `border` property reflects the `BORDER` attribute of the `IMG` tag. For images created with the `Image` constructor, the value of the `border` property is 0.

#### Examples

The following function displays the value of an image's `border` property if the value is not 0.

    function checkBorder(theImage) {
       if (theImage.border==0) {
          alert('The image has no border!')
       }
       else alert('The image's border is ' + theImage.border)
    }

#### See also

`Image.height`, `Image.hspace`, `Image.vspace`, `Image.width`

## complete

A boolean value that indicates whether the web browser has completed its attempt to load an image.

Property of | `Image`
Read-only |
Implemented in | JavaScript 1.1

#### Examples

The following example displays an image and three radio buttons. The user can click the radio buttons to choose which image is displayed. Clicking another button lets the user see the current value of the `complete` property.

    <B>Choose an image:</B>
    <BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image1" CHECKED
       onClick="document.images[0].src='f15e.gif'">F-15 Eagle
    <BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image2"
       onClick="document.images[0].src='f15e2.gif'">F-15 Eagle 2
    <BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image3"
       onClick="document.images[0].src='ah64.gif'">AH-64 Apache

    <BR><INPUT TYPE="button" VALUE="Is the image completely loaded?"
       onClick="alert('The value of the complete property is '
          + document.images[0].complete)">
    <BR>
    <IMG NAME="aircraft" SRC="f15e.gif" ALIGN="left" VSPACE="10"><BR>

#### See also

`Image.lowsrc`, `Image.src`

## handleEvent

Invokes the handler for the specified event.

Method of | `Image`
Implemented in | JavaScript 1.2

#### Syntax

    handleEvent(event)

#### Parameters

    event

The name of an event for which the specified object has an event handler.

#### Description

For information on handling events, see the Client-Side JavaScript Guide.

## height

A string specifying the height of an image in pixels.

Property of | `Image`
Read-only |
Implemented in | JavaScript 1.1

#### Description

The `height` property reflects the `HEIGHT` attribute of the `IMG` tag. For images created with the `Image` constructor, the value of the `height` property is the actual, not the displayed, height of the image.

#### Examples

The following function displays the values of an image's `height`, `width`, `hspace`, and `vspace` properties.

    function showImageSize(theImage) {
       alert('height=' + theImage.height+
          '; width=' + theImage.width +
          '; hspace=' + theImage.hspace +
          '; vspace=' + theImage.vspace)
    }

#### See also

`Image.border`, `Image.hspace`, `Image.vspace`, `Image.width`

## hspace

A string specifying a margin in pixels between the left and right edges of an image and the surrounding text.

Property of | `Image`
Read-only |
Implemented in | JavaScript 1.1

#### Description

The `hspace` property reflects the `HSPACE` attribute of the `IMG` tag. For images created with the `Image` constructor, the value of the `hspace` property is 0.

#### Examples

See the examples for the `height` property.

#### See also

`Image.border`, `Image.height`, `Image.vspace`, `Image.width`

## lowsrc

A string specifying the URL of a low-resolution version of an image to be displayed in a document.

Property of | `Image`
Implemented in | JavaScript 1.1

#### Description

The `lowsrc` property initially reflects the `LOWSRC` attribute of the `IMG` tag. The web browser loads the smaller image specified by `lowsrc` and then replaces it with the larger image specified by the `src` property. You can change the `lowsrc` property at any time.

#### Examples

See the examples for the `src` property.

#### See also

`Image.complete`, `Image.src`

## name

A string specifying the name of an object.

Property of | `Image`
Read-only |
Implemented in | JavaScript 1.1

#### Security

JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.

#### Description

Represents the value of the `NAME` attribute. For images created with the `Image` constructor, the value of the `name` property is null.

#### Examples

In the following example, the `valueGetter` function uses a `for` loop to iterate over the array of elements on the `valueTest` form. The `msgWindow` window displays the names of all the elements on the form:

    newWindow=window.open("http://home.netscape.com")

    function valueGetter() {
       var msgWindow=window.open("")
       for (var i = 0; i < newWindow.document.valueTest.elements.length; i++) {
          msgWindow.document.write(newWindow.document.valueTest.elements[i].name + "<BR>")
       }
    }

In the following example, the first statement creates a window called `netscapeWin`. The second statement displays the value `"netscapeHomePage"` in the Alert dialog box, because `"netscapeHomePage"` is the value of the `windowName` argument of `netscapeWin`.

    netscapeWin=window.open("http://home.netscape.com","netscapeHomePage")
    alert(netscapeWin.name)

## src

A string specifying the URL of an image to be displayed in a document.

Property of | `Image`
Implemented in | JavaScript 1.1

#### Description

The `src` property initially reflects the `SRC` attribute of the `IMG` tag. Setting the `src` property begins loading the new URL into the image area (and aborts the transfer of any image data that is already loading into the same area). Therefore, if you plan to alter the `lowsrc` property, you should do so before setting the `src` property. If the URL in the `src` property refers to an image that is not the same size as the image cell it is loaded into, the source image is scaled to fit. When you change the `src` property of a displayed image, the new image you specify is displayed in the area defined for the original image. For example, suppose an `Image` object originally displays the file `beluga.gif`:

    <IMG NAME="myImage" SRC="beluga.gif" ALIGN="left">

If you set `myImage.src='seaotter.gif'`, the image `seaotter.gif` is scaled to fit in the same space originally used by `beluga.gif`, even if `seaotter.gif` is not the same size as `beluga.gif`. You can change the `src` property at any time.

#### Examples

The following example displays an image and three radio buttons. The user can click the radio buttons to choose which image is displayed. Each image also uses the `lowsrc` property to display a low-resolution image.

    <SCRIPT>
    function displayImage(lowRes,highRes) {
       document.images[0].lowsrc=lowRes
       document.images[0].src=highRes
    }
    </SCRIPT>

    <FORM NAME="imageForm">
    <B>Choose an image:</B>
    <BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image1" CHECKED
       onClick="displayImage('f15el.gif','f15e.gif')">F-15 Eagle
    <BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image2"
       onClick="displayImage('f15e2l.gif','f15e2.gif')">F-15 Eagle 2
    <BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image3"
       onClick="displayImage('ah64l.gif','ah64.gif')">AH-64 Apache

    <BR>
    <IMG NAME="aircraft" SRC="f15e.gif" LOWSRC="f15el.gif" ALIGN="left" VSPACE="10"><BR>
    </FORM>

#### See also

`Image.complete`, `Image.lowsrc`

## vspace

A string specifying a margin in pixels between the top and bottom edges of an image and the surrounding text.

Property of | `Image`
Read-only |
Implemented in | JavaScript 1.1

#### Description

The `vspace` property reflects the `VSPACE` attribute of the `IMG` tag. For images created with the `Image` constructor, the value of the `vspace` property is 0.

#### Examples

See the examples for the `height` property.

#### See also

`Image.border`, `Image.height`, `Image.hspace`, `Image.width`

## width

A string specifying the width of an image in pixels.

Property of | `Image`
Read-only |
Implemented in | JavaScript 1.1

#### Description

The `width` property reflects the `WIDTH` attribute of the`IMG` tag. For images created with the `Image` constructor, the value of the `width` property is the actual, not the displayed, width of the image.

#### Examples

See the examples for the `height` property.

#### See also

`Image.border`, `Image.height`, `Image.hspace`, `Image.vspace`

Table of Contents | Previous | Next | Index

Last Updated: 05/28/99 11:59:37

Copyright (c) 1999 Netscape Communications Corporation