Availability

Netscape 4 only; discontinued in Netscape 6

Synopsis

document.layers[i] 

Constructor

new Layer(width, parent)

Arguments

width

The width of the new layer, in pixels.

parent

The Layer or Window that should be the parent of this newly created layer. This argument is optional; if omitted, the new layer is a child of the current window.

Notes

The Layer( ) constructor creates a new Layer object and returns it. You can set its size, position, and other attributes with the various Layer properties and methods described in the following lists. In particular, you must set the hidden property to false to make the new layer visible. See the src property and load( ) methods in particular for ways to set the content of a layer. Alternatively, you can dynamically generate content for the layer by writing to its document property.

Note that you can only call the Layer( ) constructor once the current document and all of its layers have finished loading.

Properties

above

A read-only property that refers to the Layer object immediately above layer in the stacking order. If there is no such layer, above is null.

background

An Image object that specifies the image displayed in the background of the layer. The initial value of this property is specified by the background attribute of the <layer> tag. You can change the image displayed in the background of the layer by setting the background.src property. If set to null, no image is displayed, and the background color (specified by bgColor) is displayed instead.

below

A read-only property that refers to the Layer object immediately below layer in the stacking order. If there is no such layer, below is null.

bgColor

A read/write string property that specifies the background color of layer. The initial value of this property is specified by the bgcolor attribute of the <layer> tag. Note that layer.background takes precedence over layer.bgColor, so the color specified by this property appears only if the background.src property of layer is null.

clip.bottom

The Y-coordinate of the bottom edge of the layer's clipping area, relative to layer.top.

clip.height

The height of the layer's clipping area. Setting this property also sets the value of layer.clip.bottom.

clip.left

Specifies the X-coordinate of the left edge of the layer's clipping area. This value is relative to layer.left.

clip.right

Specifies the X-coordinate of the right edge of the layer's clipping area. This value is relative to layer.left.

clip.top

Specifies the Y-coordinate of the top edge of the layer's clipping area. This value is relative to layer.top.

clip.width

Specifies the width of the layer's clipping area. Setting this property also sets the value of layer.clip.right.

document

A read-only reference to the Document object contained within that layer.

hidden

Specifies whether a layer is hidden (true) or visible (false). Setting this property to true hides the layer, and setting it to false makes the layer visible.

layers[]

An array that contains any child Layer objects of this layer. It is the same as the document.layers[] array of a layer.

left

A read/write integer that specifies the X-coordinate, relative to the containing layer or document, of this layer. Setting this property moves the layer to the left or right. left is a synonym for x.

name

A read/write string that specifies the name of a layer. The initial value of this property is specified by the name or id attributes of the HTML tag used to create the layer and is also used as the name of the Document property that refers to the Layer object.

pageX, pageY

Read/write integers that specify the X- and Y-coordinates of this layer relative to the top-level document. Note that these coordinates are relative to the top-level page, not relative to any containing layer.

parentLayer

A read-only reference to the Layer or Window object that contains (is the parent of ) this layer.

siblingAbove, siblingBelow

Refer to the sibling Layer object (i.e., a child of the same parent Layer) immediately above or below this layer in the stacking order. If there is no such layer, these properties are null.

src

A read/write string that specifies the URL, if any, of the contents of a layer. Setting this property to a new URL causes the browser to read the contents of that URL and display them in the layer. Note, however, that this does not work while the current document is being parsed. For this reason, you should not set src in a top-level script; instead, set it in an event handler or a function called from an event handler.

top

A read/write integer that specifies the Y-coordinate of this layer relative to the containing layer or document. Setting this property moves the layer up or down. top is a synonym for y.

visibility

A read/write string that specifies the visibility of the layer. There are three possible legal values: "show" specifies that the layer should be visible; "hide" specifies that the layer should not be visible; "inherit" specifies that the layer should inherit the visibility of its parent layer.

window

Refers to the Window object that contains the layer, regardless of how deeply nested the layer is within other layers.

x, y

The X- and Y-coordinates of the layer, relative to the containing layer or document. Setting these properties move the layer. x is a synonym for the left property, and y is a synonym for the top property.

zIndex

Specifies the position of the layer in the z-order, or stacking order, of layers. When two layers overlap, the one with the higher zIndex appears on top and obscures the one with the lower zIndex. If two sibling layers have the same zIndex, the one that appears later in the layers[] array of the containing document is displayed later and overlaps any that appear earlier.

zIndex is a read/write property. Setting this property changes the stacking order and redisplays the layers in the new order. Setting this property may reorder the layers[] array of the containing document.

Methods

captureEvents( )

Specifies event types to be captured.

handleEvent( )

Dispatches an event to the appropriate handler.

load( )

Loads a new URL and resize.

moveAbove( )

Moves this layer above another.

moveBelow( )

Moves this layer below another.

moveBy( )

Moves the layer to a relative position.

moveTo( )

Moves the layer to a position relative to its containing layer.

moveToAbsolute( )

Moves the layer to a position relative to the page.

offset( )

A synonym for moveBy( ).

releaseEvents( )

Stops capturing specified event types.

resizeBy( )

Resizes the layer by the specified amounts.

resizeTo( )

Resizes the layer to the specified size.

routeEvent( )

Routes an event to the next interested handler.

HTML Syntax

A Layer object can be created with the Netscape-specific <layer> tag in HTML:

<layer
   [ id="layername" ]         // Layer name
   [ left="x" ]               // Position relative to containing layer
   [ top="y" ]
   [ pagex="x" ]              // Position relative to top-level document
   [ pagey="y" ]
   [ width="w" ]              // Size of layer
   [ height="h" ]
   [ src="url" ]              // URL of layer contents
   [ clip="x,y,w,h" ]         // Clipping rectangle for layer
   [ clip="w,h" ]             // Alternate syntax: x,y default to 0
   [ zindex="z" ]             // Stacking order
   [ above="layername" ]      // Alternative ways of specifying stacking
   [ below="layername" ]
   [ visibility="vis" ]       // "show", "hide", or "inherit"
   [ bgcolor="color" ]        // Background color of layer
   [ background="url" ]       // Background image of layer
   [ onmouseover="handler" ]  // Invoked when mouse enters layer
   [ onmouseout="handler" ]   // Invoked when mouse leaves layer
   [ onfocus="handler" ]      // Invoked when layer gets focus
   [ onblur="handler" ]       // Invoked when layer loses focus
   [ onload="handler" ]       // Invoked when layer's contents are loaded
>

Description

The Layer object is Netscape 4's technique for supporting dynamically positionable HTML elements. Note, however, that the Layer object was never standardized and is no longer supported in Netscape 6. A Layer object can be created in three ways: with the <layer> tag; with the Layer( ) constructor; or, most portably, with CSS style attributes on HTML elements, as explained in Chapter 18.

See Also

Window; Chapter 18