scroll

Method. Scrolls a window to a specified coordinate.

Syntax

windowReference.scroll(x-coordinate,y-coordinate)

window.scroll(50,100)

Example 2: Scroll a different window. The following code, which exists in one frame, scrolls a second frame. Two Text objects let the user specify the x and y coordinates. When the user clicks the Go button, the document in frame2 scrolls to the specified coordinates.

<SCRIPT>
function scrollIt(form) {
   var x = parseInt(form.x.value)
   var y = parseInt(form.y.value)
   parent.frame2.scroll(x, y)
}
</SCRIPT>
<BODY>

<FORM NAME="myForm">
<P><B>Specify the coordinates to scroll to:</B>
<BR>Horizontal:
<INPUT TYPE="text" NAME=x VALUE="0" SIZE=4>
<BR>Vertical:
<INPUT TYPE="text" NAME=y VALUE="0" SIZE=4>
<BR><INPUT TYPE="button" VALUE="Go"
   onClick="scrollIt(document.myForm)">
</FORM>

search

Property. A string beginning with a question mark that specifies any query information in the URL.

Syntax

1. links[index].search
2. location.search
3. areaName.search

Parameters

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

areaName is the value of the NAME attribute of an Area object.

Property of

Area object (see Link object), Link object, location object

Implemented in

Navigator 2.0
Navigator 3.0: property of Area

Tainted?

Yes

Description

The search property specifies a portion of the URL. This property applies to http URLs only.

The search property contains variable and value pairs; each pair is separated by an ampersand. For example, two pairs in a search string could look like the following:

?x=7&y=5

You can set the search property at any time, although it is safer to set the href property to change a location. If the search that you specify cannot be found in the current location, you will get an error.

In event handlers, you must specify window.location.search instead of simply using location.search. Due to the scoping of static objects in JavaScript, a call to location without specifying an object name is equivalent to document.location, which is a synonym for document.URL.

See Section 3.3 of RFC 1738 for complete information about the search.

Examples

In the following example, the window.open statement creates a window called newWindow and loads the specified URL into it. The document.write statements display all the properties of newWindow.location in a window called msgWindow.

newWindow=window.open
   ("http://guide-p.infoseek.com/WW/NS/Titles?qt=RFC+1738+&col=WW")

msgWindow.document.write("newWindow.location.href = " +
   newWindow.location.href + "<P>")
msgWindow.document.write("newWindow.location.protocol = " +
   newWindow.location.protocol + "<P>")
msgWindow.document.write("newWindow.location.host = " +
   newWindow.location.host + "<P>")
msgWindow.document.write("newWindow.location.hostName = " +
   newWindow.location.hostName + "<P>")
msgWindow.document.write("newWindow.location.port = " +
   newWindow.location.port + "<P>")
msgWindow.document.write("newWindow.location.pathname = " +
   newWindow.location.pathname + "<P>")
msgWindow.document.write("newWindow.location.hash = " +
   newWindow.location.hash + "<P>")
msgWindow.document.write("newWindow.location.search = " +
   newWindow.location.search + "<P>")
msgWindow.document.close()

The previous example displays the following output:

newWindow.location.href =
   http://guide-p.infoseek.com/WW/NS/Titles?qt=RFC+1738+&col=WW
newWindow.location.protocol = http:
newWindow.location.host = guide-p.infoseek.com
newWindow.location.hostName = guide-p.infoseek.com
newWindow.location.port = 
newWindow.location.pathname = /WW/NS/Titles
newWindow.location.hash = 
newWindow.location.search = ?qt=RFC+1738+&col=WW

select method

Method. Selects the input area of the specified Password, Text, or Textarea object.

Syntax

1. passwordName.select()
2. textName.select()
3. textareaName.select()

Parameters

passwordName is either the value of the NAME attribute of a Password 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.

Method of

Password object, Text object, Textarea object

Implemented in

Navigator 2.0

Description

Use the select method to highlight the input area of a form element. You can use the select method with the focus method to highlight a field and position the cursor for a user response.

Examples

In the following example, the checkPassword function confirms that a user has entered a valid password. If the password is not valid, the select method highlights the password field and the focus method returns focus to it so the user can re-enter the password.

function checkPassword(userPass) {
   if (badPassword) {
      alert("Please enter your password again.")
      userPass.focus()
      userPass.select()
   }
}

This example assumes that the password is defined as

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

Select object

Object. A selection list on an HTML form. The user can choose one or more items from a selection list.

HTML syntax

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

<SELECT
   NAME="selectName"
   [SIZE="integer"]
   [MULTIPLE]
   [onBlur="handlerText"]
   [onChange="handlerText"]
   [onFocus="handlerText"]>
   <OPTION VALUE="optionValue" [SELECTED]> textToDisplay
      [ ... <OPTION> textToDisplay]
</SELECT>

HTML attributes

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

SIZE="integer" specifies the number of options visible when the form is displayed.

MULTIPLE specifies that multiple items can be selected. If omitted, only one item can be selected from the list.

OPTION specifies a selection element in the list. You can access the options using the options array.

VALUE="optionValue" specifies a value that is returned to the server when the option is selected and the form is submitted. You can access this value using the value property.

SELECTED specifies that the option is selected by default. You can access this value using the defaultSelected property.

textToDisplay specifies the text to display in the list. You can access this value using the text property.

Syntax

To create an option to add to an existing Select object:

optionName = new Option([text, value, defaultSelected, selected])

To add the new option to an existing Select object:

selectName.options[index1]=optionName

To delete an option from a Select object:

selectName.options[index1] = null

To use a Select object's properties and methods:

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

To use an option's properties:

1. selectName.options[index1].propertyName
2. formName.elements[index2].options[index1].propertyName
3. optionName.propertyName

