Navigator JavaScript reference

his chapter is an alphabetical reference of all objects, properties, methods, event handlers, and functions.

For each property, the "Tainted?" section indicates whether the property is tainted by default. For information on tainting, see "Using data tainting for security", "taint", and "untaint".


abs

Method. Returns the absolute value of a number.

Syntax

Math.abs(number)

Parameters

number is any numeric expression or a property of an existing object.

Method of

Math

Implemented in

Navigator 2.0

Examples

The following function returns the absolute value of the variable x:

function getAbs(x) {
   return Math.abs(x)
}


acos

Method. Returns the arc cosine (in radians) of a number.

Syntax

Math.acos(number)

Parameters

number is a numeric expression between -1 and 1, or a property of an existing object.

Method of

Math

Implemented in

Navigator 2.0

Description

The acos method returns a numeric value between zero and pi radians. If the value of number is outside this range, it returns zero.

Examples

The following function returns the arc cosine of the variable x:

function getAcos(x) {
   return Math.acos(x)
}

If you pass getAcos the value -1, it returns 3.141592653589793; if you pass it the value two, it returns zero because two is out of range.

See also

asin, atan, atan2, cos, sin, tan methods


action

Property. A string specifying a destination URL for form data that is submitted.

Syntax

formName.action

Parameters

formName is either the name of a form or an element in the forms array.

Property of

Form object

Implemented in

Navigator 2.0

Tainted?

Yes

Description

The action property is a reflection of the ACTION attribute of the <FORM> tag. Each section of a URL contains different information. See the location object for a description of the URL components.

You can set the action property at any time.

Examples

The following example sets the action property of the musicForm form to the value of the variable urlName:

document.musicForm.action=urlName

See also

encoding, method, target properties; Form object


alert

Method. Displays an Alert dialog box with a message and an OK button.

Syntax

alert("message")

Parameters

message is any string or a property of an existing object.

Method of

window object

Implemented in

Navigator 2.0

Description

An alert dialog box looks as follows:

Use the alert method to display a message that does not require a user decision. The message argument specifies a message that the dialog box contains.

Although alert is a method of the window object, you do not need to specify a windowReference when you call it. For example, windowReference.alert() is unnecessary.

You cannot specify a title for an alert dialog box, but you can use the open method to create your own "alert" dialog. See open (window object).

Examples

In the following example, the testValue 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) {
   if (textElement.length > 8) {
      alert("Please enter a name that is 8 characters or less")
   }
}

You can call the 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

confirm, prompt methods


alinkColor

Property. A string specifying the color of an active link (after mouse-button down, but before mouse-button up).

Syntax

document.alinkColor

Property of

document

Implemented in

Navigator 2.0

Tainted?

No

Description

The alinkColor property is expressed as a hexadecimal RGB triplet or as one of the string literals listed in "Color values". This property is the JavaScript reflection of the ALINK attribute of the <BODY> tag. You cannot set this property after the HTML source has been through layout.

If you express the color as a hexadecimal RGB triplet, you must use the format rrggbb. For example, the hexadecimal RGB values for salmon are red=FA, green=80, and blue=72, so the RGB triplet for salmon is "FA8072."

Examples

The following example sets the color of active links using a string literal:

document.alinkColor="aqua"

The following example sets the color of active links to aqua using a hexadecimal triplet:

document.alinkColor="00FFFF"

See also

bgColor, fgColor, linkColor, vlinkColor properties


anchor method

Method. Creates an HTML anchor that is used as a hypertext target.

Syntax

text.anchor(nameAttribute)

Parameters

text is any string or a property of an existing object.

nameAttribute is any string or a property of an existing object.

Method of

String

Implemented in

Navigator 2.0

Description

Use the anchor method with the write or writeln methods to programmatically create and display an anchor in a document. Create the anchor with the anchor method, and then call write or writeln to display the anchor in a document.

In the syntax, the text string represents the literal text that you want the user to see. The nameAttribute string represents the NAME attribute of the <A> tag.

Anchors created with the anchor method become elements in the anchors array. See the Anchor object for information about the anchors array.

Examples

The following example opens the msgWindow window and creates an anchor for the Table of Contents:

var myString="Table of Contents"

msgWindow.document.writeln(myString.anchor("contents_anchor"))

The previous example produces the same output as the following HTML:

<A NAME="contents_anchor">Table of Contents</A>

See also

link method


Anchor object

Object. A place in a document that is the target of a hypertext link.

HTML syntax

To define an anchor, use standard HTML syntax:

<A [HREF=locationOrURL]
   NAME="anchorName"
   [TARGET="windowName"]>
   anchorText
</A>

You can also define an anchor using the anchor method.

HTML attributes

HREF=locationOrURL is used only if the anchor is also a link. It identifies a destination anchor or URL for the link. See the Link object for details.

NAME="anchorName" specifies a name for the anchor. A link to the anchor uses this value for its HREF attribute. You can use this name when indexing the anchors array.

TARGET="windowName" is used only if the anchor is also a link. It specifies the window that the link is loaded into. See the Link object for details.

anchorText specifies the text or HTML source to display at the anchor.

Property of

document

Implemented in

Navigator 2.0

Description

If an Anchor object is also a Link object, the object has entries in both the anchors and links arrays.

The anchors array

You can reference the Anchor objects in your code by using the anchors array. This array contains an entry for each <A> tag containing a NAME attribute in a document in source order. For example, if a document contains three named anchors, these anchors are reflected as document.anchors[0], document.anchors[1], and document.anchors[2].

To use the anchors array:

1. document.anchors[index]
2. document.anchors.length

index is an integer representing an anchor in a document or the name of an Anchor object as specified by the NAME attribute.

To obtain the number of anchors in a document, use the length property: document.anchors.length. If a document names anchors in a systematic way using natural numbers, you can use the anchors array and its length property to validate an anchor name before using it in operations such as setting location.hash. See the example below.

Elements in the anchors array are read-only. For example, the statement document.anchors[0]="anchor1" has no effect.

Properties

The anchors object has no properties.

