window
Represents a browser window or frame. This is the top-level object for eachdocument, Location, and History object group.
JavaScript 1.1: added
JavaScript 1.2: added | |
Created by
The JavaScript runtime engine creates awindow object for each BODY or FRAMESET tag. It also creates a window object to represent each frame defined in a FRAME tag. In addition, you can create other windows by calling the window.open method. For details on defining a window, see open.
Event handlers
In JavaScript 1.1, on some platforms, placing anonBlur or onFocus event handler in a FRAMESET tag has no effect.
Description
Thewindow object is the top-level object in the JavaScript client hierarchy. A window object can represent either a top-level window or a frame inside a frameset. As a matter of convenience, you can think about a Frame object as a window object that isn't a top-level window. However, there is not really a separate Frame class; these objects really are window objects, with a very few minor differences:
-
For a top-level window, the
parentandtopproperties are references to the window itself. For a frame, thetoprefers to the topmost browser window, andparentrefers to the parent window of the current window. -
For a top-level window, setting the
defaultStatusorstatusproperty sets the text appearing in the browser status line. For a frame, setting these properties only sets the status line text when the cursor is over the frame. -
The
closemethod is not useful for windows that are frames. -
To create an
onBluroronFocusevent handler for a frame, you must set theonbluroronfocusproperty and specify it in all lowercase (you cannot specify it in HTML). -
If a
FRAMEtag containsSRCandNAMEattributes, you can refer to that frame from a sibling frame by usingparent.frameNameorparent.frames[index]. For example, if the fourth frame in a set hasNAME="homeFrame", sibling frames can refer to that frame usingparent.homeFrameorparent.frames[3].
self and window properties of a window object are synonyms for the current window, and you can optionally use them to refer to the current window. For example, you can close the current window by calling the close method of either window or self. You can use these properties to make your code more readable or to disambiguate the property reference self.status from a form called status. See the properties and methods listed below for more examples.
Because the existence of the current window is assumed, you do not have to refer to the name of the window when you call its methods and assign its properties. For example, status="Jump to a new location" is a valid property assignment, and close() is a valid method call.
However, when you open or close a window within an event handler, you must specify window.open() or window.close() instead of simply using open() or close(). Due to the scoping of static objects in JavaScript, a call to close() without specifying an object name is equivalent to document.close().
For the same reason, when you refer to the location object within an event handler, you must specify window.location instead of simply using location. A call to location without specifying an object name is equivalent to document.location, which is a synonym for document.URL.
You can refer to a window's Frame objects in your code by using the frames array. In a window with a FRAMESET tag, the frames array contains an entry for each frame.
A windows lacks event handlers until HTML that contains a BODY or FRAMESET tag is loaded into it.
Property Summary
Method Summary
watch and unwatch methods from Object.
Examples
Example 1. Windows opening other windows. In the following example, the document in the top window opens a second window,window2, and defines push buttons that open a message window, write to the message window, close the message window, and close window2. The onLoad and onUnload event handlers of the document loaded into window2 display alerts when the window opens and closes.
win1.html, which defines the frames for the first window, contains the following code:
<HTML>
<HEAD>
<TITLE>window object example: Window 1</TITLE>
</HEAD>
<BODY BGCOLOR="antiquewhite">
<SCRIPT>
window2=open("win2.html","secondWindow",
"scrollbars=yes,width=250, height=400")
document.writeln("<B>The first window has no name: "
+ window.name + "</B>")
document.writeln("<BR><B>The second window is named: "
+ window2.name + "</B>")
</SCRIPT>
<FORM NAME="form1">
<P><INPUT TYPE="button" VALUE="Open a message window"
onClick = "window3=window.open('','messageWindow',
'scrollbars=yes,width=175, height=300')">
<P><INPUT TYPE="button" VALUE="Write to the message window"
onClick="window3.document.writeln('Hey there');
window3.document.close()">
<P><INPUT TYPE="button" VALUE="Close the message window"
onClick="window3.close()">
<P><INPUT TYPE="button" VALUE="Close window2"
onClick="window2.close()">
</FORM>
</BODY>
</HTML>
win2.html, which defines the content for window2, contains the following code:
<HTML>Example 2. Creating frames. The following example creates two windows, each with four frames. In the first window, the first frame contains push buttons that change the background colors of the frames in both windows.
<HEAD>
<TITLE>window object example: Window 2</TITLE>
</HEAD>
<BODY BGCOLOR="oldlace"
onLoad="alert('Message from ' + window.name + ': Hello, World.')"
onUnload="alert('Message from ' + window.name + ': I\'m closing')">
<B>Some numbers</B>
<UL><LI>one
<LI>two
<LI>three
<LI>four</UL>
</BODY>
</HTML>
framset1.html, which defines the frames for the first window, contains the following code:
<HTML>
<HEAD>
<TITLE>Frames and Framesets: Window 1</TITLE>
</HEAD>
<FRAMESET ROWS="50%,50%" COLS="40%,60%"
onLoad="alert('Hello, World.')">
<FRAME SRC=framcon1.html NAME="frame1">
<FRAME SRC=framcon2.html NAME="frame2">
<FRAME SRC=framcon2.html NAME="frame3">
<FRAME SRC=framcon2.html NAME="frame4">
</FRAMESET>
</HTML>
framset2.html, which defines the frames for the second window, contains the following code:
<HTML>
<HEAD>
<TITLE>Frames and Framesets: Window 2</TITLE>
</HEAD>
<FRAMESET ROWS="50%,50%" COLS="40%,60%">
<FRAME SRC=framcon2.html NAME="frame1">
<FRAME SRC=framcon2.html NAME="frame2">
<FRAME SRC=framcon2.html NAME="frame3">
<FRAME SRC=framcon2.html NAME="frame4">
</FRAMESET>
</HTML>
framcon1.html, which defines the content for the first frame in the first window, contains the following code:
<HTML>
<BODY>
<A NAME="frame1"><H1>Frame1</H1></A>
<P><A HREF="framcon3.html" target=frame2>Click here</A>
to load a different file into frame 2.
<SCRIPT>
window2=open("framset2.html","secondFrameset")
</SCRIPT>
<FORM>
<P><INPUT TYPE="button" VALUE="Change frame2 to teal"
onClick="parent.frame2.document.bgColor='teal'">
<P><INPUT TYPE="button" VALUE="Change frame3 to slateblue"
onClick="parent.frames[2].document.bgColor='slateblue'">
<P><INPUT TYPE="button" VALUE="Change frame4 to darkturquoise"
onClick="top.frames[3].document.bgColor='darkturquoise'">
<P><INPUT TYPE="button" VALUE="window2.frame2 to violet"
onClick="window2.frame2.document.bgColor='violet'">
<P><INPUT TYPE="button" VALUE="window2.frame3 to fuchsia"
onClick="window2.frames[2].document.bgColor='fuchsia'">
<P><INPUT TYPE="button" VALUE="window2.frame4 to deeppink"
onClick="window2.frames[3].document.bgColor='deeppink'">
</FORM>
</BODY>
</HTML>
framcon2.html, which defines the content for the remaining frames, contains the following code:
<HTML>
<BODY>
<P>This is a frame.
</BODY>
</HTML>
framcon3.html, which is referenced in a Link object in framcon1.html, contains the following code:
<HTML>
<BODY>
<P>This is a frame. What do you think?
</BODY>
</HTML>
See also
document, Frame
alert
Displays an Alert dialog box with a message and an OK button.Syntax
alert(message)
Parameters
message |
Description
An alert dialog box looks as follows:
alert method to display a message that does not require a user decision. The message argument specifies a message that the dialog box contains.
You cannot specify a title for an alert dialog box, but you can use the open method to create your own alert dialog box. See open.
Examples
In the following example, thetestValue function checks the name entered by a user in the Text object of a form to make sure that it is no more than eight characters in length. This example uses the alert method to prompt the user to enter a valid value.
function testValue(textElement) {You can call the
if (textElement.length > 8) {
alert("Please enter a name that is 8 characters or less")
}
}
testValue function in the onBlur event handler of a form's Text object, as shown in the following example:
Name: <INPUT TYPE="text" NAME="userName"
onBlur="testValue(userName.value)">
See also
window.confirm, window.prompt
atob
Decodes a string of data which has been encoded using base-64 encoding.Syntax
atob(encodedData)
Parameters
encodedData | A string of data which has been created using base-64 encoding. |
Description
This method decodes a string of data which has been encoded using base-64 encoding. For example, thewindow.btoa method takes a binary string as a parameter and returns a base-64 encoded string.
You can use the window.btoa method to encode and transmit data which may otherwise cause communication problems, then transmit it and use the window.atob method to decode the data again. For example, you can encode, transmit, and decode characters such as ASCII values 0 through 31.
Examples
The following example encodes and decodes the string "Hello, world".// encode a string
encodedData = btoa("Hello, world");
// decode the string
decodedData = atob(encodedData);
See also
window.btoa
back
Undoes the last history step in any frame within the top-level window; equivalent to the user pressing the browser's Back button.Syntax
back()
Parameters
NoneDescription
Calling theback method is equivalent to the user pressing the browser's Back button. That is, back undoes the last step anywhere within the top-level window, whether it occurred in the same frame or in another frame in the tree of frames loaded from the top-level window. In contrast, the history object's back method backs up the current window or frame history one step.
For example, consider the following scenario. While in Frame A, you click the Forward button to change Frame A's content. You then move to Frame B and click the Forward button to change Frame B's content. If you move back to Frame A and call FrameA.back(), the content of Frame B changes (clicking the Back button behaves the same).
If you want to navigate Frame A separately, use FrameA.history.back().
Examples
The following custom buttons perform the same operation as the browser's Back button:<P><INPUT TYPE="button" VALUE="< Go Back"
onClick="history.back()">
<P><INPUT TYPE="button" VALUE="> Go Back"
onClick="myWindow.back()">
See also
window.forward, History.back
blur
Removes focus from the specified object.Syntax
blur()
Parameters
NoneDescription
Use theblur method to remove focus from a specific window or frame. Removing focus from a window sends the window to the background in most windowing systems.
See also
window.focus
btoa
Creates a base-64 encoded ASCII string from a string of binary data.Syntax
btoa(stringToEncode)
Parameters
stringToEncode |
Description
This method takes a binary ASCII string as a parameter and returns another ASCII string which has been encoded using base-64 encoding. You can use this method to encode data which may otherwise cause communication problems, transmit it, then use thewindow.atob method to decode the data again. For example, you can encode characters such as ASCII values 0 through 31.
Examples
Seewindow.atob.
See also
window.atob
captureEvents
Sets the window to capture all events of the specified type.Syntax
captureEvents(eventType1 [|eventTypeN...])
Parameters
eventType1... eventTypeN | The type of event to be captured. The available event types are discussed in Chapter 3, "Event Handlers." |
Security
When a window with frames wants to capture events in pages loaded from different locations (servers), you need to usecaptureEvents in a signed script and precede it with enableExternalCapture. You must have the UniversalBrowserWrite privilege. For more information and an example, see enableExternalCapture. For information on security, see the Client-Side JavaScript Guide.
See also
captureEvents works in tandem with releaseEvents, routeEvent, and handleEvent. For more information, see the Client-Side JavaScript Guide.
clearInterval
Cancels a timeout that was set with thesetInterval method.Syntax
clearInterval(intervalID)
Parameters
intervalID |
Timeout setting that was returned by a previous call to the |
Description
SeesetInterval.
Examples
SeesetInterval.
See also
window.setInterval
clearTimeout
Cancels a timeout that was set with thesetTimeout method.Syntax
clearTimeout(timeoutID)
Parameters
timeoutID |
A timeout setting that was returned by a previous call to the |
Description
SeesetTimeout.
Examples
SeesetTimeout.
See also
window.clearInterval, window.setTimeout
close
Closes the specified window.JavaScript 1.0: closes any window JavaScript 1.1: closes only windows opened by JavaScript JavaScript 1.2: must use signed scripts to unconditionally close a window |
Syntax
close()
Parameters
NoneSecurity
To unconditionally close a window, you need theUniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.
Description
Theclose method closes the specified window. If you call close without specifying a windowReference, JavaScript closes the current window.
The close method closes only windows opened by JavaScript using the open method. If you attempt to close any other window, a confirm is generated, which lets the user choose whether the window closes. This is a security feature to prevent "mail bombs" containing self.close(). However, if the window has only one document (the current one) in its session history, the close is allowed without any confirm. This is a special case for one-off windows that need to open other windows and then dispose of themselves.
In event handlers, you must specify window.close() instead of simply using close(). Due to the scoping of static objects in JavaScript, a call to close() without specifying an object name is equivalent to document.close().
Examples
Example 1. Any of the following examples closes the current window:window.close()Example 2: Close the main browser window. The following code closes the main browser window.
self.close()
close()
top.opener.close()Example 3. The following example closes the
messageWin window:
messageWin.close()This example assumes that the window was opened in a manner similar to the following:
messageWin=window.open("")
See also
window.closed, window.open
closed
Specifies whether a window is closed.Description
Theclosed property is a boolean value that specifies whether a window has been closed. When a window closes, the window object that represents it continues to exist, and its closed property is set to true.
Use closed to determine whether a window that you opened, and to which you still hold a reference (from the return value of window.open), is still open. Once a window is closed, you should not attempt to manipulate it.
Examples
Example 1. The following code opens a window,win1, then later checks to see if that window has been closed. A function is called depending on whether win1 is closed.
win1=window.open('opener1.html','window1','width=300,height=300')Example 2. The following code determines if the current window's opener window is still closed, and calls the appropriate function.
...
if (win1.closed)
function1()
else
function2()
if (window.opener.closed)
function1()
else
function2()
See also
window.close, window.open
confirm
Displays a Confirm dialog box with the specified message and OK and Cancel buttons.Syntax
confirm(message)
Parameters
message |
Description
A confirm dialog box looks as follows:
confirm method to ask the user to make a decision that requires either an OK or a Cancel. The message argument specifies a message that prompts the user for the decision. The confirm method returns true if the user chooses OK and false if the user chooses Cancel.
You cannot specify a title for a confirm dialog box, but you can use the open method to create your own confirm dialog. See open.
Examples
This example uses theconfirm method in the confirmCleanUp function to confirm that the user of an application really wants to quit. If the user chooses OK, the custom cleanUp function closes the application.
function confirmCleanUp() {You can call the
if (confirm("Are you sure you want to quit this application?")) {
cleanUp()
}
}
confirmCleanUp function in the onClick event handler of a form's push button, as shown in the following example:
<INPUT TYPE="button" VALUE="Quit" onClick="confirmCleanUp()">
See also
window.alert, window.prompt
crypto
An object which allows access Navigator's encryption features.Description
Thecrypto object is only available as a property of window; it provides access to methods which support Navigator's encryption features.
See also
window.crypto.random, window.crypto.signText
crypto.random
Returns a pseudo-random string whose length is the specified number of bytes.Syntax
crypto.random(numberOfBytes)
Parameters
numberOfBytes | The number of bytes of pseudo-random data the method will return. |
Description
This method generates a random string of data whose length is specified by thenumberOfBytes parameter.
Examples
The following function returns a string whose length is 16 bytes.function getRandom() {
return crypto.random(16)
}
See also
Math.random
crypto.signText
Returns a string of encoded data which represents a signed object.Syntax
crypto.signText
(text, selectionStyle [, authority1 [, ... authorityN]])
Parameters
text | |
selectionStyle | |
authority1... authorityN | Optional strings evaluating to Certificate Authorities accepted by the server using the signed text. |
Description
ThesignText method asks a user to validate a text string by attaching a digital signature to it. If the selectionStyle parameter is set to ask, signText displays a dialog box, and a user must interactively select a certificate to validate the text. If selectionStyle is set to auto, Navigator attempts to automatically select a certificate.
Use the signText method to submit an encoded signature to a server; the server decodes the signature and verifies it. If signText fails, it returns one of the following error codes:
-
error:noMatchingCertspecifies that the user's certificate does not match one of the certificates required byauthority1throughauthorityN. -
error:userCancelspecifies that the user cancelled the signature dialog box without submitting a certificate. -
error:internalErrorspecifies that an internal error occurred.
defaultStatus
The default message displayed in the status bar at the bottom of the window.Security
JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.Description
ThedefaultStatus message appears when nothing else is in the status bar. Do not confuse the defaultStatus property with the status property. The status property reflects a priority or transient message in the status bar, such as the message that appears when a mouseOver event occurs over an anchor.
You can set the defaultStatus property at any time. You must return true if you want to set the defaultStatus property in the onMouseOut or onMouseOver event handlers.
Examples
In the following example, thestatusSetter function sets both the status and defaultStatus properties in an onMouseOver event handler:
function statusSetter() {
window.defaultStatus = "Click the link for the Netscape home page"
window.status = "Netscape home page"
}
<A HREF="http://home.netscape.com"In the previous example, notice that the
onMouseOver = "statusSetter(); return true">Netscape</A>
onMouseOver event handler returns a value of true. You must return true to set status or defaultStatus in an event handler.
See also
window.status
disableExternalCapture
Disables external event capturing set by theenableExternalCapture method. Syntax
disableExternalCapture()
Parameters
NoneDescription
SeeenableExternalCapture.
document
Contains information on the current document, and provides methods for displaying HTML output to the user.Description
The value of this property is the window's associateddocument object.
enableExternalCapture
Allows a window with frames to capture events in pages loaded from different locations (servers).Syntax
enableExternalCapture()
Parameters
NoneDescription
Use this method in a signed script requestingUniversalBrowserWrite privileges, and use it before calling the captureEvents method.
If Communicator sees additional scripts that cause the set of principals in effect for the container to be downgraded, it disables external capture of events. Additional calls to enableExternalCapture (after acquiring the UniversalBrowserWrite privilege under the reduced set of principals) can be made to enable external capture again.
Examples
In the following example, the window is able to capture allClick events that occur across its frames.
<SCRIPT ARCHIVE="myArchive.jar" ID="2">
function captureClicks() {
netscape.security.PrivilegeManager.enablePrivilege(
"UniversalBrowserWrite");
enableExternalCapture();
captureEvents(Event.CLICK);
...
}
</SCRIPT>
See also
window.disableExternalCapture, window.captureEvents
find
Finds the specified text string in the contents of the specified window.Syntax
find([string[, caseSensitive, backward]])
Parameters
string | |
caseSensitive | |
backward |
Returns
true if the string is found; otherwise, false.Description
When a string is specified, the browser performs a case-insensitive, forward search. If a string is not specified, the method displays the Find dialog box, allowing the user to enter a search string.focus
Gives focus to the specified object.Syntax
focus()
Parameters
NoneDescription
Use thefocus method to navigate to a specific window or frame, and give it focus. Giving focus to a window brings the window forward in most windowing systems.
In JavaScript 1.1, on some platforms, the focus method gives focus to a frame but the focus is not visually apparent (for example, the frame's border is not darkened).
Examples
In the following example, thecheckPassword function confirms that a user has entered a valid password. If the password is not valid, the focus method returns focus to the Password object and the select method highlights it so the user can reenter the password.
function checkPassword(userPass) {This example assumes that the
if (badPassword) {
alert("Please enter your password again.")
userPass.focus()
userPass.select()
}
}
Password object is defined as
<INPUT TYPE="password" NAME="userPass">
See also
window.blur
forward
Points the browser to the next URL in the current history list; equivalent to the user pressing the browser's Forward buttonSyntax
history.forward()
forward()
Parameters
NoneDescription
This method performs the same action as a user choosing the Forward button in the browser. Theforward method is the same as history.go(1).
When used with the Frame object, forward behaves as follows: While in Frame A, you click the Back button to change Frame A's content. You then move to Frame B and click the Back button to change Frame B's content. If you move back to Frame A and call FrameA.forward(), the content of Frame B changes (clicking the Forward button behaves the same). If you want to navigate Frame A separately, use FrameA.history.forward().
Examples
The following custom buttons perform the same operation as the browser's Forward button:<P><INPUT TYPE="button" VALUE="< Go Forth"
onClick="history.forward()">
<P><INPUT TYPE="button" VALUE="> Go Forth"
onClick="myWindow.forward()">
See also
window.back
frames
An array of objects corresponding to child frames (created with theFRAME tag) in source order. frames array. This array contains an entry for each child frame (created with the FRAME tag) in a window containing a FRAMESET tag; the entries are in source order. For example, if a window contains three child frames whose NAME attributes are fr1, fr2, and fr3, you can refer to the objects in the images array either as:
parent.frames["fr1"]or as:
parent.frames["fr2"]
parent.frames["fr3"]
parent.frames[0]You can find out how many child frames the window has by using the
parent.frames[1]
parent.frames[2]
length property of the window itself or of the frames array.
The value of each element in the frames array is <object nameAttribute>, where nameAttribute is the NAME attribute of the frame.
handleEvent
Invokes the handler for the specified event.Syntax
handleEvent(event)
Parameters
event | The name of an event for which the specified object has an event handler. |
Description
handleEvent works in tandem with captureEvents, releaseEvents, and routeEvent. For more information, see the Client-Side JavaScript Guide.
history
Contains information on the URLs that the client has visited within a window.Description
The value of this property is the window's associatedHistory object.
home
Points the browser to the URL specified in preferences as the user's home page; equivalent to the user pressing the browser's Home button.Syntax
home()
Parameters
NoneDescription
This method performs the same action as a user choosing the Home button in the browser.innerHeight
Specifies the vertical dimension, in pixels, of the window's content area.Description
To create a window smaller than 100 x 100 pixels, set this property in a signed script.Security
To set the inner height of a window to a size smaller than 100 x 100 or larger than the screen can accommodate, you need theUniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.
See also
window.innerWidth, window.outerHeight, window.outerWidth
innerWidth
Specifies the horizontal dimension, in pixels, of the window's content area.Description
To create a window smaller than 100 x 100 pixels, set this property in a signed script.Security
To set the inner width of a window to a size smaller than 100 x 100 or larger than the screen can accommodate, you need theUniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.
See also
window.innerHeight, window.outerHeight, window.outerWidth
length
The number of child frames in the window.Description
This property gives you the same result as using thelength property of the frames array.
location
Contains information on the current URL.Description
The value of this property is the window's associatedLocation object.
locationbar
Represents the browser window's location bar (the region containing the bookmark and URL areas).Description
The value of thelocationbar property itself has one property, visible. If true, the location bar is visible; if false, it is hidden.
Security
Setting the value of the location bar'svisible property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.
Examples
The following example would make the referenced window "chromeless" (chromeless windows lack toolbars, scrollbars, status areas, and so on, much like a dialog box) by hiding most of the user interface toolbars:self.menubar.visible=false;
self.toolbar.visible=false;
self.locationbar.visible=false;
self.personalbar.visible=false;
self.scrollbars.visible=false;
self.statusbar.visible=false;
menubar
Represents the browser window's menu bar. This region contains the browser's drop-down menus such as File, Edit, View, Go, Communicator, and so on.Description
The value of themenubar property itself has one property, visible. If true, the menu bar is visible; if false, it is hidden.
Security
Setting the value of the menu bar'svisible property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.
Examples
The following example would make the referenced window "chromeless" (chromeless windows lack toolbars, scrollbars, status areas, and so on, much like a dialog box) by hiding most of the user interface toolbars:self.menubar.visible=false;
self.toolbar.visible=false;
self.locationbar.visible=false;
self.personalbar.visible=false;
self.scrollbars.visible=false;
self.statusbar.visible=false;
moveBy
Moves the window relative to its current position, moving the specified number of pixels.Syntax
moveBy(horizontal, vertical)
Parameters
horizontal | The number of pixels by which to move the window horizontally. |
vertical | The number of pixels by which to move the window vertically. |
Description
This method moves the window by adding or subtracting the specified number of pixels to the current location.Security
Exceeding any of the boundaries of the screen (to hide some or all of a window) requires signed JavaScript, so a window won't move past the screen boundaries. You need theUniversalBrowserWrite privilege for this. For information on security, see the Client-Side JavaScript Guide.
Examples:
To move the current window 5 pixels up towards the top of the screen (x-axis), and 10 pixels towards the right (y-axis) of the current window position, use this statement:self.moveBy(-5,10); // relative positioning
See also
window.moveTo
moveTo
Moves the top-left corner of the window to the specified screen coordinates.Syntax
moveTo(x-coordinate, y-coordinate)
Parameters
x-coordinate | |
y-coordinate |
Description
This method moves the window to the absolute pixel location indicated by its parameters. The origin of the axes is at absolute position (0,0); this is the upper left-hand corner of the display.Security
Exceeding any of the boundaries of the screen (to hide some or all of a window) requires signed JavaScript, so a window won't move past the screen boundaries. You need theUniversalBrowserWrite privilege for this. For information on security, see the Client-Side JavaScript Guide.
Examples:
To move the current window to 25 pixels from the top boundary of the screen (x-axis), and 10 pixels from the left boundary of the screen (y-axis), use this statement:self.moveTo(25,10); // absolute positioning
See also
window.moveBy
name
A string specifying the window's name.Security
JavaScript 1.1. This property is tainted by default. For information on data tainting, see the Client-Side JavaScript Guide.Description
In JavaScript 1.0,NAME was a read-only property. In later versions, this property is modifiable by your code. This allows you to assign a name to a top-level window.
Examples
In the following example, the first statement creates a window callednetscapeWin. The second statement displays the value "netscapeHomePage" in the Alert dialog box, because "netscapeHomePage" is the value of the windowName argument of netscapeWin.
netscapeWin=window.open("http://home.netscape.com","netscapeHomePage")
alert(netscapeWin.name)
offscreenBuffering
Specifies whether window updates are performed in an offscreen buffer.Description
By default, Navigator automatically determines whether updates to a window are performed in an offscreen buffer and then displayed in a window. You can either prevent buffering completely or require Navigator to buffer updates by settingoffscreenBuffering to either false or true, respectively.
Buffering can reduce the flicker that occurs during window updates, but it requires additional system resources.
open
Opens a new web browser window.Syntax
open(URL, windowName[, windowFeatures])
Parameters
URL |
A string specifying the URL to open in the new window. See the |
windowName |
A string specifying the window name to use in the |
windowFeatures |
Description
In event handlers, you must specifywindow.open() instead of simply using open(). Due to the scoping of static objects in JavaScript, a call to open() without specifying an object name is equivalent to document.open().
The open method opens a new Web browser window on the client, similar to choosing New, then Navigator Window from the Navigator File menu. The URL argument specifies the URL contained by the new window. If URL is an empty string, a new, empty window is created.
You can use open on an existing window, and if you pass the empty string for the URL, you will get a reference to the existing window, but not load anything into it. You can, for example, then look for properties in the window.
windowFeatures is an optional string containing a comma-separated list of options for the new window (do not include any spaces in this list). After a window is open, you cannot use JavaScript to change the windowFeatures. You can specify the following features:
windowFeatures string.
If windowName does not specify an existing window and you do not supply the windowFeatures parameter, all of the features which have a yes/no choice are yes by default. However, if you do supply the windowFeatures parameter, then the titlebar and hotkeys are still yes by default, but the other features which have a yes/no choice are no by default.
For example, all of the following statements turn on the toolbar option and turn off all other Boolean options:
open("", "messageWindow", "toolbar")The following statement turn on the location and directories options and turns off all other Boolean options:
open("", "messageWindow", "toolbar=yes")
open("", "messageWindow", "toolbar=1")
open("", "messageWindow", "toolbar,directories=yes")How the
alwaysLowered, alwaysRaised, and z-lock features behave depends on the windowing hierarchy of the platform. For example, on Windows, an alwaysLowered or z-locked browser window is below all windows in all open applications. On Macintosh, an alwaysLowered browser window is below all browser windows, but not necessarily below windows in other open applications. Similarly for an alwaysRaised window.
You may use open to open a new window and then use open on that window to open another window, and so on. In this way, you can end up with a chain of opened windows, each of which has an opener property pointing to the window that opened it.
Communicator allows a maximum of 100 windows to be around at once. If you open window2 from window1 and then are done with window1, be sure to set the opener property of window2 to null. This allows JavaScript to garbage collect window1. If you do not set the opener property to null, the window1 object remains, even though it's no longer really needed.
Security
To perform the following operations, you need theUniversalBrowserWrite privilege:
-
To create a window smaller than 100 x 100 pixels or larger than the screen can accommodate by using
innerWidth,innerHeight,outerWidth, andouterHeight. -
To place a window off screen by using
screenXandscreenY. -
To create a window without a titlebar by using
titlebar. -
To use
alwaysRaised,alwaysLowered, orz-lockfor any setting.
Examples
Example 1. In the following example, thewindowOpener function opens a window and uses write methods to display a message:
function windowOpener() {Example 2. The following is an
msgWindow=window.open("","displayWindow","menubar=yes")
msgWindow.document.write
("<HEAD><TITLE>Message window</TITLE></HEAD>")
msgWindow.document.write
("<CENTER><BIG><B>Hello, world!</B></BIG></CENTER>")
}
onClick event handler that opens a new client window displaying the content specified in the file sesame.html. The window opens with the specified option settings; all other options are false because they are not specified.
<FORM NAME="myform">
<INPUT TYPE="button" NAME="Button1" VALUE="Open Sesame!"
onClick="window.open ('sesame.html', 'newWin',
'scrollbars=yes,status=yes,width=300,height=300')">
</FORM>
See also
window.close
opener
Specifies the window of the calling document when a window is opened using theopen method.Description
When a source document opens a destination window by calling theopen method, the opener property specifies the window of the source document. Evaluate the opener property from the destination window.
This property persists across document unload in the opened window.
You can change the opener property at any time.
You may use window.open to open a new window and then use window.open on that window to open another window, and so on. In this way, you can end up with a chain of opened windows, each of which has an opener property pointing to the window that opened it.
Communicator allows a maximum of 100 windows to be around at once. If you open window2 from window1 and then are done with window1, be sure to set the opener property of window2 to null. This allows JavaScript to garbage collect window1. If you do not set the opener property to null, the window1 object remains, even though it's no longer really needed.
Examples
Example 1: Close the opener. The following code closes the window that opened the current window. When the opener window closes,opener is unchanged. However, window.opener.name then evaluates to undefined.
window.opener.close()Example 2: Close the main browser window.
top.opener.close()Example 3: Evaluate the name of the opener. A window can determine the name of its opener as follows:
document.write("<BR>opener property is " + window.opener.name)Example 4: Change the value of opener. The following code changes the value of the
opener property to null. After this code executes, you cannot close the opener window as shown in Example 1.
window.opener=nullExample 5: Change a property of the opener. The following code changes the background color of the window specified by the
opener property.
window.opener.document.bgColor='bisque'
See also
window.close, window.open
outerHeight
Specifies the vertical dimension, in pixels, of the window's outside boundary.Description
The outer boundary includes the scroll bars, the status bar, the toolbars, and other "chrome" (window border user interface elements). To create a window smaller than 100 x 100 pixels, set this property in a signed script.See also
window.innerWidth, window.innerHeight, window.outerWidth
outerWidth
Specifies the horizontal dimension, in pixels, of the window's outside boundary.Description
The outer boundary includes the scroll bars, the status bar, the toolbars, and other "chrome" (window border user interface elements). To create a window smaller than 100 x 100 pixels, set this property in a signed script.See also
window.innerWidth, window.innerHeight, window.outerHeight
pageXOffset
Provides the current x-position, in pixels, of a window's viewed page.Description
ThepageXOffset property provides the current x-position of a page as it relates to the upper-left corner of the window's content area. This property is useful when you need to find the current location of the scrolled page before using scrollTo or scrollBy.
Examples
The following example returns the x-position of the viewed page.x = myWindow.pageXOffset
See Also
window.pageYOffset
pageYOffset
Provides the current y-position, in pixels, of a window's viewed page.Description
ThepageYOffset property provides the current y-position of a page as it relates to the upper-left corner of the window's content area. This property is useful when you need to find the current location of the scrolled page before using scrollTo or scrollBy.
Examples
The following example returns the y-position of the viewed page.x = myWindow.pageYOffset
See also
window.pageXOffset
parent
Theparent property is the window or frame whose frameset contains the current frame.Description
This property is only meaningful for frames; that is, windows that are not top-level windows. Theparent property refers to the FRAMESET window of a frame. Child frames within a frameset refer to sibling frames by using parent in place of the window name in one of the following ways:
parent.frameNameFor example, if the fourth frame in a set has
parent.frames[index]
NAME="homeFrame", sibling frames can refer to that frame using parent.homeFrame or parent.frames[3].
You can use parent.parent to refer to the "grandparent" frame or window when a FRAMESET tag is nested within a child frame.
The value of the parent property is
<object nameAttribute>where
nameAttribute is the NAME attribute if the parent is a frame, or an internal reference if the parent is a window.
Examples
See examples forFrame.
personalbar
Represents the browser window's personal bar (also called the directories bar). This is the region the user can use for easy access to certain bookmarks.Description
The value of thepersonalbar property itself has one property, visible. If true, the personal bar is visible; if false, it is hidden.
Security
Setting the value of the personal bar'svisible property requires the UniversalBrowserWrite privilege. For information on security, see the Client-Side JavaScript Guide.
Examples
The following example would make the referenced window "chromeless" (chromeless windows lack toolbars, scrollbars, status areas, and so on, much like a dialog box) by hiding most of the user interface toolbars:self.menubar.visible=false;
self.toolbar.visible=false;
self.locationbar.visible=false;
self.personalbar.visible=false;
self.scrollbars.visible=false;
self.statusbar.visible=false;
Syntax
print()
Parameters
Noneprompt
Displays a Prompt dialog box with a message and an input field.Syntax
prompt(message[, inputDefault])
Parameters
message | |
inputDefault | A string or integer representing the default value of the input field. |
Description
A prompt dialog box looks as follows:
prompt method to display a dialog box that receives user input. If you do not specify an initial value for inputDefault, the dialog box displays <undefined>.
You cannot specify a title for a prompt dialog box, but you can use the open method to create your own prompt dialog. See open.