Parameters

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

text specifies the text to display in the select list. You can access this value using the text property.

value specifies a value that is returned to the server when the option is selected and the form is submitted. You can access this value using the value property.

defaultSelected specifies whether the option is initially selected (true or false). You can access this value using the defaultSelected property.

selected specifies the current selection state of the option (true or false). You can access this value using the selected property.

selectName is the value of the NAME attribute of a Select 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 Select object on a form or the name of a Select object as specified by the NAME attribute.

index1 is an integer representing an option in a Select object.

index2 is an integer representing a Select object on a form.

propertyName is one of the properties listed below.

methodName is one of the methods listed below.

Property of

The Select object is a property of the Form object.
The options array is a property of the Select object.

Implemented in

Navigator 2.0
Navigator 3.0: text property can be changed to change the text of an option; added type property; added Option() constructor and all its properties; added the ability to add and delete options

Description

A Select object on a form looks as follows. The user can choose one item from the list on the left; the user can choose multiple items from the list on the right:

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

The options array

You can reference the options of a Select object in your code by using the options array. This array contains an entry for each option in a Select object (<OPTION> tag) in source order. For example, if a Select object named musicStyle contains three options, these options are reflected as musicStyle.options[0], musicStyle.options[1], and musicStyle.options[2].

To use the options array:

1. selectName.options
2. selectName.options[index]
3. selectName.options.length

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

index is an integer representing an option in a Select object.

To obtain the number of options in a Select object, use the length property of either the options array or the Select object:

1. selectName.length
2. selectName.options.length

The Select object has properties that you can access only through the options array. These properties are listed below.

Each element in the options array represents a Select option; the value returned by selectName.options represents the full HTML statement for the selectName object.

Elements in the options array are read-only. For example, the statement selectName.options[0]="guitar" has no effect.

For Select objects that can have multiple selections (the <SELECT> tag has the MULTIPLE attribute), you have to loop and test each option individually:

for (var i = 0; i < select.options.length; i++) {
          if (select.options[i].selected)
                    // Statements to perform if option is selected
                    ...
}

Changing the selection state

You can use the selected and selectedIndex properties to change the selection state of options in a Select object.

The selectedIndex property for a Select object is an integer specifying the index of the selected option. This is most useful for Select objects that are created without the MULTIPLE attribute. The following statement sets a Select object's selectedIndex property: document.myForm.musicTypes.selectedIndex = i
The selected property for an option is a Boolean value specifying the current selection state of the option in a Select object. If an option is selected, its selected property is true; otherwise it is false. This is more useful for Select objects that are created with the MULTIPLE attribute. The following statement sets an option's selected property to true: document.myForm.musicTypes.options[i].selected = true

Changing option text

To change an option's text, use the text property of the options array. For example, suppose a form has the following Select object:

<SELECT name="userChoice">
<OPTION>Choice 1
<OPTION>Choice 2
<OPTION>Choice 3
</SELECT>

You can set the text of the i^th item in the selection based on text entered in a text field named whatsNew as follows:

myform.userChoice.options[i].text = myform.whatsNew.value

You do not need to reload or refresh after changing an option's text.

For example, in the following form, the user can enter some text in the first text field and then enter a number between 0 and 2 (inclusive) in the second text field. When the user clicks the button, the text will be substituted for the indicated option number and that option is selected.

The code for this example looks as follows:

<SCRIPT>
function updateList(theForm, i) {
   theForm.userChoice.options[i].text = theForm.whatsNew.value
   theForm.userChoice.options[i].selected = true
}
</SCRIPT>
<FORM>
<SELECT name="userChoice">
   <OPTION>Choice 1
   <OPTION>Choice 2
   <OPTION>Choice 3
</SELECT>
<BR>
New text for the option: <INPUT TYPE="text" NAME="whatsNew">
<BR>
Option to change (0, 1, or 2): <INPUT TYPE="text" NAME="idx">
<BR>
<INPUT TYPE="button" VALUE="Change Selection"
onClick="updateList(this.form, this.form.idx.value)">
</FORM>

Adding options using the Option() constructor

Each option created using the Option() constructor is an object and has the same properties as elements of the options array.

After you create the options and add them to the Select object, you must refresh the document by using history.go(0). This statement must be last. When the document reloads, variables are lost if not saved in cookies or form element values.

Deleting options

Deletion compresses the options array. For example, if you delete options[0], the existing options[1] becomes options[0]. It's a good idea to delete options at the end of the array first.

After you delete an option, you must refresh the document by using history.go(0). This statement must be last. When the document reloads, variables are lost if not saved in cookies or form element values.

Properties

The Select object has the following properties:


Property	Description
form property	Specifies the form containing the Select object
length	Reflects the number of options in a Select object
name	Reflects the NAME attribute
options	Reflects the <OPTION> tags
selectedIndex	Reflects the index of the selected option (or the first selected option, if multiple options are selected)
type	Specifies that the object is a Select object and indicates whether MULTIPLE is specified

The options array has the following properties:


Property	Description
length	Reflects the number of options in a Select object
selectedIndex	Reflects the index of the selected option

Each element of the options array has the following properties:


Property	Description
defaultSelected	Reflects the SELECTED attribute
index	Reflects the index of an option
selected	Lets you programmatically select an option
text property	Reflects the textToDisplay that follows an <OPTION> tag
value	Reflects the VALUE attribute

Objects created with the Option() constructor have the following properties:


Property	Description
defaultSelected	Specifies the initial selection state of the option
index	Specifies the index of the option in a Select object
prototype	Lets you add a properties to an option.
selected	Specifies the current selection state of the option
text property	Specifies the text for the option
value	Specifies the value that is returned to the server when the option is selected and the form is submitted