The anchors array has the following properties:

Property Description
length
Reflects the number of named anchors in the document

Methods

Event handlers

None.

Examples

Example 1: An anchor. The following example defines an anchor for the text "Welcome to JavaScript":

<A NAME="javascript_intro"><H2>Welcome to JavaScript</H2></A>

If the preceding anchor is in a file called intro.html, a link in another file could define a jump to the anchor as follows:

<A HREF="intro.html#javascript_intro">Introduction</A>

Example 2: anchors array. The following example opens two windows. The first window contains a series of buttons that set location.hash in the second window to a specific anchor. The second window defines four anchors named "0," "1," "2," and "3." (The anchor names in the document are therefore 0, 1, 2, ... (document.anchors.length-1).) When a button is pressed in the first window, the onClick event handler verifies that the anchor exists before setting window2.location.hash to the specified anchor name.

link1.html, which defines the first window and its buttons, contains the following code:

<HTML>
<HEAD>
<TITLE>Links and Anchors: Window 1</TITLE>
</HEAD>
<BODY>
<SCRIPT>
window2=open("link2.html","secondLinkWindow",
          "scrollbars=yes,width=250, height=400")
function linkToWindow(num) {
   if (window2.document.anchors.length > num)
      window2.location.hash=num
   else
      alert("Anchor does not exist!")
}
</SCRIPT>
<B>Links and Anchors</B>
<FORM>
<P>Click a button to display that anchor in window #2
<P><INPUT TYPE="button" VALUE="0" NAME="link0_button"
   onClick="linkToWindow(this.value)">
<INPUT TYPE="button" VALUE="1" NAME="link0_button"
   onClick="linkToWindow(this.value)">
<INPUT TYPE="button" VALUE="2" NAME="link0_button"
   onClick="linkToWindow(this.value)">
<INPUT TYPE="button" VALUE="3" NAME="link0_button"
   onClick="linkToWindow(this.value)">
<INPUT TYPE="button" VALUE="4" NAME="link0_button"
   onClick="linkToWindow(this.value)">
</FORM>
</BODY>
</HTML>

link2.html, which contains the anchors, contains the following code:

<HTML>
<HEAD>
<TITLE>Links and Anchors: Window 2</TITLE>
</HEAD>
<BODY>
<A NAME="0"><B>Some numbers</B> (Anchor 0)</A>
<UL><LI>one
<LI>two
<LI>three
<LI>four</UL>

<P><A NAME="1"><B>Some colors</B> (Anchor 1)</A>
<UL><LI>red
<LI>orange
<LI>yellow
<LI>green</UL>

<P><A NAME="2"><B>Some music types</B> (Anchor 2)</A>
<UL><LI>R&B
<LI>Jazz
<LI>Soul
<LI>Reggae
<LI>Rock</UL>

<P><A NAME="3"><B>Some countries</B> (Anchor 3)</A>
<UL><LI>Afghanistan
<LI>Brazil
<LI>Canada
<LI>Finland
<LI>India</UL>
</BODY>
</HTML>

See also

Link object, anchor method


anchors

Property. An array of objects corresponding to named anchors in source order. See the Anchor object for information.

Tainted?

No


appCodeName

Property. A string specifying the code name of the browser.

Syntax

navigator.appCodeName

Property of

navigator

Implemented in

Navigator 2.0

Tainted?

No

Description

appCodeName is a read-only property.

Examples

The following example displays the value of the appCodeName property:

document.write("The value of navigator.appCodeName is " +
   navigator.appCodeName)

For Navigator 2.0 and 3.0, this displays the following:

The value of navigator.appCodeName is Mozilla

See also

appName, appVersion, javaEnabled, userAgent properties


Applet

Object. Includes a Java applet in a web page.

HTML syntax

To include a Java applet in a web page, use standard HTML syntax:

<APPLET
   CODE=classFileName
   HEIGHT=height
   WIDTH=width
   MAYSCRIPT
   [NAME=appletName]
   [CODEBASE=classFileDirectory]
   [ALT=alternateText]
   [ALIGN="left"|"right"|
      "top"|"absmiddle"|"absbottom"|
      "texttop"|"middle"|"baseline"|"bottom"]
   [HSPACE=spaceInPixels]
   [VSPACE=spaceInPixels]>
   [<PARAM NAME=parameterName VALUE=parameterValue>]
   [ ... <PARAM>]
</APPLET>

HTML attributes

CODE=classFileName specifies the file name of the applet that you want to load. This file name must end in a .class extension.

HEIGHT=height specifies the height of the applet in pixels within the browser window.

WIDTH=width specifies the width of the applet in pixels within the browser window.

MAYSCRIPT permits the applet to access JavaScript. Use this attribute to prevent an applet from accessing JavaScript on a page without your knowledge. If omitted, the applet will not work with JavaScript.

NAME=appletName specifies the name of the applet. You can use this name when indexing the applets array.

CODEBASE=classFileDirectory specifies directory of the .class file, if it is different from the directory that contains the HTML page.

ALT=alternateText specifies text to display for browsers that do not support the <APPLET> tag.

ALIGN=alignment specifies the alignment of the applet on the HTML page.

HSPACE=spaceInPixels specifies a horizontal margin for the applet, in pixels, within the browser window.

VSPACE=spaceInPixels specifies a vertical margin for the applet, in pixels, within the browser window.

<PARAM> defines a parameter for the applet.

NAME=parameterName specifies the name of the parameter.

VALUE=parameterValue> specifies a value for the parameter.

Syntax

To use an applet object:

document.applets[index]

Parameters

index is an integer representing an applet in a document or the name of an Applet object as specified by the NAME attribute.

Property of

document

Implemented in

Navigator 3.0

Description

The author of an HTML page must permit an applet to access JavaScript by specifying the MAYSCRIPT attribute of the <APPLET> tag. This prevents an applet from accessing JavaScript on a page without the knowledge of the page author. For example, to allow the musicPicker.class applet access to JavaScript on your page, specify the following:

<APPLET CODE="musicPicker.class" WIDTH=200 HEIGHT=35
   NAME="musicApp" MAYSCRIPT>

Accessing JavaScript when the MAYSCRIPT attribute is not specified results in an exception.

For more information on using applets, see Chapter 4, "LiveConnect."

The applets array

You can reference the applets in your code by using the applets array. This array contains an entry for each Applet object (<APPLET> tag) in a document in source order. For example, if a document contains three applets, these applets are reflected as document.applets[0], document.applets[1], and document.applets[2].

To use the applets array:

1. document.applets[index]
2. document.applets.length

index is an integer representing an applet in a document or the name of an Applet object as specified by the NAME attribute.

To obtain the number of applets in a document, use the length property: document.applets.length.

Elements in the applets array are read-only. For example, the statement document.applets[0]="myApplet.class" has no effect.

Properties

All public properties of the applet are available for JavaScript access to the Applet object.

The applets array has the following properties:

Property Description
length
Reflects the number of <APPLET> tags in the document

Methods

Event handlers

None.

Examples

The following code launches an applet called "musicApp":

<APPLET CODE="musicSelect.class" WIDTH=200 HEIGHT=35
   NAME="musicApp" MAYSCRIPT>
</APPLET>

For more examples, see Chapter 4, "LiveConnect."

See also

MimeType, Plugin objects; Chapter 4, "LiveConnect"


applets

Property. An array reflecting all the applets in a document in source order. See the Applet object for information.


appName

Property. A string specifying the name of the browser.

Syntax

navigator.appName

Property of

navigator

Implemented in

Navigator 2.0

Tainted?

No

Description

appName is a read-only property.

Examples

The following example displays the value of the appName property:

document.write("The value of navigator.appName is " +
   navigator.appName)

For Navigator 2.0 and 3.0, this displays the following:

The value of navigator.appName is Netscape

See also

appCodeName, appVersion, javaEnabled, userAgent properties


appVersion

Property. A string specifying version information for the Navigator.

Syntax

navigator.appVersion

Property of

navigator

Implemented in

Navigator 2.0

Tainted?

No

Description

The appVersion property specifies version information in the following format:

releaseNumber (platform; country)

The values contained in this format are the following:

appVersion is a read-only property.

Examples

Example 1. The following example displays version information for the Navigator:

document.write("The value of navigator.appVersion is " +
   navigator.appVersion)

For Navigator 2.0 on Windows 95, this displays the following:

The value of navigator.appVersion is 2.0 (Win95, I)

For Navigator 3.0 on Windows NT, this displays the following:

The value of navigator.appVersion is 3.0 (WinNT, I)

Example 2. The following example populates a Textarea object with newline characters separating each line. Because the newline character varies from platform to platform, the example tests the appVersion property to determine whether the user is running Windows (appVersion contains "Win" for all versions of Windows). If the user is running Windows, the newline character is set to \r\n; otherwise, it's set to \n, which is the newline character for Unix and Macintosh.

<SCRIPT>
var newline=null
function populate(textareaObject){
   if (navigator.appVersion.lastIndexOf('Win') != -1)
      newline="\r\n"
      else newline="\n"
   textareaObject.value="line 1" + newline + "line 2" + newline
          + "line 3"
}
</SCRIPT>
<FORM NAME="form1">
<BR><TEXTAREA NAME="testLines" ROWS=8 COLS=55></TEXTAREA>
<P><INPUT TYPE="button" VALUE="Populate the Textarea object"
   onClick="populate(document.form1.testLines)">
</TEXTAREA>
</FORM>

See also

appCodeName, appName, userAgent properties


Area

Object. Defines an area of an image as an image map. When the user clicks the area, the area's hypertext reference is loaded into its target window. Area objects are a type of Link object. For information on Area objects, see Link object.


arguments array

Property. An array corresponding to elements of a function.

Syntax

To use the arguments array:

1. functionName.arguments[index]
2. functionName.arguments.length

Parameters

functionName is the name of a function you have created or the name of a variable or a property of an existing object that has been assigned a Function object using new.

index is an integer representing an element of a function or the name of a function as specified in the function declaration.

Property of

Function object, any user-defined function (see See "Defining and calling functions")

Implemented in

Navigator 2.0

Tainted?

No

Description

You can call a function with more arguments than it is formally declared to accept by using the arguments array. This technique is useful if a function can be passed a variable number of arguments. You can use arguments.length to determine the number of arguments passed to the function, and then treat each argument by using the arguments array.

The arguments array is available only within a function declaration. Attempting to access the arguments array outside a function declaration results in an error.

The this keyword does not refer to the currently executing function, so you must refer to functions and Function objects by name, even within the function body.

Properties

The arguments array has the following properties:

Property Description
length
Reflects the number of arguments to the function

Examples

This example defines a function that creates HTML lists. The only formal argument for the function is a string that is "U" if the list is to be unordered (bulleted), or "O" if the list is to be ordered (numbered). The function is defined as follows:

function list(type) {
   document.write("<" + type + "L>")
   for (var i=1; i<list.arguments.length; i++) {
      document.write("<LI>" + list.arguments[i])
      document.write("</" + type + "L>")
   }
}

You can pass any number of arguments to this function, and it displays each argument as an item in the type of list indicated. For example, the following call to the function

list("U", "One", "Two", "Three")

results in this output:

<UL>
<LI>One
<LI>Two
<LI>Three
</UL>

See also

caller


arguments property

Property. An array of elements in a function. See the arguments array for information.

Tainted?

No


Array

Object. Lets you create arrays and work with them.

Syntax

To create an Array object:

1. arrayObjectName = new Array([arrayLength])
2. arrayObjectName = new Array([element0, element1, ..., elementn])

To use Array objects:

1. arrayObjectName.propertyName
2. arrayObjectName.methodName(parameters)

Parameters

arrayObjectName is either the name of a new object or a property of an existing object. When using Array properties and methods, arrayObjectName is either the name of an existing Array object or a property of an existing object.

arrayLength is the initial length of the array. You can access this value using the length property.

