Table of Contents | Previous | Next | Index


window

Represents a browser window or frame. This is the top-level object for each document, Location, and History object group.

Client-side object.

Implemented in

JavaScript 1.0

JavaScript 1.1: added closed, history, and opener properties; added blur, focus, and scroll methods; added onBlur, onError, and onFocus event handlers

JavaScript 1.2: added crypto, innerHeight, innerWidth, locationbar, menubar, offscreenBuffering, outerHeight, outerWidth, pageXOffset, pageYOffset, personalbar, screenX, screenY, scrollbars, statusbar, and toolbar properties; added atob, back, btoa, captureEvents, clearInterval, crypto.random, crypto.signText, disableExternalCapture, enableExternalCapture, find, forward, handleEvent, home, moveBy, moveTo, releaseEvents, resizeBy, resizeTo, routeEvent, scrollBy, scrollTo, setHotKeys, setInterval, setResizable, setZOptions, and stop methods; deprecated scroll method

Created by

The JavaScript runtime engine creates a window object for each BODY or FRAMESET tag. It also creates a window object to represent each frame defined in a FRAME tag. In addition, you can create other windows by calling the window.open method. For details on defining a window, see open.

Event handlers

In JavaScript 1.1, on some platforms, placing an onBlur or onFocus event handler in a FRAMESET tag has no effect.

Description

The window object is the top-level object in the JavaScript client hierarchy. A window object can represent either a top-level window or a frame inside a frameset. As a matter of convenience, you can think about a Frame object as a window object that isn't a top-level window. However, there is not really a separate Frame class; these objects really are window objects, with a very few minor differences:

For all windows, the self and window properties of a window object are synonyms for the current window, and you can optionally use them to refer to the current window. For example, you can close the current window by calling the close method of either window or self. You can use these properties to make your code more readable or to disambiguate the property reference self.status from a form called status. See the properties and methods listed below for more examples.

Because the existence of the current window is assumed, you do not have to refer to the name of the window when you call its methods and assign its properties. For example, status="Jump to a new location" is a valid property assignment, and close() is a valid method call.

However, when you open or close a window within an event handler, you must specify window.open() or window.close() instead of simply using open() or close(). Due to the scoping of static objects in JavaScript, a call to close() without specifying an object name is equivalent to document.close().

For the same reason, when you refer to the location object within an event handler, you must specify window.location instead of simply using location. A call to location without specifying an object name is equivalent to document.location, which is a synonym for document.URL.

You can refer to a window's Frame objects in your code by using the frames array. In a window with a FRAMESET tag, the frames array contains an entry for each frame.

A windows lacks event handlers until HTML that contains a BODY or FRAMESET tag is loaded into it.

Property Summary

Property Description
closed

Specifies whether a window has been closed.

crypto

An object which allows access Navigator's encryption features.

defaultStatus

Reflects the default message displayed in the window's status bar.

document

Contains information on the current document, and provides methods for displaying HTML output to the user.

frames

An array reflecting all the frames in a window.

history

Contains information on the URLs that the client has visited within a window.

innerHeight

Specifies the vertical dimension, in pixels, of the window's content area.

innerWidth

Specifies the horizontal dimension, in pixels, of the window's content area.

length

The number of frames in the window.

location

Contains information on the current URL.

locationbar

Represents the browser window's location bar.

menubar

Represents the browser window's menu bar.

name

A unique name used to refer to this window.

offscreenBuffering

Specifies whether updates to a window are performed in an offscreen buffer.

opener

Specifies the window name of the calling document when a window is opened using the open method

outerHeight

Specifies the vertical dimension, in pixels, of the window's outside boundary.

outerWidth

Specifies the horizontal dimension, in pixels, of the window's outside boundary.

pageXOffset

Provides the current x-position, in pixels, of a window's viewed page.

pageYOffset

Provides the current y-position, in pixels, of a window's viewed page.

parent

A synonym for a window or frame whose frameset contains the current frame.

personalbar

Represents the browser window's personal bar (also called the directories bar).

screenX

Specifies the x-coordinate of the left edge of a window.

screenY

Specifies the y-coordinate of the top edge of a window.

scrollbars

Represents the browser window's scroll bars.

self

A synonym for the current window.

status

Specifies a priority or transient message in the window's status bar.

statusbar

Represents the browser window's status bar.

toolbar

Represents the browser window's toolbar.

top

A synonym for the topmost browser window.

window

A synonym for the current window.

Method Summary

Method Description
alert

Displays an Alert dialog box with a message and an OK button.

atob

Decodes a string of data which has been encoded using base-64 encoding.

back

Undoes the last history step in any frame within the top-level window.

blur

Removes focus from the specified object.

btoa

Creates a base-64 encoded string.

captureEvents

Sets the window or document to capture all events of the specified type.

clearInterval

Cancels a timeout that was set with the setInterval method.

clearTimeout

Cancels a timeout that was set with the setTimeout method.

close

Closes the specified window.

confirm

Displays a Confirm dialog box with the specified message and OK and Cancel buttons.

crypto.random

Returns a pseudo-random string whose length is the specified number of bytes.

crypto.signText

Returns a string of encoded data which represents a signed object.

disableExternalCapture

Disables external event capturing set by the enableExternalCapture method.

enableExternalCapture

Allows a window with frames to capture events in pages loaded from different locations (servers).

find

Finds the specified text string in the contents of the specified window.

focus

Gives focus to the specified object.

forward

Loads the next URL in the history list.

handleEvent

Invokes the handler for the specified event.

home

Points the browser to the URL specified in preferences as the user's home page.

moveBy

Moves the window by the specified amounts.

moveTo

Moves the top-left corner of the window to the specified screen coordinates.

open

Opens a new web browser window.

print

Prints the contents of the window or frame.

prompt

Displays a Prompt dialog box with a message and an input field.

releaseEvents

Sets the window to release captured events of the specified type, sending the event to objects further along the event hierarchy.

resizeBy

Resizes an entire window by moving the window's bottom-right corner by the specified amount.

resizeTo

Resizes an entire window to the specified outer height and width.

routeEvent

Passes a captured event along the normal event hierarchy.

scroll

Scrolls a window to a specified coordinate.

scrollBy

Scrolls the viewing area of a window by the specified amount.

scrollTo

Scrolls the viewing area of the window to the specified coordinates, such that the specified point becomes the top-left corner.

setHotKeys

Enables or disables hot keys in a window which does not have menus.

setInterval

Evaluates an expression or calls a function every time a specified number of milliseconds elapses.

setResizable

Specifies whether a user is permitted to resize a window.

setTimeout

Evaluates an expression or calls a function once after a specified number of milliseconds has elapsed.

setZOptions

Specifies the z-order stacking behavior of a window.

stop

Stops the current download.

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

Examples

Example 1. Windows opening other windows. In the following example, the document in the top window opens a second window, window2, and defines push buttons that open a message window, write to the message window, close the message window, and close window2. The onLoad and onUnload event handlers of the document loaded into window2 display alerts when the window opens and closes.

win1.htm, which defines the frames for the first window, contains the following code:

<HTML>
<HEAD>
<TITLE>window object example: Window 1</TITLE>
</HEAD>
<BODY BGCOLOR="antiquewhite">
<SCRIPT>
window2=open("win2.htm","secondWindow",
   "scrollbars=yes,width=250, height=400")
document.writeln("<B>The first window has no name: "
   + window.name + "</B>")
document.writeln("<BR><B>The second window is named: "
   + window2.name + "</B>")
</SCRIPT>
<FORM NAME="form1">
<P><INPUT TYPE="button" VALUE="Open a message window"
   onClick = "window3=window.open('','messageWindow',
   'scrollbars=yes,width=175, height=300')">
<P><INPUT TYPE="button" VALUE="Write to the message window"
   onClick="window3.document.writeln('Hey there');
   window3.document.close()">
