Availability

JavaScript 1.0; enhanced in JavaScript 1.1 and 1.2

Synopsis

self window window.frames[i]

Properties

The Window object defines the following properties. Nonportable, browser-specific properties are listed separately after this list.

closed

A read-only boolean value that specifies whether the window has been closed. When a browser window closes, the Window object that represents it does not simply disappear. The Window object continues to exist, but its closed property is set to true.

defaultStatus

A read/write string that specifies the default message that appears in the status line. See the Window.defaultStatus reference page.

document

A read-only reference to the Document object that describes the document contained in this window or frame. See the Document object for details.

frames[]

An array of Window objects, one for each frame contained within the this window. The frames.length property contains the number of elements in the frames[] array. Note that frames referenced by the frames[] array may themselves contain frames and may have a frames[] array of their own.

history

A read-only reference to the History object of this window or frame. See the History object for details.

length

The number of frames contained in this window or frame. length also specifies the number of elements in the frames[] array.

location

The Location object for this window or frame. This object specifies the URL of the currently loaded document. Setting this property to a new URL string causes the browser to load and display the contents of that URL. See the Location object for further details.

Math

A reference to an object holding various mathematical functions and constants. See the Math object for details.

name

A string that contains the name of the window. The name is optionally specified when the window is created with the open( ) method. Read-only in JavaScript 1.0; read/write in JavaScript 1.1. See the Window.name reference page.

navigator

A read-only reference to the Navigator object, which provides version and configuration information about the web browser. See the Navigator object for details.

opener [ JavaScript 1.1]

A read/write reference to the Window object that contained the script that called open( ) to open this top-level browser window. This property is valid only for Window objects that represent top-level windows, not those that represent frames. The opener property is useful so that a newly created window can refer to variables and functions defined in the window that created it.

parent

A read-only reference to the Window object that contains this window or frame. If this window is a top-level window, parent refers to the window itself. If this window is a frame, the parent property refers to the window or frame that contains it.

screen [ JavaScript 1.2]

The Screen object that is shared by all windows in a browser. This Screen object contains properties that specify information about the screen: the number of available pixels and the number of available colors. See the Screen object for details.

self

A read-only reference to this window itself. This is a synonym for the window property.

status

A read/write string that specifies the current contents of the browser's status line. See the Window.status reference page for details.

top

A read-only reference to the top-level window that contains this window. If this window is a top-level window itself, the top property simply contains a reference to the window itself. If this window is a frame, the top property refers to the top-level window that contains the frame. Contrast with the parent property.

window

The window property is identical to the self property; it contains a reference to this window.

Netscape Properties

innerHeight, innerWidth [Netscape 4]

Read/write properties that specify the height and width, in pixels, of the document display area of this window. These dimensions do not include the height of the menu bar, toolbars, scrollbars, and so on. As a security restriction, you are not allowed to set either of these properties to less than 100 pixels.

java [Netscape 3]

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. See the JavaPackage reference page.

locationbar.visible [Netscape 4]

A read-only boolean that specifies whether the window displays a location bar. See window features in the Window.open( ) reference page.

menubar.visible [Netscape 4]

A read-only boolean that specifies whether the window displays a menu bar. See window features in the Window.open( ) reference page.

netscape [Netscape 3]

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

outerHeight, outerWidth [Netscape 4]

Read/write integers that specify the total height and width, in pixels, of the window. These dimensions include the height and width of the menu bar, toolbars, scrollbars, window borders, and so on.

Packages [Netscape 3]

A reference to a JavaPackage object that represents the top of the Java package name hierarchy. For example, use Packages.java.lang to refer to the java.lang package. See the JavaPackage reference page.

pageXOffset, pageYOffset [Netscape 4]

Read-only integers that specify the number of pixels that the current document has been scrolled to the right (pageXOffset) and down (pageYOffset).

personalbar.visible [Netscape 4]

A read-only boolean that specifies whether this window displays a "personal bar" of bookmarks. See window features in the Window.open( ) reference page.

screenX, screenY [Netscape 4]

Read-only integers that specify the X- and Y-coordinates of the upper-left corner of the window on the screen. If this window is a frame, these properties specify the X- and Y-coordinates of the top-level window that contains the frame.

scrollbars.visible [Netscape 4]

A read-only boolean that specifies whether the scroll bars are visible in this window, or would be visible if the document was long enough or wide enough to require them. What this property really specifies is whether scrolling is enabled in this window. See window features in the Window.open( ) reference page.

statusbar.visible [Netscape 4]

A read-only boolean that specifies whether this window has a status line. See window features in the Window.open( ) reference page.

sun [Netscape 3]

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

toolbar.visible [Netscape 4]

A read-only boolean that specifies whether this window displays a toolbar. See window features in the Window.open( ) reference page.

Internet Explorer Properties

clientInformation [IE 4]

An IE-specific synonym for the navigator property. Both refer to a Navigator object. Despite the fact that clientInformation has a better name and is less Netscape-specific than navigator, it is not supported by Netscape and is therefore not portable.

event [IE 4]

An Event object that contains the details of the most recent event to occur within window. In the Netscape 4 event model and the DOM standard event model, an Event object describing the event is passed as an argument to every event handler. In the IE event model, however, no Event object is passed, and event handlers must obtain information about the event from the event property of the Window object.

Methods

The Window object has the following portable methods. Nonportable, browser-specific methods are listed separately after this list.

alert( )

Displays a simple message in a dialog box.

blur( )

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

clearInterval( )

Cancels periodic execution of code.

clearTimeout( )

Cancels a pending timeout operation.

close( )

Closes a window.

confirm( )

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

focus( )

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

moveBy( )

Moves the window by a relative amount.

moveTo( )

Moves the window to an absolute position.

open( )

Creates and opens a new window.

print( )

Simulates a click on the browser's Print button. IE 5 and Netscape 4 only.

prompt( )

Asks for simple string input with a dialog box.

resizeBy( )

Resizes the window by a specified amount.

resizeTo( )

Resizes the window to a specified size.

scroll( )

Scrolls the document displayed in the window.

scrollBy

Scrolls the window by a specified amount.

scrollTo( )

Scrolls the window to a specified position.

setInterval( )

Executes code at periodic intervals.

setTimeout( )

Executes code after a specified amount of time elapses.

Netscape Methods

back( )

Behaves as if the user clicked the Back button.

captureEvents( )

Specifies event types to be routed directly to the window.

forward( )

Simulates a click on the browser's Forward button.

handleEvent( )

Invokes the appropriate event handler for a given Event object.

home( )

Displays the browser's home page.

releaseEvents( )

Specifies types of events that will no longer be captured.

routeEvent( )

Passes an Event to the appropriate handler of the next interested object.

stop( )

Simulates a click on the browser's Stop button.

Internet Explorer Methods

navigate( )

Loads and displays the specified URL.

Event Handlers

onblur

Invoked when the window loses focus.

onerror

Invoked when a JavaScript error occurs.

onfocus

Invoked when the window gains focus.

onload

Invoked when the document (or frameset) is fully loaded.

onmove

Invoked when the window is moved. Netscape 4 only.

onresize

Invoked when the window is resized.

onunload

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 13. In client-side JavaScript, the Window serves as the "global object," and 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 global 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: e.g., 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 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 JavaScript 1.1, the opener property of the new window is a reference 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.

See Chapter 13 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 13; AbstractView in the DOM reference section