The window object represents the browser window or frame in which document content is displayed. The window object plays a vital role in scripting when scripts must communicate with document objects located in other frames or subwindows. Managing multiple windows can be tricky business because of the transient nature of cross-window references. Strict interpretation of HTML and XHTML standards frowns upon multiple windows, and many confused users may agree.

These properties are associated with the proprietary Mozilla xpconnect ("cross-platform" connect) services. These services allow scripts that have the correct security clearance to work with XPCOM (decidedly not MS COM) objects to extend the functionality of the application that uses the Mozilla engine (such as the Netscape 6 browser). Access to these services requires enabling security privileges (typically via signed scripts), as follows:

netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
// your xpconnect access code here
netscape.security.PrivilegeManager.revertPrivilege("UniversalXPConnect");

Returns the navigator object. The navigator object is named after a specific browser brand; the clientInformation property is a nondenominational way of accessing important environment variables that have historically been available through properties and methods of the navigator object (discussed separately earlier in this chapter as its own object). In Internet Explorer, you can substitute window.clientInformation for any reference that begins with navigator.

Returns the clipboardData object, discussed separately earlier in this chapter as its own object. The object (accessible as a property of a window or frame object) is a temporary container that scripts in IE 5 and later for Windows can use to transfer text data, particularly during script-controlled operations that simulate cutting, copying, and pasting, or that control dragging.

This is the Boolean value that says whether the referenced window is closed. A value of true means the window is no longer available for referencing its objects or script components. This is used most often to check whether a user has closed a subwindow generated by the window.open( ) method.

See appCore.

Return references to objects associated with Mozilla public-key cryptography internals. For more details on this subject, visit http://www.mozilla.org/projects/security/.

Specifies the default message displayed in the browser window's status bar when no browser loading activity is occurring. To temporarily change the message (during mouse rollovers, for example), set the window's status property. Most scriptable browsers and versions have difficulty managing the setting of the defaultStatus property. Expect odd behavior.

This is the string or other data type passed as extra arguments to a modal dialog window created with the window.showModalDialog( ) or (in IE 5 and later for Windows only) window.showModelessDialog( ) methods. This property is best accessed by a script in the document displayed in the dialog window in order to retrieve whatever data is passed to the new window as arguments. It is up to your script to parse the data if you include more than one argument nugget separated by whatever argument delimiter you choose.

Specify the height and width values of a modal dialog window created with the showModalDialog( ) and showModelessDialog( ) methods. Although Internet Explorer does not balk at modifying these properties (in a script running in the modal dialog window), the changed values are generally not reflected in a resized dialog window. Initial values are set as parameters to the dialog-opening methods.

Indicate the offset distance of the left and top edges of a modal dialog window (created with the showModalDialog( ) and showModelessDialog( ) methods) relative to the top-left corner of the video screen. Although Internet Explorer does not balk at modifying these properties (in a script running in the modal dialog window), the changed values are generally not reflected in a repositioned dialog window. Initial values are set as parameters to the dialog methods.

Return references to the Navigator browser window feature (the directories property is new for Netscape 6). See the discussion of the directories (et al.) objects earlier in this chapter for how to control the visibility of these window features with signed scripts.

Returns a reference to the document object contained by the window. In browsers that offer W3C DOM document tree support, this property points more specifically to the root HTMLDocument node for the document tree loaded in the window. The W3C DOM even describes this property as a member of one of its View objects (analogous to a browser window). This is the property that lets scripts references to document methods and content begin with the word document.

Internet Explorer's event model generates an event object for each user or system event. This event object is a property of the window object. For details about the IE event object, see Chapter 6 and the listing of the event object in this chapter.

Returns a reference to the external object, which provides access to lower-level functionality of the browser engine (security permissions willing). See the discussion of the external object earlier in this chapter.

If the current window is a member of a frameset or is an iframe, the frameElement property returns a reference to the frame or iframe element object (distinct from the frame-as-window object). Security restrictions, however, can impede script access to this property.