<P><INPUT TYPE="button" VALUE="Close the message window"
   onClick="window3.close()">
<P><INPUT TYPE="button" VALUE="Close window2"
   onClick="window2.close()">
</FORM>
</BODY>
</HTML>
win2.htm, which defines the content for window2, contains the following code:

<HTML>
<HEAD>
<TITLE>window object example: Window 2</TITLE>
</HEAD>
<BODY BGCOLOR="oldlace"
   onLoad="alert('Message from ' + window.name + ': Hello, World.')"
   onUnload="alert('Message from ' + window.name + ': I\'m closing')">
<B>Some numbers</B>
<UL><LI>one
<LI>two
<LI>three
<LI>four</UL>
</BODY>
</HTML>
Example 2. Creating frames. The following example creates two windows, each with four frames. In the first window, the first frame contains push buttons that change the background colors of the frames in both windows. framset1.htm, which defines the frames for the first window, contains the following code:

<HTML>
<HEAD>
<TITLE>Frames and Framesets: Window 1</TITLE>
</HEAD>
<FRAMESET ROWS="50%,50%" COLS="40%,60%"
   onLoad="alert('Hello, World.')">
<FRAME SRC=framcon1.htm NAME="frame1">
<FRAME SRC=framcon2.htm NAME="frame2">
<FRAME SRC=framcon2.htm NAME="frame3">
<FRAME SRC=framcon2.htm NAME="frame4">
</FRAMESET>
</HTML>
framset2.htm, which defines the frames for the second window, contains the following code:

<HTML>
<HEAD>
<TITLE>Frames and Framesets: Window 2</TITLE>
</HEAD>
<FRAMESET ROWS="50%,50%" COLS="40%,60%">
<FRAME SRC=framcon2.htm NAME="frame1">
<FRAME SRC=framcon2.htm NAME="frame2">
<FRAME SRC=framcon2.htm NAME="frame3">
<FRAME SRC=framcon2.htm NAME="frame4">
</FRAMESET>
</HTML>
framcon1.htm, which defines the content for the first frame in the first window, contains the following code:

<HTML>
<BODY>
<A NAME="frame1"><H1>Frame1</H1></A>
<P><A HREF="framcon3.htm" target=frame2>Click here</A>
   to load a different file into frame 2.
<SCRIPT>
window2=open("framset2.htm","secondFrameset")
</SCRIPT>
<FORM>
<P><INPUT TYPE="button" VALUE="Change frame2 to teal"
   onClick="parent.frame2.document.bgColor='teal'">
<P><INPUT TYPE="button" VALUE="Change frame3 to slateblue"
   onClick="parent.frames[2].document.bgColor='slateblue'">
<P><INPUT TYPE="button" VALUE="Change frame4 to darkturquoise"
   onClick="top.frames[3].document.bgColor='darkturquoise'">
<P><INPUT TYPE="button" VALUE="window2.frame2 to violet"
   onClick="window2.frame2.document.bgColor='violet'">
<P><INPUT TYPE="button" VALUE="window2.frame3 to fuchsia"
   onClick="window2.frames[2].document.bgColor='fuchsia'">
<P><INPUT TYPE="button" VALUE="window2.frame4 to deeppink"
   onClick="window2.frames[3].document.bgColor='deeppink'">
</FORM>
</BODY>
</HTML>
framcon2.htm, which defines the content for the remaining frames, contains the following code:

<HTML>
<BODY>
<P>This is a frame.
</BODY>
</HTML>
framcon3.htm, which is referenced in a Link object in framcon1.htm, contains the following code:

<HTML>
<BODY>
<P>This is a frame. What do you think?
</BODY>
</HTML>

See also

document, Frame


alert

Displays an Alert dialog box with a message and an OK button.

Method of

window

Implemented in

JavaScript 1.0

Syntax

alert(message)

Parameters

message

A string.

Description

An alert dialog box looks as follows:

Use the alert method to display a message that does not require a user decision. The message argument specifies a message that the dialog box contains.

You cannot specify a title for an alert dialog box, but you can use the open method to create your own alert dialog box. See open.

Examples

In the following example, the testValue function checks the name entered by a user in the Text object of a form to make sure that it is no more than eight characters in length. This example uses the alert method to prompt the user to enter a valid value.

function testValue(textElement) {
   if (textElement.length > 8) {
      alert("Please enter a name that is 8 characters or less")
   }
}
You can call the testValue function in the onBlur event handler of a form's Text object, as shown in the following example:

Name: <INPUT TYPE="text" NAME="userName"
   onBlur="testValue(userName.value)">

See also

window.confirm, window.prompt


atob

Decodes a string of data which has been encoded using base-64 encoding.

Method of

window

Implemented in

JavaScript 1.2

Syntax

atob(encodedData)

Parameters

encodedData

A string of data which has been created using base-64 encoding.

Description

This method decodes a string of data which has been encoded using base-64 encoding. For example, the window.btoa method takes a binary string as a parameter and returns a base-64 encoded string.

You can use the window.btoa method to encode and transmit data which may otherwise cause communication problems, then transmit it and use the window.atob method to decode the data again. For example, you can encode, transmit, and decode characters such as ASCII values 0 through 31.

Examples

The following example encodes and decodes the string "Hello, world".

// encode a string
encodedData = btoa("Hello, world");

// decode the string
decodedData = atob(encodedData);

See also

window.btoa


back

Undoes the last history step in any frame within the top-level window; equivalent to the user pressing the browser's Back button.

Method of

window

Implemented in

JavaScript 1.2

Syntax

back()

Parameters

None

Description

Calling the back method is equivalent to the user pressing the browser's Back button. That is, back undoes the last step anywhere within the top-level window, whether it occurred in the same frame or in another frame in the tree of frames loaded from the top-level window. In contrast, the history object's back method backs up the current window or frame history one step.

For example, consider the following scenario. While in Frame A, you click the Forward button to change Frame A's content. You then move to Frame B and click the Forward button to change Frame B's content. If you move back to Frame A and call FrameA.back(), the content of Frame B changes (clicking the Back button behaves the same).

If you want to navigate Frame A separately, use FrameA.history.back().

Examples

The following custom buttons perform the same operation as the browser's Back button:

<P><INPUT TYPE="button" VALUE="< Go Back"
   onClick="history.back()">
<P><INPUT TYPE="button" VALUE="> Go Back"
   onClick="myWindow.back()">

See also

window.forward, History.back


blur

Removes focus from the specified object.

Method of

window

Implemented in

JavaScript 1.0

Syntax

blur()

Parameters

None

Description

Use the blur method to remove focus from a specific window or frame. Removing focus from a window sends the window to the background in most windowing systems.

See also

window.focus


btoa

Creates a base-64 encoded ASCII string from a string of binary data.

Method of

window

Implemented in

JavaScript 1.2

Syntax

btoa(stringToEncode)

Parameters

stringToEncode

An arbitrary binary string to be encoded.

Description

This method takes a binary ASCII string as a parameter and returns another ASCII string which has been encoded using base-64 encoding.

You can use this method to encode data which may otherwise cause communication problems, transmit it, then use the window.atob method to decode the data again. For example, you can encode characters such as ASCII values 0 through 31.

Examples

See window.atob.

See also

window.atob


captureEvents

Sets the window to capture all events of the specified type.

Method of

window

Implemented in

JavaScript 1.2

Syntax

captureEvents(eventType1 [|eventTypeN...])

Parameters

eventType1... eventTypeN

The type of event to be captured. The available event types are discussed in Chapter 3, "Event Handlers."

Security

When a window with frames wants to capture events in pages loaded from different locations (servers), you need to use captureEvents in a signed script and precede it with enableExternalCapture. You must have the UniversalBrowserWrite privilege. For more information and an example, see enableExternalCapture. For information on security, see the Client-Side JavaScript Guide.

See also