Methods

The Select object has the following methods:


blur eval focus	toString valueOf

Event handlers

Examples

Example 1. The following example displays two selection lists. In the first list, the user can select only one item; in the second list, the user can select multiple items.

Choose the music type for your free CD:
<SELECT NAME="music_type_single">
   <OPTION SELECTED> R&B
   <OPTION> Jazz
   <OPTION> Blues
   <OPTION> New Age
</SELECT>
<P>Choose the music types for your free CDs:
<BR><SELECT NAME="music_type_multi" MULTIPLE>
   <OPTION SELECTED> R&B
   <OPTION> Jazz
   <OPTION> Blues
   <OPTION> New Age
</SELECT>

Example 2. The following example displays two selection lists that let the user choose a month and day. These selection lists are initialized to the current date. The user can change the month and day by using the selection lists or by choosing preset dates from radio buttons. Text fields on the form display the values of the Select object's properties and indicate the date chosen and whether it is Cinco de Mayo.

<HTML>
<HEAD>
<TITLE>Select object example</TITLE>
</HEAD>
<BODY>
<SCRIPT>
var today = new Date()
//---------------
function updatePropertyDisplay(monthObj,dayObj) {
   // Get date strings
   var monthInteger, dayInteger, monthString, dayString
   monthInteger=monthObj.selectedIndex
   dayInteger=dayObj.selectedIndex
   monthString=monthObj.options[monthInteger].text
   dayString=dayObj.options[dayInteger].text
   // Display property values
   document.selectForm.textFullDate.value=monthString + " " + dayString
   document.selectForm.textMonthLength.value=monthObj.length
   document.selectForm.textDayLength.value=dayObj.length
   document.selectForm.textMonthName.value=monthObj.name
   document.selectForm.textDayName.value=dayObj.name
   document.selectForm.textMonthIndex.value=monthObj.selectedIndex
   document.selectForm.textDayIndex.value=dayObj.selectedIndex
   // Is it Cinco de Mayo?
   if (monthObj.options[4].selected && dayObj.options[4].selected)
      document.selectForm.textCinco.value="Yes!"
   else
      document.selectForm.textCinco.value="No"
}
</SCRIPT>
<!--------------->
<FORM NAME="selectForm">
<P><B>Choose a month and day:</B> 
Month: <SELECT NAME="monthSelection"
   onChange="updatePropertyDisplay(this,document.selectForm.daySelection)">
   <OPTION> January <OPTION> February <OPTION> March
   <OPTION> April <OPTION> May <OPTION> June
   <OPTION> July <OPTION> August <OPTION> September
   <OPTION> October <OPTION> November <OPTION> December
</SELECT>
Day: <SELECT NAME="daySelection"
   onChange="updatePropertyDisplay(document.selectForm.monthSelection,this)">
   <OPTION> 1 <OPTION> 2 <OPTION> 3 <OPTION> 4 <OPTION> 5
   <OPTION> 6 <OPTION> 7 <OPTION> 8 <OPTION> 9 <OPTION> 10
   <OPTION> 11 <OPTION> 12 <OPTION> 13 <OPTION> 14 <OPTION> 15
   <OPTION> 16 <OPTION> 17 <OPTION> 18 <OPTION> 19 <OPTION> 20
   <OPTION> 21 <OPTION> 22 <OPTION> 23 <OPTION> 24 <OPTION> 25
   <OPTION> 26 <OPTION> 27 <OPTION> 28 <OPTION> 29 <OPTION> 30
   <OPTION> 31
</SELECT>
<P><B>Set the date to: </B>
<INPUT TYPE="radio" NAME="dateChoice"
   onClick="
      monthSelection.selectedIndex=0;
      daySelection.selectedIndex=0;
      updatePropertyDisplay
         document.selectForm.monthSelection,document.selectForm.daySelection)">
   New Year's Day
<INPUT TYPE="radio" NAME="dateChoice"
   onClick="
      monthSelection.selectedIndex=4;
      daySelection.selectedIndex=4;
      updatePropertyDisplay
         (document.selectForm.monthSelection,document.selectForm.daySelection)">
   Cinco de Mayo
<INPUT TYPE="radio" NAME="dateChoice"
   onClick="
      monthSelection.selectedIndex=5;
      daySelection.selectedIndex=20;
      updatePropertyDisplay
         (document.selectForm.monthSelection,document.selectForm.daySelection)">
   Summer Solstice
<P><B>Property values:</B>
<BR>Date chosen: <INPUT TYPE="text" NAME="textFullDate" VALUE="" SIZE=20">
<BR>monthSelection.length<INPUT TYPE="text" NAME="textMonthLength" VALUE="" SIZE=20">
<BR>daySelection.length<INPUT TYPE="text" NAME="textDayLength" VALUE="" SIZE=20">
<BR>monthSelection.name<INPUT TYPE="text" NAME="textMonthName" VALUE="" SIZE=20">
<BR>daySelection.name<INPUT TYPE="text" NAME="textDayName" VALUE="" SIZE=20">
<BR>monthSelection.selectedIndex
   <INPUT TYPE="text" NAME="textMonthIndex" VALUE="" SIZE=20">
<BR>daySelection.selectedIndex<INPUT TYPE="text" NAME="textDayIndex" VALUE="" SIZE=20">
<BR>Is it Cinco de Mayo? <INPUT TYPE="text" NAME="textCinco" VALUE="" SIZE=20">
<SCRIPT>
document.selectForm.monthSelection.selectedIndex=today.getMonth()
document.selectForm.daySelection.selectedIndex=today.getDate()-1
updatePropertyDisplay(document.selectForm.monthSelection,document.selectForm.daySelection)
</SCRIPT>
</FORM>
</BODY>
</HTML>

