[Chapter 21] Reference: Window
Author: David Flanagan
Date: Fri Aug 29 11:20:56 1997

#

| Chapter 21 JavaScript Reference |

# Window Object

## Name

Window Object---a web browser window or frame

## Availability

Navigator 2.0, Internet Explorer 3.0; enhanced in Navigator 3.0

## Synopsis

    self    the current window
    window  the current window

## Properties

`closed`

  A read-only Boolean that specifies whether a window has been closed. Available in Navigator 3.0 and later.

`defaultStatus`

  A read/write string that specifies the default message to appear in the status line.

`document`

  A reference to the Document object contained in the window.

`frames[]`

  An array of frames contained by this window.

`history`

  A reference to the History object for this window.

`java`

  A reference to the JavaPackage object that is the top of the package name hierarchy for the core java.* packages that comprise the Java language.

`length`

  The number of elements in the `frames[]` array. Same as `frames.length`. Read-only.

`location`

  A reference to the Location object for this window.

`Math`

  A reference to an object holding various mathematical functions and constants.

`name`

  A string that contains the name of the window. The name is optionally specified when the window is created with the `open()` method. In Navigator 2.0 and Internet Explorer 3.0, this property is read-only. In Navigator 3.0 and later it is read/write.

`navigator`

  A reference to the Navigator object that applies to this and all other windows.

`netscape`

  A reference to the JavaPackage object which is the top of the Java package name hierarchy for the netscape.* Java packages from Netscape.

`opener`

  A read/write property that refers to the Window object that called `open()` to create this window. Available in Navigator 3.0 and later.

`Packages`

  A reference to a JavaPackage object that represents the top of the Java package name hierarchy.

`parent`

  A reference to the parent window or frame of the current window. Only useful when the current window is a frame rather than a top-level window.

`self`

  A reference to the window itself. A synonym of `window`.

`status`

  A read/write string that specifies the current contents of the status line.

`sun`

  A reference to the JavaPackage object which is the top of the Java package name hierarchy for the sun.* Java packages from Sun Microsystems.

`top`

  A reference to the top-level window that contains the current window. Only useful when the current window is a frame rather than a top-level window.

`window`

  A reference to the window itself. A synonym of `self`.

## Methods

`alert()`

  Display a simple message in a dialog box.

`blur()`

  Take keyboard focus from the top-level browser window; this sends the window to the background on most platforms.

`clearTimeout()`

  Cancel a pending timeout operation.

`close()`

  Close a window.

`confirm()`

  Ask a yes-or-no question with a dialog box.

`focus()`

  Give the top-level browser window keyboard focus; this brings the window to the front on most platforms.

`open()`

  Create and open a new window.

`prompt()`

  Ask for simple string input with a dialog box.

`scroll()`

  Scroll the document displayed in the window.

`setTimeout()`

  Execute code after a specified amount of time elapses.

## Event Handlers

`onblur()`

  An event handler invoked when the window loses focus.

`onerror()`

  An event handler invoked when a JavaScript error occurs.

`onfocus()`

  An event handler invoked when the window gains focus.

`onLoad()`

  An event handler invoked when the document (or frameset) is fully loaded.

`onUnload()`

  An event handler invoked when the browser leaves the current document or frameset.

## Description

The Window object represents a browser window or frame. It is documented in detail in Chapter 11, Windows and the JavaScript Name Space.

In client-side JavaScript, all expressions are evaluated in the context of the current Window object. This means that no special syntax is required to refer to the current window, and you can use the properties of that window object as if they were variables. For example, you can write `document` rather than `window``.document`. Similarly, you can use the methods of the current window object as if they were functions: `alert()` instead of `window``.alert()`.

The Window object does have `window` and `self` properties that refer to the window object itself. You can use these when you want to make the current window reference explicit rather than implicit. In addition to these two properties, the `parent`, and `top` properties and the `frames[]` array refer to other Window objects related to the current one.

To refer to a frame within a window, use:

    frames[i] or self.frames[i] // frames of current window
    window.frames[i] // frames of specified window

To refer to the parent window (or frame) of a frame, use:

    parent or self.parent // parent of current window
    window.parent // parent of specified window

To refer to the top-level browser window from any frame contained within it, use:

    top or self.top // top window of current frame
    window.top // top window of specified frame

New top-level browser windows are created with the `Window.open()` method. When you call this method, save the return value of the `open()` call in a variable, and use that variable to reference the new window. In Navigator 3.0, the `opener` property of the new window is a reference back to the window that opened it.

In general, the methods of the Window object manipulate the browser window or frame in some way. The `alert()`, `confirm()` and `prompt()` methods are notable: they interact with the user through simple dialog boxes.

Since JavaScript code is evaluated in the context of the Window object in which it is running, the Window object must contain references (or references to references) to all the other JavaScript objects of interest. That is, it is the root of a JavaScript "object hierarchy." Many of the properties of the Window object are references to other important JavaScript objects. Most of these properties refer to an object particular to the window. The `location` property of a Window, for example, refers to the Location object of the window.

A number of Window properties, however, refer instead to "global" objects. The `navigator` property is one of these: it contains a reference to the Navigator object, which contains version information about the browser. Every Window object contains a `navigator` property which is a reference to this same Navigator object. Because all JavaScript expressions are evaluated in the context of a Window object, there is no way to define global variables such as `navigator` except by making them properties of every Window object. Other "global" properties of this sort are `Math`, `Packages`, `java`, `sun`, and `netscape`.

See Chapter 11, Windows and the JavaScript Name Space for an in-depth overview of the Window object, and see the individual reference pages for complete details on all the Window properties, methods, and event handlers.

## See Also

"Document", Chapter 11, Windows and the JavaScript Name Space

window |  | Window.alert()