captureEvents works in tandem with releaseEvents, routeEvent, and handleEvent. For more information, see the Client-Side JavaScript Guide.


clearInterval

Cancels a timeout that was set with the setInterval method.

Method of

window

Implemented in

JavaScript 1.2

Syntax

clearInterval(intervalID)

Parameters

intervalID

Timeout setting that was returned by a previous call to the setInterval method.

Description

See setInterval.

Examples

See setInterval.

See also

window.setInterval


clearTimeout

Cancels a timeout that was set with the setTimeout method.

Method of

window

Implemented in

JavaScript 1.0

Syntax

clearTimeout(timeoutID)

Parameters

timeoutID

A timeout setting that was returned by a previous call to the setTimeout method.

Description

See setTimeout.

Examples

See setTimeout.

See also

window.clearInterval, window.setTimeout


close

Closes the specified window.

Method of

window

Implemented in

JavaScript 1.0: closes any window

JavaScript 1.1: closes only windows opened by JavaScript

JavaScript 1.2: must use signed scripts to unconditionally close a window

Syntax

close()

Parameters

None

Security

To unconditionally close a window, you need the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

Description

The close method closes the specified window. If you call close without specifying a windowReference, JavaScript closes the current window.

The close method closes only windows opened by JavaScript using the open method. If you attempt to close any other window, a confirm is generated, which lets the user choose whether the window closes. This is a security feature to prevent "mail bombs" containing self.close(). However, if the window has only one document (the current one) in its session history, the close is allowed without any confirm. This is a special case for one-off windows that need to open other windows and then dispose of themselves.

In event handlers, you must specify window.close() instead of simply using close(). Due to the scoping of static objects in JavaScript, a call to close() without specifying an object name is equivalent to document.close().

Examples

Example 1. Any of the following examples closes the current window:

window.close()
self.close()
close()
Example 2: Close the main browser window. The following code closes the main browser window.

top.opener.close()
Example 3. The following example closes the messageWin window:

messageWin.close()
This example assumes that the window was opened in a manner similar to the following:

messageWin=window.open("")

See also

window.closed, window.open


closed

Specifies whether a window is closed.

Property of

window

Read-only

Implemented in

JavaScript 1.1

Description

The closed property is a boolean value that specifies whether a window has been closed. When a window closes, the window object that represents it continues to exist, and its closed property is set to true.

Use closed to determine whether a window that you opened, and to which you still hold a reference (from the return value of window.open), is still open. Once a window is closed, you should not attempt to manipulate it.

Examples

Example 1. The following code opens a window, win1, then later checks to see if that window has been closed. A function is called depending on whether win1 is closed.

win1=window.open('opener1.htm','window1','width=300,height=300')
...
if (win1.closed)
   function1()
   else
   function2()
Example 2. The following code determines if the current window's opener window is still closed, and calls the appropriate function.

if (window.opener.closed)
   function1()
   else
   function2()

See also

window.close, window.open


confirm

Displays a Confirm dialog box with the specified message and OK and Cancel buttons.

Method of

window

Implemented in

JavaScript 1.0

Syntax

confirm(message)

Parameters

message

A string.

Description

A confirm dialog box looks as follows:

Use the confirm method to ask the user to make a decision that requires either an OK or a Cancel. The message argument specifies a message that prompts the user for the decision. The confirm method returns true if the user chooses OK and false if the user chooses Cancel.

You cannot specify a title for a confirm dialog box, but you can use the open method to create your own confirm dialog. See open.

Examples

This example uses the confirm method in the confirmCleanUp function to confirm that the user of an application really wants to quit. If the user chooses OK, the custom cleanUp function closes the application.

function confirmCleanUp() {
   if (confirm("Are you sure you want to quit this application?")) {
      cleanUp()
   }
}
You can call the confirmCleanUp function in the onClick event handler of a form's push button, as shown in the following example:

<INPUT TYPE="button" VALUE="Quit" onClick="confirmCleanUp()">

See also

window.alert, window.prompt


crypto

An object which allows access Navigator's encryption features.

Property of

window

Read-only

Implemented in

JavaScript 1.2

Description

The crypto object is only available as a property of window; it provides access to methods which support Navigator's encryption features.

See also

window.crypto.random, window.crypto.signText


crypto.random

Returns a pseudo-random string whose length is the specified number of bytes.

Method of

window

Static

Implemented in

JavaScript 1.2

Syntax

crypto.random(numberOfBytes)

Parameters

numberOfBytes

The number of bytes of pseudo-random data the method will return.

Description

This method generates a random string of data whose length is specified by the numberOfBytes parameter.

Examples

The following function returns a string whose length is 16 bytes.

function getRandom() {
   return crypto.random(16)
}

See also

Math.random


crypto.signText

Returns a string of encoded data which represents a signed object.

Method of

window

Static

Implemented in

JavaScript 1.2

Syntax

crypto.signText
   (text, selectionStyle [, authority1 [, ... authorityN]])

Parameters

text

A string evaluating to the text you want a user to sign.

selectionStyle

A string evaluating to either of the following:

authority1... authorityN

Optional strings evaluating to Certificate Authorities accepted by the server using the signed text.

Description

The signText method asks a user to validate a text string by attaching a digital signature to it. If the selectionStyle parameter is set to ask, signText displays a dialog box, and a user must interactively select a certificate to validate the text. If selectionStyle is set to auto, Navigator attempts to automatically select a certificate.

Use the signText method to submit an encoded signature to a server; the server decodes the signature and verifies it. If signText fails, it returns one of the following error codes:


defaultStatus

The default message displayed in the status bar at the bottom of the window.

Property of

window

Implemented in

JavaScript 1.0

Security

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

Description

The defaultStatus message appears when nothing else is in the status bar. Do not confuse the defaultStatus property with the status property. The status property reflects a priority or transient message in the status bar, such as the message that appears when a mouseOver event occurs over an anchor.

You can set the defaultStatus property at any time. You must return true if you want to set the defaultStatus property in the onMouseOut or onMouseOver event handlers.

Examples

In the following example, the statusSetter function sets both the status and defaultStatus properties in an onMouseOver event handler:

function statusSetter() {
   window.defaultStatus = "Click the link for the Netscape home page"
   window.status = "Netscape home page"
}
<A HREF="http://home.netscape.com"
   onMouseOver = "statusSetter(); return true">Netscape</A>
In the previous example, notice that the onMouseOver event handler returns a value of true. You must return true to set status or defaultStatus in an event handler.

See also

window.status


disableExternalCapture

Disables external event capturing set by the enableExternalCapture method.

Method of

window

Implemented in

JavaScript 1.2

Syntax

disableExternalCapture()

Parameters

None

Description

See enableExternalCapture.


document

Contains information on the current document, and provides methods for displaying HTML output to the user.

Property of

window

Implemented in

JavaScript 1.0

Description

The value of this property is the window's associated document object.


enableExternalCapture

Allows a window with frames to capture events in pages loaded from different locations (servers).

Method of

window

Implemented in

JavaScript 1.2

Syntax

enableExternalCapture()

Parameters

None

Description

Use this method in a signed script requesting UniversalBrowserWrite privileges, and use it before calling the captureEvents method.

If Communicator sees additional scripts that cause the set of principals in effect for the container to be downgraded, it disables external capture of events. Additional calls to enableExternalCapture (after acquiring the UniversalBrowserWrite privilege under the reduced set of principals) can be made to enable external capture again.

Examples

In the following example, the window is able to capture all Click events that occur across its frames.

<SCRIPT ARCHIVE="myArchive.jar" ID="2">
function captureClicks() {
   netscape.security.PrivilegeManager.enablePrivilege(
      "UniversalBrowserWrite");
   enableExternalCapture();
   captureEvents(Event.CLICK);
   ...
}
</SCRIPT>

See also

window.disableExternalCapture, window.captureEvents


find