elementn is a list of values for the array's elements. When this form is specified, the array is initalized with the specified values as its elements, and the array's length property is set to the number of arguments.

propertyName is one of the properties listed below.

methodName is one of the methods listed below.

Property of

None.

Implemented in

Navigator 3.0

Description

The Array object is a built-in JavaScript object.

You can specify an initial length when you create the array. The following code creates an array of five elements:

billingMethod = new Array(5)

When you create an array, all of its elements are initially null. The following code creates an array of 25 elements, then assigns values to the first three elements:

musicTypes = new Array(25)
musicTypes[0] = "R&B"
musicTypes[1] = "Blues"
musicTypes[2] = "Jazz"

An array's length increases if you assign a value to an element higher than the current length of the array. The following code creates an array of length zero, then assigns a value to element 99. This changes the length of the array to 100.

colors = new Array()
colors[99] = "midnightblue"

You can construct a dense array of two or more elements starting with index 0 if you define initial values for all elements. A dense array is one in which each element has a value. The following code creates a dense array with three elements:

myArray = new Array("Hello", myVar, 3.14159)

In Navigator 2.0, you must index arrays by their ordinal number, for example document.forms[0]. In Navigator 3.0, you can index arrays by either their ordinal number or their name (if defined). For example, suppose you define the following array:

myArray = new Array("Wind","Rain","Fire")

You can then refer to the first element of the array as myArray[0] or myArray["Wind"].

Properties

The Array object has the following properties:

Property Description
length
Reflects the number of elements in an array
prototype
Lets you add a properties to an Array object.

Methods

The Array object has the following methods:

eval

join

reverse

sort

toString

valueOf

Event handlers

None.

Examples

Example 1. The following example creates an array, msgArray, with a length of 0, then assigns values to msgArray[0] and msgArray[99], changing the length of the array to 100.

msgArray = new Array()
msgArray [0] = "Hello"
msgArray [99] = "world"
if (msgArray .length == 100)     // This is true, because defined msgArray [99] element.
   document.write("The length is 100.")

See also the examples for the onError event handler.

Example 2: Two-dimensional array. The following code creates a two-dimensional array and displays the results.

a = new Array(4)
for (i=0; i < 4; i++) {
   a[i] = new Array(4)
   for (j=0; j < 4; j++) {
      a[i][j] = "["+i+","+j+"]"
   }
}
for (i=0; i < 4; i++) {
   str = "Row "+i+":"
   for (j=0; j < 4; j++) {
      str += a[i][j]
   }
   document.write(str,"<p>")
}

This example displays the following results:

Multidimensional array test

Row 0:[0,0][0,1][0,2][0,3]

Row 1:[1,0][1,1][1,2][1,3]

Row 2:[2,0][2,1][2,2][2,3]

Row 3:[3,0][3,1][3,2][3,3]

See also

Image object


asin

Method. Returns the arc sine (in radians) of a number.

Syntax

Math.asin(number)

Parameters

number is a numeric expression between -1 and 1, or a property of an existing object.

Method of

Math

Implemented in

Navigator 2.0

Description

The asin method returns a numeric value between -pi/2 and pi/2 radians. If the value of number is outside this range, it returns zero.

Examples

The following function returns the arc sine of the variable x:

function getAsin(x) {
   return Math.asin(x)
}

If you pass getAsin the value one, it returns 1.570796326794897 (pi/2); if you pass it the value two, it returns zero because two is out of range.

See also

acos, atan, atan2, cos, sin, tan methods


atan

Method. Returns the arc tangent (in radians) of a number.

Syntax

Math.atan(number)

Parameters

number is either a numeric expression or a property of an existing object, representing the tangent of an angle.

Method of

Math

Implemented in

Navigator 2.0

Description

The atan method returns a numeric value between -pi/2 and pi/2 radians.

Examples

The following function returns the arc tangent of the variable x:

function getAtan(x) {
   return Math.atan(x)
}

If you pass getAtan the value 1, it returns 0.7853981633974483; if you pass it the value .5, it returns 0.4636476090008061.

See also

acos, asin, atan2, cos, sin, tan methods


atan2

Method. Returns the angle in radians from the X axis to a point.

Syntax

Math.atan2(x,y)

Parameters

x is either a numeric expression or a property of an existing object, representing the cartesian x-coordinate.

y is either a numeric expression or a property of an existing object, representing the cartesian y-coordinate.

Method of

Math

Implemented in

Navigator 2.0

Description

The atan2 method returns a numeric value between 0 and 2pi representing the angle theta of an (x,y) point. This is the counter-clockwise angle, measured in radians, between the positive X axis, and the point (x,y).

atan2 is passed separate x and y arguments, and atan is passed the ratio of those two arguments.

Examples

The following function returns the angle of the polar coordinate:

function getAtan2(x,y) {
   return Math.atan2(x,y)
}

If you pass getAtan2 the values (90,15), it returns 1.4056476493802699; if you pass it the values (15,90), it returns 0.16514867741462683.

See also

acos, asin, atan, cos, sin, tan methods


back

Method. Loads the previous URL in the history list.

Syntax

history.back()

Method of

history object

Implemented in

Navigator 2.0

Description

This method performs the same action as a user choosing the Back button in the Navigator. The back method is the same as history.go(-1).

Examples

The following custom buttons perform the same operations as the Navigator Back and Forward buttons:

<P><INPUT TYPE="button" VALUE="< Back"
   onClick="history.back()">
<P><INPUT TYPE="button" VALUE="> Forward"
   onClick="history.forward()">

See also

forward, go methods


bgColor

Property. A string specifying the color of the document background.

Syntax

document.bgColor

Property of

document

Implemented in

Navigator 2.0

Tainted?

No

Description

The bgColor property is expressed as a hexadecimal RGB triplet or as one of the string literals listed in "Color values". This property is the JavaScript reflection of the BGCOLOR attribute of the <BODY> tag. The default value of this property is set by the user on the Colors tab of the Preferences dialog box, which is displayed by choosing General Preferences from the Options menu.

