Methods

[Contents] [Previous] [Next] [Last]

Chapter 4
Methods

This section describes the new and revised methods for the following objects:

Array

Document

Navigator

String

Window

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):

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`

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()

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>

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.

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.

open

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 window.open in the JavaScript Reference.

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.

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.

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

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

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

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

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. For information on the debugger, see Getting Started with Netscape JavaScript Debugger.

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.

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]

Last Updated: 10/22/97 11:48:03

Chapter 4 Methods

Document Method

getSelection

Syntax

Method of

Navigator Method

preference

Syntax

Parameters

Method of

Description

Example

Window Methods

back

Syntax

Parameters

Method of

clearInterval

Syntax

Parameters

Method of

Description

See Also

disableExternalCapture

Syntax

Method of

Description

enableExternalCapture

Syntax

Method of

Description

Example

See also

find

Syntax

Parameters

Returns

Method of

Description

forward

Syntax

Parameters

Method of

home

Syntax

Parameters

Method of

moveBy

Syntax

Parameters

Method of

Description

See Also

moveTo

Syntax

Parameters

Method of

Description

See Also

open

Syntax

Parameters

Method of

print

Syntax

Parameters

Method of

resizeBy

Syntax

Parameters

Method of

Description

See Also

resizeTo

Syntax

Parameters

Method of

Description

See Also

scrollBy

Chapter 4
Methods