[Previous] [Next] [TOC] 


Methods

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

In addition, Shared Methods 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 set a preference:

navigator.preference(prefName)

To set a preference:

navigator.preference(prefName, setValue)

Parameters

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.

Method of

navigator object

Description

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


Window Methods

back

Client-side method. Points the Navigator to the previous URL in the current history list; equivalent to the user pressing the Navigator Back button.

Syntax

windowReference.back()

Parameters

windowReference is the name of a window object.

Method of

window object


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

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."

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:

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.

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 extends the capabilities of 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


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

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.


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

Frame object, window object

Description

See the description for setInterval method.

See Also

setInterval method


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.


print

Client-side method. Prints the contents of the window or frame; equivalent to the user pressing the Navigator Print button.

Syntax

windowReference.print()
frameReference.print()

Parameters

windowReference is the name of a window object.

frameReference is the name of a frame object.

Method of

window and Frame objects


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 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.


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 or frame 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

Frame object, 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

Frame object, window object

See Also

clearTimeout in the "JavaScript Guide" and setInterval methods


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]


[Previous] [Next] [TOC] 



Copyright © 1997 Netscape Communications Corporation