 (1997).iso/Media/Tools/HTMLib/content/Images/top.gif){kind=small}
The Window object is the top level object and represents the window of the browser. It is the parent of the objects below it in the hierarchy list.
| Properties | Methods | Events |
| name, parent, self, top, location, defaultStatus, status, frames, history, document, length*, opener | alert, confirm, prompt, open, close, setTimeout, clearTimeout, blur*, focus*, scroll*, clearInterval**, setInterval**, moveBy**, moveTo**, resizeBy**, resizeTo**, scrollBy**, scrollTo** | OnLoad, OnUnload, OnBlur*, OnError*, OnFocus* |
Window objects are either the current window (if the browser is displaying only a single document), or those created with a window.open() method (where the name is specified in the code), or separate frames, if the document is laid out using a <FRAMESET> definition (where the windows are named in the <FRAME> element). As the Window object is the top level object in the object hierarchy and the existance of the current window is assumed, most Window properties need not be prefixed by Window. For example, the following two references are identical :
window.defaultStatus
defaultStatus
and would both return the default text of the status bar for the current window. NOTE : The only exception to this is the open() and close() methods, which require an explicit window. prefix (i.e. window.open() and window.close()). Windows can also be referenced by using the properties top, parent or name, where the name property is replaced with the actual window name (as specified in the window.open() code, or <FRAMESET>. The parent and top properties are exactly as those used in <A HREF="..." TARGET="..."> constructs if the windows are part of a frameset.
Window Properties
name
The name property represents the name of a window object. It is read-only (that is, script functions can interrogate window names, but can not define them dynamically)
parent
The parent object returns the current windows parent object if the current window is part of a frame set (if it isn't, then accessing the parent property returns the current window object, acting as the self property). For example :
vStrParentName=parent.name
would store the name property of the parent window of the current window in the variable vStrParentName.
self
The self property returns the window object of the current window. For example :
vStrStatus=self.status
stores the text in the current window's status bar in the variable vStrStatus.
top
The top property returns the window object of the top-most browser window. For example :
vLocation=top.location
sets the vLocation variable to the complete URL of the document in the top-most browser window.
location
The location property returns the URL of the window objects current document. This is also an object in it's own right, with various properties. For more details, see the Location Object. The example above shows the location property/object in use.
defaultStatus
The defaultStatus property can be accessed to return or set the text to be shown in the status bar of the browser while the current document. The defaultStatus property is different to the status property in that the text is always shown in the status bar. As seen below, the status property can be used to temporarily alter the status bar text. Internet Explorer currently set this property as the default status text and so works as the status property.
status
As said above, the status property can be used to temporarily change the text displayed in the status bar of a browser window. It is commonly used to set the status bar text when the mouse is moved over links in a document, so that more explanatory text, instead of a URL is displayed. For example :
self.status="This goes to the HTMLib web site"
would set the text in the status bar to "This goes to the HTMLib web site". See Scripting the <A> element for more information. Also, note that when documents are presented in a frame based layout, all windows share common access to the browsers status bar, so using self.status in any frame based document, would affect the main status bar for the browser, rather than for particular frames.
frames
The frames property is an indexed array of all the frames of a window object. It is also an object with it's own properties and methods. For more information, see the The Frame object. When a document is a framed document, the individual frames are indexed, starting at 0. So, for example, to access the location object of the frame defined third in the <FRAME> definitions, the following could be used :
vLocation=window.frames(2).location
NOTE : The above example uses Visual Basic Script notation (i.e. '(' and ')') to denote the index. JavaScript functions require the use of square bracket ('[' and ']').
history
The history property is also an object in it's own right, with properties and methods. For more information, see The History Object. It represents the browsers current history list (a list of recently visited sites).
document
The document property is also an object in it's own right, with properties and methods. For more information, see The Document Object. The document object has properties that contain information about the current document being viewed in the browser window object. For example :
vColour=parent.document.bgColor
stores the background colour of the document in the current window's parent in the variable vColour.
length
The Netscape specific length property returns the number of frames in a window object (when used under the window object. The length property is common to many scriptable objects). For example :
vFrames=HelpWin.length
would store the number of frames in the window named HelpWin (which is either a single frame, or a window created using the window.open() method) in the variable vFrames.
opener
The opener property returns the name of the window that created the current window (via a window.open() event). It can be used with further object properties (such as location etc.) to access properties of the window/document that opened the current window, or methods such as close() to automatically close the window that created the current window. For example :
self.opener.close()
would automatically close the window that created the new window.
Window Methods
alert
The alert method can be used to display a message to the user. (Internet Explorer Visual Basic Script also allows the use of the MsgBox function to do the same, with more interaction options). For example :
alert "Hi there, welcome to my page"
would display the message "Hi there, welcome to my page" over the current window. (NOTE : As alert is a method of the window object (the top level object), it does not require the window. prefix.) Also note that the message string can be a text string, or a property of any existing object.
confirm
Similar to the alert method, the confirm method displays a message to the user, but offers basic "OK" and "Cancel" buttons. For example, the following code displays a confirmation message and if the user chooses OK, the browser goes to the HTMLib web site. If they choose Cancel, then nothing happens.
function leave()
{
if (confirm("Are you sure you want to visit the HTMLib web site?"))
{location.href= "http://subnet.virtual-pc.com/~le387818"}
}
prompt
Again, like the above two methods, the prompt method allows you to present the user with a dialog allowing them to enter values (like Visual Basic Script's InputBox method). The method is called, defining a default value in the input box. For example, the following code asks the user to enter a year, giving 1996 as the default value.
prompt("Enter a year", 1996)
open
The open method allows script functions to create new browser windows and load documents into them. It also allows control over the window's appearance and size. The basic syntax is :
Variable=window.open("URL", windowname, "window_appearance")
where URL is the URL of the document to be loaded into the new window, windowname is the name given to the new window (subsequently it's name property (see above)) and window_appearance is a comma-delimited list setting the window features. The window features are boolean values (i.e. either '0' or '1', or 'no' or 'yes'). The features controllable are :
NOTE : The window features labelled above, with '*' characters are only supported in Javascript 1.2, as supported by Navigator 4.0 and above. To be sure that any Javascript functions using these extended features don't throw a scripting error (or produce unwanted results), make sure to version the LANGUAGE attribute of the <SCRIPT> appropriately and provide version specific scripts if necessary. For more information, see Versioning Javascript..
NOTE : Netscape documentation describes a resizable feature, while Microsoft documentation describes a resizeable feature (note the 'e'). Netscape only supports resizable, while Internet Explorer puports to only support the resizeable feature. Also note that for Netscape, the window features must be separated by only a comma, with no white space between them (Internet Explorer is more forgiving about the white space)
NOTE : When using Visual Basic Script, the parenthesis characters must not be used surrounding the various window.open methods. I.e., the method should be used as follows under Visual Basic Script :
window.open URL,"window_name","window_options"
Internet Explorer now fully supports (from 3.02) the previously Netscape specific format of the window.open method. For example :
WindowName=window.open (URL,"WindowName","window_options")
where WindowName can then be used to control the newly created window.
A note about the top and left window options
top and left should be used with care when positioning new windows exactly (i.e. by pixel measurements) because you can not be sure of the users screen resolution (although Navigator 4.0 now provides window resizing and moving methods (see below)). Also, be aware of a current limitation in the Internet Explorer 3.01 support of these window settings. If the document calling the window.open method is displayed singularly (i.e. not part of a frameset), then top and left behave as expected and can be used to set the position of the new window, (in pixel units) on the screen.
If the document calling the window.open method is a framed document (i.e. displayed in a frame), however, then it starts to get a little complicated. For some as yet unknown reason the top and left co-ordinates should be reversed, to display the newly created window in the right position. For example if the following code is executed in a non-framed document,
NewWin=window.open(URL,name,"left=640,top=480");
then the new window would be created at a position x=640 pixels and y=480 pixels. However, if the same code was executed from a framed document, then the new window would be created and displayed at x=480 y=640 pixels. For the same code to work, displaying the window in the same position, called from a framed document, the code would need to be :
NewWin=window.open(URL,name,"left=480,top=640");
Just to add to the confusion, Internet Explorer 3.02 seems to have permanently reversed the top and left settings (so that calling ...left=x1, top=y1 actually places the new window at a position x=y1, y=x1 pixels), regardless of whether the document utilising the window.open method is framed or single. Support of these two method attributes is basically a legacy of the previously supported 'Explorer' object, which was supported in the Windows 95/NT4 v3.01 of Internet Explorer, but removed from v3.02 for security reasons.
NOTE : The top and left attributes are not officially documented as being supported by Internet Explorer, so should be used with care as their support may possibly change without notice.
close
The window.close() method closes the window specified in the window. prefix, which is required. Any window can be closed using this method, providing it is referenced either by it's name property, or by parent, self or top. NOTE : In JavaScript 1.1 (as supported by Navigator 3.0 and above), the window.close() method only allows automatic closing of windows generated by a corresponding window.open() event. Attempting to close any other window will display a confirm dialog, prompting the user to choose whether the window is closed or not.
setTimeout
The setTimeout method can be used to execute a script function, or access any existing object property or method, after a specified time interval. For example, the following code section would execute the script function TooMuchTime() after 5 seconds :
MyTimeOut=setTimeout ("TooMuchTime()", 5000)
The time interval is always specified in milliseconds.
In Javascript 1.2 (as supported by Navigator 4.0 and above), the setTimeout method can be used to evaluate an expression, as well as calling functions. Note that this will require using LANGUAGE="Javascript1.2" in the <SCRIPT> element, so as to prevent older browsers throwing a scripting error, or not functioning as expected.
clearTimeout
The clearTimeout method is used to clear a specified setTimeout method, by referencing it by the ID of the setTimeout method. For example, to clear the setTimeout given in the previous example, use the following code :
clearTimeout MyTimeOut
NOTE : both the setTimeout and clearTimeout do not need the window. prefix, as they are methods of the top level Window object.
blur
This Netscape specific method can be used to forceably remove focus from a given window object. For example, suppose you have created a window (via window.open() code, called 'HelpWin'), the following :
HelpWin.blur()
would remove focus from the newly created window.
focus
This Netscape specific method can be used to force the focus to any window object. For example, given the above example, the following function snippet :
HelpWin.focus()
would pass the focus to the newly created window named HelpWin.
scroll
This Netscape specific method can be used to automatically move the user to any point in the current window. It is similar to mid page links, using <A HREF="#..."> constructs, except it moves the user to a position of pixel values, rather than links. For example :
HelpWin.scroll(200,300)
would scroll the user to the position 200,300 (in pixels). The number sequence is x-coordinate, y-coordinate.
clearInterval
As also used in the Frame object, the clearInterval method cancels a corresponding setInterval method (described below. The syntax is :
clearInterval (MyInterval)
setInterval
As also used in the Frame object, the setInterval method can be used to either call a Javascript function, or evaluate an expression, after a specified time interval (in millisecond) has expired. For example :
setInterval=MyInterval (startanim(),1000,20,100)
would execute the function startanim(), after 1 second has elapsed (1000 milliseconds), passing it 20 and 100 as arguments to the function. Any number of arguments can be passed in the setInterval method (i.e. as many as are required by the function). The setInterval method will repeatedly call the referenced function, or expression, until the user leaves the document that contains the script. This is essentially the only difference between it and the setTimeout method, which is only executed once, after the specified time interval.
moveBy
The moveBy method can be used to re-position the Navigator window, relative to it's current position. For example :
self.moveBy (50,200)
would move the current Navigator window 50 pixels to the right and 200 pixels down from it's current position. ('self' is used above, but any valid reference to a window object is useable).
moveTo
moveTo can be used to move the Navigator window to a specific point on the screen, by moving the top-left corner of the Navigator to the position specified :
self.moveTo (50,200)
would move the Navigator window to the position 50,200 on the users screen.
resizeBy
As you'll probably have guessed, the resizeBy method resizes the Navigator window from it's current size by the amounts specified. For example :
self.resizeBy (50,200)
would move the bottom right hand corner of the navigator window 50 pixels to the right and 200 pixels down, creating a larger window.
resizeTo
Like the moveTo method above, the resizeTo method can be used to resize the Navigator window to a specific size. For example :
self.resizeTo (640,480)
would resize the Navigator window to 640 by 480 pixels.
Coupled together with the moveTo and moveBy methods, these provide indispensable window control, particularly when working with document layers (see <LAYER> and <ILAYER>). Currently (in Communicator preview release 2) it is possible to move/resize the Navigator window to totally unworkable sizes/positions. Netscape have stated that all four of these methods may be restricted in future versions to prevent users ending up in such positions. Also, be aware that you can not guarantee the viewers screen resolution, so regardless of the Netscape imposed restrictions, use these methods with caution. The sensible option would be to always use a moveTo method to set the Navigator window at the top-left corner of the users screen before performing any resizing methods, to ensure the entire viewing area is visible. Also limiting the maximum size of sites requiring this functionality to 640x480 pixels would also be sensible.
scrollBy
As with the other *By methods, scrollBy scrolls the viewing area of the Navigator window by the amounts specified in the values. For example :
self.scrollBy (50,100)
would scroll the viewing window 50 pixels to the left and 100 pixels down. Scrolling to the right would only be effective is there is content currently off the screen (for example, you may have layers currently off-screen, or very wide images).
scrollTo
This method scrolls the viewing window to an exact pixel position, given by the values. For example :
self.scrollTo (100,300)
scrolls to the point 100 pixels to the right and 300 pixels down.
NOTE : scrollTo extends the scroll method (see above), which is still supported in Navigator 4.0 and above for backwards compatibility.
A note about window references for the positioning/moving methods
For the moveBy, moveTo, resizeBy and resizeTo methods, the whole navigator window is moved or resized. This means that if the methods are invoked in a framed document, then the entire Navigator window is altered, regardless of the window reference (providing that it is valid). I.e. using 'top', 'self' and 'parent', or referencing any framed document currently in the same Navigator display window all have the same effect. Single documents, or separate windows (created from links, or the open method) can be referenced by their name.
For the scrollBy and scrollTo methods, all windows (framed or otherwise) can be manipulated by using a valid reference. However, if the window referenced doesn't contain sufficient content for scrollbars to be necessary, then both these methods will do nothing.
Window Events
OnLoad
The OnLoad event can be used in window objects. It is used in the <BODY> element, or <FRAMESET> elements (Netscape only) and executes functions when the document (framed or normal) has finished loading. For information about this event, see the Scripting the <BODY> element, or Scripting the <FRAMESET> element topics.
OnUnLoad
The opposite of the above event, the OnUnLoad event is used to execute script functions when the user exits a window object (a frame window, or a normal window). It is also used only in the <BODY> and <FRAMESET> elements (supported in both elements, by both browsers). For details, see the Scripting the <BODY> element, or Scripting the <FRAMESET> element topics.
OnBlur
This Netscape specific event handler can be used in <BODY> and <FRAMESET> elements. For details, see the Scripting the <BODY> element, or Scripting the <FRAMESET> element topics.
OnError
This Netscape specific event handler can be used in <BODY> and <FRAMESET> elements. For details, see the Scripting the <BODY> element, or Scripting the <FRAMESET> element topics.
OnFocus
This Netscape specific event handler can be used in <BODY> and <FRAMESET> elements. For details, see the Scripting the <BODY> element, or Scripting the <FRAMESET> element topics.
 (1997).iso/Media/Tools/HTMLib/content/Images/LEFT.GIF){kind=small}
 (1997).iso/Media/Tools/HTMLib/content/Images/UP.GIF){kind=small}
 (1997).iso/Media/Tools/HTMLib/content/Images/RIGHT.GIF){kind=small}