You can set the bgColor property at any time.

If you express the color as a hexadecimal RGB triplet, you must use the format rrggbb. For example, the hexadecimal RGB values for salmon are red=FA, green=80, and blue=72, so the RGB triplet for salmon is "FA8072."

Examples

The following example sets the color of the document background to aqua using a string literal:

document.bgColor="aqua"

The following example sets the color of the document background to aqua using a hexadecimal triplet:

document.bgColor="00FFFF"

See also

alinkColor, fgColor, linkColor, vlinkColor properties


big

Method. Causes a string to be displayed in a big font as if it were in a <BIG> tag.

Syntax

stringName.big()

Parameters

stringName is any string or a property of an existing object.

Method of

String

Implemented in

Navigator 2.0

Description

Use the big method with the write or writeln methods to format and display a string in a document.

Examples

The following example uses string methods to change the size of a string:

var worldString="Hello, world"

document.write(worldString.small())
document.write("<P>" + worldString.big())
document.write("<P>" + worldString.fontsize(7))

The previous example produces the same output as the following HTML:

<SMALL>Hello, world</SMALL>
<P><BIG>Hello, world</BIG>
<P><FONTSIZE=7>Hello, world</FONTSIZE>

See also

fontsize, small methods


blink

Method. Causes a string to blink as if it were in a <BLINK> tag.

Syntax

stringName.blink()

Parameters

stringName is any string or a property of an existing object.

Method of

String

Implemented in

Navigator 2.0

Description

Use the blink method with the write or writeln methods to format and display a string in a document.

Examples

The following example uses string methods to change the formatting of a string:

var worldString="Hello, world"

document.write(worldString.blink())
document.write("<P>" + worldString.bold())
document.write("<P>" + worldString.italics())
document.write("<P>" + worldString.strike())

The previous example produces the same output as the following HTML:

<BLINK>Hello, world</BLINK>
<P><B>Hello, world</B>
<P><I>Hello, world</I>
<P><STRIKE>Hello, world</STRIKE>

See also

bold, italics, strike methods


blur

Method. Removes focus from the specified object.

Syntax

1. fileUploadName.blur()
2. passwordName.blur()
3. selectName.blur()
4. textName.blur()
5. textareaName.blur()
6. frameReference.blur()
7. windowReference.blur()

Parameters

fileUploadName is either the value of the NAME attribute of a FileUpload object or an element in the elements array.

passwordName is either the value of the NAME attribute of a Password object or an element in the elements array.

selectName is either the value of the NAME attribute of a Select object or an element in the elements array.

textName is either the value of the NAME attribute of a Text object or an element in the elements array.

textareaName is either the value of the NAME attribute of a Textarea object or an element in the elements array.

frameReference is a valid way of referring to a frame, as described in the Frame object.

windowReference is a valid way of referring to a window, as described in the window object.

Method of

Button object, Checkbox object, FileUpload object, Frame object, Password object, Radio object, Reset object object, Select object, Submit object, Text object, Textarea object, window object

Implemented in

Description

Use the blur method to remove focus from a specific form element, window, or frame. Removing focus from a window sends the window to the background in most windowing systems.

Examples

The following example removes focus from the password element userPass:

userPass.blur()

This example assumes that the password is defined as

<INPUT TYPE="password" NAME="userPass">

See also

focus method, select method


bold

Method. Causes a string to be displayed as bold as if it were in a <B> tag.

Syntax

stringName.bold()

Parameters

stringName is any string or a property of an existing object.

Method of

String

Implemented in

Navigator 2.0

Description

Use the bold method with the write or writeln methods to format and display a string in a document.

Examples

The following example uses string methods to change the formatting of a string:

var worldString="Hello, world" 
document.write(worldString.blink())
document.write("<P>" + worldString.bold())
document.write("<P>" + worldString.italics())
document.write("<P>" + worldString.strike())

The previous example produces the same output as the following HTML:

<BLINK>Hello, world</BLINK>
<P><B>Hello, world</B>
<P><I>Hello, world</I>
<P><STRIKE>Hello, world</STRIKE>

See also

blink, italics, strike methods


Boolean

Object. Lets you work with Boolean values. The Boolean object is an object wrapper for a boolean value.

Syntax

To create a Boolean object:

booleanObjectName = new Boolean(value)

To use a Boolean object:

booleanObjectName.propertyName

Parameters

booleanObjectName is either the name of a new object or a property of an existing object. When using Boolean properties, booleanObjectName is either the name of an existing Boolean object or a property of an existing object.

value is the initial value of the Boolean object. The value is converted to a boolean value, if necessary. If value is omitted or is 0, null, false, or the empty string "", it the object has an initial value of false. All other values, including the string "false" create an object with an initial value of true.

propertyName is one of the properties listed below.

Property of

None

Implemented in

Navigator 3.0

Description

The Boolean object is a built-in JavaScript object.

Use a Boolean object when you need to convert a non-boolean value to a boolean value. You can use the Boolean object any place JavaScript expects a primitive boolean value. JavaScript returns the primitive value of the Boolean object by automatically invoking the valueOf method.

Properties

The Boolean object has the following properties:

Property Description
prototype
Lets you add a properties to a Boolean object.

Methods

Event handlers

None.

Examples

The following examples create Boolean objects with an initial value of false:

bNoParam = new Boolean()
bZero = new Boolean(0)
bNull = new Boolean(null)
bEmptyString = new Boolean("")
bfalse = new Boolean(false)

The following examples create Boolean objects with an initial value of true:

btrue = new Boolean(true)
btrueString = new Boolean("true")
bfalseString = new Boolean("false")
bSuLin = new Boolean("Su Lin")


border

Property. A string specifying the width, in pixels, of an image border.

Syntax

imageName.border

Parameters

imageName is either the name of an Image object or an element in the images array.

Property of

Image

Implemented in

Navigator 3.0

Tainted?

No

Description

The border property reflects the BORDER attribute of the <IMG> tag. For images created with the Image() constructor, the value of the border property is 0.

border is a read-only property.

Examples