Example 3. Add an option using the Option() constructor. The following example creates two Select objects, one without the MULTIPLE attribute and one with. No options are initially defined for either object. When the user clicks a button associated with the Select object, the populate function creates four options for the Select object and selects the first option.

<SCRIPT>
function populate(inForm) {
   colorArray = new Array("Red", "Blue", "Yellow", "Green")

   var option0 = new Option("Red", "color_red")
   var option1 = new Option("Blue", "color_blue")
   var option2 = new Option("Yellow", "color_yellow")
   var option3 = new Option("Green", "color_green")

   for (var i=0; i < 4; i++) {
      eval("inForm.selectTest.options[i]=option" + i)
      if (i==0) {
         inForm.selectTest.options[i].selected=true
      }
   }

   history.go(0)
}
</SCRIPT>


<H3>Select Option() constructor</H3>
<FORM>
<SELECT NAME="selectTest"></SELECT><P>
<INPUT TYPE="button" VALUE="Populate Select List" onClick="populate(this.form)">
<P>
</FORM>

<HR>
<H3>Select-Multiple Option() constructor</H3>
<FORM>
<SELECT NAME="selectTest" multiple></SELECT><P>
<INPUT TYPE="button" VALUE="Populate Select List" onClick="populate(this.form)">
</FORM>

Example 4. Delete an option. The following function removes an option from a Select object.

function deleteAnItem(theList,itemNo) {
   theList.options[itemNo]=null
   history.go(0)
}

selected

Property. A Boolean value indicating whether an option in a Select object is selected.

Syntax

1. selectName.options[index].selected
2. optionName.selected

Parameters

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

index is an integer representing an option in a Select object.

optionName is the name of a Select object option created using the Option() constructor.

Property of

Option object (see Select object), options array (see Select object)

Implemented in

Navigator 2.0
Navigator 3.0: property of Option

Tainted?

Yes

Description

If an option in a Select object is selected, the value of its selected property is true; otherwise, it is false.

You can set the selected property at any time. The display of the Select object updates immediately when you set the selected property.

In general, the selected property is more useful than the selectedIndex property for Select objects that are created with the MULTIPLE attribute. With the selected property, you can evaluate every option in the options array to determine multiple selections, and you can select individual options without clearing the selection of other options.

Examples

See the examples for the defaultSelected property.

selectedIndex

Property. An integer specifying the index of the selected option in a Select object.

Syntax

1. selectName.selectedIndex
2. selectName.options.selectedIndex

Parameters

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

Property of

Select object; options array (see Select object)

Implemented in

Navigator 2.0

Tainted?

Yes

Description

Options in a Select object are indexed in the order in which they are defined, starting with an index of zero. You can set the selectedIndex property at any time. The display of the Select object updates immediately when you set the selectedIndex property. Both forms of the syntax specify the same value. If no option is selected, selectedIndex has a value of -1.

In general, the selectedIndex property is more useful for Select objects that are created without the MULTIPLE attribute. If you evaluate selectedIndex when multiple options are selected, the selectedIndex property specifies the index of the first option only. Setting selectedIndex clears any other options that are selected in the Select object.

The selected property of the Select object's options array is more useful for Select objects that are created with the MULTIPLE attribute. With the selected property, you can evaluate every option in the options array to determine multiple selections, and you can select individual options without clearing the selection of other options.

Examples

In the following example, the getSelectedIndex function returns the selected index in the musicType Select object:

function getSelectedIndex() {
   return document.musicForm.musicType.selectedIndex
}

The previous example assumes that the Select object is similar to the following:

<SELECT NAME="musicType"> 
   <OPTION SELECTED> R&B
   <OPTION> Jazz
   <OPTION> Blues
   <OPTION> New Age
</SELECT>

self

Property. The self property is a synonym for the current window or frame.

Syntax

1. self.propertyName
2. self.methodName

Parameters

propertyName is the defaultStatus, status, length, or name property when self refers to a window object.

propertyName is the length or name property when self refers to a Frame object.

methodName is any method associated with the window object.

Property of

Frame object, window object

Implemented in

Navigator 2.0

Tainted?

Description

The self property refers to the current window or frame.

Use the self property to disambiguate a window property from a form or form element of the same name. You can also use the self property to make your code more readable.

The self property is read-only. The value of the self property is

     <object nameAttribute>

where nameAttribute is the NAME attribute if self refers to a frame, or an internal reference if self refers to a window.

Examples

In the following example, self.status is used to set the status property of the current window. This usage disambiguates the status property of the current window from a form or form element called "status" within the current window.

<A HREF=""
   onClick="this.href=pickRandomURL()"
   onMouseOver="self.status='Pick a random URL' ; return true">
Go!</A>

setDate

Method. Sets the day of the month for a specified date.

Syntax

dateObjectName.setDate(dayValue)

Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

dayValue is an integer from one to 31 or a property of an existing object, representing the day of the month.

Method of

Date

Implemented in

Navigator 2.0

Examples

The second statement below changes the day for theBigDay to July 24 from its original value.

theBigDay = new Date("July 27, 1962 23:30:00")
theBigDay.setDate(24)

setHours

Method. Sets the hours for a specified date.

Syntax

dateObjectName.setHours(hoursValue)

Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

hoursValue is an integer between zero and 23 or a property of an existing object, representing the hour.

Method of

Date

Implemented in

Navigator 2.0

Examples

theBigDay.setHours(7)

setMinutes

Method. Sets the minutes for a specified date.

Syntax

dateObjectName.setMinutes(minutesValue)

Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

minutesValue is an integer between zero and 59 or a property of an existing object, representing the minutes.

Method of

Date

Implemented in

Navigator 2.0

