[Chapter 21] Reference: Image
Author: David Flanagan
Date: Fri Aug 29 11:16:34 1997

#

| Chapter 21 JavaScript Reference |

# Image Object

## Name

Image Object---an embedded image in an HTML document

## Availability

Navigator 3.0

## Synopsis

    document.images[i]
    document.images.length
    document.image-name

## Constructor

    new Image([width, height]);

### Arguments

`width`, `height`

  An optionally specified width and height for the image.

### Returns

A newly created Image object.

## Properties

`border`

  A read-only integer that specifies the width, in pixels, of the border around an image. Its value is set by the `BORDER` attribute.

`complete`

  A read-only Boolean that specifies whether the image is completely loaded yet.

`height`

  A read-only integer that specifies the height, in pixels, of the image. Its value is set by the `HEIGHT` attribute.

`hspace`

  A read-only integer that specifies the amount of extra horizontal space, in pixels, inserted on the left and right of the image. Its value is set by the `HSPACE` attribute.

`lowsrc`

  A read/write string that specifies the URL of an alternate image, suitable for display at low resolutions. Its initial value is set by the `LOWSRC` attribute.

`name`

  A read-only string, specified by the HTML `NAME` attribute, that specifies the name of the image. When an image is given an name with the `NAME` attribute, a reference to the image is placed in the `image-name` property, in addition to being placed in the `document.images[]` array.

`src`

  A read/write string that specifies the URL of the image to be displayed. Its initial value is set by the `SRC` attribute.

`vspace`

  A read-only integer that specifies the amount of extra vertical space, in pixels, inserted above and below the image. Its value is set by the `VSPACE` attribute.

`width`

  A read-only integer that specifies the width, in pixels, of the image. Its value is set by the `WIDTH` attribute.

## Event Handlers

`onabort`

  Invoked if the user aborts the download of an image.

`onerror`

  Invoked if an error occurs while downloading the image.

`onload`

  Invoked when the image successfully finishes loading.

## HTML Syntax

The Image object is created with a standard HTML `<IMG>` tag, with the addition of event handlers. Some `<IMG>` attributes have been omitted from the syntax below, because they are not used by or accessible from JavaScript.

    <IMG SRC="url" the image to display
         WIDTH=pixels the width of the image
         HEIGHT=pixels    the height of the image
         [ NAME="image_name" ]    a property name for the image
         [ LOWSRC="url" ] alternate low-resolution image
         [ BORDER=pixels ]    width of image border
         [ HSPACE=pixels ]    extra horizontal space around image
         [ VSPACE=pixels ]    extra vertical space around image
         [ onLoad=handler ]   invoked when image fully loaded
         [ onError=handler ]  invoked if error in loading
         [ onAbort=handler ]  invoked if user aborts load
    >

## Description

The Image objects in the `document.images[]` array represent the images embedded in an HTML document using the `<IMG>` tag. Most of the properties of this object are currently read-only. The `src` and `lowsrc` properties are exceptions, however. Usually, the `src` (and perhaps `lowsrc`) properties are set once, when the Image object is created from HTML. But these properties may also be set dynamically. When you set the `src` property, the browser will load the image specified by the new value of the `src` property, or by the `lowsrc` property, if specified, for low-resolution monitors. Note that if you want to use the `lowsrc` property, you must set it before you set the `src` property, because setting the `src` property starts the download of the new image.

You can dynamically create Image objects in your JavaScript code using the `Image()` constructor function. Note that this constructor method does not have an argument to specify the image to be loaded. As with images created from HTML, you tell Navigator to load an image by setting the `src` property of any images you create explicitly. There is no way to display an Image object in the web browser. All you can do is force the Image object to download an image by setting the `src` property. This is useful, however, because it loads an image into the browser's cache. Later, if that same image URL is specified for one of the images in the `images[]` array, it will be preloaded, and will be displayed quickly. You might do this with lines like the following:

    document.images[2].src = preloaded_image.src;
    document.toggle_image.src = toggle_off.src;

## Usage

Setting the `src` property of an Image object can be used to implement simple animations in your web pages. It is also an excellent technique for changing the graphics on a page as the user interacts with the page. For example, you might create your own "submit" button using an image and a hypertext link. The button would start out with a "disabled" graphic and remain that way until the user had correctly entered all the required information into the form, at which point the graphic would change, and the user would be able to submit the form.

## See Also

"Document"

History.previous |  | Image.border