[Contents] [Previous] [Next]
[Last]
This section describes the new and revised methods for the following objects:
In addition, "Shared
Methods" on page 52 describes methods used by several objects.
Document Method
getSelection
Client-side method. Returns a string containing the text of the current selection.
Syntax
document.getSelection()
Method of
document object
Navigator Method
preference
Client-side method. Allows a signed script to get and set certain Navigator
preferences.
NOTE: This method must be called in a signed
script.
Syntax
To get a preference:
navigator.preference(prefName)
To set a preference to a particular value:
navigator.preference(prefName, setValue)
Parameters
prefName is a string that names the preference you want to get or set. The
allowed preferences are listed below.
setValue is the value you want to assign to the
preference. This can be a string, number, or Boolean, depending on the preference.
Method of
navigator object
Description
This method must be used in a signed script that has UniversalPreferencesRead
or UniversalPreferencesWrite permission.
The preference method returns the value of the
preference. If you use this method to set a preference, it returns the new value.
With permission, you can get and set the following preferences
(additional preferences will be included in future documentation):
Example
The following code turns off the automatic loading of images in the browser:
navigator.preference ("general.always_load_images", false);
Window Methods
back
Client-side method. Calling the back method is equivalent to the user
pressing the Navigator 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().
Syntax
windowReference.back()
Parameters
windowReference is the name of a window object.
Method of
window object
clearInterval
Client-side method. Cancels a timeout set with the setInterval
method.
Syntax
clearInterval(intervalID)
Parameters
intervalID is a timeout setting that was returned by a previous call to
the setInterval
method.
Method of
window object
Description
See the description for setInterval
method.
See Also
setInterval method
disableExternalCapture
Client-side method. Disables external event capturing set by the enableExternalCapture
method.
Syntax
disableExternalCapture()
Method of
window object
Description
See the description for enableExternalCapture
method.
enableExternalCapture
Client-side method. Allows a window with frames to capture events in pages loaded from
different locations (servers).
Syntax
enableExternalCapture()
Method of
window object
Description
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.
Example
In the following example, the window is able to capture all Click events that occur
across its frames.
<SCRIPT LANGUAGE="JavaScript1.2" ARCHIVE="myArchive.jar" ID="2">
...
function captureClicks() {
netscape.security.PrivilegeManager.enablePrivilege(
"UniversalBrowserWrite");
enableExternalCapture();
captureEvents(Event.CLICK);
...
}
...
</SCRIPT>
See also
disableExternalCapture method and captureEvents
method
find
Client-side method. Finds the specified text string in the contents of the specified
window.
Syntax
windowReference.find(["string"][,true|false][,true|false])
Parameters
windowReference is the name of a window object.
string is the text string for which to search.
Returns
true if the string is found; otherwise false.
Method of
window object
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 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.
forward
Client-side method. Points the Navigator to the next URL in the current history list;
equivalent to the user pressing the Navigator Forward button.
Syntax
windowReference.forward()
Parameters
windowReference is the name of a window object.
Method of
window object
home
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.
Syntax
windowReference.home()
Parameters
windowReference is the name of a window object.
Method of
window object
moveBy
Client-side method. Moves the window by the specified amounts.
Syntax
windowReference.moveBy(horizontal, vertical)
Parameters
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.
Method of
window object
Description
To move a window offscreen, call this method in a signed
script.
See Also
moveTo method
moveTo
Client-side method. Moves the top-left corner of the window to the specified screen
coordinates.
Syntax
windowReference.moveTo(x-coordinate, y-coordinate)
Parameters
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.
Method of
window object
Description
To move a window offscreen, call this method in a signed
script.
See Also
moveBy method
open
Client-side method. Opens a new web browser window. The following provides a
description of the open method and the new window features.
Syntax
[windowVar = ][window].open("URL", "windowName", ["windowFeatures"])
Parameters
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).
| Feature |
Description |
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. How this feature behaves depends on
the windowing hierarchy of the platform. For example, on Windows, an alwaysRaised
Navigator window is on top of all windows in all open applications. On Macintosh, an alwaysRaised
Navigator window 1is on top of all Navigator windows, but not necessarily on top of
windows in other open applications. |
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. How this feature behaves depends on the
windowing hierarchy of the platform. For example, on Windows, an alwaysLowered
Navigator window is below all windows in all open applications. On Macintosh, an alwaysLowered
Navigator window is below all Navigator windows, but not necessarily below windows in
other open applications. |
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 false, 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. Replaces width. width
remains for backwards compatibility. |
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. Replaces height. height
remains for backwards compatibility. |
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
|
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
|
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. How this feature behaves depends on the windowing
hierarchy of the platform. For example, on Windows, a z-locked Navigator
window is below all windows in all open applications. On Macintosh, a z-locked
Navigator window is below all Navigator windows, but not necessarily below windows in
other open applications. |
Method of
window object
print
Client-side method. Prints the contents of the window; equivalent to the user pressing
the Navigator Print button.
Syntax
windowReference.print()
Parameters
windowReference is the name of a window object.
Method of
window object
resizeBy
Client-side method. Resizes the entire window by moving the window's bottom-right
corner by the specified amount.
Syntax
windowReference.resizeBy(horizontal, vertical)
Parameters
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.
Method of
window object
Description
To resize a window below a minimum size of 100 x 100 pixels, call this method in a signed
script.
See Also
resizeTo method
resizeTo
Client-side method. Resizes the entire window to the specified outer height and width.
Syntax
windowReference.resizeTo(outerwidth, outerheight)
Parameters
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.
Method of
window object
Description
To resize a window below a minimum size of 100 x 100 pixels, call this method in a signed
script.
See Also
resizeBy method
scrollBy
Client-side method. Scrolls the viewing area of the window by the given amount.
Syntax
windowReference.scrollBy(horizontal, vertical)
Parameters
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.
Method of
window object
See Also
scrollTo method
scrollTo
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 replaces scroll.
scroll remains for backward compatibility.
Syntax
windowReference.scrollTo(x-coordinate, y-coordinate)
Parameters
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.
Method of
window object
See Also
scrollBy method
setInterval
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 is
destroyed or the interval is canceled using the clearInterval
method.
Syntax
Used to call a function:
intervalID=setInterval(function, msec, [arg1, ..., argn])
Used to evaluate an expression:
intervalID=setInterval(expression, msec)
Parameters
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.
Method of
window object
See Also
clearInterval and setTimeout
methods
setTimeout
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.
Syntax
Used to call a function:
timeoutID=setTimeout("function", msec, [arg1, ..., argn])
Used to evaluate an expression:
timeoutID=setTimeout(expression, msec)
Parameters
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.
Method of
window object
See Also
setInterval
methods
stop
Client-side method. Stops the current download; equivalent to the user pressing the
Navigator Stop button.
Syntax
windowReference.stop()
Parameters
windowReference is the name of a window object.
Method of
window object
Shared Methods
eval
Core method and global function. In Navigator 2.0, eval was a
top-level function. In Navigator 3.0 eval was also a method of every
object. The ECMA-262 standard for JavaScript made eval available only as a top-level
function. For this reason, in Navigator 4.0, eval is once again a
top-level function.
For backward compatibility, in Navigator 4.02, obj.eval(str)
is equilvalent in all scopes to with(obj)eval(str), except of course that the
latter is a statement, not an expression.
watch
Core method of all objects. Watches for a property to be assigned a value and runs a
function when that occurs.
Syntax
objectReference.watch(prop, handler)
Parameters
objectReference is the name of an object.
prop is the name of a property of objectReference.
handler is a function to call.
Method of
all objects
Description
Watches for assignment to a property named prop in objectReference,
calling handler(prop, oldval, newval) whenever prop is set and
storing the return value in that property. A watchpoint can filter (or nullify) the value
assignment, by returning a modified newval (or oldval).
If you delete a property for which a watchpoint has been set,
that watchpoint does not disappear. If you later recreate the property, the watchpoint is
still in effect.
To remove a watchpoint, use the unwatch
method.
The JavaScript debugger has functionality similar to that provided by
this method, as well as other debugging options.
Example
<script language="JavaScript1.2">
o = {p:1}
o.watch("p",
function (id,oldval,newval) {
document.writeln("o." + id + " changed from "
+ oldval + " to " + newval)
return newval
})
o.p = 2
o.p = 3
delete o.p
o.p = 4
o.unwatch('p')
o.p = 5
</script>
This script displays the following:
o.p changed from 1 to 2
o.p changed from 2 to 3
o.p changed from 3 to 4
unwatch
Core method of all objects. Removes a watchpoint set with the watch
method.
The JavaScript debugger has functionality similar to that provided by
this method, as well as other debugging options.
Syntax
objectReference.unwatch(prop)
Parameters
objectReference is the name of an object.
prop is the name of a property of objectReference.
Method of
all objects
Example
See watch.
captureEvents
Client-side method. Sets the window or document to capture all events of the specified
type.
Syntax
objectReference.captureEvents(eventType)
Parameters
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.
Method of
window , document, and layer objects
Description
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".
handleEvent
Client-side method. Invokes the handler for the specified event.
Syntax
objectReference.handleEvent(event)
Parameters
objectReference is the name of an object.
event is the name of an event for which the
specified object has an event handler.
Method of
objects with event handlers
Description
handleEvent works in tandem with captureEvents,
releaseEvents,
and routeEvent.
For more information, see Event
Capturing.
releaseEvents
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.
Syntax
objectReference.releaseEvents(eventType)
Parameters
objectReference is the name of a window, document, or layer object.
eventType is the type of event to be captured.
Method of
window , document, and layer objects
Description
releaseEvents works in tandem with captureEvents,
routeEvent,
and handleEvent.
For more information, see "Event
Capturing".
routeEvent
Client-side method. Passes a captured event along the normal event hierarchy.
Syntax
objectReference.routeEvent(event)
Parameters
objectReference is the name of a window, document, or layer object.
event is the name of the event to be routed.
Method of
window , document, and layer objects
Description
If a subobject (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".
toString
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.
Example
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].
[Contents] [Previous] [Next]
[Last]
|