Examples

theBigDay.setMinutes(45)

setMonth

Method. Sets the month for a specified date.

Syntax

dateObjectName.setMonth(monthValue)

Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

monthValue is an integer between zero and 11 (representing the months January through December) or a property of an existing object.

Method of

Date

Implemented in

Navigator 2.0

Examples

theBigDay.setMonth(6)

setSeconds

Method. Sets the seconds for a specified date.

Syntax

dateObjectName.setSeconds(secondsValue)

Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

secondsValue is an integer between zero and 59 or a property of an existing object.

Method of

Date

Implemented in

Navigator 2.0

Examples

theBigDay.setSeconds(30)

setTime

Method. Sets the value of a Date object.

Syntax

dateObjectName.setTime(timevalue)

Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

timevalue is an integer or a property of an existing object, representing the number of milliseconds since the epoch (1 January 1970 00:00:00).

Method of

Date

Implemented in

Navigator 2.0

Description

Use the setTime method to help assign a date and time to another Date object.

Examples

theBigDay = new Date("July 1, 1999")
sameAsBigDay = new Date()
sameAsBigDay.setTime(theBigDay.getTime())

setTimeout

Method. Evaluates an expression after a specified number of milliseconds has elapsed.

Syntax

timeoutID=setTimeout(expression, msec)

Parameters

timeoutID is an identifier that is used only to cancel the evaluation with the clearTimeout method.

expression is a string expression or a property of an existing object.

msec is a numeric value, numeric string, or a property of an existing object in millisecond units.

Method of

Frame object, window object

Implemented in

Navigator 2.0

Description

The setTimeout method evaluates an expression after a specified amount of time. It does not evaluate the expression repeatedly. For example, if a setTimeout method specifies five seconds, the expression is evaluated after five seconds, not every five seconds.

Examples

Example 1. The following example displays an alert message five seconds (5,000 milliseconds) after the user clicks a button. If the user clicks the second button before the alert message is displayed, the timeout is canceled and the alert does not display.

<SCRIPT LANGUAGE="JavaScript">
function displayAlert() {
   alert("5 seconds have elapsed since the button was clicked.")
}
</SCRIPT>
<BODY>
<FORM>
Click the button on the left for a reminder in 5 seconds; 
click the button on the right to cancel the reminder before 
it is displayed.
<P>
<INPUT TYPE="button" VALUE="5-second reminder"
   NAME="remind_button"
   onClick="timerID=setTimeout('displayAlert()',5000)">
<INPUT TYPE="button" VALUE="Clear the 5-second reminder"
   NAME="remind_disable_button"
   onClick="clearTimeout(timerID)">
</FORM>
</BODY>

Example 2. The following example displays the current time in a Text object. The showtime function, which is called recursively, uses the setTimeout method to update the time every second.

<HEAD>
<SCRIPT LANGUAGE="JavaScript">
<!--
var timerID = null
var timerRunning = false
function stopclock(){
   if(timerRunning)
      clearTimeout(timerID)
   timerRunning = false
}
function startclock(){
   // Make sure the clock is stopped
   stopclock()
   showtime()
}
function showtime(){
   var now = new Date()
   var hours = now.getHours()
   var minutes = now.getMinutes()
   var seconds = now.getSeconds()
   var timeValue = "" + ((hours > 12) ? hours - 12 : hours)
   timeValue += ((minutes < 10) ? ":0" : ":") + minutes
   timeValue += ((seconds < 10) ? ":0" : ":") + seconds
   timeValue += (hours >= 12) ? " P.M." : " A.M."
   document.clock.face.value = timeValue 
   timerID = setTimeout("showtime()",1000)
   timerRunning = true
}
//-->
</SCRIPT>
</HEAD>

<BODY onLoad="startclock()">
<FORM NAME="clock" onSubmit="0">
   <INPUT TYPE="text" NAME="face" SIZE=12 VALUE ="">
</FORM>
</BODY>

setYear

Method. Sets the year for a specified date.

Syntax

dateObjectName.setYear(yearValue)

Parameters

dateObjectName is either the name of a Date object or a property of an existing object.

yearValue is an integer greater than 1900 or a property of an existing object.

Method of

Date

Implemented in

Navigator 2.0

Examples

theBigDay.setYear(96)

sin

Method. Returns the sine of a number.

Syntax

Math.sin(number)

Parameters

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

Method of

Math

Implemented in

Navigator 2.0

Description

The sin method returns a numeric value between -1 and one, which represents the sine of the argument.

Examples

The following function returns the sine of the variable x:

function getSine(x) {
   return Math.sin(x)
}

If you pass getSine the value Math.PI/2, it returns 1.

small

Method. Causes a string to be displayed in a small font, as if it were in a <SMALL> tag.

Syntax

stringName.small()

Parameters

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

Method of

String

Implemented in

Navigator 2.0

Description

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

sort

Method. Sorts the elements of an array.

Syntax

arrayName.sort(compareFunction)

Parameters

arrayName is the name of an Array object or a property of an existing object.

compareFunction specifies a function that defines the sort order. If omitted, the array is sorted lexicographically (in dictionary order) according to the string conversion of each element.

Method of

Array

Implemented in

Navigator 3.0

Description

If compareFunction is not supplied, elements are sorted by converting them to strings and comparing strings in lexicographic ("dictionary" or "telephone book," not numerical) order. For example, "80" comes before "9" in lexicographic order, but if you are comparing numbers 9 needs to come before 80.

If compareFunction is supplied, the array elements are sorted according to the return value of the compare function. If a and b are two elements being compared, then:

If compareFunction(a, b) is less than zero, sort b to a lower index than a.
If compareFunction(a, b) returns zero, leave a and b unchanged with respect to each other, but sorted with respect to all different elements.
If compareFunction(a, b) is greater than zero, sort b to a higher index than a.