The following function displays the value of an image's border property if the value is not zero.

function checkBorder(theImage) {
   if (theImage.border==0) {
      alert('The image has no border!')
   }
   else alert('The image's border is ' + theImage.border)
}

See also

height, hspace, vspace, width properties


Button

Object. A pushbutton on an HTML form.

HTML syntax

To define a button, use standard HTML syntax with the addition of JavaScript event handlers:

<INPUT
   TYPE="button"
   NAME="buttonName"
   VALUE="buttonText"
   [onBlur="handlerText"]
   [onClick="handlerText"]
   [onFocus="handlerText"]>

HTML attributes

NAME="buttonName" specifies the name of the Button object. You can access this value using the name property, and you can use this name when indexing the elements array.

VALUE="buttonText" specifies the label to display on the button face. You can access this value using the value property.

Syntax

To use a Button object's properties and methods:

1. buttonName.propertyName
2. buttonName.methodName(parameters)
3. formName.elements[index].propertyName
4. formName.elements[index].methodName(parameters)

Parameters

buttonName is the value of the NAME attribute of a Button object.

formName is either the value of the NAME attribute of a Form object or an element in the forms array.

index is an integer representing a Button object on a form or the name of a Button object as specified by the NAME attribute.

propertyName is one of the properties listed below.

methodName is one of the methods listed below.

Property of

Form object

Implemented in

Description

A Button object on a form looks as follows:

A Button object is a form element and must be defined within a <FORM> tag.

The Button object is a custom button that you can use to perform an action you define. The button executes the script specified by its onClick event handler.

Properties

The Button object has the following properties:

Property Description
form property
Specifies the form containing the Button object
name
Reflects the NAME attribute
type
Reflects the TYPE attribute
value
Reflects the VALUE attribute

Methods

The Button object has the following methods:

blur

click

eval

focus

toString

valueOf

Event handlers

Examples

The following example creates a button named calcButton. The text "Calculate" is displayed on the face of the button. When the button is clicked, the function calcFunction is called.

<INPUT TYPE="button" VALUE="Calculate" NAME="calcButton"
   onClick="calcFunction(this.form)">

See also

Form object, Reset object, Submit object


caller

Property. Returns the name of the function that invoked the currently executing function.

Syntax

functionName.caller

Parameters

functionName is the name of a function you have created or the name of a variable or a property of an existing object that has been assigned a Function object using new.

Property of

Function object, any user-defined function (see See "Defining and calling functions")

Implemented in

Navigator 2.0

Tainted?

No

Description

The caller property is available only within the body of a function. If used outside a function declaration, the caller property is null.

If the currently executing function was invoked by the top level of a JavaScript program, the value of caller is null.

The this keyword does not refer to the currently executing function, so you must refer to functions and Function objects by name, even within the function body.

The caller property is a reference to the calling function, so

Examples

The following code checks the value of a function's caller property.

function myFunc() {
   if (myFunc.caller == null) {
      alert("The function was called from the top!")
   } else alert("This function's caller was " + myFunc.caller)
}

See also

arguments array


ceil

Method. Returns the least integer greater than or equal to a number.

Syntax

Math.ceil(number)

Parameters

number is any numeric expression or a property of an existing object.

Method of

Math

Implemented in

Navigator 2.0

Examples

The following function returns the ceil value of the variable x:

function getCeil(x) {
   return Math.ceil(x)
}

If you pass getCeil the value 45.95, it returns 46; if you pass it the value -45.95, it returns -45.

See also

floor method


charAt

Method. Returns the character at the specified index.

Syntax

stringName.charAt(index)

Parameters

stringName is any string or a property of an existing object.

index is any integer from zero to stringName.length - 1, or a property of an existing object.

Method of

String

Implemented in

Navigator 2.0

Description

Characters in a string are indexed from left to right. The index of the first character is zero, and the index of the last character is stringName.length - 1. If the index you supply is out of range, JavaScript returns an empty string.

Examples

The following example displays characters at different locations in the string "Brave new world":

var anyString="Brave new world"

document.write("The character at index 0 is " + anyString.charAt(0))
document.write("The character at index 1 is " + anyString.charAt(1))
document.write("The character at index 2 is " + anyString.charAt(2))
document.write("The character at index 3 is " + anyString.charAt(3))
document.write("The character at index 4 is " + anyString.charAt(4))

See also

indexOf, lastIndexOf, split methods


Checkbox

Object. A checkbox on an HTML form. A checkbox is a toggle switch that lets the user set a value on or off.

HTML syntax

To define a checkbox, use standard HTML syntax with the addition of JavaScript event handlers:

<INPUT
   TYPE="checkbox"
   NAME="checkboxName"
   VALUE="checkboxValue"
   [CHECKED]
   [onBlur="handlerText"]
   [onClick="handlerText"]
   [onFocus="handlerText"]>
   textToDisplay

HTML attributes

NAME="checkboxName" specifies the name of the Checkbox object. You can access this value using the name property, and you can use this name when indexing the elements array.

VALUE="checkboxValue" specifies a value that is returned to the server when the checkbox is selected and the form is submitted. This defaults to "on." You can access this value using the value property.

CHECKED specifies that the checkbox is displayed as checked. You can access this value using the defaultChecked property.

textToDisplay specifies the label to display beside the checkbox.

Syntax

To use a Checkbox object's properties and methods:

1. checkboxName.propertyName
2. checkboxName.methodName(parameters)
3. formName.elements[index].propertyName
4. formName.elements[index].methodName(parameters)

Parameters

checkboxName is the value of the NAME attribute of a Checkbox object.

formName is either the value of the NAME attribute of a Form object or an element in the forms array.

index is an integer representing a Checkbox object on a form or the name of a Checkbox object as specified by the NAME attribute.

propertyName is one of the properties listed below.

methodName is one of the methods listed below.

Property of

Form object

Implemented in

Description

A Checkbox object on a form looks as follows:

Overnight delivery

A Checkbox object is a form element and must be defined within a <FORM> tag.

Use the checked property to specify whether the checkbox is currently checked. Use the defaultChecked property to specify whether the checkbox is checked when the form is loaded or reset.

Properties

The Checkbox object has the following properties:

Property Description
checked
Boolean property that reflects the current state of the checkbox: true for checked or false for unchecked. Lets you programmatically check a checkbox
defaultChecked
Boolean property that reflects the CHECKED attribute: true if checkbox is checked by default, false otherwise.
form property
Specifies the form containing the Checkbox object
name
Reflects the NAME attribute
type
Reflects the TYPE attribute
value
Reflects the VALUE attribute

Methods

The Checkbox object has the following methods:

blur

click

eval

focus

toString

valueOf

Event handlers

Examples

Example 1. The following example displays a group of four checkboxes that all appear checked by default:

<B>Specify your music preferences (check all that apply):</B>
<BR><INPUT TYPE="checkbox" NAME="musicpref_rnb" CHECKED> R&B
<BR><INPUT TYPE="checkbox" NAME="musicpref_jazz" CHECKED> Jazz
<BR><INPUT TYPE="checkbox" NAME="musicpref_blues" CHECKED> Blues
<BR><INPUT TYPE="checkbox" NAME="musicpref_newage" CHECKED> New Age

Example 2. The following example contains a form with three text boxes and one checkbox. The user can use the checkbox to choose whether the text fields are converted to uppercase. Each text field has an onChange event handler that converts the field value to uppercase if the checkbox is checked. The checkbox has an onClick event handler that converts all fields to uppercase when the user checks the checkbox.

<HTML>
<HEAD>
<TITLE>Checkbox object example</TITLE>
</HEAD>
<SCRIPT>
function convertField(field) {
   if (document.form1.convertUpper.checked) {
      field.value = field.value.toUpperCase()}
}
function convertAllFields() {
   document.form1.lastName.value = document.form1.lastName.value.toUpperCase()
   document.form1.firstName.value = document.form1.firstName.value.toUpperCase()
   document.form1.cityName.value = document.form1.cityName.value.toUpperCase()
}
</SCRIPT>
<BODY>
<FORM NAME="form1">
<B>Last name:</B>
<INPUT TYPE="text" NAME="lastName" SIZE=20 onChange="convertField(this)">
<BR><B>First name:</B>
<INPUT TYPE="text" NAME="firstName" SIZE=20 onChange="convertField(this)">
<BR><B>City:</B>
<INPUT TYPE="text" NAME="cityName" SIZE=20 onChange="convertField(this)">
<P><INPUT TYPE="checkBox" NAME="convertUpper"
   onClick="if (this.checked) {convertAllFields()}"
   > Convert fields to upper case
</FORM>
</BODY>
</HTML>

See also

Form object, Radio objects


checked

Property. A Boolean value specifying the selection state of a Checkbox object or radio button.

Syntax

1. checkboxName.checked
2. radioName[index].checked

Parameters

checkboxName is either the value of the NAME attribute of a Checkbox object or an element in the elements array.

radioName is the value of the NAME attribute of a Radio object.

index is an integer representing a radio button in a Radio object.

Property of

Checkbox, Radio

Implemented in

Navigator 2.0

Tainted?

Yes

Description

If a checkbox or radio button is selected, the value of its checked property is true; otherwise, it is false.

You can set the checked property at any time. The display of the checkbox or radio button updates immediately when you set the checked property.

Examples

The following example examines an array of radio buttons called musicType on the musicForm form to determine which button is selected. The VALUE attribute of the selected button is assigned to the checkedButton variable.

function stateChecker() {
   var checkedButton = ""
   for (var i in document.musicForm.musicType) {
      if (document.musicForm.musicType[i].checked=="1") {
         checkedButton=document.musicForm.musicType[i].value
      }
   }
}

See also

defaultChecked property


clearTimeout

Method. Cancels a timeout that was set with the setTimeout method.

Syntax

clearTimeout(timeoutID)

Parameters

timeoutID is a timeout setting that was returned by a previous call to the setTimeout method.

Method of

Frame object, window object

Implemented in

Navigator 2.0

Description

See the description for the setTimeout method.

Examples

See the examples for the setTimeout method.

See also

setTimeout method


click

Method. Simulates a mouse-click on the calling form element.

Syntax

1. buttonName.click()
2. radioName[index].click()
3. checkboxName.click()

Parameters

buttonName is either the value of the NAME attribute of a Button, Reset, or Submit object or an element in the elements array.

radioName is the value of the NAME attribute of a Radio object or an element in the elements array.

index is an integer representing a radio button in a Radio object.

checkboxName is either the value of the NAME attribute of a Checkbox object or an element in the elements array.

Method of

Button, Checkbox, Radio, Reset object, Submit object

Implemented in

Navigator 2.0

Description

The effect of the click method varies according to the calling element:

The click method does not trigger an object's onClick event handler.

Examples

The following example toggles the selection status of the first radio button in the musicType Radio object on the musicForm form:

document.musicForm.musicType[0].click()

The following example toggles the selection status of the newAge checkbox on the musicForm form:

document.musicForm.newAge.click()


close (document object)

Method. Closes an output stream and forces data sent to layout to display.

Syntax

document.close()

Method of

document

Implemented in

Navigator 2.0

Description

The close method closes a stream opened with the document.open() method. If the stream was opened to layout, the close method forces the content of the stream to display. Font style tags, such as <BIG> and <CENTER>, automatically flush a layout stream.

The close method also stops the "meteor shower" in the Netscape icon and displays "Document: Done" in the status bar.

Examples

The following function calls document.close() to close a stream that was opened with document.open(). The document.close() method forces the content of the stream to display in the window.

function windowWriter1() {
   var myString = "Hello, world!"
   msgWindow.document.open()
   msgWindow.document.write(myString + "<P>")
   msgWindow.document.close()
}

See also

open (document object), write, writeln methods


close (window object)

Method. Closes the specified window.

Syntax

windowReference.close()

Parameters

windowReference is a valid way of referring to a window, as described in the window object.

Method of

window object

Implemented in

Description

The close 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

Any of the following examples closes the current window:

window.close()
self.close()
close()

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

closed property; open (window object) method


closed

Property. Specifies whether a window is closed.

Syntax

[windowReference.]closed

Parameters

windowReference is a valid way of referring to a window, as described in the window object.

Property of

window object

Implemented in

Navigator 3.0

Tainted?

No

Description

The closed 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 window.open()'s return value), is still open. Once a window is closed, you should not attempt to manipulate it.

closed is a read-only property.

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')
...
if (win1.closed)
   function1()
   else
   function2()

Example 2. The following code determines if the current window's opener window is still closed, and calls the appropriate function.

if (window.opener.closed)
   function1()
   else
   function2()

See also

close (window object), open (window object) methods


complete

Property. A boolean value that indicates whether Navigator has completed its attempt to load an image.

Syntax

imageName.complete

Parameters

imageName is either the name of an Image object or an element in the images array.

Property of

Image

Implemented in

Navigator 3.0

Tainted?

No

Description

complete is a read-only property.

Examples

The following example displays an image and three radio buttons. The user can click the radio buttons to choose which image is displayed. Clicking another button lets the user see the current value of the complete property.

<B>Choose an image:</B>
<BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image1" CHECKED
   onClick="document.images[0].src='f15e.gif'">F-15 Eagle
<BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image2"
   onClick="document.images[0].src='f15e2.gif'">F-15 Eagle 2
<BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image3"
   onClick="document.images[0].src='ah64.gif'">AH-64 Apache

<BR><INPUT TYPE="button" VALUE="Is the image completely loaded?"
   onClick="alert('The value of the complete property is '
      + document.images[0].complete)">