Returns a collection (array) of window objects that are implemented as frames or iframes in the current window. For a frameset's parent or top window, the array contains references to first-generation frame windows. Index values can be zero-based integers (in source code order) or the identifier assigned to the name attribute of the frame element.

Contains the history object for the current window or frame. For details, see the discussion of the history object.

Specify the pixel measure of the height and width of the content region of a browser window or frame. This area is where the document content appears, exclusive of all window "chrome." For comparable values in IE, see the body element object.

Specifies the number of frames (if any) nested within the current window. This value is the same as that returned by window.frames.length. When no frames are defined for the window, the value is zero.

Returns a location object containing URL details of the document currently loaded in the window or frame. To navigate to another page, you assign a URL to the location.href property (or see the navigate( ) method for an IE-only alternative). See the location object.

See directories.

See directories.

This is the identifier associated with a frame or subwindow for use as the value assigned to target attributes or as script references to the frame/subwindow. For a frame, the value is usually assigned via the name attribute of the frame tag, but it can be modified by a script if necessary. The name of a subwindow is assigned as a parameter to the window.open( ) method. The primary browser window does not have a name by default, but you can assign one via script if you need a subwindow to target a link or form back to the main window.

Returns a reference to the navigator object. Since the window reference is optional, syntax without the window reference works on all scriptable versions of Internet Explorer and Navigator. See the navigator object.

Indicates whether the browser should use offscreen buffering to improve path animation performance. Although the property is implemented in IE 5 for Macintosh, it is unclear that it offers any functionality. Recent versions of IE for Windows connect this property to the DirectX ActiveX control. When the document loads, the property is set to auto. After that, a script may turn buffering on and off by assigning a Boolean value to this property.

This is an object reference to the window (or frame) that used a window.open( ) method to generate the current window. This property allows subwindows to assemble references to objects, variables, and functions in the originating window. To access document objects in the creating window, a reference can begin with opener and work its way through the regular document object hierarchy from there, as shown in the left side of the following example statement. The relationship between the opening window and the opened window is not strictly parent-child. The term "parent" has other connotations in scripted window and frame references. IE's dialog windows (the showModalDialog( ) and showModelessDialog( ) windows) do not support this property. Values between the main and dialog windows must be passed at creation time and via the dialog window's returnValue property upon closing.

Specify the pixel measure of the height and width of the browser window or frame, including (for the top window) all tool bars, scoll bars, and other visible window "chrome." IE offers no equivalent properties.

Specify the pixel measure of the amount of the page's content that has been scrolled upward and/or to the left. For example, if a document has been scrolled so that the topmost 100 pixels of the document (the "page") are not visible because the window is scrolled, the pageYOffset value for the window is 100. When a document is not scrolled, both values are zero.

Returns a reference to the parent window object whose document defined the frameset in which the current frame is specified. Use parent in building a reference from one child frame to variables or methods in the parent document or to variables, methods, and objects in another child frame. For example, if a script in one child frame must reference the content of a text input form element in the other child frame (named "content"), the reference would be:

parent.content.document.forms[0].entryField.value

See directories.

See crypto.

See appCore.

A value to be returned to the main window when an IE dialog window (generated by showModalDialog( ) method only) closes. The value assigned to this property in a script running in the dialog window becomes the value returned by the showModalDialog( ) method in the main window. For example, the document in the modal dialog window may have a statement that sets the returnValue property with information from the dialog:

window.returnValue = window.document.forms[0].userName.value;

Returns a reference to the screen object. Since the window reference is optional, syntax without the window reference works on all scriptable versions of Internet Explorer and Navigator.

Return pixel coordinates of the top-left corner of the browser content area relative to the top-left corner of the screen. A maximized browser window returns a screenLeft value of 0, but the screenTop value varies with the complement of toolbars the user chooses to display. Use window.moveTo( ) to change the window position.

