Saturday, August 06, 2005
Properties VII: The Window Object
Blog Entry #18
• 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:
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:
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
window.top.document.title = "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.
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).
Here is a Netscape 7.02 screenshot from my computer
showing the full complement of browser bars listed under the View menu:
(a) When I set window.locationbar.visible = false (boolean true and false values are not put in quotes), this part
of the navigation bar
(b) On my iMac, the browser menubar
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:
(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)
disappear. The component bar's buttons correspond to the commands under the 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
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.
However, at least the width and height of newly opened windows can be set straightforwardly, as we'll see in Primer #11 (vide supra).
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).
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".)
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 (x.xxx 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
clientInformation, crypto, event, Frame, History, Location, navigator, netscape, Packages, pkcs11, screen