So the compare function has the following form:

function compare(a, b) {
   if (a is less than b by some ordering criterion)
      return -1
   if (a is greater than b by the ordering criterion)
      return 1
   // a must be equal to b
   return 0
}

To compare numbers instead of strings, the compare function can simply subtract b from a:

function compareNumbers(a, b) {
   return a - b
}

JavaScript uses a stable sort: the index partial order of a and b does not change if a and b are equal. If a's index was less than b's before sorting, it will be after sorting, no matter how a and b move due to sorting.

Note

On some platforms, the sort method does not work. Please see the release notes (after starting Netscape, choose Release Notes from the Help menu).

Examples

The following example creates four arrays and displays the original array, then the sorted arrays. The numeric arrays are sorted without, then with, a compare function.

<SCRIPT>
stringArray = new Array("Blue","Humpback","Beluga")
numericStringArray = new Array("80","9","700")
numberArray = new Array(40,1,5,200)
mixedNumericArray = new Array("80","9","700",40,1,5,200)

function compareNumbers(a, b) {
   return a - b
}

document.write("<B>stringArray:</B> " + stringArray.join() +"<BR>")
document.write("<B>Sorted:</B> " + stringArray.sort() +"<P>")

document.write("<B>numberArray:</B> " + numberArray.join() +"<BR>")
document.write("<B>Sorted without a compare function:</B> " + numberArray.sort() +"<BR>")
document.write("<B>Sorted with compareNumbers:</B> " + numberArray.sort(compareNumbers) +"<P>")

document.write("<B>numericStringArray:</B> " + numericStringArray.join() +"<BR>")
document.write("<B>Sorted without a compare function:</B> " + numericStringArray.sort() +"<BR>")
document.write("<B>Sorted with compareNumbers:</B> " + numericStringArray.sort(compareNumbers) +"<P>")

document.write("<B>mixedNumericArray:</B> " + mixedNumericArray.join() +"<BR>")
document.write("<B>Sorted without a compare function:</B> " + mixedNumericArray.sort() +"<BR>")
document.write("<B>Sorted with compareNumbers:</B> " + mixedNumericArray.sort(compareNumbers) +"<BR>")
</SCRIPT>

This example produces the following output. As the output shows, when a compare function is used, numbers sort correctly whether they are numbers or numeric strings.

stringArray: Blue,Humpback,Beluga
Sorted: Beluga,Blue,Humpback

numberArray: 40,1,5,200
Sorted without a compare function: 1,200,40,5
Sorted with compareNumbers: 1,5,40,200

numericStringArray: 80,9,700
Sorted without a compare function: 700,80,9
Sorted with compareNumbers: 9,80,700

mixedNumericArray: 80,9,700,40,1,5,200
Sorted without a compare function: 1,200,40,5,700,80,9
Sorted with compareNumbers: 1,5,9,40,80,200,700

split

Method. Splits a String object into an array of strings by separating the string into substrings.

Syntax

stringName.split([separator])

Parameters

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

separator specifies the character to use for separating the string. The separator is treated as a string. If separator is omitted, the array returned contains one element consisting of the entire string.

Method of

String

Implemented in

Navigator 3.0

Description

The split method returns the new array.

Examples

The following example defines a function that splits a string into an array of strings using the specified separator. After splitting the string, the function displays messages indicating the original string (before the split), the separator used, the number of elements in the array, and the individual array elements.

function splitString (stringToSplit,separator) {
   arrayOfStrings = stringToSplit.split(separator)
   document.write ('<P>The original string is: "' + stringToSplit + '"')
   document.write ('<BR>The separator is: "' + separator + '"')
   document.write ("<BR>The array has " + arrayOfStrings.length + " elements: ")

   for (var i=0; i < arrayOfStrings.length; i++) {
      document.write (arrayOfStrings[i] + " / ")
   }
}

var tempestString="Oh brave new world that has such people in it."
var monthString="Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"

var space=" "
var comma=","

splitString(tempestString,space)
splitString(tempestString)
splitString(monthString,comma)

This example produces the following output:

The original string is: "Oh brave new world that has such people in it."
The separator is: " "
The array has 10 elements: Oh / brave / new / world / that / has / such / people / in / it. /

The original string is: "Oh brave new world that has such people in it."
The separator is: "undefined"
The array has 1 elements: Oh brave new world that has such people in it. /

The original string is: "Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
The separator is: ","
The array has 12 elements: Jan / Feb / Mar / Apr / May / Jun / Jul / Aug / Sep / Oct / Nov / Dec /

sqrt

Method. Returns the square root of a number.

Syntax

Math.sqrt(number)

Parameters

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

Method of

Math

Implemented in

Navigator 2.0

Description

If the value of number is outside the required range, sqrt returns zero.

Examples

The following function returns the square root of the variable x:

function getRoot(x) {
   return Math.sqrt(x)
}

If you pass getRoot the value nine, it returns three; if you pass it the value two, it returns 1.414213562373095.

SQRT1_2

Property. The square root of one-half; equivalently, one over the square root of two, approximately 0.707.

Syntax

Math.SQRT1_2

Property of

Math

Implemented in

Navigator 2.0

Tainted?

Description

Because SQRT1_2 is a constant, it is a read-only property of Math.

Examples

The following function returns one over the square root of two:

function getRoot1_2() {
   return Math.SQRT1_2
}

SQRT2

Property. The square root of two, approximately 1.414.

Syntax

Math.SQRT2

Property of

Math

Implemented in

Navigator 2.0

Tainted?

Description

Because SQRT2 is a constant, it is a read-only property of Math.

Examples

The following function returns the square root of two:

function getRoot2() {
   return Math.SQRT2
}

src

Property. A string specifying the URL of an image to be displayed in a document.

Syntax

imageName.src

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?

Description

The src property initially reflects the SRC attribute of the <IMG> tag. Setting the src property begins loading the new URL into the image area (and aborts the transfer of any image data that is already loading into the same area). Therefore, if you plan to alter the lowsrc property, you should do so before setting the src property. If the URL in the src property references an image that is not the same size as the image cell it is loaded into, the source image is scaled to fit.

When you change the src property of a displayed image, the new image you specify is displayed in the area defined for the original image. For example, suppose an Image object originally displays the file beluga.gif:

<IMG NAME="myImage" SRC="beluga.gif" ALIGN="left">

If you set myImage.src='seaotter.gif', the image seaotter.gif is scaled to fit in the same space originally used by beluga.gif, even if seaotter.gif is not the same size as beluga.gif.

You can change the src property at any time.

Examples

The following example displays an image and three radio buttons. The user can click the radio buttons to choose which image is displayed. Each image also uses the lowsrc property to display a low-resolution image.

<SCRIPT>
function displayImage(lowRes,highRes) {
   document.images[0].lowsrc=lowRes
   document.images[0].src=highRes
}
</SCRIPT>

<FORM NAME="imageForm">
<B>Choose an image:</B>
<BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image1" CHECKED
   onClick="displayImage('f15el.gif','f15e.gif')">F-15 Eagle
<BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image2"
   onClick="displayImage('f15e2l.gif','f15e2.gif')">F-15 Eagle 2
<BR><INPUT TYPE="radio" NAME="imageChoice" VALUE="image3"
   onClick="displayImage('ah64l.gif','ah64.gif')">AH-64 Apache

<BR>
<IMG NAME="aircraft" SRC="f15e.gif" LOWSRC="f15el.gif" ALIGN="left" VSPACE="10"><BR>
</FORM>

status

Property. Specifies a priority or transient message in the status bar at the bottom of the window, such as the message that appears when a mouseOver event occurs over an anchor. This property can only be set, not read, in IE 3.0

Syntax

windowReference.status

Parameters

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

Property of

window object

Implemented in

Navigator 2.0

Tainted?

Yes

Description

Do not confuse the status property with the defaultStatus property. The defaultStatus property reflects the default message displayed in the status bar.

You can set the status property at any time. You must return true if you want to set the status property in the onMouseOver event handler.

Examples

Suppose you have created a JavaScript function called pickRandomURL that lets you select a URL at random. You can use the onClick event handler of an anchor to specify a value for the HREF attribute of the anchor dynamically, and the onMouseOver event handler to specify a custom message for the window in the status property:

<A HREF=""
   onClick="this.href=pickRandomURL()"
   onMouseOver="self.status='Pick a random URL'; return true">
Go!</A>

In the preceding example, the status property of the window is assigned to the window's self property, as self.status. As this example shows, you must return true to set the status property in the onMouseOver event handler.

strike

Method. Causes a string to be displayed as struck-out text, as if it were in a <STRIKE> tag.

Syntax

stringName.strike()

Parameters

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

Method of

String

Implemented in

Navigator 2.0

Description

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

String

Object. A series of characters.

Syntax

To create a String object:

stringObjectName = new String(string)

To use a String object:

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

Parameters

stringObjectName is the name of a new String object.

string is any string.

stringName is the name of a String object or string variable.

propertyName is one of the properties listed below.

methodName is one of the methods listed below.

Property of

None

Implemented in