Finds the specified text string in the contents of the specified window.

Method of

window

Implemented in

JavaScript 1.2

Syntax

find([string[, caseSensitive, backward]])

Parameters

string

The text string for which to search.

caseSensitive

Boolean value. If true, specifies a case-sensitive search. If you supply this parameter, you must also supply backward.

backward

Boolean. If true, specifies a backward search. If you supply this parameter, you must also supply casesensitive.

Returns

true if the string is found; otherwise, false.

Description

When a string is specified, the browser performs a case-insensitive, forward search. If a string is not specified, the method displays the Find dialog box, allowing the user to enter a search string.


focus

Gives focus to the specified object.

Method of

window

Implemented in

JavaScript 1.1

Syntax

focus()

Parameters

None

Description

Use the focus method to navigate to a specific window or frame, and give it focus. Giving focus to a window brings the window forward in most windowing systems.

In JavaScript 1.1, on some platforms, the focus method gives focus to a frame but the focus is not visually apparent (for example, the frame's border is not darkened).

Examples

In the following example, the checkPassword function confirms that a user has entered a valid password. If the password is not valid, the focus method returns focus to the Password object and the select method highlights it so the user can reenter the password.

function checkPassword(userPass) {
   if (badPassword) {
      alert("Please enter your password again.")
      userPass.focus()
      userPass.select()
   }
}
This example assumes that the Password object is defined as

<INPUT TYPE="password" NAME="userPass">

See also

window.blur


forward

Points the browser to the next URL in the current history list; equivalent to the user pressing the browser's Forward button

Method of

window

Implemented in

JavaScript 1.2

Syntax

history.forward()
forward()

Parameters

None

Description

This method performs the same action as a user choosing the Forward button in the browser. The forward method is the same as history.go(1).

When used with the Frame object, forward behaves as follows: While in Frame A, you click the Back button to change Frame A's content. You then move to Frame B and click the Back button to change Frame B's content. If you move back to Frame A and call FrameA.forward(), the content of Frame B changes (clicking the Forward button behaves the same). If you want to navigate Frame A separately, use FrameA.history.forward().

Examples

The following custom buttons perform the same operation as the browser's Forward button:

<P><INPUT TYPE="button" VALUE="< Go Forth"
   onClick="history.forward()">
<P><INPUT TYPE="button" VALUE="> Go Forth"
   onClick="myWindow.forward()">

See also

window.back


frames

An array of objects corresponding to child frames (created with the FRAME tag) in source order.

Property of

window

Read-only

Implemented in

JavaScript 1.0

You can refer to the child frames of a window by using the frames array. This array contains an entry for each child frame (created with the FRAME tag) in a window containing a FRAMESET tag; the entries are in source order. For example, if a window contains three child frames whose NAME attributes are fr1, fr2, and fr3, you can refer to the objects in the images array either as:

parent.frames["fr1"]
parent.frames["fr2"]
parent.frames["fr3"]
or as:

parent.frames[0]
parent.frames[1]
parent.frames[2]
You can find out how many child frames the window has by using the length property of the window itself or of the frames array.

The value of each element in the frames array is <object nameAttribute>, where nameAttribute is the NAME attribute of the frame.


handleEvent

Invokes the handler for the specified event.

Method of

window

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

handleEvent works in tandem with captureEvents, releaseEvents, and routeEvent. For more information, see the Client-Side JavaScript Guide.


history

Contains information on the URLs that the client has visited within a window.

Property of

window

Implemented in

JavaScript 1.1

Description

The value of this property is the window's associated History object.


home

Points the browser to the URL specified in preferences as the user's home page; equivalent to the user pressing the browser's Home button.

Method of

window

Implemented in

JavaScript 1.2

Syntax

home()

Parameters

None

Description

This method performs the same action as a user choosing the Home button in the browser.


innerHeight

Specifies the vertical dimension, in pixels, of the window's content area.

Property of

window

Implemented in

JavaScript 1.2

Description

To create a window smaller than 100 x 100 pixels, set this property in a signed script.

Security

To set the inner height of a window to a size smaller than 100 x 100 or larger than the screen can accommodate, you need the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

See also

window.innerWidth, window.outerHeight, window.outerWidth


innerWidth

Specifies the horizontal dimension, in pixels, of the window's content area.

Property of

window

Implemented in

JavaScript 1.2

Description

To create a window smaller than 100 x 100 pixels, set this property in a signed script.

Security

To set the inner width of a window to a size smaller than 100 x 100 or larger than the screen can accommodate, you need the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

See also

window.innerHeight, window.outerHeight, window.outerWidth


length

The number of child frames in the window.

Property of

window

Read-only

Implemented in

JavaScript 1.0

Description

This property gives you the same result as using the length property of the frames array.


location

Contains information on the current URL.

Property of

window

Implemented in

JavaScript 1.0

Description

The value of this property is the window's associated Location object.


locationbar

Represents the browser window's location bar (the region containing the bookmark and URL areas).

Property of

window

Implemented in

JavaScript 1.2

Description

The value of the locationbar property itself has one property, visible. If true, the location bar is visible; if false, it is hidden.

Security

Setting the value of the location bar's visible property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

Examples

The following example would make the referenced window "chromeless" (chromeless windows lack toolbars, scrollbars, status areas, and so on, much like a dialog box) by hiding most of the user interface toolbars:

self.menubar.visible=false;
self.toolbar.visible=false;
self.locationbar.visible=false;
self.personalbar.visible=false;
self.scrollbars.visible=false;
self.statusbar.visible=false;

menubar

Represents the browser window's menu bar. This region contains the browser's drop-down menus such as File, Edit, View, Go, Communicator, and so on.

Property of

window

Implemented in

JavaScript 1.2

Description

The value of the menubar property itself has one property, visible. If true, the menu bar is visible; if false, it is hidden.

Security

Setting the value of the menu bar's visible property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

Examples

The following example would make the referenced window "chromeless" (chromeless windows lack toolbars, scrollbars, status areas, and so on, much like a dialog box) by hiding most of the user interface toolbars:

self.menubar.visible=false;
self.toolbar.visible=false;
self.locationbar.visible=false;
self.personalbar.visible=false;
self.scrollbars.visible=false;
self.statusbar.visible=false;

moveBy

Moves the window relative to its current position, moving the specified number of pixels.

Method of

window

Implemented in

JavaScript 1.2

Syntax

moveBy(horizontal, vertical)

Parameters

horizontal

The number of pixels by which to move the window horizontally.

vertical

The number of pixels by which to move the window vertically.

Description

This method moves the window by adding or subtracting the specified number of pixels to the current location.

Security

Exceeding any of the boundaries of the screen (to hide some or all of a window) requires signed JavaScript, so a window won't move past the screen boundaries. You need the UniversalBrowserWrite privilege for this. For information on security, see the Client-Side JavaScript Guide.

Examples:

To move the current window 5 pixels up towards the top of the screen (x-axis), and 10 pixels towards the right (y-axis) of the current window position, use this statement:

self.moveBy(-5,10); // relative positioning

See also

window.moveTo


moveTo

Moves the top-left corner of the window to the specified screen coordinates.

Method of

window

Implemented in

JavaScript 1.2

Syntax

moveTo(x-coordinate, y-coordinate)

Parameters

x-coordinate 

The left edge of the window in screen coordinates.

y-coordinate

The top edge of the window in screen coordinates.

Description

This method moves the window to the absolute pixel location indicated by its parameters. The origin of the axes is at absolute position (0,0); this is the upper left-hand corner of the display.

Security

Exceeding any of the boundaries of the screen (to hide some or all of a window) requires signed JavaScript, so a window won't move past the screen boundaries. You need the UniversalBrowserWrite privilege for this. For information on security, see the Client-Side JavaScript Guide.

Examples:

To move the current window to 25 pixels from the top boundary of the screen (x-axis), and 10 pixels from the left boundary of the screen (y-axis), use this statement:

self.moveTo(25,10); // absolute positioning

See also

window.moveBy


name

A string specifying the window's name.

Property of

window

Read-only (2.0); Modifiable (later versions)

Implemented in

JavaScript 1.0

Security

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

Description

In JavaScript 1.0, NAME was a read-only property. In later versions, this property is modifiable by your code. This allows you to assign a name to a top-level window.

Examples

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)

