reptile7's JavaScript blog
Saturday, August 06, 2005
Properties VII: The Window Object
Blog Entry #18

JavaScript window object pages:
(1) DevGuru
(2) JavaScript Kit
(3) IRT

In at least one respect, I can see why Joe Burns skipped over the window object in his treatment of JavaScript properties in HTML Goodies' JavaScript Primers #7; many window object properties are supported by Netscape but, frustratingly, not by MSIE. Nonetheless, we at reptile7's JavaScript blog are ready to put these properties under the microscope. (Indeed, as Dan Quayle might say, we are ready for any foreseen or unforeseen property that may or may not occur in JavaScript. ;-)) In this entry, we will briefly address the following window properties-related issues:
• referencing the window object
• the constituent parts of a window
• dimensions of a window
• positioning of a window and of the document therein
• status of a window
• child objects of the window object

Referencing a Window: window vs. self vs. parent vs. top

There are five properties of the window object that relate, if overlappingly, to referencing a window:

opener, parent, self, top, window

No, that's not a mistake - there really is a window property of the window object. As a property, window specifically refers to the browser window or to the frame of the browser window that is currently active, as does the synonymous self property. To the best of my knowledge, window and self refer to the same window or frame under all circumstances, and to use one or the other is purely a stylistic choice. But what about the parent and top properties? Let's look at an example that distinguishes between window/self, parent, and top (and thus shows why there's a need for a window property for the window object).

Consider a frameset page, fram1.html, comprising a left frame and a right frame, fram2.html and fram3.html, respectively:

<frameset cols="70%,30%">
<frame src="fram2.html">
<frame src="fram3.html">

In this situation, the fram1.html window is the parent of the fram2.html and fram3.html windows. If we put in fram3.html the following script:

<script type="text/javascript">
window.document.bgColor = "yellow";
parent.document.title = "I'm the parent.";

then we will color the right frame yellow and set a new title for the frameset page, which is the page we actually see (the title, if any, of the isolated fram3.html page is unaffected).

The window.document.bgColor = "yellow" command can alternately be written as:
window.window.document.bgColor = "yellow"; or
window.self.document.bgColor = "yellow"; or
self.document.bgColor = "yellow"; or, more sanely, just
document.bgColor = "yellow";
In most cases, it is not necessary to reference window either as an object or as a property.

Besides being a parent window, the fram1.html window is also a top window, defined as the topmost browser window. It follows that the parent.document.title = "I'm the parent." command can alternately be written as:
window.parent.document.title = "I'm the parent."; or = "I'm the parent."; or
top.document.title = "I'm the parent.";

But let's suppose that fram2.html is itself a frameset page that comprises a upper frame and a lower frame, fram4.html and fram5.html, respectively. The fram2.html window is now the parent of the fram4.html and fram5.html windows; the fram1.html window is still the top window and is still the parent of the fram2.html and fram3.html windows. Got all that? A locally hosted, iframe-containing version of this structure appears below:

Outside of a frames situation, window, self, parent, and top all refer to the currently active window and can be used interchangeably.

Lastly, the opener property refers to a window that has opened one or more windows; we'll return to this property when we discuss the opening of new windows with JavaScript in Primer #11. We'll also see in this primer that the window name property is used to target the 'output' of a window to another window. Unlike the objects that we've been talking about in the last few entries, however, a window object is not referenced by its name.

The Parts of a Window

There are eight properties of the window object that represent constituent parts of the browser window:

document, locationbar, menubar, personalbar, scrollbars, sidebar, statusbar, toolbar

Except for document, all of these properties are supported by Netscape but not by MSIE. Except for sidebar, the window.–bar expression for the various bars of the window returns [object BarProp] (when using Netscape, and undefined when using MSIE).

All of these window parts are themselves JavaScript objects. We have already discussed the document object and many of its properties in Blog Entry #13. Except for sidebar, the window bars, as objects, have a single boolean property, visible, whose default value is true but which can be set to false so as to hide/collapse the bar(s) in question. Back in the day when Netscape Communicator 4.x was Netscape's state-of-the-art browser, Netscape required a scriptwriter to obtain a UniversalBrowserWrite privilege via a signed script in order to write the visible property, but this has evidently been phased out, as I am able to set the value of window.–bar.visible for most of the window bars above when using Netscape 6.2 and Netscape 7.02.

Here is a Netscape 7.02 screenshot from my computer

Netscape 7.02 screenshot

showing the full complement of browser bars listed under the View menu:

The Netscape 7.02 View menu and its Show/Hide submenu

(a) When I set window.locationbar.visible = false (boolean true and false values are not put in quotes), this part

The Netscape 7.02 location bar

of the navigation bar

The Netscape 7.02 navigation bar


(b) On my iMac, the browser menubar

The Netscape 7.02 menu bar

is not part of the window but is separate therefrom, and setting window.menubar.visible = false has no effect.

(c) When I set window.personalbar.visible = false, this bar disappears:

The Netscape 7.02 personal bar

(d) When setting window.scrollbars.visible = false, I find that the page must be reloaded to make the scrollbars disappear (FYI: when using MSIE, a document.body.scroll = "no" command will lose the scrollbars).

(e) When I set window.statusbar.visible = false, both the status bar and the component bar (the small bar to the left of the status bar)

The Netscape 7.02 component bar

disappear. The component bar's buttons correspond to the commands under the Window menu:

The Netscape 7.02 Window menu

(f) Setting window.toolbar.visible = false subtracts the Back, Forward, Reload, Stop, and Print buttons of the navigation bar.

To bring these bars back, neither simply reloading the page nor toggling the Navigation Toolbar, Personal Toolbar, and Status Bar commands under the View menu is effective; rather, in each case window.–bar.visible must be reset, to true. (Again, revisualizing the scrollbars requires a page reload.)

As far as I am aware, the window object does not have navigationbar, tabbar, and componentbar properties.

Introduced with Netscape 6, the sidebar

The Netscape 7.02 sidebar

stands apart from the other browser bars; the sidebar functions in effect as a frame of the browser window, much like MSIE's Explorer Bar, and its content is programmable. Propertywise, the window.sidebar expression on my computer cryptically returns:

[xpconnect wrapped (nsISupports, nsISidebar, nsIClassInfo)]

As an object, the sidebar does not have a visible property (window.sidebar.visible returns undefined) but has four methods, listed here, whose discussion is outside the scope of this blog entry.

Window Dimensions

The window object does not have simple width and height properties (even as the JavaScript event, Image, and screen objects all do) but instead has specialized innerWidth, innerHeight, outerWidth, and outerHeight properties that are all read/write but that are, annoyingly, supported by Netscape but not by MSIE. The outerWidth and outerHeight properties specify respectively the total width and height in pixels of the browser window, including all of the browser bars and presumably also the title bar and the window border. In turn, the innerWidth and innerHeight properties specify respectively the width and height in pixels of the document content area. Having said this, on my computer window.innerWidth and window.outerWidth return the same value with and without the right scrollbar.

JavaScript Kit's window object page claims that there are for MSIE document.body.clientWidth and document.body.clientHeight properties that are equivalent to window.innerWidth and window.innerHeight, respectively; not quite. As noted at Stephen Le Hunte's HTMLib Index resource, the clientWidth and clientHeight properties of the <body> element/object are read-only.

However, at least the width and height of newly opened windows can be set straightforwardly, as we'll see in Primer #11 (vide supra).

Window Positioning

At their window object pages, JavaScript Kit and IRT list screenX and screenY properties that specify "the x and y coordinates of the window relative to the user's monitor screen", quoting JavaScript Kit; these properties are again supported by Netscape but not by MSIE. (DevGuru lists screenX and screenY properties for the event object but not for the window object.) More specifically, a window's x coordinate is the number of pixels separating the window's left border from the monitor screen's left boundary, whereas a window's y coordinate is the number of pixels separating the window's top border from the monitor screen's top boundary (much like the x and y properties of the Image object, which we briefly discussed in Blog Entry #15). The window screenX and screenY properties are reliably readable, even if the browser window is moved manually beyond the monitor screen's boundaries; for example, window.screenX and window.screenY dutifully return negative numbers if the window is moved to the left and above the screen's left and top boundaries, respectively.

The screenX and screenY properties are writable to an extent, and can be used to move the window across the screen without incident as long as the movement does not bring the window into contact with the screen's boundaries; this works best, clearly, for smaller windows. Assigning suitably large values to window.screenX and window.screenY will not move a window off-screen and may cause larger windows to shrink in size in an unpredictable way (at least this is what happened when I tried to shift with screenX/screenY a full-sized browser window).

JavaScript Kit lists "IE5+ only" window screenLeft and screenTop properties whose descriptions are identical to those of screenX and screenY; however, MSIE returns undefined for both window.screenLeft and window.screenTop on my iMac. Sure enough, notes that screenLeft and screenTop are not supported by IE5 for the Macintosh.

The window object also has two properties, pageXOffset and pageYOffset, relating to the position of the document in the window. The pageXOffset and pageYOffset properties return the number of pixels that the document has been scrolled, horizontally and vertically, from the leftmost and topmost positions of the document within the window, respectively; these properties are not supported by MSIE, and are read-only. (My attempts to write them gave "Error: setting a property that has only a getter".)

JavaScript Kit notes that the IE4+ equivalents of pageXOffset and pageYOffset are document.body.scrollLeft and document.body.scrollTop, respectively. Gratifyingly, I find that the scrollLeft and scrollTop properties of the body object are recognized by both MSIE and Netscape, and are read/write.

Roll your mouse over these words to read the scrollTop property.

(Mind you, Webmasters who create Web pages that require horizontal scrolling should be tarred and feathered, IMHO, but that's another blog entry for another time.)

Window Status, revisited

We discussed the window status property in some detail in Blog Entry #7. The window object also has a related defaultStatus property that can be used to write a new default status bar message in place of the browser's normal default status bar message, which on my computer is "Internet zone" and "Document:Done ( secs)" for MSIE and Netscape, respectively.

In setting a new default status bar message, I find that window.defaultStatus and window.status commands can be used interchangeably. When using Netscape, the window.defaultStatus = "message" (or window.status = "message") command can be put in a script and executed in either the document head or the document body. When using MSIE, which seems to be more sensitive to the timing of browser/script events than is Netscape, I am only able to execute window.defaultStatus = "message" (or window.status = "message") when I assign it to an onload attribute in the document <body> tag (or trigger it by some other event handler of a document body element) - this also works for Netscape.

DevGuru notes that a window.status message should transiently supplant a window.defaultStatus message; however, IRT warns on its window object page that "the default status value may not be properly restored on some platforms", and this is indeed the case on my computer, with a window.status message permanently overriding a window.defaultStatus message. The converse is not true; a window.defaultStatus message will not displace a preceding window.status message. If you put

onload="window.status = 'This is message #1.'; window.defaultStatus = 'This is message #2.';"

in the document <body> tag, then you'll see 'This is message #1.' in the status bar. On the other hand, a not-so-transient window.status message will be displaced by a subsequent window.status message.

Other Window Children

Besides document and the browser bars, there are a number of other JavaScript objects, some of them admittedly obscure, whose immediate parent in the JavaScript object hierarchy is the window object, and are thus properties of the window object, including:

clientInformation, crypto, event, Frame, History, Location, navigator, netscape, Packages, pkcs11, screen

The next post will conclude our discourse on JavaScript properties with a brief look at the properties of the History and Location objects.


Comments: Post a Comment

<< Home

Powered by Blogger

Actually, reptile7's JavaScript blog is powered by Café La Llave. ;-)