Navigator 2.0
Navigator 3.0: added String() constructor (in previous releases, you construct strings by quoting characters); added prototype property; added split method; added ability to pass strings among scripts in different windows or frames (in previous releases, you had to add an empty string to another window's string to reference it)

Description

The String object is a built-in JavaScript object.

A string can be represented as a literal enclosed by single or double quotation marks; for example, "Netscape" or 'Netscape'.

Properties

The String object has the following properties:


Property	Description
length	Reflects the length of the string
prototype	Lets you add properties to a String object.

Methods

The String object has the following methods:


anchor method big blink bold charAt eval fixed fontcolor	fontsize indexOf italics lastIndexOf link method small split strike	sub substring sup toLowerCase toUpperCase toString valueOf

Event handlers

None.

Examples

Example 1: String variable. The following statement creates a string variable:

var last_name = "Schaefer"

Example 2: String object properties. The following statements evaluate to eight, "SCHAEFER," and "schaefer":

last_name.length
last_name.toUpperCase()
last_name.toLowerCase()

Example 3: Pass a string among scripts in different windows or frames. The following code creates two string variables and opens a second window:

var lastName = new String("Schaefer")
var firstName = new String ("Jesse")
empWindow=window.open('string2.html','window1','width=300,height=300')

If the HTML source for the second window (string2.html) creates two string variables, empLastName and empFirstName, the following code in the first window assigns values to the second window's variables:

empWindow.empFirstName=firstName
empWindow.empLastName=lastName

The following code in the first window displays the values of the second window's variables:

alert('empFirstName in empWindow is ' + empWindow.empFirstName)
alert('empLastName in empWindow is ' + empWindow.empLastName)

sub

Method. Causes a string to be displayed as a subscript, as if it were in a <SUB> tag.

Syntax

stringName.sub()

Parameters

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

Method of

String

Implemented in

Navigator 2.0

Description

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

Examples

The following example uses the sub and sup methods to format a string:

var superText="superscript"
var subText="subscript"

document.write("This is what a " + superText.sup() + " looks like.")
document.write("<P>This is what a " + subText.sub() + " looks like.")

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

This is what a <SUP>superscript</SUP> looks like.
<P>This is what a <SUB>subscript</SUB> looks like.

submit method

Method. Submits a form.

Syntax

formName.submit()

Parameters

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

Method of

Form object

Implemented in

Navigator 2.0

Description

The submit method submits the specified form. It performs the same action as a submit button.

Use the submit method to send data back to an HTTP server. The submit method returns the data using either "get" or "post," as specified in the method property.

The submit method fails without notice, if the form's action is a mailto:, news:, or snews: URL. This is for security purposes. Users can submit forms with such URLs by clicking a submit button, but a confirming dialog will tell them that they are about to give away private or sensitive information.

Examples

The following example submits a form called musicChoice:

document.musicChoice.submit()

If musicChoice is the first form created, you also can submit it as follows:

document.forms[0].submit()

Submit object

Object. A submit button on an HTML form. A submit button causes a form to be submitted.

HTML syntax

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

<INPUT
   TYPE="submit"
   NAME="submitName"
   VALUE="buttonText"
   [onBlur="handlerText"]
   [onClick="handlerText"]
   [onFocus="handlerText"]>

HTML attributes

NAME="submitName" specifies the name of the Submit 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 Submit object's properties and methods:

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

Parameters

submitName is the value of the NAME attribute of a Submit 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 Submit object on a form or the name of a Submit 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

Navigator 2.0
Navigator 3.0: added type property; added onBlur and onFocus event handlers; added blur and focus methods

Description

A Submit object on a form looks as follows:

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

Clicking a submit button submits a form to the URL specified by the form's action property. This action always loads a new page into the client; it may be the same as the current page, if the action so specifies or is not specified.

The submit button's onClick event handler cannot prevent a form from being submitted; instead, use the form's onSubmit event handler or use the submit method instead of a Submit object. See the examples for the Form object.

If a form contains only one element, a Text object, then when the user enters a value and presses Return, the form submits. (This is a standard HTML feature.)

Properties

The Submit object has the following properties:


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

Methods

The Submit object has the following methods:


blur click eval	focus toString valueOf

Event handlers

Examples

The following example creates a Submit object called submitButton. The text "Done" is displayed on the face of the button.

<INPUT TYPE="submit" NAME="submitButton" VALUE="Done">

substring

Method. Returns a subset of a String object.

Syntax

stringName.substring(indexA, indexB)

Parameters

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

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

indexB is any integer from zero to stringName.length, 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 indexA is less than indexB, the substring method returns the subset starting with the character at indexA and ending with the character before indexB.
If indexA is greater than indexB, the substring method returns the subset starting with the character before indexB and ending with the character at indexA.
If indexA is equal to indexB, the substring method returns the empty string.

Examples

Example 1. The following example uses substring to display characters from the string "Netscape":

var anyString="Netscape"

//Displays "Net"
document.write(anyString.substring(0,3))
document.write(anyString.substring(3,0))
//Displays "cap"
document.write(anyString.substring(4,7))
document.write(anyString.substring(7,4))
//Displays "Netscap"
document.write(anyString.substring(0,7))
//Displays "Netscape"
document.write(anyString.substring(0,8))
document.write(anyString.substring(0,10))

Example 2. The following example replaces a substring within a string. It will replace both individual characters and substrings. The function call at the end of the example changes the string "Brave New World" into "Brave New Web".

function replaceString(oldS,newS,fullS) {
// Replaces oldS with newS in the string fullS
   for (var i=0; i<fullS.length; i++) {
      if (fullS.substring(i,i+oldS.length) == oldS) {
         fullS = fullS.substring(0,i)+newS+fullS.substring(i+oldS.length,fullS.length)
      }
   }
   return fullS
}

replaceString("World","Web","Brave New World")

suffixes

Property. A string listing possible file suffixes (also known as file name extensions) for the MIME type.

Syntax

navigator.mimeTypes[index].suffixes

Parameters

index is either an integer representing a MIME type supported by the client or a string containing the type of a MimeType object (from the type property).

Property of

MimeType

Implemented in

Navigator 3.0

Tainted?

Description

The suffixes property is a string consisting of each valid suffix (typically three letters long) separated by commas. For example, the suffixes for the "audio/x-midi" MIME type are "mid, midi".

suffixes is a read-only property.

Examples

See the examples for the MimeType object.

sup

Method. Causes a string to be displayed as a superscript, as if it were in a <SUP> tag.

Syntax

stringName.sup()

Parameters

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

Method of

String

Implemented in

Navigator 2.0

Description

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

Examples

The following example uses the sub and sup methods to format a string:

var superText="superscript"
var subText="subscript"

document.write("This is what a " + superText.sup() + " looks like.")
document.write("<P>This is what a " + subText.sub() + " looks like.")

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

This is what a <SUP>superscript</SUP> looks like.
<P>This is what a <SUB>subscript</SUB> looks like.

scroll

Syntax

Parameters

Method of

Implemented in

Description

Examples

search

Syntax

Parameters

Property of

Implemented in

Tainted?

Description

Examples

See also

select method

Syntax

Parameters

Method of

Implemented in

Description

Examples

See also

Select object

HTML syntax

HTML attributes

Syntax

Parameters

Property of

Implemented in

Description

The options array

Changing the selection state

Changing option text

Adding options using the Option() constructor

Deleting options

Properties

Methods

Event handlers

Examples

See also

selected

Syntax

Parameters

Property of

Implemented in

Tainted?

Description

Examples

See also

selectedIndex

Syntax

Parameters

Property of

Implemented in

Tainted?

Description

Examples

See also

self

Syntax

Parameters

Property of

Implemented in

Tainted?

Description

Examples

See also

setDate

Syntax

Parameters

Method of

Implemented in

Examples

See also

setHours

Syntax

Parameters

Method of