offscreenBuffering

Specifies whether window updates are performed in an offscreen buffer.

Property of

window

Implemented in

JavaScript 1.2

Description

By default, Navigator automatically determines whether updates to a window are performed in an offscreen buffer and then displayed in a window. You can either prevent buffering completely or require Navigator to buffer updates by setting offscreenBuffering to either false or true, respectively.

Buffering can reduce the flicker that occurs during window updates, but it requires additional system resources.


open

Opens a new web browser window.

Method of

window

Implemented in

JavaScript 1.0

JavaScript 1.2: added several new windowFeatures

Syntax

open(URL, windowName[, windowFeatures])

Parameters

URL

A string specifying the URL to open in the new window. See the Location object for a description of the URL components.

windowName

A string specifying the window name to use in the TARGET attribute of a FORM or A tag. windowName can contain only alphanumeric or underscore (_) characters.

windowFeatures

A string containing a comma-separated list determining whether or not to create various standard window features. These options are described in the following section.

Description

In event handlers, you must specify window.open() instead of simply using open(). Due to the scoping of static objects in JavaScript, a call to open() without specifying an object name is equivalent to document.open().

The open method opens a new Web browser window on the client, similar to choosing New, then Navigator Window from the Navigator File menu. The URL argument specifies the URL contained by the new window. If URL is an empty string, a new, empty window is created.

You can use open on an existing window, and if you pass the empty string for the URL, you will get a reference to the existing window, but not load anything into it. You can, for example, then look for properties in the window.

windowFeatures is an optional string containing a comma-separated list of options for the new window (do not include any spaces in this list). After a window is open, you cannot use JavaScript to change the windowFeatures. You can specify the following features:

Table 1.4 Optional features to specify for a new window.
windowFeatures Description
alwaysLowered

(JavaScript 1.2) If yes, creates a new window that floats below other windows, whether it is active or not. This is a secure feature and must be set in signed scripts.

alwaysRaised

(JavaScript 1.2) If yes, creates a new window that floats on top of other windows, whether it is active or not. This is a secure feature and must be set in signed scripts.

dependent

(JavaScript 1.2) If yes, creates a new window as a child of the current window. A dependent window closes when its parent window closes. On Windows platforms, a dependent window does not show on the task bar.

directories

If yes, creates the standard browser directory buttons, such as What's New and What's Cool.

height

(JavaScript 1.0 and 1.1) Specifies the height of the window in pixels.

hotkeys

(JavaScript 1.2) If no (or 0), disables most hotkeys in a new window that has no menu bar. The security and quit hotkeys remain enabled.

innerHeight

(JavaScript 1.2) Specifies the height, in pixels, of the window's content area. To create a window smaller than 100 x 100 pixels, set this feature in a signed script. This feature replaces height, which remains for backwards compatibility.

innerWidth

(JavaScript 1.2) Specifies the width, in pixels, of the window's content area. To create a window smaller than 100 x 100 pixels, set this feature in a signed script. This feature replaces width, which remains for backwards compatibility.

location

If yes, creates a Location entry field.

menubar

If yes, creates the menu at the top of the window.

outerHeight

(JavaScript 1.2) Specifies the vertical dimension, in pixels, of the outside boundary of the window. To create a window smaller than 100 x 100 pixels, set this feature in a signed script.

personalbar

(JavaScript 1.2) If yes, creates the Personal Toolbar, which displays buttons from the user's Personal Toolbar bookmark folder.

resizable

If yes, allows a user to resize the window.

screenX

(JavaScript 1.2) Specifies the distance the new window is placed from the left side of the screen. To place a window offscreen, set this feature in a signed scripts.

screenY

(JavaScript 1.2) Specifies the distance the new window is placed from the top of the screen. To place a window offscreen, set this feature in a signed scripts.

scrollbars

If yes, creates horizontal and vertical scrollbars when the Document grows larger than the window dimensions.

status

If yes, creates the status bar at the bottom of the window.

titlebar

(JavaScript 1.2) If yes, creates a window with a title bar. To set the titlebar to no, set this feature in a signed script.

toolbar

If yes, creates the standard browser toolbar, with buttons such as Back and Forward.

width

(JavaScript 1.0 and 1.1) Specifies the width of the window in pixels.

z-lock

(JavaScript 1.2) If yes, creates a new window that does not rise above other windows when activated. This is a secure feature and must be set in signed scripts.

Many of these features (as noted above) can either be yes or no. For these features, you can use 1 instead of yes and 0 instead of no. If you want to turn a feature on, you can also simply list the feature name in the windowFeatures string.

If windowName does not specify an existing window and you do not supply the windowFeatures parameter, all of the features which have a yes/no choice are yes by default. However, if you do supply the windowFeatures parameter, then the titlebar and hotkeys are still yes by default, but the other features which have a yes/no choice are no by default.

For example, all of the following statements turn on the toolbar option and turn off all other Boolean options:

open("", "messageWindow", "toolbar")
open("", "messageWindow", "toolbar=yes")
open("", "messageWindow", "toolbar=1")
The following statement turn on the location and directories options and turns off all other Boolean options:

open("", "messageWindow", "toolbar,directories=yes")
How the alwaysLowered, alwaysRaised, and z-lock features behave depends on the windowing hierarchy of the platform. For example, on Windows, an alwaysLowered or z-locked browser window is below all windows in all open applications. On Macintosh, an alwaysLowered browser window is below all browser windows, but not necessarily below windows in other open applications. Similarly for an alwaysRaised window.

You may use open to open a new window and then use open on that window to open another window, and so on. In this way, you can end up with a chain of opened windows, each of which has an opener property pointing to the window that opened it.

Communicator allows a maximum of 100 windows to be around at once. If you open window2 from window1 and then are done with window1, be sure to set the opener property of window2 to null. This allows JavaScript to garbage collect window1. If you do not set the opener property to null, the window1 object remains, even though it's no longer really needed.

Security

To perform the following operations, you need the UniversalBrowserWrite privilege:

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

Examples

Example 1. In the following example, the windowOpener function opens a window and uses write methods to display a message:

function windowOpener() {
   msgWindow=window.open("","displayWindow","menubar=yes")
   msgWindow.document.write
      ("<HEAD><TITLE>Message window</TITLE></HEAD>")
   msgWindow.document.write
      ("<CENTER><BIG><B>Hello, world!</B></BIG></CENTER>")
}
Example 2. The following is an onClick event handler that opens a new client window displaying the content specified in the file sesame.htm. The window opens with the specified option settings; all other options are false because they are not specified.

<FORM NAME="myform">
<INPUT TYPE="button" NAME="Button1" VALUE="Open Sesame!"
   onClick="window.open ('sesame.htm', 'newWin',
   'scrollbars=yes,status=yes,width=300,height=300')">
</FORM>

See also

window.close


opener

Specifies the window of the calling document when a window is opened using the open method.

Property of

window

Implemented in

JavaScript 1.1

Description

When a source document opens a destination window by calling the open method, the opener property specifies the window of the source document. Evaluate the opener property from the destination window.

This property persists across document unload in the opened window.

You can change the opener property at any time.

You may use window.open to open a new window and then use window.open on that window to open another window, and so on. In this way, you can end up with a chain of opened windows, each of which has an opener property pointing to the window that opened it.

Communicator allows a maximum of 100 windows to be around at once. If you open window2 from window1 and then are done with window1, be sure to set the opener property of window2 to null. This allows JavaScript to garbage collect window1. If you do not set the opener property to null, the window1 object remains, even though it's no longer really needed.

