Chapter 21
JavaScript Reference

Image Object

Name

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

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.

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.