This section describes the new and revised methods for the following objects:
In addition, Shared Methods describes methods used by several objects.
Client-side method. Returns a string containing the text of the current selection.
document.getSelection()
document object
Client-side method. Allows a signed script to get and set certain Navigator preferences.
Note: This method must be called in a signed script.
To set a preference:
navigator.preference(prefName)
To set a preference:
navigator.preference(prefName, setValue)
prefName is the name of the preference you want to get or set. Description lists the allowed preferences.
setValue is the value you want to assign to the preference. This can be a string, number, or Boolean.
navigator object
This method must be used in a signed script that has UniversalPreferencesRead or UniversalPreferencesWrite permission.
With permission, you can get and set the following preferences (additional preferences will be included in future documentation):
Task from Navigator Advanced Preferences |
Preference | Value |
Automatically load images | general.always_load_images | true or false |
Enable Java | security.enable_java | true or false |
Enable JavaScript | javascript.enabled | true or false |
Enable style sheets | browser.enable_style_sheets | true or false |
Enable autoinstall | autoupdate.enabled | true or false |
Accept all cookies | network.cookie.cookieBehavior | 0 |
Accept only cookies that get sent back to the originating server |
network.cookie.cookieBehavior | 1 |
Disable cookies | network.cookie.cookieBehavior | 2 |
Warn before accepting cookie | network.cookie.warnAboutCookies | true or false |
Client-side method. Points the Navigator to the previous URL in the current history list; equivalent to the user pressing the Navigator Back button.
windowReference.back()
windowReference is the name of a window object.
window object
Client-side method. Disables external event capturing set by the enableExternalCapture method.
disableExternalCapture()
window object
See the description for enableExternalCapture method.
Client-side method. Allows a window with frames to capture events in pages loaded from different locations (servers).
enableExternalCapture( )
window object
Use this method in a signed script requesting UniversalBrowserWrite privileges, and use it before calling the captureEvents method.
If additional scripts are seen by Communicator that cause the set of principals in effect for the container to be downgraded, external capture of events will be disabled. Additional calls to enableExternalCapture (after acquiring the UniversalBrowserWrite privilege under the reduced set of principals) can be made to enable external capture again.
In the following example, the window is able to capture all Click events that occur across its frames.
<SCRIPT ARCHIVE="myArchive.jar" ID="2">
...
function captureClicks() { netscape.security.PrivilegeManager.enablePrivilege("UniversalBrowserWrite"); enableExternalCapture(); captureEvents(Event.CLICK); ... }
...
</SCRIPT>
disableExternalCapture method and captureEvents method
Client-side method. Finds the specified text string in the contents of the specified window.
windowReference.find(["string"][,true|false][,true|false])
windowReference is the name of a window object.
string is the text string for which to search.
true if the string is found; otherwise false.
window object
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 the search string.
The two optional Boolean parameters allow you to specify search options. The first parameter, if true, specifies a case-sensitive search. The second parameter, if true, specifies a backward search. To use either parameter, both must be specified.
Client-side method. Points the Navigator to the next URL in the current history list; equivalent to the user pressing the Navigator Forward button.
windowReference.forward()
windowReference is the name of a window object.
window object
Client-side method. Points the Navigator to the URL specified in preferences as the user's home page; equivalent to the user pressing the Navigator Home button.
windowReference.home()
windowReference is the name of a window object.
window object
Client-side method. Moves the window by the specified amounts.
windowReference.moveBy(horizontal, vertical)
windowReference is a valid way of referring to a window.
horizontal is an integer representing the number of pixels by which to move the window horizontally.
vertical is an integer representing the number of pixels by which to move the window vertically.
window object
To move a window offscreen, call this method in a signed script.
moveTo method
Client-side method. Moves the top-left corner of the window to the specified screen coordinates.
windowReference.moveTo(x-coordinate, y-coordinate)
windowReference is a valid way of referring to a window.
x-coordinate is an integer representing the left edge of the window in screen coordinates.
y-coordinate is an integer representing the top edge of the window in screen coordinates.
window object
To move a window offscreen, call this method in a signed script.
moveBy method
Client-side method. Opens a new web browser window. The following provides a description of the open method and the new window features. For a complete description of open, see open (window object) in the "JavaScript Guide."
[windowVar = ][window].open("URL", "windowName", ["windowFeatures"])
windowVar is the name of a new window. Use this variable when referring to a window's properties, methods, and containership.
URL specifies the URL to open in the new window.
windowName is the window name to use in the TARGET attribute of a FORM or <A> tag. windowName can contain only alphanumeric or underscore (_) characters.
windowFeatures is a comma-separated list of any of the following options and values:
alwaysLowered [=yes|no]|[=1|0] alwaysRaised [=yes|no]|[=1|0] dependent [=yes|no]|[=1|0] hotkeys [=yes|no]|[=1|0] innerWidth=pixels replaces width innerHeight=pixels replaces height outerWidth=pixels outerHeight=pixels screenX=pixels screenY=pixels titlebar [=yes|no]|[=1|0] z-lock [=yes|no]|[=1|0]
Note: Several of these features require the use of signed scripts. This is stated in the feature's description.
Not specifying a chrome part is equivalent to setting the property to no (except for hotkeys and titlebar which are set to true by default).
alwaysRaised if true, creates a new window that floats on top of other windows, whether it is active or not. This is a secure feature and must be set in signed scripts.
alwaysLowered if true, creates a new window that floats below other windows, whether it is active or not. This is a secure feature and must be set in signed scripts.
dependent if true, creates a new window as a child of the current window. A dependent window closes when its parent window closes. On Windows platforms, a dependent window does not show on the taskbar.
hotkeys if true, disables most hotkeys in a new window that has no menu bar. The security and quit hotkeys remain enabled.
innerWidth specifies the width, in pixels, of the window's content area. To create a window smaller than 100 x 100 pixels, set this feature in a signed script.
innerHeight specifies the height, in pixels, of the window's content area. To create a window smaller than 100 x 100 pixels, set this feature in a signed script.
outerWidth specifies the horizontal dimension, in pixels, of the window's outside boundary. To create a window smaller than 100 x 100 pixels, set this feature in a signed script.
outerHeight specifies the vertical dimension, in pixels, of the outside boundary of the window. To create a window smaller than 100 x 100 pixels, set this feature in a signed script.
screenX is the distance the new window is placed from the left side of the screen. To place a window offscreen, set this feature in a signed scripts.
screenY is the distance the new window is placed from the top of the screen. To place a window offscreen, set this feature in a signed scripts.
titlebar if true, creates a window with a title bar. To set the titlebar to false, set this feature in a signed script.
z-lock if true, creates a new window that does not rise above other windows when activated. This is a secure feature and must be set in signed scripts.
window object
Client-side method. Resizes the entire window by moving the window's bottom-right corner by the specified amount.
windowReference.resizeBy(horizontal, vertical)
windowReference is a valid way of referring to a window.
horizontal is an integer representing the number of pixels by which to resize the window horizontally.
vertical is an integer representing the number of pixels by which to resize the window vertically.
window object
To resize a window below a minimum size of 100 x 100 pixels, call this method in a signed script.
resizeTo method
Client-side method. Resizes the entire window to the specified outer height and width.
windowReference.resizeTo(outerwidth, outerheight)
windowReference is a valid way of referring to a window.
outerwidth is an integer representing the window's width in pixels.
outerheight is an integer representing the window's height in pixels.
window object
To resize a window below a minimum size of 100 x 100 pixels, call this method in a signed script.
resizeBy method
Client-side method. Scrolls the viewing area of the window by the given amount.
windowReference.scrollBy(horizontal, vertical)
windowReference is a valid way of referring to a window.
horizontal is an integer representing the number of pixels by which to scroll the viewing area horizontally.
vertical is an integer representing the number of pixels by which to scroll the viewing area vertically.
window object
scrollTo method
Client-side method. Scrolls the viewing area of the window to the specified coordinates, such that the point (x, y) becomes the top-left corner.
Note: scrollTo extends the capabilities of scroll. scroll remains for backward compatibility.
windowReference.scrollTo(x-coordinate, y-coordinate)
windowReference is a valid way of referring to a window.
x-coordinate is an integer representing the x-coordinate of the viewing area in pixels.
y-coordinate is an integer representing the y-coordinate of the viewing area in pixels.
window object
scrollBy method
Client-side method. Stops the current download; equivalent to the user pressing the Navigator Stop button.
windowReference.stop()
windowReference is the name of a window object.
window object
Client-side method. Sets the window or document to capture all events of the specified type.
objectReference.captureEvents(eventType)
objectReference is the name of a window or document object.
eventType is the type of event to be captured. The available event types are listed with the event object.
window, document, and layer objects
When a window with frames wants to capture events in pages loaded from different locations (servers), you need to use captureEvents in a signed script and precede it with enableExternalCapture. For more information and an example, see enableExternalCapture.
captureEvents works in tandem with releaseEvents, routeEvent, and handleEvent. For more information, see Event Capturing.
Client-side method. Cancels a timeout set with the setInterval method.
clearInterval(intervalID)
intervalID is a timeout setting that was returned by a previous call to the setInterval method.
Frame object, window object
See the description for setInterval method.
setInterval method
Client-side method. Invokes the handler for the specified event.
objectReference.handleEvent(event)
objectReference is the name of an object.
event is the name of an event for which the specified object has an event handler.
objects with event handlers
handleEvent works in tandem with captureEvents, releaseEvents, and routeEvent. For more information, see Event Capturing.
Client-side method. Prints the contents of the window or frame; equivalent to the user pressing the Navigator Print button.
windowReference.print()
frameReference.print()
windowReference is the name of a window object.
frameReference is the name of a frame object.
window and Frame objects
Client-side method. Sets the window or document to release captured events of the specified type, sending the event to objects further along the event hierarchy.
Note: If the original target of the event is a window, the window receives the event even if it is set to release that type of event.
objectReference.releaseEvents(eventType)
objectReference is the name of a window, document, or layer object.
eventType is the type of event to be captured.
window, document, and layer objects
releaseEvents works in tandem with captureEvents, routeEvent, and handleEvent. For more information, see Event Capturing.
Client-side method. Passes a captured event along the normal event hierarchy.
objectReference.routeEvent(event)
objectReference is the name of a window, document, or layer object.
event is the name of the event to be routed.
window, document, and layer objects
If a sub-object (document or layer) is also capturing the event, the event is sent to that object. Otherwise, it is sent to its original target.
routeEvents works in tandem with captureEvents, releaseEvents, and handleEvent. For more information, see Event Capturing.
Client-side method. Repeatedly calls a function or evaluates an expression after a specified number of milliseconds has elapsed.
The timeouts continue to fire until the associated window or frame is destroyed or the interval is canceled using the clearInterval method.
Used to call a function:
intervalID=setInterval(function, msec, [arg1, ..., argn])
Used to evaluate an expression:
intervalID=setInterval(expression, msec)
intervalID is an identifier that is used only to cancel the function call with the clearInterval method.
function is any function.
expression is a string expression or a property of an existing object. The expression must be quoted; otherwise, setInterval calls it immediately. For example setInterval("calcnum(3, 2)", 25).
msec is a numeric value, numeric string, or a property of an existing object in millisecond units.
arg1, ..., argn are the arguments, if any, passed to function.
Frame object, window object
clearInterval and setTimeout methods
Client-side method. Calls a function or evaluates an expression after a specified number of milliseconds has elapsed.
The setTimeout method calls a function after a specified amount of time. It does not call the function repeatedly. For example, if a setTimeout method specifies five seconds, the function is evaluated after five seconds, not every five seconds. For repetitive timeouts, use the setInterval method.
setTimeout does not stall the script. The script continues immediately (not waiting for the timeout to expire). The call simply schedules an additional future event.
Used to call a function:
timeoutID=setTimeout("function", msec, [arg1, ..., argn])
Used to evaluate an expression:
timeoutID=setTimeout(expression, msec)
timeoutID is an identifier that is used only to cancel the evaluation with the clearTimeout method.
function is any function.
expression is a string expression or a property of an existing object. The expression must be quoted; otherwise, setTimeout calls it immediately. For example setTimeout("calcnum(3, 2)", 25).
msec is a numeric value, numeric string, or a property of an existing object in millisecond units.
arg1, ..., argn are the arguments, if any, passed to function.
Frame object, window object
clearTimeout in the "JavaScript Guide" and setInterval methods
Client-side method. If you specify LANGUAGE="JavaScript1.2" in the script tag, using the toString method converts objects and arrays to literals. An object literal has the form {property1:value1, property2:value2, ...}. An array literal has the form [element0, element1, ...].
Converting to literals allows you to capture a persistent form of the object for debugging or as source for another JavaScript program.
The following example converts myHonda to a literal.
<SCRIPT LANGUAGE="JavaScript1.2"> myHonda = new Object(); myHonda.color = "red"; myHonda.wheels = 4; document.write(myHonda.toString()); </SCRIPT>
Prints {color:"red", wheels:4}
Without LANGUAGE="JavaScript1.2" in the <SCRIPT> tag, this prints [object Object]