Examples

Example 1: Close the opener. The following code closes the window that opened the current window. When the opener window closes, opener is unchanged. However, window.opener.name then evaluates to undefined.

window.opener.close()
Example 2: Close the main browser window.

top.opener.close()
Example 3: Evaluate the name of the opener. A window can determine the name of its opener as follows:

document.write("<BR>opener property is " + window.opener.name)
Example 4: Change the value of opener. The following code changes the value of the opener property to null. After this code executes, you cannot close the opener window as shown in Example 1.

window.opener=null
Example 5: Change a property of the opener. The following code changes the background color of the window specified by the opener property.

window.opener.document.bgColor='bisque'

See also

window.close, window.open


outerHeight

Specifies the vertical dimension, in pixels, of the window's outside boundary.

Property of

window

Implemented in

JavaScript 1.2

Description

The outer boundary includes the scroll bars, the status bar, the toolbars, and other "chrome" (window border user interface elements). To create a window smaller than 100 x 100 pixels, set this property in a signed script.

See also

window.innerWidth, window.innerHeight, window.outerWidth


outerWidth

Specifies the horizontal dimension, in pixels, of the window's outside boundary.

Property of

window

Implemented in

JavaScript 1.2

Description

The outer boundary includes the scroll bars, the status bar, the toolbars, and other "chrome" (window border user interface elements). To create a window smaller than 100 x 100 pixels, set this property in a signed script.

See also

window.innerWidth, window.innerHeight, window.outerHeight


pageXOffset

Provides the current x-position, in pixels, of a window's viewed page.

Property of

window

Read-only

Implemented in

JavaScript 1.2

Description

The pageXOffset property provides the current x-position of a page as it relates to the upper-left corner of the window's content area. This property is useful when you need to find the current location of the scrolled page before using scrollTo or scrollBy.

Examples

The following example returns the x-position of the viewed page.

x = myWindow.pageXOffset

See Also

window.pageYOffset


pageYOffset

Provides the current y-position, in pixels, of a window's viewed page.

Property of

window

Read-only

Implemented in

JavaScript 1.2

Description

The pageYOffset property provides the current y-position of a page as it relates to the upper-left corner of the window's content area. This property is useful when you need to find the current location of the scrolled page before using scrollTo or scrollBy.

Examples

The following example returns the y-position of the viewed page.

x = myWindow.pageYOffset

See also

window.pageXOffset


parent

The parent property is the window or frame whose frameset contains the current frame.

Property of

window

Read-only

Implemented in

JavaScript 1.0

Description

This property is only meaningful for frames; that is, windows that are not top-level windows.

The parent property refers to the FRAMESET window of a frame. Child frames within a frameset refer to sibling frames by using parent in place of the window name in one of the following ways:

parent.frameName
parent.frames[index]
For example, if the fourth frame in a set has NAME="homeFrame", sibling frames can refer to that frame using parent.homeFrame or parent.frames[3].

You can use parent.parent to refer to the "grandparent" frame or window when a FRAMESET tag is nested within a child frame.

The value of the parent property is

<object nameAttribute>
where nameAttribute is the NAME attribute if the parent is a frame, or an internal reference if the parent is a window.

Examples

See examples for Frame.


personalbar

Represents the browser window's personal bar (also called the directories bar). This is the region the user can use for easy access to certain bookmarks.

Property of

window

Implemented in

JavaScript 1.2

Description

The value of the personalbar property itself has one property, visible. If true, the personal bar is visible; if false, it is hidden.

Security

Setting the value of the personal bar's visible property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

Examples

The following example would make the referenced window "chromeless" (chromeless windows lack toolbars, scrollbars, status areas, and so on, much like a dialog box) by hiding most of the user interface toolbars:

self.menubar.visible=false;
self.toolbar.visible=false;
self.locationbar.visible=false;
self.personalbar.visible=false;
self.scrollbars.visible=false;
self.statusbar.visible=false;

print

Prints the contents of the window.

Method of

window

Implemented in

JavaScript 1.2

Syntax

print()

Parameters

None


prompt

Displays a Prompt dialog box with a message and an input field.

Method of

window

Implemented in

JavaScript 1.0

Syntax

prompt(message[, inputDefault])

Parameters

message

A string to be displayed as the message.

inputDefault

A string or integer representing the default value of the input field.

Description

A prompt dialog box looks as follows:

Use the prompt method to display a dialog box that receives user input. If you do not specify an initial value for inputDefault, the dialog box displays <undefined>.

You cannot specify a title for a prompt dialog box, but you can use the open method to create your own prompt dialog. See open.

Examples

prompt("Enter the number of cookies you want to order:", 12)

See also

window.alert, window.confirm


releaseEvents

Sets the window or document to release captured events of the specified type, sending the event to objects further along the event hierarchy.

Method of

window

Implemented in

JavaScript 1.2

NOTE: If the original target of the event is a window, the window receives the event even if it is set to release that type of event.

Syntax

releaseEvents(eventType1 [|eventTypeN...])

Parameters

eventType1... eventTypeN

The type of event to be captured. The available event types are discussed in Chapter 3, "Event Handlers."

Description

releaseEvents works in tandem with captureEvents, routeEvent, and handleEvent. For more information, see the Client-Side JavaScript Guide.


resizeBy

Resizes an entire window by moving the window's bottom-right corner by the specified amount.

Method of

window

Implemented in

JavaScript 1.2

Syntax

resizeBy(horizontal, vertical)

Parameters

horizontal

The number of pixels by which to resize the window horizontally.

vertical

The number of pixels by which to resize the window vertically.

Description

This method changes the window's dimensions by setting its outerWidth and outerHeight properties. The upper left-hand corner remains anchored and the lower right-hand corner moves. resizeBy moves the window by adding or subtracting the specified number of pixels to that corner's current location.

Security

Exceeding any of the boundaries of the screen (to hide some or all of a window) requires signed JavaScript, so a window won't move past the screen boundaries. In addition, windows have an enforced minimum size of 100 x 100 pixels; resizing a window to be smaller than this minimum requires signed JavaScript. You need the UniversalBrowserWrite privilege for this. For information on security, see the Client-Side JavaScript Guide.

Examples

To make the current window 5 pixels narrower and 10 pixels taller than its current dimensions, use this statement:

self.resizeBy(-5,10); // relative positioning

See also

window.resizeTo


resizeTo

Resizes an entire window to the specified pixel dimensions.

Method of

window

Implemented in

JavaScript 1.2

Syntax

resizeTo(outerWidth, outerHeight)

Parameters

outerWidth

An integer representing the window's width in pixels.

outerHeight

An integer representing the window's height in pixels.

Description

This method changes the window's dimensions by setting its outerWidth and outerHeight properties. The upper left-hand corner remains anchored and the lower right-hand corner moves. resizeBy moves to the specified position. The origin of the axes is at absolute position (0,0); this is the upper left-hand corner of the display.

Security

Exceeding any of the boundaries of the screen (to hide some or all of a window) requires signed JavaScript, so a window won't move past the screen boundaries. In addition, windows have an enforced minimum size of 100 x 100 pixels; resizing a window to be smaller than this minimum requires signed JavaScript. You need the UniversalBrowserWrite privilege for this. For information on security, see the Client-Side JavaScript Guide.

Examples

To make the window 225 pixels wide and 200 pixels tall, use this statement:

self.resizeTo(225,200); // absolute positioning

See also

window.resizeBy


routeEvent

Passes a captured event along the normal event hierarchy.

Method of

window

Implemented in

JavaScript 1.2

Syntax

routeEvent(event)

Parameters

event

Name of the event to be routed.

Description

If a sub-object (document or layer) is also capturing the event, the event is sent to that object. Otherwise, it is sent to its original target.