Return pixel coordinates of the top-left corner of the entire browser window (including "chrome") relative to the top-left corner of the screen. A browser window maximized under Windows returns screenX and screenY values of -4 because the chrome extends slightly beyond the screen display. You can adjust the window location through these properties or the window.moveTo( ) method.

Return the pixel distance the window is scrolled along the horizontal (scrollX) and vertical (scrollY) axes. To determine these values in IE, you must take into account compatibility mode settings in IE 6 (see the DOCTYPE element in Chapter 8). In backward compatibility mode and in IE for Macintosh, use the document.body.scrollLeft and document.body.scrollTop properties. In IE 6 standards compatibility mode (where document.compatMode == "CSS1Compat"), use document.body.parentNode.scrollLeft and document.body.parentNode.scrollTop to get the scroll values of the html element.

See directories.

This is a reference to the current window or frame. This property is synonymous with window, but is sometimes used to improve clarity in a complex script that refers to many windows or frames. Never use the reference window.self to refer to the current window or frame because some browser versions get confused with the reference.

See appCore.

Specifies the text of the status bar of the browser window. Setting the status bar to some message is recommended only for temporary messages, such as for mouse rollovers atop images, areas, or links. Double or single quotes in the message must be escaped (\'). Many users don't notice incidental text in the status bar, so avoid putting mission-critical information there. Temporary messages conflict with browser-driven use of the status bar for loading progress and other purposes. To set the default status bar message (when all is at rest), see the defaultStatus property.

See directories.

See directories.

This is an object reference to the browser window. Script statements from inside nested frames can refer to the browser window properties and methods or to variables or functions stored in the document loaded in the topmost position. Do not begin a reference with window.top, just top. To replace a frameset with a new document that occupies the entire browser window, assign a URL to the top.location.href property.

This is an object reference to the browser window.

Although the window object as we know it is not officially part of the W3C DOM, Netscape 6 implements this W3C DOM event model method for the window object. See the addEventListener( ) method discussion among the shared methods described earlier in this chapter.

Displays an alert dialog box with a message of your choice. Script execution halts while the dialog box appears. A single button lets the user close the dialog. The title bar of the window (and the "JavaScript Alert" legend in earlier browser versions) cannot be altered by script.

This IE event model method, shared among all element objects, is also a member of the window object. See the attachEvent( ) method discussion among the shared methods described earlier in this chapter.

Navigates one step backward through the history list of the window or frame. You may prefer the cross-browser history.back( ) method.

Removes focus from the window and fires an onBlur event (in IE). No other element necessarily receives focus as a result, but if another IE window is open at the time, the current window moves to the rear of the stack.

Instructs the browser to grab events of a specific type before they reach their intended target objects. The object invoking this method must then have event handlers defined for the given event types to process the event. Although this method is part of the Navigator 4 event model, it continues to be supported in Netscape 6, creating the equivalent of a W3C DOM capture-mode event listener for the document object. Continue to use this method if you must support Navigator 4, but migrate new code to the W3C DOM event listener syntax as described in Chapter 6.

Turns off the interval looping action referenced by the intervalID parameter. See setInterval( ) for how to initiate such a loop.

Turns off the timeout delay counter referenced by the timeoutID parameter. See setTimeout( ) for how to initiate such a delay.

Closes the current window. A script in a subwindow cannot close the main window without receiving the user's explicit permission from a security dialog box. A window can close itself (i.e., from a script running in the same window) or a window it generated via the window.open( ) method.

Displays a dialog box with a message and two clickable buttons. Script execution halts while the dialog box appears. One button indicates a Cancel operation; the other button indicates the user's approval (OK or Yes). The text of the buttons is not scriptable. The message should ask a question to which either button would be a logical reply. A click of the Cancel button returns a value of false; a click of the OK button returns a value of true.

Opens a blank popup rectangular space that can be populated with HTML content, yet the space can extend across frame boundaries and even window borders. Scripts must assign content (not an external URL) to the popup object returned by the method. See the popup object for more details and an example of usage.

This IE event model method, shared among all element objects, is also a member of the window object. See the detachEvent( ) method discussion among the shared methods described earlier in this chapter.

With signed scripts and the user's permission, a script can capture events in other windows or frames that come from domains other than the one that served the document with event-capturing scripts. Navigator 4 only.

Although the window object is not officially part of the W3C DOM, Netscape 6 implements this W3C DOM event model method for the window object. See the dispatchEvent( ) method discussion among the shared methods described earlier in this chapter.

Evaluates one or more script expressions in any scripting language embedded in the browser. Expressions must be contained within a single string; multiple expressions are delimited with semicolons:

window.execScript("var x = 3; alert(x * 3)")

Searches the document body text for a string and selects the first matching string. Optionally, you can specify whether the search should be case-sensitive or should search upward in the document. With the found text selected in Navigator 4, you can then use the document.getSelection( ) method to grab a copy of the found text. You don't, however, have nearly the dynamic content abilities afforded by Internet Explorer 4's TextRange object (for Win32). This method is disconnected in Netscape 6 (it always returns false), but is reconnected in Netscape 7.

Brings the window to the front of all regular browser windows and fires the onFocus event (in IE). If another window had focus at the time, that other window receives an onBlur event.

Navigates one step forward through the history list of the window or frame. If the forward history has no entries, no action takes place.

Mistakenly exposed to scripters, this method calls upon the operating system's way of alerting a user that the application needs attention. In Windows, the Taskbar box for the browser window flashes; in the Mac OS, a beep sounds, and a bullet appears next to the application in the Application menu. If the browser window is already at the front, no user signal appears. Removed for Netscape 7.

Returns a style object (specifically, a CSSStyleDeclaration object in the W3C DOM terminology) showing the net cascade of style settings that affect the element passed as the first parameter. To retrieve a particular style attribute value (including a value inherited from the default browser style sheet), use the getPropertyValue( ) method of the style object returned from this method:

var compStyle = getComputedStyle(document.getElementById("myP"), "");
var pBGColor = compStyle.getPropertyValue("background-color");

Returns a selection object, which can then be turned into a W3C DOM Range object. This method takes the place of the old document.getSelection( ) method, which is deprecated in Netscape 6. The corresponding IE operation is the document.selection property. See the selection object for details on working with a selection.

Navigates to the URL designated as the home page for the browser. This is the same as the user clicking on the Home button.

This is a convenience method that shifts the location of the window by specified pixel amounts along both axes. To shift along only one axis, set the other value to zero. Positive values for deltaX shift the window to the right; negative values to the left. Positive values for deltaY shift the window downward; negative values upward.

This is a convenience method that shifts the location of the current window to a specific coordinate point. The moveTo( ) method uses the screen coordinate system.

Loads a new document into the window or frame. This is the IE-specific way of assigning a value to the window.location.href property.

Opens a new window (without closing the original one). You can specify a URL to load into the new window or set that parameter to an empty string to allow scripts to document.write( ) into that new window. The windowName parameter lets you assign a name that can be used by target attributes of link and form elements. This name is not to be used in script references as frame names are. Instead, a script reference to a subwindow must be to the window object returned by the window.open( ) method. Therefore, if your scripts must communicate with a window opened in this manner, it is best to save the returned value as a global variable so that future statements can use it.

Starts the printing process for the window or frame. A user must still confirm the print dialog box to send the document to the printer. This method is the same as clicking the browser's Print button or selecting Print from the File menu.

Displays a dialog box with a message, a one-line text entry field, and two clickable buttons. Script execution halts while the dialog box appears. The message should urge the user to enter a specific kind of answer. One button indicates a Cancel operation; the other button indicates the user's approval of the text entered into the field (OK or Yes). The text of the buttons is not scriptable. A click of the Cancel button returns a value of null; a click of the OK button returns a string of whatever is in the text entry field at the time (including the possibility of an empty string). It is up to your scripts to test for the type of response (if any) supplied by the user.

The opposite of window.captureEvents( ), this method turns off event capture at the window level for one or more specific events named in the parameter list. Although this method is part of the Navigator 4 event model, it continues to be supported in Netscape 6, creating the equivalent of a W3C DOM capture-mode event listener for the document object. Continue to use this method if you must support Navigator 4, but migrate new code to the W3C DOM event listener syntax as described in Chapter 6.

Although the window object as we know it is not officially part of the W3C DOM, Netscape 6 implements this W3C DOM event model method for the window object. See the removeEventListener( ) method discussion among the shared methods described earlier in this chapter.

This is a convenience method that shifts the width and height of the window by specified pixel amounts. To adjust along only one axis, set the other value to zero. Positive values for deltaX make the window wider; negative values make the window narrower. Positive values for deltaY make the window taller; negative values make the window shorter. The top and left edges remain fixed; only the right and bottom edges are moved.

This is a convenience method that adjusts the height and width of the window to specific pixel sizes. The top and left edges of the window remain fixed, while the bottom and right edges move in response to this method.

Used inside an event handler function, this method directs Navigator 4 (only) to let the event pass to its intended target object.

Sets the scrolled position of the document inside the current window or frame. To return the document to its unscrolled position, set both parameters to zero.

Scrolls the document in the window by specified pixel amounts along both axes. To adjust along only one axis, set the other value to zero. Positive values for deltaX scroll the document to the left (so the user sees content to the right in the document); negative values scroll the document to the right. Positive values for deltaY scroll the document upward (so the user sees content lower in the document); negative values scroll the document downward. Scrolling does not continue past the zero coordinate points (except in Navigator 4 for the Macintosh).

Scroll the document in the window downward (positive value) or upward (negative value) by the increment of lines or pages. The methods perform the same actions as the user clicking on the arrow and "page" regions of the vertical scrollbar, respectively.

Scrolls the document in the window to a specific scrolled pixel position.

Changes the cursor to a desired type. This method is an alternate to the style sheet cursor attribute. Starting with Netscape 6.2, a cursor changed with this method maintains its shape until explicitly changed to another shape or the default auto style. Precise cursor shape is determined by the operating system repertoire. Removed from Netscape 7.

Starts a timer that continually invokes the expression every msecs. Other scripts can run in the time between calls to expression. This method is useful for starting animation sequences that must reposition an element along a path at a fixed rate of speed. A repetitive call to an animation function would look like the following:

intervalID = setInterval("advanceAnimation( )", 500);

Starts a one-time timer that invokes the scriptExpression or functionReference after a delay of msecs. Other scripts can run while the browser waits to invoke the expression. A statement that sets the timer would look like the following:

timeoutID = setTimeout("finishWindow( )", 50);

Displays a WinHelp window with the .hlp document specified with the URL parameter.

Displays a special window that remains atop all browser windows until the user explicitly closes the dialog window. This kind of window is different from the browser windows generated with the window.open( ) method. A modal dialog has no scriptable relationship with its opening window once the dialog window is opened. All values necessary for displaying content must be in the HTML document that loads into the window or be passed as parameters. The modal dialog may then have a script set its returnValue property, which becomes the value returned to the original script statement that opened the modal dialog box as the returned value of the showModalDialog( ) method.

Displays a special window that remains atop all browser windows, yet allows the user to interact with other open windows and their content. Other than browser versions that support it, this method has the same parameters and characteristics as the showModalDialog( ) method. See that method for details.

Lets the browser determine the optimum window size to display the window's content. Suitable for subwindows that display a limited amount of information.

Halts the download of external data of any kind. This method is the same as clicking the browser's Stop button.

Instructs the object to accept and process the event whose specifications are passed as the parameter to the method. The object must have an event handler for the event type to process the event. Navigator 4 only.