<BR>
<IMG NAME="aircraft" SRC="f15e.gif" ALIGN="left" VSPACE="10"><BR>

See also

lowsrc, src properties


confirm

Method. Displays a Confirm dialog box with the specified message and OK and Cancel buttons.

Syntax

confirm("message")

Parameters

message is any string or a property of an existing object.

Method of

window object

Implemented in

Navigator 2.0

Description

A confirm dialog box looks as follows:

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

Although confirm is a method of the window object, you do not need to specify a windowReference when you call it. For example, windowReference.confirm() is unnecessary.

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

Examples

This example uses the confirm 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() {
   if (confirm("Are you sure you want to quit this application?")) {
      cleanUp()
   }
}

You can call the confirmCleanUp function in the onClick event handler of a form's pushbutton, as shown in the following example:

<INPUT TYPE="button" VALUE="Quit" onClick="confirmCleanUp()">

See also

alert, prompt methods


constructor

Property. Specifies the function that creates an object prototype.

Syntax

objectType.constructor

Parameters

objectType is the name of a constructor or function specifying an object type.

Property of

constructor is a property of any prototype object (see "Creating new objects").

Implemented in

Navigator 3.0

Tainted?

No

Description

Each prototype object has a constructor property that refers to the function that created the object.

Examples

The following example creates a prototype object, Tree and an object of that type, theTree. The example then displays the constructor property for the object theTree.