routeEvent works in tandem with captureEvents, releaseEvents, and handleEvent. For more information, see the Client-Side JavaScript Guide.


screenX

Specifies the x-coordinate of the left edge of a window.

Property of

window

Implemented in

JavaScript 1.2

Security

Setting the value of the screenX property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

See also

window.screenY


screenY

Specifies the y-coordinate of the top edge of a window.

Property of

window

Implemented in

JavaScript 1.2

Security

Setting the value of the screenY property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

See also

window.screenX


scroll

Scrolls a window to a specified coordinate.

Method of

window

Implemented in

JavaScript 1.1

JavaScript 1.2: deprecated

Description

In JavaScript 1.2, scroll is no longer used and has been replaced by scrollTo. scrollTo extends the capabilities of scroll. scroll remains for backward compatibility.


scrollbars

Represents the browser window's vertical and horizontal scroll bars for the document area.

Property of

window

Implemented in

JavaScript 1.2

Description

The value of the scrollbars property itself has one property, visible. If true, both scrollbars are visible; if false, they are hidden.

Security

Setting the value of the scrollbars' visible property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

Examples

The following example would make the referenced window "chromeless" (chromeless windows lack toolbars, scrollbars, status areas, and so on, much like a dialog box) by hiding most of the user interface toolbars:

self.menubar.visible=false;
self.toolbar.visible=false;
self.locationbar.visible=false;
self.personalbar.visible=false;
self.scrollbars.visible=false;
self.statusbar.visible=false;

scrollBy

Scrolls the viewing area of a window by the specified amount.

Method of

window

Implemented in

JavaScript 1.2

Syntax

scrollBy(horizontal, vertical)

Parameters

horizontal

The number of pixels by which to scroll the viewing area horizontally.

vertical

The number of pixels by which to scroll the viewing area vertically.

Description

This method scrolls the content in the window if portions that can't be seen exist outside of the window. scrollBy scrolls the window by adding or subtracting the specified number of pixels to the current scrolled location.

For this method to have an effect the visible property of window.scrollbars must be true.

Examples

To scroll the current window 5 pixels towards the left and 30 pixels down from the current position, use this statement:

self.scrollBy(-5,30); // relative positioning

See also

window.scrollTo


scrollTo

Scrolls the viewing area of the window so that the specified point becomes the top-left corner.

Method of

window

Implemented in

JavaScript 1.2

Syntax

scrollTo(x-coordinate, y-coordinate)

Parameters

x-coordinate

An integer representing the x-coordinate of the viewing area in pixels.

y-coordinate

An integer representing the y-coordinate of the viewing area in pixels.

Description

scrollTo replaces scroll. scroll remains for backward compatibility.

The scrollTo method scrolls the content in the window if portions that can't be seen exist outside of the window. For this method to have an effect the visible property of window.scrollbars must be true.

Examples

Example 1: Scroll the current viewing area. To scroll the current window to the leftmost boundary and 20 pixels down from the top of the window, use this statement:

self.scrollTo(0,20); // absolute positioning
Example 2: Scroll a different viewing area. The following code, which exists in one frame, scrolls the viewing area of a second frame. Two Text objects let the user specify the x and y coordinates. When the user clicks the Go button, the document in frame2 scrolls to the specified coordinates.

<SCRIPT>
function scrollIt(form) {
   var x = parseInt(form.x.value)
   var y = parseInt(form.y.value)
   parent.frame2.scrollTo(x, y)
}
</SCRIPT>
<BODY>
<FORM NAME="myForm">
<P><B>Specify the coordinates to scroll to:</B>
<BR>Horizontal:
<INPUT TYPE="text" NAME=x VALUE="0" SIZE=4>
<BR>Vertical:
<INPUT TYPE="text" NAME=y VALUE="0" SIZE=4>
<BR><INPUT TYPE="button" VALUE="Go"
   onClick="scrollIt(document.myForm)">
</FORM>

See also

window.scrollBy


self

The self property is a synonym for the current window.

Property of

window

Read-only

Implemented in

JavaScript 1.0

Description

The self property refers to the current window. That is, the value of this property is a synonym for the object itself.

Use the self property to disambiguate a window property from a form or form element of the same name. You can also use the self property to make your code more readable.

The value of the self property is

<object nameAttribute>
where nameAttribute is the NAME attribute if self refers to a frame, or an internal reference if self refers to a window.

Examples

In the following example, self.status is used to set the status property of the current window. This usage disambiguates the status property of the current window from a form or form element called status within the current window.

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

setHotKeys

Enables or disables hot keys in a window which does not have menus.

Method of

window

Implemented in

JavaScript 1.2

Syntax

setHotKeys(trueOrFalse)

Parameters

trueOrFalse

A Boolean value specifying whether hot keys are enabled:

Security

To enable or disable hot keys, you need the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

Description

By default, hot keys are disabled in a window which does not display a menu. With the setHotKeys method, you can explicitly enable or disable all hot keys except security and quit, which are always enabled.

You can also specify whether to enable hot keys at the time you create a window when you use the window.open method.

See also

window.open


setInterval

Evaluates an expression or calls a function every time a specified number of milliseconds elapses, until canceled by a call to clearInterval.

Method of

window

Implemented in

JavaScript 1.2

Syntax

setInterval(expression, msec)
setInterval(function, msec[, arg1[, ..., argN]])

Parameters

function

Any function.

expression

A string containing a JavaScript expression. The expression must be quoted; otherwise, setInterval calls it immediately. For example, setInterval("calcnum(3, 2)", 25).

msec

A numeric value or numeric string, in millisecond units.

arg1, ..., argn

The arguments, if any, passed to function.

Description

The timeouts continue to fire until the associated window or frame is destroyed or the interval is canceled using the clearInterval method.

setInterval does not stall the script. The script continues immediately (not waiting for the interval to elapse). The call simply schedules a future event.

Examples

The following code displays the current time in a Text object. In the startclock function, the call to the setInterval method causes the showtime function to be called every second to update the clock. Notice that the startclock function and setInterval method are each called only one time.

<SCRIPT LANGUAGE="JavaScript">
var timerID = null
var timerRunning = false

function stopclock(){
   if(timerRunning)
      clearInterval(timerID)
   timerRunning = false
}
function startclock(){
   // Make sure the clock is stopped
   stopclock()
   timerID = setInterval("showtime()",1000)
   timerRunning = true
}

function showtime(){
   var now = new Date()
   var hours = now.getHours()
   var minutes = now.getMinutes()
   var seconds = now.getSeconds()
   var timeValue = "" + ((hours > 12) ? hours - 12 : hours)
   timeValue += ((minutes < 10) ? ":0" : ":") + minutes
   timeValue += ((seconds < 10) ? ":0" : ":") + seconds
   timeValue += (hours >= 12) ? " P.M." : " A.M."
   document.clock.face.value = timeValue
}
</SCRIPT>

<BODY onLoad="startclock()">
<FORM NAME="clock" onSubmit="0">
   <INPUT TYPE="text" NAME="face" SIZE=12 VALUE ="">
</FORM>
</BODY>

See also

window.clearInterval, window.setTimeout


setResizable

Specifies whether a user is permitted to resize a window.

Method of

window

Implemented in

JavaScript 1.2

Syntax

setResizable(trueOrFalse)

Parameters

trueOrFalse

A Boolean value specifying whether a user can resize a window:

Description

By default, a new Navigator window is resizable. With the setResizable method, you can explicitly enable or disable the ability of a user to resize a window. Not all operating systems support this method.

You can also specify whether a window is resizable at the time you create it when you use the window.open method.

See also

window.open


setTimeout

Evaluates an expression or calls a function once after a specified number of milliseconds elapses.

Method of

window

Implemented in

JavaScript 1.0: evaluating an expression

JavaScript 1.2: calling a function

Syntax

