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* | 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 exisiting 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 : 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.
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"
A note about the top and left window options
top and left are Internet Explorer specific attributes in the window.open method and you should be careful when positioning new windows exactly (i.e. by pixel measurements) because you can not be sure of the users screen resolution. 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. that 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");
Also note that in framed documents, each separate frame can be thought of as being it's own Explorer object, with differing top and left values. For more information, see the Explorer Object.
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.
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.
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.