function Tree(name) {
   this.name=name
}
theTree = new Tree("Redwood")
document.writeln("<B>theTree.constructor is</B> " +
   theTree.constructor + "<P>")

This example displays the following output:

theTree.constructor is function Tree(name) { this.name = name; }

See also

prototype property; "Creating new objects"


cookie

Property. String value of a cookie, which is a small piece of information stored by the Navigator in the cookies.txt file.

Syntax

document.cookie

Property of

document

Implemented in

Navigator 2.0

Tainted?

Yes

Description

Use string methods such as substring, charAt, indexOf, and lastIndexOf to determine the value stored in the cookie. See the Appendix D, "Netscape cookies" for a complete specification of the cookie syntax.

You can set the cookie property at any time.

The "expires=" component in the cookie file sets an expiration date for the cookie, so it persists beyond the current browser session. This date string is formatted as follows:

Wdy, DD-Mon-YY HH:MM:SS GMT

This format represents the following values:

For example, a valid cookie expiration date is

expires=Wednesday, 09-Nov-99 23:12:40 GMT

The cookie date format is the same as the date returned by toGMTString, with the following exceptions:

Examples

The following function uses the cookie property to record a reminder for users of an application. The cookie expiration date is set to one day after the date of the reminder.

function RecordReminder(time, expression) {
   // Record a cookie of the form "@<T>=<E>" to map
   // from <T> in milliseconds since the epoch,
   // returned by Date.getTime(), onto an encoded expression,
   // <E> (encoded to contain no white space, semicolon,
   // or comma characters)
   document.cookie = "@" + time + "=" + expression + ";"
   // set the cookie expiration time to one day
   // beyond the reminder time
   document.cookie += "expires=" + cookieDate(time + 24*60*60*1000)
   // cookieDate is a function that formats the date
   //according to the cookie spec
}

See also

Hidden object


cos

Method. Returns the cosine of a number.

Syntax

Math.cos(number)

Parameters

number is a numeric expression representing the size of an angle in radians, or a property of an existing object.

Method of

Math

Implemented in

Navigator 2.0

Description

The cos method returns a numeric value between -1 and one, which represents the cosine of the angle.

Examples

The following function returns the cosine of the variable x:

function getCos(x) {
   return Math.cos(x)
}

If x equals Math.PI/2, getCos returns 6.123031769111886e-017; if x equals Math.PI, getCos returns -1.

See also

acos, asin, atan, atan2, sin, tan methods


current

Property. A string specifying the complete URL of the current history entry.

Syntax

history.current

Property of

history object

Implemented in

Navigator 3.0

Tainted?

Yes

Description

The current property has a value only if data tainting is enabled; if data tainting is not enabled, current has no value.

current is a read-only property.

Examples

The following example determines whether history.current contains the string "netscape.com". If it does, the function myFunction is called.

if (history.current.indexOf("netscape.com") != -1) {
   myFunction(history.current)
}

See also

next, previous properties; "Using data tainting for security"


[Next reference file]