setTimeout(expression, msec)
setTimeout(function, msec[, arg1[, ..., argN]])

Parameters

expression

A string containing a JavaScript expression. The expression must be quoted; otherwise, setTimeout calls it immediately. For example, setTimeout("calcnum(3, 2)", 25).

msec

A numeric value or numeric string, in millisecond units.

function

Any function.

arg1, ..., argN

The arguments, if any, passed to function.

Description

The setTimeout method evaluates an expression or calls a function after a specified amount of time. It does not act repeatedly. For example, if a setTimeout method specifies five seconds, the expression is evaluated or the function is called after five seconds, not every five seconds. For repetitive timeouts, use the setInterval method.

setTimeout does not stall the script. The script continues immediately (not waiting for the timeout to expire). The call simply schedules a future event.

Examples

Example 1. The following example displays an alert message five seconds (5,000 milliseconds) after the user clicks a button. If the user clicks the second button before the alert message is displayed, the timeout is canceled and the alert does not display.

<SCRIPT LANGUAGE="JavaScript">
function displayAlert() {
   alert("5 seconds have elapsed since the button was clicked.")
}
</SCRIPT>
<BODY>
<FORM>
Click the button on the left for a reminder in 5 seconds;
click the button on the right to cancel the reminder before
it is displayed.
<P>
<INPUT TYPE="button" VALUE="5-second reminder"
   NAME="remind_button"
   onClick="timerID=setTimeout('displayAlert()',5000)">
<INPUT TYPE="button" VALUE="Clear the 5-second reminder"
   NAME="remind_disable_button"
   onClick="clearTimeout(timerID)">
</FORM>
</BODY>
Example 2. The following example displays the current time in a Text object. The showtime function, which is called recursively, uses the setTimeout method to update the time every second.

<HEAD>
<SCRIPT LANGUAGE="JavaScript">
<!--
var timerID = null
var timerRunning = false
function stopclock(){
   if(timerRunning)
      clearTimeout(timerID)
   timerRunning = false
}
function startclock(){
   // Make sure the clock is stopped
   stopclock()
   showtime()
}
function showtime(){
   var now = new Date()
   var hours = now.getHours()
   var minutes = now.getMinutes()
   var seconds = now.getSeconds()
   var timeValue = "" + ((hours > 12) ? hours - 12 : hours)
   timeValue += ((minutes < 10) ? ":0" : ":") + minutes
   timeValue += ((seconds < 10) ? ":0" : ":") + seconds
   timeValue += (hours >= 12) ? " P.M." : " A.M."
   document.clock.face.value = timeValue
   timerID = setTimeout("showtime()",1000)
   timerRunning = true
}
//-->
</SCRIPT>
</HEAD>
<BODY onLoad="startclock()">
<FORM NAME="clock" onSubmit="0">
   <INPUT TYPE="text" NAME="face" SIZE=12 VALUE ="">
</FORM>
</BODY>

See also

window.clearTimeout, window.setInterval


setZOptions

Specifies the z-order stacking behavior of a window.

Method of

window

Implemented in

JavaScript 1.2

Syntax

setZOptions(windowPosition)

Parameters

windowPosition

A string evaluating to any of the following values:

Security

To set this property, you need the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

Description

By default, a Navigator window rises to the top of the z-order when it is activated and moves down in the z-order as other windows are activated. With the setZOptions method, you can explicitly specify a window's position in the z-order.

If you do not specify an argument for setZOptions, this method restores the default z-order stacking behavior of a Navigator window.

You can also specify the order stacking behavior of a window at the time you create it when you use the window.open method.

See also

window.open


status

Specifies a priority or transient message in the status bar at the bottom of the window, such as the message that appears when a mouseOver event occurs over an anchor.

Property of

window

Implemented in

JavaScript 1.0

Security

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

Description

Do not confuse the status property with the defaultStatus property. The defaultStatus property reflects the default message displayed in the status bar.

You can set the status property at any time. You must return true if you want to set the status property in the onMouseOver event handler.

Examples

Suppose you have created a JavaScript function called pickRandomURL that lets you select a URL at random. You can use the onClick event handler of an anchor to specify a value for the HREF attribute of the anchor dynamically, and the onMouseOver event handler to specify a custom message for the window in the status property:

<A HREF=""
   onClick="this.href=pickRandomURL()"
   onMouseOver="self.status='Pick a random URL'; return true">
Go!</A>
In the preceding example, the status property of the window is assigned to the window's self property, as self.status.

See also

window.defaultStatus


statusbar

Represents the browser window's status bar. This is the region containing the security indicator, browser status, and so on.

Property of

window

Implemented in

JavaScript 1.2

Description

The value of the statusbar property itself one property, visible. If true, the status bar is visible; if false, it is hidden.

Security

Setting the value of the status bar's visible property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

Examples

The following example would make the referenced window "chromeless" (chromeless windows lack toolbars, scrollbars, status areas, and so on, much like a dialog box) by hiding most of the user interface toolbars:

self.menubar.visible=false;
self.toolbar.visible=false;
self.locationbar.visible=false;
self.personalbar.visible=false;
self.scrollbars.visible=false;
self.statusbar.visible=false;

stop

Stops the current download.

Method of

window

Implemented in

JavaScript 1.2

Syntax

stop()

Parameters

None

Definition

This method performs the same action as a user choosing the Stop button in the browser.


toolbar

Represents the browser window's toolbar, containing the navigation buttons, such as Back, Forward, Reload, Home, and so on.

Property of

window

Implemented in

JavaScript 1.2

Description

The value of the toolbar property itself has one property, visible. If true, the toolbar is visible; if false, it is hidden.

Security

Setting the value of the toolbar's visible property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.

Examples

The following example would make the referenced window "chromeless" (chromeless windows lack toolbars, scrollbars, status areas, and so on, much like a dialog box) by hiding most of the user interface toolbars:

self.menubar.visible=false;
self.toolbar.visible=false;
self.locationbar.visible=false;
self.personalbar.visible=false;
self.scrollbars.visible=false;
self.statusbar.visible=false;

top

The top property is a synonym for the topmost browser window, which is a document window or web browser window.

Property of

window

Read-only

Implemented in

JavaScript 1.0

Description

The top property refers to the topmost window that contains frames or nested framesets. Use the top property to refer to this ancestor window.

The value of the top property is

<object objectReference>
where objectReference is an internal reference.

Examples

The statement top.close() closes the topmost ancestor window.

The statement top.length specifies the number of frames contained within the topmost ancestor window. When the topmost ancestor is defined as follows, top.length returns three:

<FRAMESET COLS="30%,40%,30%">
<FRAME SRC=child1.htm NAME="childFrame1">
<FRAME SRC=child2.htm NAME="childFrame2">
<FRAME SRC=child3.htm NAME="childFrame3">
</FRAMESET>
The following example sets the background color of a frame called myFrame to red. myFrame is a child of the topmost ancestor window.

top.myFrame.document.bgColor="red"

window

The window property is a synonym for the current window or frame.

Property of

window

Read-only

Implemented in

JavaScript 1.0

Description

The window property refers to the current window or frame. That is, the value of this property is a synonym for the object itself.

Although you can use the window property as a synonym for the current frame, your code may be more readable if you use the self property. For example, window.name and self.name both specify the name of the current frame, but self.name may be easier to understand (because a frame is not displayed as a separate window).

Use the window property to disambiguate a property of the window object from a form or form element of the same name. You can also use the window property to make your code more readable.

The value of the window property is

<object nameAttribute>
where nameAttribute is the NAME attribute if window refers to a frame, or an internal reference if window refers to a window.

Examples

In the following example, window.status is used to set the status property of the current window. This usage disambiguates the status property of the current window from a form called "status" within the current window.

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

See also

window.self


Table of Contents | Previous | Next | Index

Last Updated: 05/28/99 12:00:46

Copyright (c) 1999 Netscape Communications Corporation