 |  |
| |
This part of the book is a reference section that documents the classes, methods, properties, and event handlers defined by web browsers that support client-side JavaScript. These classes, methods, and properties form the de facto standard called the DOM Level 0 API. Beginning scripters and programmers writing with backward compatibility in mind will use this reference section in conjunction with the core JavaScript reference of Part III. The introduction and sample reference page explain how to use and get the most out of this reference section. Take the time to read this material carefully, and you will find it easier to locate and use the information you need!
This reference section is arranged alphabetically. The reference pages for the methods and properties of classes are alphabetized by their full names, which include the names of the classes that define them. For example, if you want to read about the submit( ) method of the Form class, you would look under "Form.submit," not just "submit."
To save space in this enlarged fourth edition of the book, most properties in this reference section do not have reference pages of their own (all methods and event handlers do have their own reference pages, however). Instead, simple properties are completely documented in the reference page for the class that defines them. For example, you can read about the images[] property of the Document class in the "Document" reference page. Nontrivial properties that require substantial explanation do have reference pages of their own, and you'll find a cross-reference to these pages within the reference page of the class or interface that defines the properties. For example, when you look up the cookie property in the "Document" reference page or the status property in the "Window" reference page, you'll find a short description of the property and a reference to pages named "Document.cookie" and "Window.status."
Client-side JavaScript has a number of global properties and functions, such as window, history, and alert( ). In client-side JavaScript, a Window object serves as the global object, and the "global" properties and functions of client-side JavaScript are actually properties of the Window class. Therefore, in this client-side reference section, global properties and functions are documented in the "Window" reference page or under names such as "Window.alert( )."
Sometimes you may find that you don't know the name of the class or interface that defines the method or property you want to look up, or you may not be sure which of the three reference sections to look up a class or interface in. Part VI of this book is a special index designed to help with these situations. Look up the name of a class, method, or property, and it will tell you which reference section to look in and which class to look under in that section. For example, if you look up "Button," it will tell you that the Button class is documented in this client-side reference section. And if you look up the name "alert," it will tell you that alert( ) is a method of the client-side Window class.
Once you've found the reference page you're looking for, you shouldn't have much difficulty finding the information you need. Still, you'll be able to make better use of this reference section if you understand how the reference pages are written and organized. What follows is a sample reference page titled "Sample Entry" that demonstrates the structure of each reference page and tells you where to find various types of information within the pages. Take the time to read this page before diving into the rest of the reference material.
| Sample Entry | how to read client-side reference pages |
Availability
Inherits from
Every reference entry begins with a title block like that above. The entries are alphabetized by title. The short description, shown next to the title, gives you a quick summary of the item documented in the entry; it can help you quickly decide if you're interested in reading the rest of the page.
The information in this section tells you when a class, method, or event handler was introduced. For some less portable items, this section specifies which versions of Netscape and Internet Explorer support it. If the item is well supported by web browsers and support was added by Netscape and IE within the same browser generation, this section specifies its availability in terms of a version of core JavaScript. You can use the tables in Chapter 1 to determine the particular releases of Netscape and Internet Explorer to which these versions correspond. Of course, since most properties do not have their own reference pages, they do not have availability information. If the availability of a property is different from the availability of the class that defines it, however, this fact is noted in the description of the property.
If a class inherits from a superclass, that information is shown in the "Inherits from" section. As described in Chapter 8, JavaScript classes can inherit properties and methods from other classes. For example, the Button class inherits from Input, which in turn inherits from HTMLElement. When you see this inheritance information, you may also want to look up the listed superclasses.
Every reference page has a "Synopsis" section that shows how you might use the class, method, or event handler in your code. For example, the synopsis for the Form class is:
document.form_name document.forms[form_number]
This synopsis shows two different ways of referring to a Form object. Text in this font must be typed exactly as shown. The italic font indicates text that is to be replaced with something else. form_name should be replaced with the name of a form, and form_number should be replaced with the index of the form in the forms[] array. Similarly, document should be replaced in these synopses with a reference to a Document object. By looking at the "Synopsis" section of the "Document" reference page, we discover that it also has two forms:
document window.document
That is, you can replace document with the literal document or with window.document. If you choose the latter, you'll need to look up the synopsis of the Window class to find out how to refer to a Window -- that is, what to replace window with.
If a reference page documents a method, the "Synopsis" section is followed by an "Arguments" subsection that describes the arguments to the method. If the method has no arguments, this subsection is simply omitted.
This section explains the method's return value. If the method does not return a value, this subsection is omitted.
If the reference page documents a class that has a constructor method, this section shows you how to use the constructor method to create instances of the class. Since constructors are a type of method, the "Constructor" section looks a lot like the "Synopsis" section of a method's reference page and has an "Arguments" subsection as well.
If the reference page documents a class, the "Properties" section lists and documents the properties defined by that class. In this client-side reference section, only particularly complex properties have reference pages of their own.
The reference page for a class that defines methods includes a "Methods" section that lists the names of the methods and provides a short description of each. Full documentation for each method is found in a separate reference page.
The reference page for a class that defines event handlers includes an "Event Handlers" section that lists the names of the handlers and provides a short description of each. Full documentation for each event handler is found in a separate reference page.
A number of client-side JavaScript classes have analogs in HTML. The reference pages for these classes include a section that shows the annotated HTML syntax used to create an HTML element that corresponds to a JavaScript object.
Most reference pages contain a "Description" section, which is the basic description of the class, method, or event handler that is being documented. This is the heart of the reference page. If you are learning about a class, method, or handler for the first time, you may want to skip directly to this section and then go back and look at previous sections such as "Arguments," "Properties," and "Methods." If you are already familiar with an item, you probably won't need to read this section and instead will just want to quickly look up some specific bit of information (for example, from the "Arguments" or "Properties" sections).
In some entries, this section is no more than a short paragraph. In others, it may occupy a page or more. For some simple methods, the "Arguments" and "Returns" sections document the method sufficiently by themselves, so the "Description" section is omitted.
A few pages include an example that shows typical usage. Most pages do not contain examples, however -- you'll find those in first half of this book.
When an item doesn't work quite right, this section describes the bugs. Note, however, that this book does not attempt to catalog every bug in every version and implementation of client-side JavaScript.
Many reference pages conclude with cross-references to related reference pages that may be of interest. Most of these cross references are to other reference pages in this client-side reference section. Some are to individual property descriptions contained within a class reference page, however, and others are to related reference pages in the DOM reference section or to chapters in the first two parts of the book.
| Anchor | the target of a hypertext link |
JavaScript 1.2
Inherits from HTMLElement
document.anchors[i] document.anchors.length
Anchor inherits properties from HTMLElement and defines or overrides the following:
HTMLElement.innerText provides the IE 4 equivalent of this Netscape-specific property.
An Anchor object is created by any standard HTML <a> tag that contains a name attribute:
<a name="name" // Links may refer to this anchor by this name > text </a>
An anchor is a named location within an HTML document. Anchors are created with an <a> tag that has a name attribute specified. The Document object has an anchors[] array property that contains Anchor objects that represent each of the anchors in the document. This anchors[] array has existed since JavaScript 1.0, but the Anchor object was not implemented until JavaScript 1.2. Therefore, the elements of anchors[] were null until JavaScript 1.2.
Note that the <a> tag used to create anchors is also used to create hypertext links. Although hypertext links are often called anchors in HTML parlance, they are represented in JavaScript with the Link object, not with the Anchor object. In the DOM reference section of this book, however, both anchors and links are documented under HTMLAnchorElement.
anchors[] property of the Document object, Link; HTMLAnchorElement in the DOM reference section
| Applet | an applet embedded in a web page Applet object |
JavaScript 1.1
document.applets[i] document.appletName
The properties of an Applet object are the same as the public fields of the Java applet it represents.
The methods of an Applet object are the same as the public methods of the Java applet it represents.
The Applet object represents a Java applet embedded in an HTML document. The properties of the Applet object represent the public fields of the applet, and the methods of the Applet object represent the public methods of the applet. LiveConnect technology in Netscape and ActiveX technology in Internet Explorer allow JavaScript programs to use the Applet object to read and write the fields and invoke the methods of the corresponding Java applet. See Chapter 22 for details.
Remember that Java is a strongly typed language. This means that each field of an applet has been declared to have a specific data type, and setting it to a value of some other type causes a runtime error. The same is true of applet methods: each argument has a specific type, and arguments cannot be omitted as they can be in JavaScript.
| Area | see Link |
| Button | a graphical push buttonButton object |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
form.button_name form.elements[i]
Button inherits properties from Input and HTMLElement and defines or overrides the following:
Button inherits methods from Input and HTMLElement.
Button inherits event handlers from Input and HTMLElement and defines or overrides the following:
A Button element is created with a standard HTML <input> tag:
<form>
...
<input
type="button" // Specifies that this is a button
value="label" // The text that is to appear within the button
// Specifies the value property
[ name="name" ] // A name you can use later to refer to the button
// Specifies the name property
[ onclick="handler" ] // JavaScript statements to be executed when the button
// is clicked
>
...
</form>Button objects can also be created with the HTML 4 <button> tag:
<button id="name"
onclick="handler">
label
</button>The Button element represents a graphical push button in a form within an HTML document. The value property contains the text displayed by the button. The name property is the name the button may be referred to as. The onclick event handler is invoked when the user clicks on the button.
Use a Button element whenever you want to allow the user to trigger some action on your web page. You can sometimes use a Link object for the same purpose, but unless the desired action is to follow a hypertext link, a Button is a better choice than a Link, because it makes it more explicit to the user that there is something to be triggered.
Note that the Submit and Reset elements are types of Buttons that submit a form and reset a form's values. Often these default actions are sufficient for a form, and you do not need to create any other types of buttons.
<form name="form1">
<input type="button"
name="press_me_button"
value="Press Me"
onclick="username = prompt('What is your name?',")"
>
</form>Form, HTMLElement, Input, Reset, Submit; HTMLInputElement in the DOM reference section
| Button.onclick | the handler invoked when a Button is clicked |
<input type="button" value="button-text" onclick="handler"> button.onclick
The onclick property of a Button object refers to an event handler function that is invoked when the user clicks on the button. See HTMLElement.onclick for complete details. Note, however, that Button.onclick has been supported since JavaScript 1.0, unlike the generalized HTMLElement.onclick handler.
HTMLElement.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Checkbox | a graphical checkbox |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
A single Checkbox element with a unique name may be referenced in either of these ways:
form.checkbox_name form.elements[i]
When a form contains a group of checkboxes with the same name, they are placed in an array and may be referenced as follows:
form.checkbox_name[j] form.checkbox_name.length
Checkbox inherits properties from Input and HTMLElement and defines or overrides the following:
If you set checked to true, the checkbox appears checked. Similarly, if you set this property to false, the checkbox appears unchecked. Note that setting the checked property does not cause the Checkbox element's onclick event handler to be invoked.
Note that the value field does not specify whether the checkbox is selected; the checked property specifies the current state of the checkbox. When defining a group of related checkboxes that share the same name in a form that is submitted to the server, it is important that each be given a distinct value attribute.
Checkbox inherits the methods of Input and HTMLElement.
Checkbox inherits event handlers from Input and HTMLElement and defines or overrides the following:
A Checkbox element is created with a standard HTML <input> tag. Multiple Checkbox elements are often created in groups by specifying multiple <input> tags that have the same name attribute.
<form>
...
<input
type="checkbox" // Specifies that this is a checkbox
[ name="name" ] // A name you can use later to refer to this checkbox
// or to the group of checkboxes with this name
// Specifies the name property
[ value="value" ] // The value returned when this checkbox is selected
// Specifies the value property
[ checked ] // Specifies that the checkbox is initially checked
// Specifies the defaultChecked property
[ onclick="handler" ] // JavaScript statements to be executed
> // when the checkbox is clicked
label // The HTML text that should appear next to the checkbox
...
</form>The Checkbox element represents a single graphical checkbox in an HTML form. Note that the text that appears next to the checkbox is not part of the Checkbox element itself and must be specified externally to the Checkbox's HTML <input> tag.
The onclick event handler allows you to specify JavaScript code to be executed when the checkbox is checked or unchecked. You can examine the checked property to determine the state of the checkbox and set this property to check or uncheck the checkbox. Note that setting checked changes the graphical appearance of the checkbox but does not invoke the onclick event handler.
It is good programming style to specify the name attribute for a checkbox; this is mandatory if the checkbox is part of a form that submits data to a CGI script running on a web server. Specifying a name attribute sets the name property and allows you to refer to the checkbox by name (instead of as a member of the form elements array) in your JavaScript code, which makes the code more modular and portable.
For example, if the name attribute of a checkbox in form f is "opts", f.opts refers to the Checkbox element. Checkbox elements are often used in related groups, however, and each member of the group is given the same name attribute (the shared name defines the members of the group). In this case, JavaScript places each Checkbox element in the group in an array, and the array is given the shared name. If, for example, each of a group of checkboxes in form f has its name attribute set to "opts", f.opts is an array of Checkbox elements, and f.opts.length is the number of elements in the array.
You can set the value attribute or the value property of a checkbox to specify the string that is passed to the server if the checkbox is checked when the form is submitted. For a single checkbox used alone, the default value of "on" is usually adequate. When multiple checkboxes with the same name are used, each should specify a distinct value so a list of values from selected checkboxes can be passed to the server.
Checkbox elements can present the user with one or more options. This element type is suitable for presenting non-mutually exclusive choices. Use the Radio element for mutually exclusive lists of options.
Form, HTMLElement, Input, Radio; HTMLInputElement in the DOM reference section
| Checkbox.onclick | the handler invoked when a checkbox is selected |
<input type="checkbox" onclick="handler"> checkbox.onclick
The onclick property of a Checkbox object refers to an event handler function that is invoked when the user clicks on the checkbox. See HTMLElement.onclick for complete details. Note, however, that Checkbox.onclick has been supported since JavaScript 1.0, unlike the generalized HTMLElement.onclick handler.
HTMLElement.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Document | represents an HTML document |
JavaScript 1.0; enhanced in JavaScript 1.1, Netscape 4, and IE 4
Inherits from HTMLElement
window.document document
Document inherits properties from HTMLElement and defines the following properties. Netscape and Internet Explorer both define a number of incompatible Document properties that are used mostly for DHTML; they are listed separately after these properties.
Prior to JavaScript 1.2, the Anchor object was unimplemented, and the elements of anchors[] were all null.
document.applets[0] document.animator document.applets["animator"]
Document.plugins[] is a synonym for Document.embeds[]. Do not confuse it with Navigator.plugins[].
Document inherits methods from HTMLElement and defines the following methods. Netscape and IE both define a number of incompatible Document methods that are used mostly for DHTML; they are listed separately.
The <body> tag has onload and onunload attributes. Technically, however, the onload and onunload event handlers belong to the Window object rather than the Document object. See Window.onload and Window.onunload.
The Document object obtains values for a number of its properties from attributes of the HTML <body> tag. Also, the HTML contents of a document appear between the <body> and </body> tags:
<body [ background="imageURL" ] // A background image for the document [ bgcolor="color" ] // A background color for the document [ text="color" ] // The foreground color for the document's text [ link="color" ] // The color for unvisited links [ alink="color" ] // The color for activated links [ vlink="color" ] // The color for visited links [ onload="handler" ] // JavaScript to run when the document is loaded [ onunload="handler" ] // JavaScript to run when the document is unloaded > // HTML document contents go here </body>
The Document object represents the HTML document displayed in a browser window or frame (or layer, in Netscape 4). The properties of this object provide details about many aspects of the document, from the colors of the text, background, and anchors, to the date on which the document was last modified. The Document object also contains a number of arrays that describe the contents of the document. The links[] array contains one Link object for each hypertext link in the document. Similarly, the applets[] array contains one object for each Java applet embedded in the document, and the forms[] array contains one Form object for each HTML form that appears in the document.
The write( ) method of the Document object is especially notable. When invoked in scripts that are run while the document is loading, you can call document.write( ) to insert dynamically generated HTML text into the document.
See Chapter 14 for an overview of the Document object and of many of the JavaScript objects to which it refers. See Chapter 17 for an overview of the DOM standard.
Form, the document property of the Window object; Chapter 14; Document, HTMLDocument, and HTMLBodyElement in the DOM reference section
| Document.all[] | all HTML elements in a document Internet Explorer 4 |
document.all[i] document.all[name] document.all.tags(tagname)
all[] is a versatile array that contains all the HTML elements in a document. all[] contains the elements in source order, and you can extract them directly from the array if you know their exact numeric position within the array. It is more common, however, to use the all[] array to retreive elements by the value of their name or id HTML attributes. If more than one element has the specified name, using that name as an index into the all[] returns an array of elements that share the name.
all.tags( ) is passed a tag name and returns an array of HTML elements of the specified type.
| Document.captureEvents( ) | see Window.captureEvents( ) |
| Document.clear( ) | clear a document |
JavaScript 1.0; deprecated
document.clear( )
The clear( ) method of the Document object is deprecated and should not be used. To clear a document, you should simply open a new one with Document.open( ).
| Document.close( ) | close an output stream |
JavaScript 1.0
document.close( )
This method displays any output to document that has been written but not yet displayed and closes the output stream to document. When generating complete HTML pages with Document.write( ), you should invoke Document.close( ) when you reach the end of the page.
After document.close( ) has been called, if any further output is written to document (e.g., with document.write( )), the document is implicitly cleared and reopened, erasing all the output that was written prior to calling the close( ) method.
| Document.cookie | the cookie(s) of the document |
JavaScript 1.0
document.cookie
cookie is a string property that allows you to read, create, modify, and delete the cookie or cookies that apply to the current document. A cookie is a small amount of named data stored by the web browser. It gives web browsers a "memory" so they can use data input on one page in another page or recall user preferences across web browsing sessions. Cookie data is automatically transmitted between web browser and web server when appropriate so CGI scripts on the server end can read and write cookie values. Client-side JavaScript code can also read and write cookies with this property.
The Document.cookie property does not behave like a normal read/write property. You may both read and write the value of Document.cookie, but the value you read from this property is, in general, not the same as the value you write. For complete details on the use of this particularly complex property, see Chapter 16.
Cookies are intended for infrequent storage of small amounts of data. They are not intended as a general-purpose communication or programming mechanism, so use them in moderation. Note that web browsers are not required to retain the value of more than 20 cookies per web server (for the entire server, not just for your site on the server), nor to retain a cookie name/value pair of more than 4 KB in length.
| Document.domain | the security domain of a document |
JavaScript 1.1
document.domain
For security reasons, an unsigned script running in one window is not allowed to read properties of another window unless that window comes from the same web server as the host. This causes problems for large web sites that use multiple servers. For example, a script on the host www.oreilly.com might want to share properties with a script from the host search.oreilly.com.
The domain property helps to address this problem. Initially, this string property contains the hostname of the web server from which the document was loaded. You can set this property, but only in a very restricted way: it can be set only to a domain suffix of itself. For example, a script loaded from search.oreilly.com could set its own domain property to "oreilly.com". If a script from www.oreilly.com is running in another window, and it also sets its domain property to "oreilly.com", these two scripts can share properties, even though they did not originate on the same server.
Note, however, that a script from search.oreilly.com cannot set its domain property to "search.oreilly". And, more importantly, a script from snoop.spam.com cannot set its domain to "oreilly.com", which might allow it to determine, for example, which search keywords you use.
| Document.elementFromPoint( ) | determine which HTML element is at a given point |
document.elementFromPoint(x, y)
The HTML element that appears at point (x, y) in document.
| Document.getSelection( ) | return the selected text Netscape 4 |
document.getSelection( )
The text, if any, that is currently selected within the document. This returned text has HTML formatting tags removed.
| Document.handleEvent( ) | see Window.handleEvent( ) |
| Document.lastModified | the modification date of a document |
JavaScript 1.0
document.lastModified
lastModified is a read-only string property that contains the date and time at which document was most recently modified. This data is derived from HTTP header data sent by the web server. The web server generally obtains the last-modified date by examining the modification date of the file itself.
Web servers are not required to provide last-modified dates for the documents they serve. When a web server does not provide a last-modified date, JavaScript assumes 0, which translates to a date of midnight, January 1, 1970, GMT. The following example shows how you can test for this case.
It is a good idea to let readers know how recent the information you provide on the Web is. You can include an automatic timestamp in your documents by placing the following script at the end of each HTML file. Doing this means you do not need to update the modification time by hand each time you make a change to the file. Note that this script tests that the supplied date is valid before displaying it:
<script>
if (Date.parse(document.lastModified) != 0)
document.write('<p><hr><small><i>Last modified: '
+ document.lastModified
+ '</i></small>');
</script> The Document location, referrer, and title properties
| Document.links[] | the Link objects in a document |
JavaScript 1.0
document.links document.links.length
The links property is an array of Link objects -- one object for each hypertext link that appears in document. The links[] array has links.length elements, numbered from zero to links.length-1.
| Document.open( ) | begin a new document |
document.open( ) document.open(mimetype)
The document.open( ) method opens a stream to document so subsequent document.write( ) calls can append data to the document. The optional mimetype argument specifies the type of data to be written and tells the browser how to interpret that data.
If any existing document is displayed when the open( ) method is called, it is automatically cleared by the call to open( ) or by the first call to write( ) or writeln( ). After opening a document with open( ) and writing data to it with write( ), you should complete the document by calling close( ).
You usually call Document.open( ) with no argument to open an HTML document. Occasionally, a "text/plain" document is useful, for example, for a pop-up window of debugging messages.
Document.close( ), Document.write( ); HTMLDocument.open( ) in the DOM reference section
| Document.releaseEvents( ) | see Window.releaseEvents( ) |
| Document.routeEvent( ) | see Window.routeEvent( ) |
| Document.URL | the URL of the current document |
JavaScript 1.1
document.URL
URL is a read-only string property that contains the complete URL of the current document.
document.URL is usually equal to window.location.href for the window that contains document. These two are not always equal, however, because the Document.URL property may be modified through URL redirection -- Window.location contains the requested URL, and Document.URL specifies the actual URL where it was found.
Some web authors like to include the URL of a document somewhere within the document so, for example, if the document is cut-and-pasted to a file or printed out, there is still a reference to its location online. The following script, when appended to a document, automatically adds the document's URL:
<script>
document.write('<p><hr><small><i>URL: ' + document.URL
+ '</i></small>');
</script>The lastModified, location, referrer, and title properties of the Document object; the location property of the Window object
| Document.write( ) | append data to a document |
JavaScript 1.0
document.write(value, ...)
document.write( ) appends each of its arguments, in order, to document. Any arguments that are not strings are converted to strings before they are written to the end of the document.
Document.write( ) is usually used in one of two ways. First, it can be invoked on the current document within a <script> tag or within a function that is executed while the document is being parsed. In this case, the write( ) method writes its HTML output as if that output appeared literally in the file at the location of the code that invoked the method.
Second, you can use Document.write( ) to dynamically generate the contents of a document for a window other than the current window. In this case, the target document is never in the process of being parsed, and so the output cannot appear "in place" as it does in the case just described. In order for write( ) to output text into a document, that document must be open. You can open a document by explicitly calling the Document.open( ) method. In most cases this is unnecessary, however, because when write( ) is invoked on a document that is closed, it implicitly opens the document. When a document is opened, any contents that previously appeared in that document are discarded and replaced with a blank document.
Once a document is open, Document.write( ) can append any amount of output to the end of the document. When a new document has been completely generated by this technique, the document should be closed by calling Document.close( ). Note that although the call to open( ) is usually optional, the call to close( ) is never optional.
The results of calling Document.write( ) may not be immediately visible in the targeted web browser window or frame. This is because a web browser may buffer up data to output in larger chunks. Calling Document.close( ) is the only way to explicitly force all buffered output to be "flushed" and displayed in the browser window.
Document.close( ), Document.open( ), Document.writeln( ); Chapter 14
| Document.writeln( ) | append data and a newline to a document |
JavaScript 1.0
document.writeln(value, ...)
Document.writeln( ) behaves just like Document.write( ) except that after appending all of its arguments to document, it also appends a newline character. See the Document.write( ) reference page for more information on this method.
Newline characters are not usually displayed in HTML documents, so Document.writeln( ) is generally useful only when writing text to appear in a <pre> environment, or when writing to a document opened with a MIME type of "text/plain".
| Element | see Input |
| Event | details about an event |
JavaScript 1.2; incompatible versions supported by Netscape 4 and IE 4
function handler(event) { ... } // Event handler argument in Netscape 4
window.event // Window property in IE 4
In Netscape 4, the Event object defines bitmask constants for each of the supported event types. These static properties are used to form the bitmasks that are passed to captureEvents( ) and releaseEvents( ). The available constants are:
Event.ABORT |
Event.BLUR |
Event.CHANGE |
Event.CLICK |
Event.DBLCLICK |
Event.DRAGDROP |
Event.ERROR |
Event.FOCUS |
Event.KEYDOWN |
Event.KEYPRESS |
Event.KEYUP |
Event.LOAD |
Event.MOUSEDOWN |
Event.MOUSEMOVE |
Event.MOUSEOUT |
Event.MOUSEOVER |
Event.MOUSEUP |
Event.MOVE |
Event.RESET |
Event.RESIZE |
Event.SELECT |
Event.SUBMIT |
Event.UNLOAD |
The Event object provides details about an event that has occurred. Unfortunately, these details are not standardized, and Netscape 4 and IE 4 define Event objects that are almost entirely incompatible. Besides having different properties, Netscape 4 and IE 4 provide access to Event objects in different ways. In Netscape, an Event object is passed as an argument to every event handler. For event handlers defined by HTML attributes, the name of the event argument is event. In IE, the Event object of the most recent event is instead stored in the event property of the Window object.
In addition to the incompatibility between the Netscape 4 Event object and the IE Event object, the W3C DOM defines its own Event object that is incompatible with both. See the Event, UIEvent, and MouseEvent entries in the DOM reference section.
Chapter 19; Event, UIEvent, and MouseEvent in the DOM reference section
| FileUpload | a file upload field for form input |
JavaScript 1.0 Inherits from Input, HTMLElement
form.name form.elements[i]
FileUpload inherits properties from Input and HTMLElement and defines or overrides the following:
To prevent malicious programs from uploading arbitrary files from the client, this property may not be set by JavaScript code. Similarly, the value attribute of the <input> tag does not specify the initial value for this property.
FileUpload inherits methods from Input and HTMLElement.
FileUpload inherits event handlers from Input and HTMLElement and defines or overrides the following:
A FileUpload element is created with a standard HTML <input> tag:
<form enctype="multipart/form-data"
method="post"> // Required attributes
...
<input
type="file" // Specifies that this is a FileUpload element
[ name="name" ] // A name you can use later to refer to this element
// Specifies the name property
[ size="integer" ] // How many characters wide the element is
[ maxlength="integer" ] // Maximum allowed number of input characters
[ onblur="handler" ] // The onblur( ) event handler
[ onchange="handler" ] // The onchange( ) event handler
[ onfocus="handler" ] // The onfocus( ) event handler
>
...The FileUpload element represents a file upload input element in a form. In many respects, this input element is much like the Text element. On the screen, it appears like a text input field with the addition of a Browse button that opens a directory browser. Entering a filename into a FileUpload element (either directly or through the browser) causes Netscape to submit the contents of that file along with the form. For this to work, the form must use "multipart/form-data" encoding and the POST method.
The FileUpload element does not have a defaultValue property and does not recognize the value HTML attribute to specify an initial value for the input field. Similarly, the value property of the FileUpload element is read-only. Only the user may enter a filename; JavaScript may not enter text into the FileUpload field in any way. This is to prevent malicious JavaScript programs from uploading arbitrary files (such as password files) from the user's machine.
Form, HTMLElement, Input, Text; HTMLInputElement in the DOM reference section
| FileUpload.onchange | the handler invoked when input value changes |
<input type="file" onchange="handler"...> fileupload.onchange
The onchange property of a FileUpload element specifies an event handler function that is invoked when the user changes the value in the input field (either by typing directly or using the Browse button) and then moves input focus elsewhere. This handler is intended to process a complete change to the input value and therefore is not invoked on a keystroke-by-keystroke basis.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onchange attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onchange handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
Input.onchange; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Form | an HTML input form |
JavaScript 1.0 Inherits from HTMLElement
document.form_name document.forms[form_number]
Form inherits properties from HTMLElement and defines or overrides the following:
The get method is the default. It is usually used for form submissions such as database queries that do not have side effects. With this method, the encoded form data is appended to the URL specified by the Form.action property. The post method is appropriate for form submissions, such as additions to databases, that have side effects. With this method, encoded form data is sent in the body of the HTTP request.
Form inherits methods from HTMLElement and defines the following:
Form inherits event handlers from HTMLElement and defines the following:
A Form object is created with a standard HTML <form> tag. The form contains any input elements created with the <input>, <select>, and <textarea> tags between <form> and </form>:
<form
[ name="form_name" ] // Used to name the form in JavaScript
[ target="window_name" ] // The name of the window for responses
[ action="url" ] // The URL to which the form is submitted
[ method=("get"|"post") ] // The method of form submission
[ enctype="encoding" ] // How the form data is encoded
[ onreset="handler" ] // A handler invoked when form is reset
[ onsubmit="handler" ] // A handler invoked when form is submitted
>
// Form text and input elements go here
</form> The Form object represents an HTML <form> in a document. Each form in a document is represented as an element of the Document.forms[] array. Named forms are also represented by the form_name property of their document, where form_name is the name specified in the name attribute of the <form> tag.
The elements of a form (buttons, input fields, checkboxes, and so on) are collected in the Form.elements[] array. Named elements, like named forms, can also be referenced directly by name -- the element name is used as a property name of the Form object. Thus, to refer to a Text object element named phone within a form named questionnaire, you might use the JavaScript expression:
document.questionnaire.phone
Button, Checkbox, FileUpload, Hidden, Input, Password, Radio, Reset, Select, Submit, Text, Textarea; Chapter 15; HTMLFormElement in the DOM reference section
| Form.elements[] | the input elements of the form |
form.elements[i] form.elements.length
form.elements[] is an array of the form input objects in form. The array has elements.length items in it. These items may be of any of the form input element types: Button, Checkbox, Hidden, Password, Radio, Reset, Select, Submit, Text, and Textarea. These form input objects appear in the array in the same order that they appear in the HTML source code for the form.
If an item in the form.elements[] array has been given a name with the name="name" attribute of its HTML <input> tag, that item's name becomes a property of form, and this property refers to the item. Thus, it is possible to refer to input objects by name instead of by number:
form.name
Referring to elements by name is usually easier, so it is a good idea to specify the name attribute for all form elements.
Button, Checkbox, Form, Hidden, Input, Password, Radio, Reset, Select, Submit, Text, Textarea
| Form.onreset | the handler invoked when a form is reset |
<form ... onreset="handler" ... > form.onreset
The onreset property of a Form object specifies an event handler function that is invoked when the user clicks on a Reset button in the form or when Form.reset( ) is called.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onreset attribute of the HTML <form> tag. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than the scope of the containing window.
In the Netscape 4 event model, the onreset handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
If the onreset handler returns false, the elements of the form are not reset.
You could use the following event handler to ask the user to confirm that they really want to reset the form:
<form ...
onreset="return confirm('Really erase all entered data?')"
> Form.onsubmit, Form.reset( ); Chapter 19; Section , EventListener, and EventTarget in the DOM reference section
| Form.onsubmit | invoked when a form is submitted |
<form ... onsubmit="handler" ... > form.onsubmit
The onsubmit property of a Form object specifies an event handler function that is invoked when the user submits a form by clicking on a Submit button in the form. Note that this event handler is not invoked when the Form.submit( ) method is called.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onsubmit attribute of the HTML <form> tag. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than the scope of the containing window.
In the Netscape 4 event model, the onsubmit handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
If the onsubmit handler returns false, the elements of the form are not submitted. If the handler returns any other value or returns nothing, the form is submitted normally. Because the onsubmit handler can cancel form submission, it is ideal for performing form data validation.
Form.onreset, Form.submit( ); Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Form.reset( ) | reset the elements of a form |
form.reset( )
The reset( ) method resets the specified form, restoring each element of the form to its default value, exactly as if a Reset button had been pressed by the user. The form's onreset( ) event handler is first invoked and may prevent the reset from occurring by returning the value false.
| Form.submit( ) | submit a formJavaScript 1.0 |
form.submit( )
The submit( ) method submits the specified form, almost as if a Submit button had been pressed by the user. The form is submitted as specified by the action, method, and encoding properties of form (or the action, method, and enctype attributes of the <form> tag), and the results are displayed in the window or frame specified by the target property or the target attribute.
The one important difference between the submit( ) method and form submission by the user is that the onsubmit( ) event handler is not invoked when submit( ) is called. If you use onsubmit( ) to perform input validation, for example, you'll have to do that validation explicitly before calling submit( ).
It is more common to use a Submit button that allows the user to submit the form than to call the submit( ) method yourself.
| Form.target | the window for form results |
JavaScript 1.0;
read-only in Internet Explorer 3
form.target
target is a read/write string property of the Form object. It specifies the name of the frame or window in which the results of the submission of form should be displayed. The initial value of this property is specified by the target attribute of the <form> tag. If unset, the default is that form submission results appear in the same window as the form.
Note that the value of target is the name of a frame or window, not the actual frame or window itself. The name of a frame is specified by the name attribute of the <frame> tag. The name of a window is specified when the window is created with a call to the Window.open( ) method. If target specifies the name of a window that does not exist, the browser automatically opens a new window to display the results of form submission, and any future forms with the same target name use the same newly created window.
Four special target names are supported. The target named "_blank" specifies that a new, empty browser window should be created and used to display the results of the form submission. The target "_self" is the default; it specifies that the form submission results should be displayed in the same frame or window as the form itself. The target "_parent" specifies that the results should be displayed in the parent frame of the frame that contains the form. Finally, the "_top" target specifies that the results should be displayed in the topmost frame -- in other words, all frames should be removed, and the results should occupy the entire browser window.
You can set this property in IE 3, but doing so has no effect on the actual target of the form.
| Frame | a type of Window object |
window.frames[i] window.frames.length frames[i] frames.length
Though the Frame object is sometimes referred to, there is, strictly speaking, no such object. All frames within a browser window are instances of the Window object, and they contain the same properties and support the same methods and event handlers as the Window object. See the Window object and its properties, methods, and event handlers for details.
There are a few practical differences between Window objects that represent top-level browser windows and those that represent frames within a browser window, however:
When the defaultStatus property is set for a frame, the specified status message is visible only when the mouse is within that frame.
The top and parent properties of a top-level browser window always refer to the top-level window itself. These properties are really useful only for frames.
The close( ) method is not useful for Window objects that are frames.
| getClass( ) | return the JavaClass of a JavaObject |
Netscape 3 LiveConnect
getClass(javaobj)
The JavaClass object of javaobj.
getClass( ) is a function that takes a JavaObject object ( javaobj) as an argument. It returns the JavaClass object of that JavaObject. That is, it returns the JavaClass object that represents the Java class of the Java object represented by the specified JavaObject.
Don't confuse the JavaScript getClass( ) function with the getClass method of all Java objects. Similarly, don't confuse the JavaScript JavaClass object with the Java java.lang.Class class.
Consider the Java Rectangle object created with the following line:
var r = new java.awt.Rectangle( );
r is a JavaScript variable that holds a JavaObject object. Calling the JavaScript function getClass( ) returns a JavaClass object that represents the java.awt.Rectangle class:
var c = getClass(r);
You can see this by comparing this JavaClass object to java.awt.Rectangle:
if (c == java.awt.Rectangle) ...
The Java getClass( ) method is invoked differently and performs an entirely different function:
c = r.getClass( );
After executing the above line of code, c is a JavaObject that represents a java.lang.Class object. This java.lang.Class object is a Java object that is a Java representation of the java.awt.Rectangle class. See your Java documentation for details on what you can do with the java.lang.Class class.
To summarize, you can see that the following expression always evaluates to true for any JavaObject o:
(getClass(o.getClass( )) == java.lang.Class)
JavaArray, JavaClass, JavaObject, JavaPackage, the java property of the Window object; Chapter 22
| Hidden | hidden data for client/server communication |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
form.name form.elements[i]
Hidden inherits properties from Input and HTMLElement and defines or overrides the following:
A Hidden element is created with a standard HTML <input> tag:
<form>
...
<input
type="hidden" // Specifies that this is a Hidden element
[ name="name" ] // A name you can use later to refer to this element
// Specifies the name property
[ value="value" ] // The value transmitted when the form is submitted
// Specifies the initial value of the value property
>
...
</form> The Hidden element is an invisible form element that allows arbitrary data to be transmitted to the server when the form is submitted. You can use a Hidden element when you want to transmit information other than the user's input data to the server.
When an HTML document is generated on the fly by a server, another use of Hidden form elements is to transmit data from the server to the client for later processing by JavaScript on the user's side. For example, the server might transmit raw data to the client in a compact, machine-readable form by specifying the data in the value attribute of a Hidden element or elements. On the client side, a JavaScript program (transmitted along with the data or in another frame) could read the value property of the Hidden element or elements and process, format, and display that data in a less compact, human-readable (and perhaps user-configurable) format.
Hidden elements can also be useful for communication between CGI scripts, even without the intervention of JavaScript on the client side. In this usage, one CGI script generates a dynamic HTML page containing hidden data, which is then submitted to a second CGI script. This hidden data can communicate state information, such as the results of the submission of a previous form.
Cookies can also be used to transmit data from client to server. An important difference between Hidden form elements and cookies, however, is that cookies are persistent on the client side.
Document.cookie, Form, HTMLElement, Input; HTMLInputElement in the DOM reference section
| History | the URL history of the browser |
window.history frame.history history
The History object represents the browsing history of a window -- it maintains a list of recently visited web pages. For security and privacy reasons, however, the contents of this list are not accessible to scripts. Although scripts cannot access the URLs represented by the History object, they can use the length property to determine the number of URLs in the list and the back( ), forward( ), and go( ) methods to cause the browser to revisit any of the URLs in the array.
The following line performs the same action as clicking a browser's Back button:
history.back( );
The following performs the same action as clicking the Back button twice:
history.go(-2);
| History.back( ) | return to the previous URL |
history.back( )
back( ) causes the window or frame to which the History object belongs to revisit the URL (if any) that was visited immediately before the current one. Calling this method has the same effect as clicking on the browser's Back button. It is also equivalent to:
history.go(-1);
| History.forward( ) | visit the next URL |
history.forward( )
forward( ) causes the window or frame to which the History object belongs to revisit the URL (if any) that was visited immediately after the current one. Calling this method has the same effect as clicking on the browser's Forward button. It is also equivalent to:
history.go(1);
Note that if the user has not used the Back button or the Go menu to move backward through the history, and if JavaScript has not invoked the History.back( ) or History.go( ) methods, the forward( ) method has no effect because the browser is already at the end of its list of URLs, and there is no URL to go forward to.
| History.go( ) | revisit a URL |
JavaScript 1.0; enhanced in JavaScript 1.1
history.go(relative_position) history.go(target_string)
The first form of the History.go( ) method takes an integer argument and causes the browser to visit the URL that is the specified number of positions distant in the history list maintained by the History object. Positive arguments move the browser forward through the list, and negative arguments move it backward. Thus, calling history.go(-1) is equivalent to calling history.back( ) and produces the same effect as clicking on the Back button. Similarly, history.go(3) revisits the same URL that would be visited by calling history.forward( ) three times. Calling go( ) with an argument of 0 causes the current page to be reloaded (although in Netscape 3, the Location.reload( ) provides a better way of doing this). This form of the method is buggy in multiframe documents in Netscape 3, and in Internet Explorer it can be called only with the values 1, 0, and -1.
The second form of the History.go( ) method was implemented in JavaScript 1.1. It takes a string argument and causes the browser to revisit the first (i.e., most recently visited) URL that contains the specified string.
| HTMLElement | the superclass of all HTML elements |
HTMLElement is the superclass of all classes that represent HTML elements. Therefore, HTMLElement objects are used in many contexts in client-side JavaScript and are available in all of the following ways:
document.images[i] document.links[i] document.anchors[i] document.forms[i] document.forms[i].elements[j] document.elementName document.formName.elementName document.all[i]
HTMLElement is the superclass of all JavaScript classes that represent HTML elements: Anchor, Form, Image, Input, Link, and so on. HTMLElement defines event handlers that are implemented by all elements in both IE 4 and Netscape 4. Because The IE 4 document object model exposes all HTML elements in a document, it defines quite a few properties and methods for those elements. Netscape 4 implements none of these IE properties and methods (except handleEvent( ), which is Netscape-specific), but Netscape 6 implements those that have been standardized by the W3C DOM. See the Chapter 25 reference section for complete information on the standard properties and methods of HTML elements.
Anchor, Form, Image, Input, Link; Chapter 17; Chapter 19; Element, HTMLElement, and Node in the DOM reference section
| HTMLElement.contains( ) | whether one element is contained in another |
element.contains(target)
true if element contains target; false if it does not.
| HTMLElement.getAttribute( ) | get an attribute value |
Internet Explorer 4, Netscape 6
element.getAttribute(name)
The value of the named attribute of element or null if element does not have an attribute named name.
| HTMLElement.handleEvent( ) | see Window.handleEvent( ) |
| HTMLElement.insertAdjacentHTML( ) | insert HTML text around an element |
element.insertAdjacentHTML(where, text)
insertAdjacentHTML( ) inserts the HTML text at a position within or next to element, as specified by the argument where.
| HTMLElement.insertAdjacentText( ) | insert plain text before or after an element |
element.insertAdjacentText(where, text)
insertAdjacentText( ) inserts the plain text text at a position within or next to element, as specified by the argument where.
| HTMLElement.onclick | the handler invoked when the user clicks on an element |
<element onclick="handler" ... > element.onclick
The onclick property of an HTMLElement object specifies an event handler function that is invoked when the user clicks on the element. Note that onclick is different than onmousedown. A click event does not occur unless a mousedown event and the subsequent mouseup event both occur over the same element.
The initial value of this property is a function that contains the JavaScript statements specified by the onclick attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onclick handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
In Netscape 4, the Event.which property specifies which mouse button was pressed. In IE 4, the Event.button property specifies the button number.
Event, Input.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| HTMLElement.ondblclick | the handler invoked when the user double-clicks on an element |
<element ondblclick="handler" ... > element.ondblclick
The ondblclick property of an HTMLElement object specifies an event handler function that is invoked when the user double-clicks on the element.
The initial value of this property is a function that contains the JavaScript statements specified by the ondblclick attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the ondblclick handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
Event; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| HTMLElement.onhelp | the handler invoked when the user presses F1 |
<element onhelp="handler" ... > element.onhelp
The onhelp property of element specifies an event handler function that is invoked when the user presses the F1 key while element has keyboard focus.
The initial value of this property is a function that contains the JavaScript statements specified by the onhelp attribute of the HTML tag that defined the element. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
After the onhelp handler function is invoked, Internet Explorer 4 displays the built-in help window.
| HTMLElement.onkeydown | the handler invoked when the user presses a key |
<element onkeydown="handler" ... > element.onkeydown
The onkeydown property of an HTMLElement object specifies an event handler function that is invoked when the user presses a key over the element.
The initial value of this property is a function that contains the JavaScript statements specified by the onkeydown attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onkeydown handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
The character code of the key pressed is contained in the which property of the Event object in Netscape and in the keyCode property of the Event object in IE. You can convert this keycode to a string with String.fromCharCode( ). The modifier keys in effect can be determined from the Event.modifiers property in Netscape or with Event.shiftKey( ) and related methods in IE.
In the Netscape event model, you can cancel processing of the keystroke by returning false from this handler. In the IE event model, you cancel processing by setting Event.returnValue to false. In IE, this handler may return an alternate keycode that is used in place of the key actually pressed by the user.
You can often use the onkeypress event handler instead of the onkeydown and onkeyup handlers.
| HTMLElement.onkeypress | the handler invoked when the user presses a key |
<element onkeypress="handler" ... > element.onkeypress
The onkeypress property of an HTMLElement object specifies an event handler function that is invoked when the user presses a key over the element. A keypress event is generated after a key down event and before the corresponding key up event. The keypress and key down events are similar. Unless you care about receiving individual key up events, you should use onkeypress instead of onkeydown.
The initial value of this property is a function that contains the JavaScript statements specified by the onkeypress attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onkeypress handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
The character code of the key pressed is contained in the which property of the Event object in Netscape and in the keyCode property of the Event object in IE. You can convert this keycode to a string with String.fromCharCode( ). The modifier keys in effect can be determined from the Event.modifiers property in Netscape or with Event.shiftKey( ) and related methods in IE.
In Netscape, you can cancel processing of the keystroke by returning false from this handler. In IE, you cancel processing by setting Event.returnValue to false. In IE, this handler may return an alternate keycode that is used in place of the key actually pressed by the user.
| HTMLElement.onkeyup | the handler invoked when the user releases a key |
JavaScript 1.2; HTML 4.0
<element onkeyup=" handler" ... > element.onkeyup
The onkeyup property of an HTMLElement object specifies an event handler function that is invoked when the user releases a key over the element.
The initial value of this property is a function that contains the JavaScript statements specified by the onkeyup attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onkeyup handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
| HTMLElement.onmousedown | the handler invoked when the user presses a mouse button |
<element onmousedown="handler" ... > element.onmousedown
The onmousedown property of an HTMLElement object specifies an event handler function that is invoked when the user presses a mouse button over element.
The initial value of this property is a function that contains the JavaScript statements specified by the onmousedown attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onmousedown handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
In Netscape, the Event.which property specifies which mouse button was pressed. In IE, the Event.button property specifies the button number.
Event, HTMLElement.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| HTMLElement.onmousemove | the handler invoked when the mouse moves within an element |
JavaScript 1.2; HTML 4.0
<element onmousemove="handler" ... > element.onmousemove
The onmousemove property of an HTMLElement object specifies an event handler function that is invoked when the user moves the mouse pointer within the element.
The initial value of this property is a function that contains the JavaScript statements specified by the onmousemove attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onmousemove handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
If you define an onmousemove event handler, mouse motion events are generated and reported in huge quantities when the mouse is moved within element. Keep this in mind when writing the function to be invoked by the event handler.
In Netscape 4, you cannot define this event handler on individual elements; instead, you must explicitly register your interest in mouse motion events by capturing them with the captureEvents( ) method of a Window, Document, or Layer object.
Event, Window.captureEvents( ); Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| HTMLElement.onmouseout | the handler invoked when mouse moves out of an element |
<element onmouseout="handler" ... > element.onmouseout
The onmouseout property of an HTMLElement object specifies an event handler function that is invoked when the user moves the mouse pointer out of the element.
The initial value of this property is a function that contains the JavaScript statements specified by the onmouseout attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onmouseout handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
Event, Link.onmouseout; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| HTMLElement.onmouseover | the handler invoked when the mouse moves over an element |
<element onmouseover="handler" ... > element.onmouseover
The onmouseover property of an HTMLElement object specifies an event handler function that is invoked when the user moves the mouse pointer over the element.
The initial value of this property is a function that contains the JavaScript statements specified by the onmouseover attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In Netscape 4, the onmouseover handler function is passed an Event object as an argument. In IE 4, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
| HTMLElement.onmouseup | the handler invoked when the user releases a mouse button |
<element onmouseup="handler" ... > element.onmouseup
The onmouseup property of an HTMLElement object specifies an event handler function that is invoked when the user releases a mouse button over the element.
The initial value of this property is a function that contains the JavaScript statements specified by the onmouseup attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onmouseup handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
In Netscape 4, the Event.which property specifies which mouse button was pressed. In IE, the Event.button property specifies the button number.
Event, HTMLElement.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| HTMLElement.removeAttribute( ) | delete an attribute |
Internet Explorer 4, Netscape 6
element.removeAttribute(name)
true on success; false on failure.
removeAttribute( ) deletes the attribute name from element. If element does not have an attribute named name, this method returns false.
| HTMLElement.scrollIntoView( ) | make an element visible |
element.scrollIntoView(top)
scrollIntoView( ) scrolls the document containing element so the top of element is aligned with the top of the display area or the bottom of element is aligned with the bottom of the display area.
| HTMLElement.setAttribute( ) | set the value of an attribute |
Internet Explorer 4, Netscape 6
element.setAttribute(name, value)
setAttribute( ) sets the attribute name of element to value.
| Image | an image in an HTML document |
Inherits from HTMLElement
document.images[i] document.images.length document.image-name
new Image(width, height)
Image inherits properties from HTMLElement and defines the following properties, most of which correspond to the HTML attributes of the <img> tag. In JavaScript 1.1 and later, the src and lowsrc properties are read/write and may be set to change the displayed image. In browsers that do not allow document reflow, such as IE 3 and Netscape 4, the other properties are read-only.
Setting this property has no immediate effect. If the src property is set, however, a new image is loaded, and on low-resolution systems, the current value of the lowsrc property is used instead of the newly updated value of src.
Image inherits event handlers from HTMLElement and defines the following:
The Image object is created with a standard HTML <img> tag. Some <img> attributes have been omitted from the following syntax because they are not used by or accessible from JavaScript:
<img src="url" // The image to display
width="pixels" // The width of the image
height="pixels" // The height of the image
[ name="image_name" ] // A property name for the image
[ lowsrc="url" ] // Alternate low-resolution image
[ border="pixels" ] // Width of image border
[ hspace="pixels" ] // Extra horizontal space around image
[ vspace="pixels" ] // Extra vertical space around image
[ onload="handler" ] // Invoked when image is fully loaded
[ onerror="handler" ] // Invoked if error in loading
[ onabort="handler" ] // Invoked if user aborts load
>The Image objects in the document.images[] array represent the images embedded in an HTML document using the <img> tag. The src property is the most interesting one; when you set this property, the browser loads and displays the image specified by the new value.
You can create Image objects dynamically in your JavaScript code using the Image( ) constructor function. Note that this constructor method does not have an argument to specify the image to be loaded. As with images created from HTML, you tell the browser to load an image by setting the src property of any images you create explicitly. There is no way to display an Image object in the web browser. All you can do is force the Image object to download an image by setting the src property. This is useful, however, because it loads an image into the browser's cache. Later, if that same image URL is specified for one of the images in the images[] array, it is preloaded and displays quickly. You can do this with the following lines:
document.images[2].src = preloaded_image.src; document.toggle_image.src = toggle_off.src;
Setting the src property of an Image object is a way to implement simple animations in your web pages. It is also an excellent technique for changing the graphics on a page as the user interacts with the page. For example, you can create your own Submit button using an image and a hypertext link. The button will start out with a disabled graphic and remain that way until the user correctly enters all the required information into the form, at which point the graphic changes, and the user is able to submit the form.
| Image.onabort | the handler invoked when the user aborts image loading |
<img ... onabort="handler" ... > image.onabort
The onabort property of an Image object specifies an event handler function that is invoked when the user aborts the loading of an image (for example, by clicking the Stop button).
The initial value of this property is a function that contains the JavaScript statements specified by the onabort attribute of the <img> tag that defined the Image object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onabort handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
| Image.onerror | the handler invoked when an error occurs during image loading |
<img ... onerror="handler" ... > image.onerror
The onerror property of an Image object specifies an event handler function that is invoked when an error occurs during the loading of an image.
The initial value of this property is a function that contains the JavaScript statements specified by the onerror attribute of the <img> tag that defined the Image object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onerror handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
| Image.onload | the handler invoked when an image finishes loading |
<img ... onload="handler" ... > image.onload
The onload property of an Image object specifies an event handler function that is invoked when an image loads successfully.
The initial value of this property is a function that contains the JavaScript statements specified by the onload attribute of the <img> tag that defined the Image object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onload handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Input | an input element in an HTML form |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from HTMLElement
form.elements[i] form.name
Input inherits properties from HTMLElement and defines or overrides the following:
Input inherits methods from HTMLElement and defines or overrides the following:
Input inherits event handlers from HTMLElement and defines or overrides the following:
Form elements are stored in the elements[] array of the Form object. The contents of this array are Input objects, which represent the individual buttons, input fields, and other controls that appear within the form. Many types of input elements are created with the <input> tag; others are created with the <select> and <option> tags and the <textarea> tag. The various form input elements share quite a few properties, methods, and event handlers, which are described on this reference page. Specific behaviors for specific types of form elements are described on their own pages.
The Input object defines many shared properties, methods, and event handlers, but not all of them are shared by all types of form elements. For example, the Button object triggers the onclick event handler but not the onchange handler, while the Text object triggers onchange but not onclick. The following figure shows all of the form elements and the properties associated with them.
|
|
There are two broad categories of form elements. The first is the buttons: Button, Checkbox, Radio, Reset, and Submit. These elements have an onclick event handler but not an onchange handler. Similarly, they respond to the click( ) method but not to the select( ) method. The second category contains those elements that display text: Text, Textarea, Password, and FileUpload. These elements have an onchange event handler rather than an onclick handler, and they respond to the select( ) method but not to the click( ) method.
The Select element is a special case. It is created with the <select> tag and is less like the <input> elements than the other form elements. Although the Select element is technically represented by a different object type, it is still convenient to consider it an Input object.
Button, Checkbox, FileUpload, Form, Hidden, Password, Radio, Reset, Select, Submit, Text, Textarea; Chapter 15; HTMLInputElement in the DOM reference section
| Input.blur( ) | remove keyboard focus from a form element |
input.blur( )
The blur( ) method of a form element removes keyboard focus from that element without invoking the onblur event handler; it is essentially the opposite of the focus( ) method. The blur( ) method does not transfer keyboard focus anywhere, however, so the only time that it is actually useful to call this method right before you transfer keyboard focus elsewhere with the focus( ) method, when you don't want to trigger the onblur event handler. That is, by removing focus explicitly from the element, you won't be notified when it is removed implicitly by a focus( ) call on another element.
All form elements other than Hidden support the blur( ) method. Unfortunately, not all platforms support keyboard navigation equally well. In Netscape 2 and 3 for Unix platforms, the blur( ) method is functional only for those form elements that display text: Text, Textarea, Password, and FileUpload.
| Input.click( ) | simulate a mouse-click on a form element |
input.click( )
The click( ) method of a form element simulates a mouse-click on the form element but does not invoke the onclick event handler of the element.
The click( ) method is not often useful. Because it does not invoke the onclick event handler, it is not useful to call this method on Button elements -- they don't have any behavior other than that defined by the onclick handler. Calling click( ) on a Submit or Reset element submits or resets a form, but this can be more directly achieved with the submit( ) and reset( ) method of the Form object itself.
| Input.focus( ) | give keyboard focus to a form element |
JavaScript 1.0
input.focus( )
The focus( ) method of a form element transfers keyboard focus to that element without calling the onfocus event handler. That is, it makes the element active with respect to keyboard navigation and keyboard input. Thus, if you call focus( ) for a Text element, any text the user types appears in that text element. Or, if you call focus( ) for a Button element, the user can invoke that button from the keyboard.
All form elements except the Hidden element support the focus( ) method. Unfortunately, not all platforms support keyboard navigation equally well. In Unix versions of Netscape, focus( ) is functional only for those form elements that display text: Text, Textarea, Password, and FileUpload.
| Input.name | the name of a form element |
input.name
name is a read-only string property of every form element. The value of this property is set by the name attributes of the HTML <input> tag that defines the form element.
The name of a form element is used for two purposes. First, it is used when the form is submitted. Data for each element in the form is usually submitted in the format:
name=value
where name and value are encoded as necessary for transmission. If a name is not specified for a form element, the data for that element cannot be submitted to a web server.
The second use of the name property is to refer to a form element in JavaScript code. The name of an element becomes a property of the form that contains the element. The value of this property is a reference to the element. For example, if address is a form that contains a text input element with the name zip, address.zip refers to that text input element.
With Radio and Checkbox form elements, it is common to define more than one related object, each of which have the same name property. In this case, data is submitted to the server with this format:
name=value1,value2,...,valuen
Similarly, in JavaScript, each of the elements that shares a name becomes an element of an array with that name. Thus, if four Checkbox objects in the form order share the name options, they are available in JavaScript as elements of the array order.options[].
| Input.onblur | the handler invoked when a form element loses focus |
<input type="type"onblur="handler"> input.onblur
The onblur property of an Input object specifies an event handler function that is invoked when the user transfers keyboard focus away from that input element. Calling blur( ) to remove focus from an element does not invoke onblur for that object. Note, however, that calling focus( ) to transfer focus to some other element causes the onblur event handler to be invoked for whichever element currently has the focus.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onblur attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onblur handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
The onblur event handler is available for all form elements except the Hidden element. In Netscape on Unix platforms, however, it is invoked only for the text-entry elements: Text, Textarea, Password, and FileUpload. Note that in JavaScript 1.1, the Window object also defines an onblur event handler.
Window.onblur; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Input.onchange | the handler invoked when a form element's value changes |
<input type="type"onchange="handler"> input.onchange
The onchange property of an Input object specifies an event handler function that is invoked when the user changes the value displayed by a form element. Such a change may be an edit to the text displayed in Text, Textarea, Password, or FileUpload elements, or the selection or deselection of an option in a Select element. Note that this event handler is only invoked when the user makes such a change -- it is not invoked if a JavaScript program changes the value displayed by an element.
Also note that the onchange handler is not invoked every time the user enters or deletes a character in a text-entry form element. onchange is not intended for that type of character-by-character event handling. Instead, onchange is invoked when the user's edit is complete. The browser assumes that the edit is complete when keyboard focus is moved from the current element to some other element -- for example, when the user clicks on the next element in the form. See the HTMLElement.onkeypress reference page for character-by-character event notification.
The onchange event handler is not used by the Hidden element or by any of the button elements. Those elements -- Button, Checkbox, Radio, Reset, and Submit -- use the onclick event handler instead.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onchange attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onchange handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
HTMLElement.onkeypress; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Input.onclick | the handler invoked when a form element is clicked |
JavaScript 1.0; enhanced in JavaScript 1.1
<input type="type"onclick="handler"> input.onclick
The onclick property of an Input object specifies an event handler function that is invoked when the user clicks on the input element. It is not invoked when the click( ) method is called for the element.
Only form elements that are buttons invoke the onclick event handler. These are the Button, Checkbox, Radio, Reset, and Submit elements. Other form elements use the onchange event handler instead of onclick.
The initial value of the onclick property is a function containing the semicolon-separated JavaScript statements specified by the onclick attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onclick handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
Note that the Reset and Submit elements perform a default action when clicked: they reset and submit, respectively, the form that contains them. You can use the onclick event handlers of each of these elements to perform actions in addition to these default actions. In JavaScript 1.1, you can also prevent these default actions by returning false. That is, if the onclick handler of a Reset button returns false, the form is not reset, and if the onclick handler of a Submit button returns false, the form is not submitted. Note that you do similar things with the onsubmit and onreset event handlers of the Form object itself.
Finally, note that the Link object also defines an onclick event handler.
Link.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Input.onfocus | the handler invoked when a form element gains focus |
<input type="type"onfocus="handler"> input.onfocus
The onfocus property of an Input object specifies an event handler function that is invoked when the user transfers keyboard focus to that input element. Calling focus( ) to set focus to an element does not invoke onfocus for that object.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onfocus attribute of the HTML tag that defined the object. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onfocus handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
The onfocus event handler is available for all form elements except the Hidden element. In Netscape on Unix platforms, however, it is invoked only for the text-entry elements: Text, Textarea, Password, and FileUpload. Note that in JavaScript 1.1, the Window object also defines an onfocus event handler.
Window.onfocus; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Input.select( ) | select the text in a form element |
input.select( )
The select( ) method selects the text displayed in a Text, Textarea, Password, or FileUpload element. The effects of selecting text may vary from platform to platform, but typically, invoking this method produces the same result as the user dragging the mouse across all the text in the specified Text object. On most platforms, this produces the following effects:
The text is highlighted, often displayed with colors reversed.
If the text remains selected the next time the user types a character, the selected text is deleted and replaced with the newly typed character.
On some platforms, the text becomes available for cut-and-paste.
The user can usually deselect text by clicking in the Text object or by moving the cursor. Once deselected, the user can add and delete individual characters without replacing the entire text value.
| Input.type | the type of a form element |
input.type
type is a read-only string property of all form elements that specifies the type of the form element. The value of this property for each possible form element is given in the following table.
|
Object type |
HTML tag |
type property |
|---|---|---|
|
Button |
<input type="button"> |
"button" |
|
Checkbox |
<input type="checkbox"> |
"checkbox" |
|
FileUpload |
<input type="file"> |
"file" |
|
Hidden |
<input type="hidden"> |
"hidden" |
|
Password |
<input type="password"> |
"password" |
|
Radio |
<input type="radio"> |
"radio" |
|
Reset |
<input type="reset"> |
"reset" |
|
Select |
<select> |
"select-one" |
|
Select |
<select multiple> |
"select-multiple" |
|
Submit |
<input type="submit"> |
"submit" |
|
Text |
<input type="text"> |
"text" |
|
Textarea |
<textarea> |
"textarea" |
Note that the Select element has two possible type values, depending on whether it allows single or multiple selection. Also note that unlike other input element properties, type is not available in JavaScript 1.0.
| Input.value | the value displayed or submitted by a form element |
Netscape 2; buggy in Internet Explorer 3
input.value
value is a read/write string property of all form elements that specifies the value displayed by the form element and/or submitted for the element when the form is submitted. The value property of the Text element, for example, is the user's input, which is also the value submitted with the form. For the Checkbox object, on the other hand, the value property specifies a string that is not displayed but is submitted with the form if the Checkbox element is checked when the form is submitted.
The initial value of the value property is specified by the value attribute of the HTML tag that defines the form element.
For Button, Submit, and Reset objects, the value property specifies the text that appears within the button. On some platforms, changing the value property of these elements actually changes the text displayed by the buttons onscreen. This does not work on all platforms, however, and is not an advisable technique. Changing the label of a button may change the size of the button, causing it to overlap and obscure other portions of the document.
The Select element has a value property, like all form elements, but does not use it. Instead, the value submitted by this element is specified by the value property of the Option objects it contains.
For security reasons, the value property of the FileUpload element is read-only.
| JavaArray | JavaScript representation of a Java array |
javaarray.length // The length of the array javaarray[index] // Read or write an array element
The JavaArray object is a JavaScript representation of a Java array that allows JavaScript code to read and write the elements of the array using familiar JavaScript array syntax. In addition, the JavaArray object has a length field that specifies the number of elements in the Java array.
When reading and writing values from array elements, data conversion between JavaScript and Java representations is automatically handled by the system. See Chapter 22 for full details.
Note that Java arrays differ from JavaScript arrays in a couple of important aspects. First, Java arrays have a fixed length that is specified when they are created. For this reason, the JavaArray length field is read-only. The second difference is that Java arrays are typed (i.e., their elements must all be of the same type of data). Attempting to set an array element to a value of the wrong type results in a JavaScript error or exception.
java.awt.Polygon is a JavaClass object. We can create a JavaObject representing an instance of the class like this:
p = new java.awt.Polygon( );
The object p has properties xpoints and ypoints, which are JavaArray objects representing Java arrays of integers. We can initialize the contents of these arrays with JavaScript code like the following:
for(int i = 0; i < p.xpoints.length; i++)
p.xpoints[i] = Math.round(Math.random( )*100);
for(int i = 0; i < p.ypoints.length; i++)
p.ypoints[i] = Math.round(Math.random( )*100); getClass( ), JavaClass, JavaObject, JavaPackage, the java property of the Window object; Chapter 22
| JavaClass | JavaScript representation of a Java class |
javaclass.static_member // Read or write a static Java field or method new javaclass(...) // Create a new Java object
Each JavaClass object contains properties that have the same names as the public static fields and methods of the Java class it represents. These properties allow you to read and write the static fields of the class and invoke the static methods of the class. Each JavaClass object has different properties; you can use a for/in loop to enumerate them for any given JavaClass object.
The JavaClass object is a JavaScript representation of a Java class. The properties of a JavaClass object represent the public static fields and methods (sometimes called class fields and class methods) of the represented class. Note that the JavaClass object does not have properties representing the instance fields of a Java class -- individual instances of a Java class are represented by the JavaObject object.
The JavaClass object implements the LiveConnect functionality that allows JavaScript programs to read and write the static variables of Java classes using normal JavaScript syntax. It also provides the functionality that allows JavaScript to invoke the static methods of a Java class.
In addition to allowing JavaScript to read and write Java variable and method values, the JavaClass object allows JavaScript programs to create Java objects (represented by a JavaObject object) by using the new keyword and invoking the constructor method of a JavaClass.
The data conversion required for communication between JavaScript and Java through the JavaClass object is handled automatically by LiveConnect. See Chapter 22 for full details.
Bear in mind that Java is a typed language. This means that each of the fields of an object has a specific data type that is set to values of only that type. Attempting to set a field to a value that is not of the correct type results in a JavaScript error or exception. Attempting to invoke a method with arguments of the wrong type also causes an error or exception.
java.lang.System is a JavaClass object that represents the java.lang.System class in Java. You can read a static field of this class with code like the following:
var java_console = java.lang.System.out;
You can invoke a static method of this class with a line like this one:
var version = java.lang.System.getProperty("java.version"); Finally, the JavaClass object also allows you to create new Java objects:
var java_date = new java.lang.Date( );
getClass( ), JavaArray, JavaObject, JavaPackage, the java property of the Window object; Chapter 22
| JavaObject | JavaScript representation of a Java object |
javaobject.member // Read or write an instance field or method
Each JavaObject object contains properties that have the same names as the public instance fields and methods (but not the static or class fields and methods) of the Java object it represents. These properties allow you to read and write the value of public fields and invoke the public methods. The properties of a given JavaObject object obviously depend on the type of Java object it represents. You can use the for/in loop to enumerate the properties of any given JavaObject.
The JavaObject object is a JavaScript representation of a Java object. The properties of a JavaObject object represent the public instance fields and public instance methods defined for the Java object. (The class or static fields and methods of the object are represented by the JavaClass object.)
The JavaObject object implements the LiveConnect functionality that allows JavaScript programs to read and write the public instance fields of a Java object using normal JavaScript syntax. It also provides the functionality that allows JavaScript to invoke the methods of a Java object. Data conversion between JavaScript and Java representations is handled automatically by LiveConnect. See Chapter 22 for full details.
Bear in mind that Java is a typed language. This means that each of the fields of an object has a specific data type, and you can set it only to values of that type. For example, the width field of a java.awt.Rectangle object is an integer field, and attempting to set it to a string causes a JavaScript error or exception.
java.awt.Rectangle is a JavaClass that represents the java.awt.Rectangle class. We can create a JavaObject that represents an instance of this class like this:
var r = new java.awt.Rectangle(0,0,4,5);
We can then read the public instance variables of this JavaObject r with code like this:
var perimeter = 2*r.width + 2*r.height;
We can also set the value of public instance variables of r using JavaScript syntax:
r.width = perimeter/4; r.height = perimeter/4;
getClass( ), JavaArray, JavaClass, JavaPackage, the java property of the Window object; Chapter 22
| JavaPackage | JavaScript representation of a Java package |
package.package_name // Refers to another JavaPackage package.class_name // Refers to a JavaClass object
The properties of a JavaPackage object are the names of the JavaPackage objects and JavaClass objects that it contains. These properties are different for each individual JavaPackage. Note that it is not possible to use the JavaScript for/in loop to iterate over the list of property names of a Package object. Consult a Java reference manual to determine the packages and classes contained within any given package.
The JavaPackage object is a JavaScript representation of a Java package. A package in Java is a collection of related classes. In JavaScript, a JavaPackage can contain classes (represented by the JavaClass object) and other JavaPackage objects.
The Window object has properties java, netscape, and sun that represent the java.*, netscape.*, and sun.* package hierarchies. These JavaPackage objects define properties that refer to other JavaPackage objects. For example, java.lang and java.net refer to the java.lang and java.net packages. The java.awt JavaPackage contains properties named Frame and Button, which are both references to JavaClass objects and represent the classes java.awt.Frame and java.awt.Button.
The Window object also defines a property named Packages, which is the root JavaPackage whose properties refer to the roots of all known package hierarchies. For example, the expression Packages.java.awt is the same as java.awt.
It is not possible to use the for/in loop to determine the names of the packages and classes contained within a JavaPackage. You must have this information in advance. You can find it in any Java reference manual or by examining the Java class hierarchy.
See Chapter 22 for further details on working with Java packages, classes, and objects.
JavaArray, JavaClass, JavaObject; the java, netscape, sun, and Packages properties of the Window object; Chapter 22
| JSObject | Java representation of a JavaScript object |
Netscape 3, Internet Explorer 4
public final class netscape.javascript.JSObject extends Object
The JSObject is a Java class, not a JavaScript object; it cannot be used in your JavaScript programs. Instead, the JSObject is used by Java applets that wish to communicate with JavaScript by reading and writing JavaScript properties and array elements, invoking JavaScript methods, and evaluating and executing arbitrary strings of JavaScript code. Obviously, since JSObject is a Java class, you must understand Java programming in order to use it.
Full details on programming with the JSObject can be found in Chapter 22.
| JSObject.call( ) | invoke a method of a JavaScript object |
Netscape 3, Internet Explorer 4
public Object call(String methodName, Object args[])
A Java object that represents the return value of the JavaScript method.
The call( ) method of the Java JSObject class invokes a named method of the JavaScript object represented by the JSObject. Arguments are passed to the method as an array of Java objects, and the return value of the JavaScript method is returned as a Java object.
Chapter 22 describes the data conversion of the method arguments from Java objects to JavaScript values and the method return value from a JavaScript value to a Java object.
| JSObject.eval( ) | evaluate a string of JavaScript code |
Netscape 3, Internet Explorer 4
public Object eval(String s)
The JavaScript value of the last expression evaluated in s, converted to a Java object.
The eval( ) method of the Java JSObject class evaluates the JavaScript code contained in the string s in the context of the JavaScript object specified by the JSObject. The behavior of the eval( ) method of the Java JSObject class is much like that of the JavaScript global eval( ) function.
The argument s may contain any number of JavaScript statements separated by semicolons; these statements are executed in the order in which they appear. The return value of eval( ) is the value of the last statement or expression evaluated in s.
| JSObject.getMember( ) | read a property of a JavaScript object |
Netscape 3, Internet Explorer 4
public Object getMember(String name)
A Java object that contains the value of the named property of the specified JSObject.
The getMember( ) method of the Java JSObject class reads and returns to Java the value of a named property of a JavaScript object. The return value may be another JSObject object or a Double, Boolean, or String object, but it is returned as a generic Object, which you must cast as necessary.
| JSObject.getSlot( ) | read an array element of a JavaScript object |
Netscape 3, Internet Explorer 4
public Object getSlot(int index)
The value of the array element at the specified index of a JavaScript object.
The getSlot( ) method of the Java JSObject class reads and returns to Java the value of an array element at the specified index of a JavaScript object. The return value may be another JSObject object or a Double, Boolean, or String object, but it is returned as a generic Object, which you must cast as necessary.
| JSObject.getWindow( ) | return initial JSObject for browser window |
Netscape 3, Internet Explorer 4
public static JSObject getWindow(java.applet.Applet applet)
A JSObject that represents the JavaScript Window object for the web browser window that contains the specified applet.
The getWindow( ) method is the first JSObject method that any Java applet calls. JSObject does not define a constructor, and the static getWindow( ) method provides the only way to obtain an initial "root" JSObject from which other JSObjects may be obtained.
| JSObject.removeMember( ) | delete a property of a JavaScript object |
Netscape 3, Internet Explorer 4
public void removeMember(String name)
The removeMember( ) method of the Java JSObject class deletes a named property from the JavaScript object represented by the JSObject.
| JSObject.setMember( ) | set a property of a JavaScript object |
Netscape 3, Internet Explorer 4
public void setMember(String name, Object value)
The setMember( ) method of the Java JSObject class sets the value of a named property of a JavaScript object from Java. The specified value may be any Java Object. Primitive Java values may not be passed to this method. In JavaScript, the specified value is accessible as a JavaObject object.
| JSObject.setSlot( ) | set an array element of a JavaScript object |
Netscape 3, Internet Explorer 4
public void setSlot(int index, Object value)
The setSlot( ) method of the Java JSObject class sets the value of a numbered array element of a JavaScript object from Java. The specified value may be any Java Object. Primitive Java values may not be passed to this method. In JavaScript, the specified value is accessible as a JavaObject object.
| JSObject.toString( ) | return the string value of a JavaScript object |
Netscape 3, Internet Explorer 4
public String toString( )
The string returned by invoking the toString( ) method of the JavaScript object represented by the specified Java JSObject.
The toString( ) method of the Java JSObject class invokes the JavaScript toString( ) method of the JavaScript object represented by a JSObject and returns the result of that method.
| Layer | an independent layer in a DHTML document |
Netscape 4 only; discontinued in Netscape 6
document.layers[i]
new Layer(width, parent)
The Layer( ) constructor creates a new Layer object and returns it. You can set its size, position, and other attributes with the various Layer properties and methods described in the following lists. In particular, you must set the hidden property to false to make the new layer visible. See the src property and load( ) methods in particular for ways to set the content of a layer. Alternatively, you can dynamically generate content for the layer by writing to its document property.
Note that you can only call the Layer( ) constructor once the current document and all of its layers have finished loading.
zIndex is a read/write property. Setting this property changes the stacking order and redisplays the layers in the new order. Setting this property may reorder the layers[] array of the containing document.
A Layer object can be created with the Netscape-specific <layer> tag in HTML:
<layer [ id="layername" ] // Layer name [ left="x" ] // Position relative to containing layer [ top="y" ] [ pagex="x" ] // Position relative to top-level document [ pagey="y" ] [ width="w" ] // Size of layer [ height="h" ] [ src="url" ] // URL of layer contents [ clip="x,y,w,h" ] // Clipping rectangle for layer [ clip="w,h" ] // Alternate syntax: x,y default to 0 [ zindex="z" ] // Stacking order [ above="layername" ] // Alternative ways of specifying stacking [ below="layername" ] [ visibility="vis" ] // "show", "hide", or "inherit" [ bgcolor="color" ] // Background color of layer [ background="url" ] // Background image of layer [ onmouseover="handler" ] // Invoked when mouse enters layer [ onmouseout="handler" ] // Invoked when mouse leaves layer [ onfocus="handler" ] // Invoked when layer gets focus [ onblur="handler" ] // Invoked when layer loses focus [ onload="handler" ] // Invoked when layer's contents are loaded >
The Layer object is Netscape 4's technique for supporting dynamically positionable HTML elements. Note, however, that the Layer object was never standardized and is no longer supported in Netscape 6. A Layer object can be created in three ways: with the <layer> tag; with the Layer( ) constructor; or, most portably, with CSS style attributes on HTML elements, as explained in Chapter 18.
| Layer.captureEvents( ) | see Window.captureEvents( ) |
| Layer.handleEvent( ) | see Window.handleEvent( ) |
| Layer.load( ) | change layer contents and width |
layer.load(src, width)
load( ) loads a new document into layer and specifies a width at which the lines of that document are wrapped.
Note, however, that load( ) does not work while the current document is being parsed. For this reason, you should not call load( ) in a top-level script; instead, call it in an event handler or a function called from an event handler.
The src property of the Layer object
| Layer.moveAbove( ) | move one layer above another Netscape 4 only |
layer.moveAbove(target)
moveAbove( ) changes the stacking order so layer appears on top of target. layer becomes a sibling of target if it is not one already. layer is given the same zIndex as target and is placed after target in the layers[] array of the containing document.
| Layer.moveBelow( ) | move one layer below another Netscape 4 only |
layer.moveBelow(target)
moveBelow( ) changes the stacking order so layer appears beneath target. layer becomes a sibling of target if it is not one already. layer is given the same zIndex as target and is placed before target in the layers[] array of the containing document.
| Layer.moveBy( ) | move a Layer to a relative position Netscape 4 only |
layer.moveBy(dx, dy)
moveBy( ) moves layer dx pixels to the right and dy pixels down from its current position.
| Layer.moveTo( ) | move a Layer Netscape 4 only |
layer.moveTo(x, y)
moveTo( ) moves the upper-left corner of layer to the coordinates specified by x and y. Note that these coordinates are expressed relative to the containing layer or document.
| Layer.moveToAbsolute( ) | move a Layer to page coordinates |
layer.moveToAbsolute(x, y)
moveToAbsolute( ) moves the upper-left corner of layer to the document coordinates specified by x and y. Note that these coordinates are expressed relative to the page or top-level document, not relative to any containing layers.
| Layer.offset( ) | move a Layer to a relative position |
layer.offset(dx, dy)
offset( ) moves a layer relative to its current position. offset( ) is deprecated in favor of moveBy( ).
| Layer.releaseEvents( ) | see Window.releaseEvents( ) |
| Layer.resizeBy( ) | resize a Layer by a relative amount |
layer.resizeBy(dw, dh)
resizeBy( ) resizes layer by incrementing its clip.width and clip.height properties by dw and dh. It does not cause the contents of the layer to be reformatted, so making a layer smaller may clip the layer's contents.
| Layer.resizeTo( ) | resize a Layer Netscape 4 only |
layer.resizeTo(width, height)
resizeTo( ) resizes layer by setting its clip.width and clip.height properties to width and height. It does not cause the contents of the layer to be reformatted, so making a layer smaller may clip the layer's contents.
| Layer.routeEvent( ) | see Window.routeEvent( ) |
| Link | a hypertext link |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from HTMLElement
document.links[] document.links.length
Link inherits properties from HTMLElement and defines the following properties. Many of the properties represent portions of a URL. For each of these properties, the example given is a portion of the following (fictitious) URL:
http://www.oreilly.com:1234/catalog/search.html?q=JavaScript&m=10#results
Link inherits the methods of HTMLElement.
Link inherits the event handlers of HTMLElement and defines special behavior for the following:
A Link object is created with standard <a> and </a> tags. The href attribute is required for all Link objects. If the name attribute is also specified, an Anchor object is also created:
<a href="url" // The destination of the link
[ name="anchor_tag" ] // Creates an Anchor object
[ target="window_name" ] // Where the new document should be displayed
[ onclick="handler" ] // Invoked when link is clicked
[ onmouseover="handler" ] // Invoked when mouse is over link
[ onmouseout="handler" ] // Invoked when mouse leaves link
>
link text or image // The visible part of the link
</a>In JavaScript 1.1 and later, a Link object is also created by each <area> tag within a client-side image map. This is also standard HTML:
<map name="map_name">
<area shape="area_shape"
coords="coordinates"
href="url" // The destination of the link
[ target="window_name" ] // Where the new document should be displayed
[ onclick="handler" ] // Invoked when area is clicked
[ onmouseover="handler" ] // Invoked when mouse is over area
[ onmouseout="handler" ] // Invoked when mouse leaves area
>
...
</map>The Link object represents a hypertext link or a clickable area of a client-side image map in an HTML document. All links created with the <a> and <area> tags are represented by Link objects and stored in the links[] array of the Document object. Note that links created by both the <a> and <area> tags are stored in the same array -- there is no distinction between them.
The destination of a hypertext link is a URL, of course, and many of the properties of the Link object specify the contents of that URL. The Link object is similar to the Location object, which also has a full set of URL properties. In the case of the Location object, these properties describe the URL of the currently displayed document.
In addition to its properties, the Link object has three event handlers. The onmouseover( ), onclick( ), and onmouseout( ) event handlers specify code to be executed when the mouse passes over the hypertext link, clicks on it, and moves off or out of the link's region of the screen.
Anchor, Location; HTMLAnchorElement in the DOM reference section
| Link.onclick | the handler invoked when a Link is clicked |
JavaScript 1.0; enhanced in JavaScript 1.1
<a ... onclick="handler" ... > <area ... onclick="handler" ... > link.onclick
The onclick property of a Link object specifies an event handler function that is invoked when the user clicks on the link. The initial value of this property is a function that contains the JavaScript statements specified by the onclick attribute of the <a> or <area> tag that defined the Link object. When an event handler function is defined in this way by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
The onclick event handler is invoked before the browser follows the clicked hypertext link. This allows you to dynamically set href, target, and other properties of the link (using the this keyword to refer to the clicked link). You may also use the methods Window.alert( ), Window.confirm( ), and Window.prompt( ) from this event handler.
In JavaScript 1.1, you may prevent the browser from following the link by returning false. If you return true, any other value, or nothing, the browser follows the link as soon as onclick returns. You might stop the browser from following a link if you use the Window.confirm( ) method to ask the user if he really wants to follow the link and the user chooses the Cancel button, for example. In general, if you want a link that performs some action but does not cause a new URL to be displayed, it is better to use the onclick event handler of a Button object instead of the onclick handler of a Link object.
Note that while the onclick event handler returns false to tell the browser not to perform its default action (following a link), the onmouseover event handler must return true to tell the browser not to take its default action (displaying the URL of the link). This incompatibility exists for historical reasons. The standard for Form and form element event handlers is to return false to prevent the browser from performing a default action.
In the Netscape 4 event model, the onclick handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the hypertext link.
In Netscape 3, the onclick event handler of the <area> does not work on Windows platforms. A workaround is to specify a javascript: URL as the value of the href attribute of the <area> tag.
Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Link.onmouseout | the handler invoked when the mouse leaves a link |
<a ... onmouseout="handler" ... > <area ... onmouseout="handler" ... > link.onmouseout
The onmouseout property of a Link object specifies an event handler function that is invoked when the user moves the mouse off a hypertext link. The initial value of this property is a function that contains the JavaScript statements specified by the onmouseout attribute of the <a> or <area> tag that defined the Link object. When an event handler function is defined in this way by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onmouseout handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the hypertext link.
Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Link.onmouseover | the handler invoked when the mouse goes over a link |
<a ... onmouseover="handler" ... > <area ... onmouseover="handler" ... > link.onmouseover
The onmouseover property of a Link object specifies an event handler function that is invoked when the user moves the mouse over a hypertext link. The initial value of this property is a function that contains the JavaScript statements specified by the onmouseover attribute of the <a> or <area> tag that defined the Link object. When an event handler function is defined in this way by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
By default, the browser displays the URL that a hypertext link refers to in the status line whenever the mouse goes over the link. The onmouseover event handler is invoked before the URL is displayed. If the handler returns true, the browser does not display the URL. Thus, an event handler function that returns true can display a custom message in the status line by setting the Window.status property to any desired value.
Note that while this event handler returns true to tell the browser not to perform its default action (displaying the URL of a link), the onclick event handler of the Link object must return false to tell the browser not to take its default action (following the link). This incompatibility exists for historical reasons. The standard for Form and form element event handlers is to return false to prevent the browser from performing a default action.
In the Netscape 4 event model, the onmouseover handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the hypertext link.
Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Link.target | the target window of a hypertext link |
link.target
target is a read/write string property of the Link object. It specifies the name of the frame or window in which the URL referred to by the Link object should be displayed. The initial value of this property is specified by the target attribute of the <a> tag that creates the Link object. If this attribute is unset, the default is that the window containing the link is used, so following a hypertext link overwrites the document that contains the link.
Note that the value of target is the name of a frame or window, not an actual JavaScript reference to the frame or window itself. The name of a frame is specified by the name attribute of the <frame> tag. The name of a window is specified when the window is created with a call to the Window.open( ) method. If target specifies the name of a window that does not exist, the browser automatically opens a new window to display the URL, and any future links with the same target name use that freshly created window.
Four special target names are supported. The target named "_blank" specifies that a new, empty browser window should be created and used to display the new URL. The target "_self" is the default; it specifies that the new URL should be displayed in the same frame or window as the link. The target "_parent" specifies that the results should be displayed in the parent frame of the frame that contains the link. Finally, the "_top" target specifies that the new URL should be displayed in the topmost frame -- in other words, all frames should be removed, and the new URL should occupy the entire browser window.
| Location | represents and controls browser location |
JavaScript 1.0; enhanced in JavaScript 1.1
location window.location
The properties of a Location object refer to the various portions of the current document's URL. In each of the following property descriptions, the example given is a portion of this (fictitious) URL:
http://www.oreilly.com:1234/catalog/search.html?q=JavaScript&m=10#results
The Location object is stored in the location property of the Window object and represents the web address (the "location") of the document currently displayed in that window. The href property contains the complete URL of that document, and the other properties of the Location object each describe a portion of that URL. These properties are much like the URL properties of the Link object.
While the Link object represents a hyperlink in a document, the Location object represents the URL, or location, currently displayed by the browser. But the Location object does more than that: it also controls the location displayed by the browser. If you assign a string containing a URL to the Location object or to its href property, the web browser responds by loading the newly specified URL and displaying the document it refers to.
Instead of setting location or location.href to replace the current URL with a completely new one, you can also modify just a portion of the current URL by assigning strings to the other properties of the Location object. This creates a new URL with one new portion, which the browser loads and displays. For example, if you set the hash property of the Location object, you can cause the browser to move to a named location within the current document. Similarly, if you set the search property, you can cause the browser to reload the current URL with a new query string appended. If the URL refers to a server-side program, the document resulting from the new query string may be quite different from the original document.
In addition to its URL properties, the Location object also defines two methods. The reload( ) method reloads the current document, and the replace( ) method loads a new document without creating a new history entry for it -- the new document replaces the current one in the browser's history list.
| Location.reload( ) | reload the current document |
location.reload( ) location.reload(force)
The reload( ) method of the Location object reloads the document that is currently displayed in the window of the Location object. When called with no arguments or with the argument false, it uses the If-Modified-Since HTTP header to determine whether the document has changed on the web server. If the document has changed, reload reloads the document from the server, and if not, it reloads the document from the cache. This is the same action that occurs when the user clicks on the browser's Reload button.
When reload( ) is called with the argument true, it always bypasses the cache and reloads the document from the server, regardless of the last-modified time of the document. This is the same action that occurs when the user Shift-clicks on the browser's Reload button.
| Location.replace( ) | replace one displayed document with another |
location.replace(url)
The replace( ) method of the Location object loads and displays a new document. Loading a document in this way is different from simply setting location or location.href in one important respect: the replace( ) method does not generate a new entry in the History object. When you use replace( ), the new URL overwrites the current entry in the History object. After calling replace( ), the browser's Back button does not return you to the previous URL; it returns you to the URL before that one.
When you are working with multiple frames and/or JavaScript-generated documents, you sometimes end up with quite a few temporary documents. If there are more than just a few of these documents, backing out of your web site with the Back button can be annoying. If you use the replace( ) method to load these documents, however, you can prevent this problem.
| MimeType | represents a MIME data type |
navigator.mimeTypes[i] navigator.mimeTypes["type"] navigator.mimeTypes.length
The navigator.mimeType[] array tells you whether a given MIME type is supported by the browser. The enabledPlugin property of the MimeType object, however, tells you whether a particular supported type is supported with a plugin (MIME types can also be supported with helper applications, or directly by the browser). If a MIME type is supported by a plugin, data of that type can be embedded in a web page with the <embed> tag.
The MimeType object represents a MIME type (i.e., a data format) supported by Netscape. The format may be supported directly by the browser or through an external helper application or a plugin for embedded data.
The navigator.mimeTypes[] array may be indexed numerically or with the name of the desired MIME type (which is the value of the type property). To check which MIME types are supported by Netscape, you can loop through each element in the array numerically. Or, if you just want to check whether a specific type is supported, you can write code like the following:
var show_movie = (navigator.mimeTypes["video/mpeg"] != null);
| Navigator | information about the browser in use |
JavaScript 1.0; enhanced in JavaScript 1.1 and 1.2
navigator
The plugins[] array is defined by IE 4 but is always empty because IE 4 does not support plugins or the Plugin object.
Mozilla/4.0 (compatible; MSIE 4.01; Windows 95)
The Navigator object contains properties that describe the web browser in use. You can use its properties to perform platform-specific customization. The name of this object obviously refers to the Netscape Navigator browser, but other browsers that implement JavaScript support this object as well.
There is only a single instance of the Navigator object, which you can reference through the navigator property of any Window object. Because of the implicit window reference, you can always refer to the Navigator object simply as navigator.
| Navigator.javaEnabled( ) | test whether Java is available |
JavaScript 1.1
navigator.javaEnabled( )
true if Java is supported by and enabled on the current browser; false otherwise.
You can use navigator.javaEnabled( ) to check whether the current browser supports Java and can therefore display applets.
| Navigator.plugins.refresh( ) | make newly installed plugins available |
navigator.plugins.refresh([reload])
The refresh( ) method causes Netscape to check whether any new plugins have been installed. If so, the plugins[] array is updated ("refreshed") to include the newly installed plugins. If the reload argument is specified and is true, Netscape also reloads any currently displayed documents that contain <embed> tags and use plugins.
Note the unusual synopsis for this method. refresh( ) is a method of the plugins[] array, not of the Navigator object. For almost all purposes, however, it is simpler to consider it a method of the Navigator object, which is why it is grouped here with the methods and properties of that object.
| Option | an option in a Select box |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from HTMLElement
select.options[i]
In JavaScript 1.1, Option objects can be dynamically created with the Option( ) constructor, as follows:
new Option(text, value, defaultSelected, selected)
Option inherits the properties of HTMLElement and defines the following:
In JavaScript 1.0, the text property is read-only. In JavaScript 1.1, it is read/write. By setting a new value for this property, you can change the text that appears for the option within its Select object. Note that if you plan to set this property in a browser that cannot reflow document content, you should ensure that changing the option label does not make the Select object wider. If the object must become wider, ensure that no information to the right of the Select object becomes obscured when it grows.
An Option object is created by an <option> tag within a <select>, which is within a <form>. Multiple <option> tags typically appear within the <select>:
<form ...>
<select ...>
<option
[ value="value" ] // The value returned when the form is submitted
[ selected ] > // Specifies whether this option is initially selected
plain_text_label // The text to display for this option
[ </option> ]
...
</select>
...
</form>The Option object describes a single option displayed within a Select object. The properties of this object specify whether it is selected by default, whether it is currently selected, the position it has in the options[] array of its containing Select object, the text it displays, and the value it passes to the server if it is selected when the containing form is submitted.
Note that although the text displayed by this option is specified outside of the <option> tag, it must be plain, unformatted text without any HTML tags so it can be properly displayed in list boxes and drop-down menus that do not support HTML formatting.
In JavaScript 1.1, you can dynamically create new Option objects for display in a Select object with the Option( ) constructor. Once a new Option object is created, it can be appended to the list of options in a Select object s by assigning it to:
s.options[options.length]
See the Select.options[] reference page for details.
Select, Select.options[]; HTMLOptionElement and HTMLSelectElement in the DOM reference section
| Password | a text input field for sensitive data |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
form.name form.elements[i]
Password inherits properties from Input and HTMLElement and defines or overrides the following:
Password inherits methods from Input and HTMLElement.
Password inherits event handlers from Input and HTMLElement.
A Password element is created with a standard HTML <input> tag:
<form>
...
<input
type="password" // Specifies that this is a Password element
[ name="name" ] // A name you can use later to refer to this element
// Specifies the name property
[ value="default" ] // The default value transmitted when the form is submitted
[ size="integer" ] // How many characters wide the element is
>
...
</form> The Password element is a text input field intended for input of sensitive data, such as passwords. As the user types characters, only asterisks appear. This prevents bystanders from reading the input value over the user's shoulder. As a further security precaution, there are limitations on how JavaScript can read and write the value property of a Password element. See the Text and Input reference pages for more information.
Input, Text; HTMLInputElement in the DOM reference section
| Plugin | describes an installed plugin |
navigator.plugins[i] navigator.plugins['name']
var sw_installed = (navigator.plugins["Shockwave"] != null);
The array elements of the Plugin object are MimeType objects that specify the data formats supported by the plugin.
A plugin is a software module that can be invoked by Netscape to display specialized types of embedded data within the browser window. In Netscape 3, plugins are represented by the Plugin object. This object is somewhat unusual in that it has both regular object properties and array elements. The properties of the Plugin object provide various pieces of information about the plugin, and its array elements are MimeType objects that specify the embedded data formats that the plugin supports.
Plugin objects are obtained from the plugins[] array of the Navigator object. navigator.plugins[] may be indexed numerically when you want to loop through the complete list of installed plugins, looking for one that meets your needs (for example, one that supports the MIME type of the data you want to embed in your web page). This array can also be indexed by plugin name, however. That is, if you want to check whether a specific plugin is installed in the user's browser, you might use code like this:
document.write( navigator.plugins("Shockwave") ?
"<embed src="movie.dir' height=100 width=100>" :
"You don't have the Shockwave plugin!" ); The name used as an array index with this technique is the same name that appears as the value of the name property of the Plugin.
Don't confuse the fact that Plugin objects are stored in an array of the Navigator object with the fact that each Plugin object is itself an array of MimeType objects. Because there are two arrays involved, you may end up with code that looks like this:
navigator.plugins[i][j] // The jth MIME type of the ith plugin navigator.plugins["LiveAudio"][0] // First MIME type of LiveAudio plugin
Finally, note that while the array elements of a Plugin object specify the MIME types supported by that plugin, you can also determine which plugin supports a given MIME type with the enabledPlugin property of the MimeType object.
| Radio | a graphical radio button |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
The Radio button element is usually used in groups of mutually exclusive options that have the same name. To reference one Radio element within a group, use this syntax:
form.radio_name[j] form.radio_name.length
Radio inherits properties from Input and HTMLElement and defines or overrides the following:
Radio inherits methods from Input and HTMLElement.
Radio inherits event handlers from Input and HTMLElement and defines or overrides the following:
A Radio element is created with a standard HTML <input> tag. Radio elements are created in groups by specifying multiple <input> tags that have the same name attribute:
<form>
...
<input
type="radio" // Specifies that this is a radio button
[ name="name" ] // A name you can use later to refer to this button
// or to the group of buttons with this name
// Specifies the name property
[ value="value" ] // The value returned when this button is selected
// Specifies the value property
[ checked ] // Specifies that the button is initially checked
// Specifies the defaultChecked property
[ onclick="handler" ] // JavaScript statements to be executed when the button
// is clicked
>
label // The HTML text that should appear next to the button
...
</form> The Radio element represents a single graphical radio button in an HTML form. A radio button is one button in a group of buttons that represents mutually exclusive choices. When one button is selected, the previously selected button is deselected. The onclick event handler allows you to specify JavaScript code to be executed when the button is selected.
You can examine the checked property to determine the state of the button and set this property to select or deselect the button. Note that setting checked changes the graphical appearance of the button but does not invoke the onclick event handler. The initial value of the checked property and the value of the defaultChecked property are determined by the checked attribute. Only one Radio element in a group may contain this attribute -- it sets the checked and defaultChecked properties true for that element and false for all other radio buttons in the group. If none of the elements has the checked attribute, the first one in the group is checked (and defaultChecked) by default.
Note that the text that appears next to a radio button is not part of the Radio element itself and must be specified externally to the Radio's HTML <input> tag.
Radio elements are used in groups of mutually exclusive options. A mutually exclusive group is defined as the set of all Radio elements within a form that have the same name. If the shared name of a group of Radio elements in form f is opts, f.opts is an array of Radio elements, and f.opts.length is the number of elements in the array.
You can set the value attribute or the value property of a Radio element to specify the string that is passed to the server if the Radio element is checked when the form is submitted. Each Radio element in a group should specify a distinct value so a script on the server can determine which one was checked when the form was submitted.
Radio elements can present the user with a list of multiple mutually-exclusive options. Use the Checkbox element to present a single option or a list of options that are not mutually exclusive.
Checkbox, Form, Input; HTMLInputElement in DOM reference section
| Radio.onclick | the handler invoked when a radio button is selected |
JavaScript 1.0
<input type="radio" onclick="handler"... > radio.onclick
The onclick property of a Radio object refers to an event handler function that is invoked when the user clicks on the checkbox. See the HTMLElement.onclick reference page for complete details. Note, however, that Radio.onclick has been supported since JavaScript 1.0, unlike the generalized HTMLElement.onclick handler.
HTMLElement.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Reset | a button to reset a form's values |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
form.name form.elements[i]
Reset inherits properties from Input and HTMLElement and defines or overrides the following:
Reset inherits the methods of Input and HTMLElement.
Reset inherits the event handlers of Input and HTMLElement and defines or overrides the following:
A Reset element is created with a standard HTML <input> tag:
<form>
...
<input
type="reset" // Specifies that this is a Reset button
[ value="label" ] // The text that is to appear within the button
// Specifies the value property
[ name="name" ] // A name you can use later to refer to the button
// Specifies the name property
[ onclick="handler" ] // JavaScript statements to be executed when the button
// is clicked
>
...
</form> Reset objects can also be created with the HTML 4 <button> tag:
<button id="name"
type="reset"
onclick="handler">
label
</button>The Reset element has the same properties and methods as the Button element but has a more specialized purpose. When a Reset element is clicked, the values of all input elements in the form that contains it are reset to their initial default values. (For most elements, this means to the value specified by the HTML value attribute.) If no initial value was specified, a click on the Reset button clears any user input from those elements.
If no value attribute is specified for a Reset element, it is labeled "Reset". In some forms, it may be better to label the button "Clear Form" or "Defaults".
In JavaScript 1.1, you can simulate the action of a Reset button with the reset( ) method of the Form object. Also in JavaScript 1.1, the onreset event handler of the Form object is invoked before the form is reset. This event handler can cancel the reset by returning false.
Button, Form, HTMLElement, Input; HTMLInputElement in the DOM reference section
| Reset.onclick | the handler invoked when a Reset button is clicked |
JavaScript 1.0; enhanced in JavaScript 1.1
<input type="reset" onclick="handler" ... > reset.onclick
The onclick property of a Reset object refers to an event handler function that is invoked when the user clicks on the Reset button. See the HTMLElement.onclick reference page for complete details. Note, however, that Reset.onclick has been supported since JavaScript 1.0, unlike the generalized HTMLElement.onclick handler.
The Reset button has the special function of resetting all form elements to their default value. The onclick event handler may add any additional functionality to the Reset button. In JavaScript 1.1, the onclick handler may return false to prevent the Reset object from resetting the form. (For example, the onclick handler could use confirm( ) to ask the user to confirm the reset and return false if it was not confirmed.)
Form.onreset, Form.reset( ), HTMLElement.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Screen | provides information about the display |
screen
In IE 4, colorDepth specifies the color depth of the screen in bits-per-pixel, rather than the depth of a preallocated color palette. The screen.pixelDepth property provides this value in Netscape.
The screen property of every Window refers to a Screen object. The static properties of this global object contain information about the screen on which the browser is displayed. JavaScript programs can use this information to optimize their output to match the user's display capabilities. For example, a program can choose between large and small images based on the display size and between 16-bit color images and 8-bit color images based on the screen's color depth. A JavaScript program can also use the information about the size of the screen to center new browser windows on the screen.
The screen property of the Window object
| Select | a graphical selection list |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
form.element_name form.elements[i]
Select inherits properties from Input and HTMLElement and defines or overrides the following:
In JavaScript 1.0, selectedIndex is a read-only property. In JavaScript 1.1, it is read/write. Setting the value of this property selects the specified option and deselects all other options, even if the Select object has the multiple attribute specified. When you're doing list-box selection (instead of drop-down menu selection), you can deselect all options by setting selectedIndex to -1. Note that changing the selection in this way does not trigger the onchange( ) event handler.
Select inherits the methods of Input and HTMLElement.
Select inherits event handlers from Input and HTMLElement and defines or overrides the following:
A Select element is created with a standard HTML <select> tag. Options to appear within the Select element are created with the <option> tag:
<form>
...
<select
name="name" // A name that identifies this element; specifies name property
[ size="integer" ] // Number of visible options in Select element
[ multiple ] // Multiple options may be selected, if present
[ onchange="handler" ] // Invoked when the selection changes
>
<option value="value1" [selected]> option_label1
<option value="value2" [selected]> option_label2
// Other options here
</select>
...
</form>The Select element represents a graphical list of choices for the user. If the multiple attribute is present in the HTML definition of the element, the user may select any number of options from the list. If that attribute is not present, the user may select only one option, and options have a radio button behavior -- selecting one deselects whichever was previously selected.
The options in a Select element may be displayed in two distinct ways. If the size attribute has a value greater than 1, or if the multiple attribute is present, they are displayed in a list box which is size lines high in the browser window. If size is smaller than the number of options, the list box includes a scrollbar so all the options are accessible. On the other hand, if size is specified as 1 and multiple is not specified, the currently selected option is displayed on a single line, and the list of other options is made available through a drop-down menu. The first presentation style displays the options clearly but requires more space in the browser window. The second style requires minimal space but does not display alternative options as explicitly.
The options[] property of the Select element is the most interesting. This is the array of Option objects that describe the choices presented by the Select element. The length property specifies the length of this array (as does options.length). See the documentation of the Option object for details.
In JavaScript 1.1, the options displayed by the Select element may be dynamically modified. You can change the text displayed by an Option object simply by setting its text property. You can change the number of options displayed by the Select element by setting the options.length property. And you can create new options for display with the Option( ) constructor function. See the Select.options[] and Option reference pages for details.
Note that the Select object is a kind of Input object and inherits from Input, despite the fact that Select objects are not created with HTML <input> tags.
Form, HTMLElement, Input, Option; HTMLSelectElement in the DOM reference section
| Select.onchange | the handler invoked when the selection changes |
JavaScript 1.0
<select ... onchange="handler" ... > select.onchange
The onchange property of a Select object refers to an event handler function that is invoked when the user selects or deselects an option. See the Input.onchange reference page for further details on this event handler.
Input.onchange, Option; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Select.options[] | the choices in a Select object |
JavaScript 1.0; enhanced in JavaScript 1.1
select.options[i] select.options.length
The options[] property contains an array of Option objects, each of which describes one of the selection options presented within the Select object select. The options.length property specifies the number of elements in the array, as does the select.length property. See the Option object for further details.
In JavaScript 1.1, you can modify the options displayed in a Select object in any of the following ways:
If you set options.length to 0, all options in the Select object are cleared.
If you set options.length to a value less than the current value, the number of options in the Select object is decreased, and those at the end of the array disappear.
If you set an element in the options[] array to null, that option is removed from the Select object, and the elements above it in the array are moved down, changing their indices to occupy the new space in the array.
If you create a new Option object with the Option( ) constructor (see the "Option" reference entry), you can add that option to the end of list of options in the Select object by assigning the newly created option to a position at the end of the options[] array. To do this, set options[options.length].
| Style | Cascading Style Sheet attributes |
Internet Explorer 4, Netscape 6
htmlElement.style
The Style object has properties corresponding to each of the CSS attributes supported by the browser.
The properties of the Style object correspond directly to the CSS attributes supported by the browser. For compatibility with JavaScript syntax, however, hyphenated CSS attribute names are written with mixed capitalization with the hyphen removed. So, for example, the CSS color attribute is represented by the color property of the Style object, while the CSS background-color attribute is represented by the backgroundColor property of the Style object. See Chapter 18 for more information about element styles.
{XREF}; Chapter 18; CSSStyleDeclaration and CSS2Properties in the DOM reference section.
| Submit | a button to submit a form |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
form.name form.elements[i] form.elements['name']
Submit inherits properties from Input and HTMLElement and defines or overrides the following:
Submit inherits methods from Input and HTMLElement.
Submit inherits event handlers from Input and HTMLElement and defines or overrides the following:
A Submit object is created with a standard HTML <input> tag:
<form>
...
<input
type="submit" // Specifies that this is a Submit button
[ value="label" ] // The text that is to appear within the button
// Specifies the value property
[ name="name" ] // A name you can use later to refer to the button
// Specifies the name property
[ onclick="handler" ] // JavaScript statements to be executed when the button
// is clicked
>
...
</form>Submit objects can also be created with the HTML 4 <button> tag:
<button id="name"
type="submit"
value="value"
onclick="handler">label
</button>The Submit element has the same properties and methods as the Button object but has a more specialized purpose. When a Submit button is clicked, it submits the data in the form that contains the button to the server specified by the form's action attribute and loads the resulting HTML page sent back by that server. In JavaScript 1.1, the exception is that the form is not submitted if either the Submit.onclick or Form.onsubmit event handler returns false.
Note that in JavaScript 1.1 the Form.submit( ) method provides an alternative way to submit a form.
If no value attribute is specified for a Submit object, it is typically labeled "Submit Query". In some forms, it may make more sense to label the button "Submit", "Done", or "Send".
Button, Form.onsubmit, Form.submit( ), HTMLElement, Input; HTMLInputElement in the DOM reference section
| Submit.onclick | invoked when a Submit button is clicked |
JavaScript 1.0; enhanced in JavaScript 1.1
<input type="submit" onclick="handler" ... > submit.onclick
The onclick property of a Submit object refers to an event handler function that is invoked when the user clicks on the Submit button. See the HTMLElement.onclick reference page for complete details. Note, however, that Submit.onclick has been supported since JavaScript 1.0, unlike the generalized HTMLElement.onclick handler.
The Submit button has the special function of submitting the form to a server. The onclick event handler may add any additional functionality to the Submit button. In JavaScript 1.1 the onclick handler may return false to prevent the Submit object from submitting the form. (For example, the onclick handler could perform form validation and return false if required fields in the form are not filled in.)
Form.onsubmit, Form.submit( ), HTMLElement.onclick; Chapter 19; EventListener, EventTarget, and MouseEvent in the DOM reference section
| Text | a graphical text input field |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
form.name form.elements[i]
Text inherits properties from Input and HTMLElement and defines or overrides the following:
Text inherits the methods of Input and HTMLElement.
Text inherits the event handlers of Input and HTMLElement and defines or overrides the following:
A Text element is created with a standard HTML <input> tag:
<form>
...
<input
type="text" // Specifies that this is a Text element
[ name="name" ] // A name you can use later to refer to this element
// Specifies the name property
[ value="default" ] // Default value transmitted when the form is submitted
// Specifies the defaultValue property
[ size="integer" ] // How many characters wide the element is
[ maxlength="integer" ] // Maximum allowed number of input characters
[ onchange="handler" ] // The onchange( ) event handler
>
...
</form>The Text element represents a text input field in a form. The size attribute specifies the width, in characters, of the input field as it appears on the screen, and the maxlength attribute specifies the maximum number of characters the user is allowed to enter.
Besides these HTML attributes, value is the main property of interest for the Text element. You can read this property to obtain the user's input or set it to display arbitrary (unformatted) text in the input field.
Use the Password element instead of the Text element when the value you are asking the user to enter is sensitive information, such as a password that should not be displayed openly on the screen. Use a Textarea element to allow the user to enter multiple lines of text.
When a form contains only one Text or Password element, the form is automatically submitted if the user strikes the Return key in that Text or Password element. In many forms, this is a useful shortcut. In some, however, it can be confusing if the user strikes Return and submits the form before entering input into other form elements, such as Checkboxes and Radio buttons. You can sometimes minimize this confusion by placing Text elements with their default submission action at the bottom of the form.
Form, Input, Password, Textarea; HTMLInputElement in the DOM reference section
| Text.onchange | the handler invoked when input value changes |
<input type="text" onchange="handler" ... > text.onchange
The onchange property of a Text element refers to an event handler function that is invoked when the user changes the value in the input field and then "commits" those changes by moving keyboard focus (i.e., by clicking the mouse elsewhere or pressing Tab or Return).
Note that the onchange event handler is not invoked when the value property of a Text object is set by JavaScript. Also note that this handler is intended to process a complete change to the input value, and therefore it is not invoked on a keystroke-by-keystroke basis. See the HTMLElement.onkeypress reference page for information on receiving notification of every key press event.
See Input.onchange for complete details about the onchange event handler.
HTMLElement.onkeypress, Input.onchange; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Textarea | a multiline text input area |
JavaScript 1.0; enhanced in JavaScript 1.1
Inherits from Input, HTMLElement
form.name form.elements[i]
Textarea inherits the properties of Input and HTMLElement and defines or overrides the following:
Textarea inherits the methods of Input and HTMLElement.
Textarea inherits the event handlers of Input and HTMLElement and defines or overrides the following:
A Textarea element is created with standard HTML <textarea> and </textarea> tags:
<form>
...
<textarea
[ name="name" ] // A name that can be used to refer to this element
[ rows="integer" ] // How many lines tall the element is
[ cols="integer" ] // How many characters wide the element is
[ onchange="handler" ] // The onchange( ) event handler
>
plain_text // The initial text; specifies defaultValue
</textarea>
...
</form>The Textarea element represents a text input field in a form. The name attribute specifies a name for the element. This is mandatory if the form is to be submitted, and it also provides a convenient way to refer to the Textarea element from JavaScript code. The cols attribute specifies the width, in characters, of the element as it appears on the screen, and the rows attribute specifies the height, in lines of text, of the element. The wrap attribute specifies how long lines should be handled: the value off specifies that they should be left as-is, the value virtual specifies that they should be displayed with line breaks but transmitted without them, and the value physical specifies that they should be displayed and transmitted with line breaks inserted.
In addition to these HTML attributes, value is the main property of interest for the Textarea element. You can read this property to obtain the user's input or set it to display arbitrary (unformatted) text in the Textarea. The initial value of the value property (and the permanent value of the defaultValue property) is the text that appears between the <textarea> and </textarea> tags.
Note that the Textarea object is a kind of Input object and inherits from Input, despite the fact that Textarea objects are not created with HTML <input> tags.
If you need only a single line of input text, use the Text element. If the text to be input is sensitive information, such as a password, use the Password element.
Form, HTMLElement, Input, Password, Text; HTMLTextAreaElement in the DOM reference section
| Textarea.onchange | the handler invoked when input value changes |
<textarea onchange="handler" ... >... </textarea> textarea.onchange
The onchange property of a Textarea element refers to an event handler function that is invoked when the user changes the value in the text area and then "commits" those changes by moving keyboard focus elsewhere.
Note that the onchange event handler is not invoked when the value property of a Text object is set by JavaScript. Also note that this handler is intended to process a complete change to the input value, and therefore it is not invoked on a keystroke-by-keystroke basis. See the HTMLElement.onkeypress reference page for information on receiving notification of every key press event.
See Input.onchange for complete details about the onchange event handler.
HTMLElement.onkeypress, Input.onchange; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| URL | see Link, Location, or Document.URL |
| Window | a web browser window or frame |
JavaScript 1.0; enhanced in JavaScript 1.1 and 1.2
self window window.frames[i]
The Window object defines the following properties. Nonportable, browser-specific properties are listed separately after this list.
The Window object has the following portable methods. Nonportable, browser-specific methods are listed separately after this list.
The Window object represents a browser window or frame. It is documented in detail in Chapter 13. In client-side JavaScript, the Window serves as the "global object," and all expressions are evaluated in the context of the current Window object. This means that no special syntax is required to refer to the current window, and you can use the properties of that window object as if they were global variables. For example, you can write document rather than window.document. Similarly, you can use the methods of the current window object as if they were functions: e.g., alert( ) instead of window.alert( ).
The Window object does have window and self properties that refer to the window object itself. You can use these to make the current window reference explicit rather than implicit. In addition to these two properties, the parent and top properties and the frames[] array refer to other Window objects related to the current one.
To refer to a frame within a window, use:
frames[i] or self.frames[i] // Frames of current window window.frames[i] // Frames of specified window
To refer to the parent window (or frame) of a frame, use:
parent or self.parent // Parent of current window window.parent // Parent of specified window
To refer to the top-level browser window from any frame contained within it, use:
top or self.top // Top window of current frame window.top // Top window of specified frame
New top-level browser windows are created with the Window.open( ) method. When you call this method, save the return value of the open( ) call in a variable and use that variable to reference the new window. In JavaScript 1.1, the opener property of the new window is a reference to the window that opened it.
In general, the methods of the Window object manipulate the browser window or frame in some way. The alert( ), confirm( ), and prompt( ) methods are notable: they interact with the user through simple dialog boxes.
See Chapter 13 for an in-depth overview of the Window object, and see the individual reference pages for complete details on all the Window properties, methods, and event handlers.
Document; Chapter 13; AbstractView in the DOM reference section
| Window.alert( ) | display a message in a dialog box |
JavaScript 1.0
window.alert(message)
The alert( ) method displays the specified message to the user in a dialog box. The dialog box contains an OK button that the user can click to dismiss the dialog box.
On Windows platforms, the dialog box displayed by alert( ) is modal, and JavaScript execution pauses until the user dismisses it. In Netscape 4 on Unix platforms, however, the alert( ) dialog box is nonmodal, and execution continues uninterrupted.
Perhaps the most common use of the alert( ) method is to display error messages when the user's input to some form element is invalid in some way. The alert dialog box can inform the user of the problem and explain what needs to be corrected to avoid the problem in the future.
The appearance of the alert( ) dialog box is platform-dependent, but it generally contains graphics that indicate an error, warning, or alert message of some kind. While alert( ) can display any desired message, the alert graphics of the dialog box mean that this method is not appropriate for simple informational messages like "Welcome to my home page" or "You are the 177th visitor this week!"
Note that the message displayed in the dialog box is a string of plain text, not formatted HTML. You can use the newline character "\n" in your strings to break your message across multiple lines. You can also do some rudimentary formatting using spaces and can approximate horizontal rules with underscore characters, but the results depend greatly on the font used in the dialog box, and thus are system-dependent.
| Window.back( ) | go back to previous document |
window.back( )
Calling back( ) makes the browser display the document previously displayed in window, exactly as if the user had clicked on the window's Back button.
Note that for framed documents, there may be differences between the behavior of Window.back( ) and History.back( ).
| Window.blur( ) | remove keyboard focus from a top-level window |
JavaScript 1.1
window.blur( )
The blur( ) method removes keyboard focus from the top-level browser window specified by the Window object. If the Window object is a frame, keyboard focus is given to the top-level window that contains that frame. On most platforms, a top-level window is sent to the background (i.e., to the bottom of the window stack) when keyboard focus is taken from it.
| Window.captureEvents( ) | specify event types to be captured Netscape 4 |
window.captureEvents(eventmask) document.captureEvents(eventmask) layer.captureEvents(eventmask)
captureEvents( ) is a method of the Window, Document, and Layer classes. Its purpose is the same for all three: in the Netscape 4 event model, captureEvents( ) specifies that all events of a given type or types occurring within the specified window, document, or layer should be passed to the window, document, or layer instead of to the object on which they actually occurred.
The type of the events to be captured is specified by eventmask, a bitmask comprised of static constants defined by the Event class. See the "Event.TYPE" reference page for a full list of these bitmask constants.
Event, Window.handleEvent( ), Window.releaseEvents( ), Window.routeEvent( ); Chapter 19; EventTarget.addEventListener( ) in the DOM reference section
| Window.clearInterval( ) | stop periodically executing code |
window.clearInterval(intervalId)
clearInterval( ) stops the repeated execution of code that was started by a call to setInterval( ). intervalId must be the value that was returned by a call to setInterval( ).
| Window.clearTimeout( ) | cancel deferred execution |
window.clearTimeout(timeoutId)
clearTimeout( ) cancels the execution of code that has been deferred with the setTimeout( ) method. The timeoutId argument is a value returned by the call to setTimeout( ) and identifies which (of possibly more than one) block of deferred code to cancel.
| Window.close( ) | close a browser window |
JavaScript 1.0
window.close( )
The close( ) method closes the top-level browser window specified by window. A window can close itself by calling self.close( ) or simply close( ).
In JavaScript 1.1, only windows opened by JavaScript can be closed by JavaScript. This prevents malicious scripts from causing the user's browser to exit.
There is no meaningful way to close a frame within a window. Thus, the close( ) method should be invoked only for Window objects that represent top-level browser windows, not for those that represent frames.
Window.open( ), the closed and opener properties of Window
| Window.confirm( ) | ask a yes-or-no question |
window.confirm(question)
true if the user clicks the OK button; false if the user clicks the Cancel button.
The confirm( ) method displays the specified question in a dialog box that pops up over window. The appearance of the dialog box is platform-dependent, but it generally contains graphics that indicate that the user is being asked a question. The dialog box contains OK and Cancel buttons that the user can use to answer the question. If the user clicks the OK button, confirm( ) returns true. If the user clicks Cancel, confirm( ) returns false.
The dialog box that is displayed by the confirm( ) method is modal -- that is, it blocks all user input to the main browser window until the user dismisses the dialog box by clicking on the OK or Cancel buttons. Since this method returns a value depending on the user's response to the dialog box, JavaScript execution pauses in the call to confirm( ), and subsequent statements are not executed until the user responds to the dialog box.
Note that the question displayed in the dialog box is a string of plain text, not formatted HTML. You can use the newline character, "\n", in your strings to break your question across multiple lines. You can also do some rudimentary formatting using spaces and can approximate horizontal rules with underscore characters, but the results depend greatly on the font used in the dialog box and thus are system-dependent.
Also, there is no way to change the labels that appear in the buttons of the dialog box (to make them read Yes and No, for example). Therefore, you should take care to phrase your question or message in such a way that OK and Cancel are suitable responses.
| Window.defaultStatus | the default status line text |
JavaScript 1.0
window.defaultStatus
defaultStatus is a read/write string property that specifies the default text that will appear in the window's status line. Web browsers typically use the status line to display the browser's progress while loading a file and to display the destination of hypertext links that the mouse is over. While it is not displaying any of these transient messages, the status line is, by default, blank. However, you can set the defaultStatus property to specify a default message to be displayed when the status line is not otherwise in use, and you can read the defaultStatus property to determine what the default message is. The text you specify may be temporarily overwritten with other messages, such as those that are displayed when the user moves the mouse over a hypertext link, but the defaultStatus message is always redisplayed when the transient message is erased.
If you set defaultStatus for a Window object that is a frame, the message you specify is visible whenever the mouse is within that frame (regardless of whether that frame has focus). When you specify defaultStatus for a top-level window that contains no frames, your message is always visible when the window is visible. If you specify defaultStatus for a top-level window that contains frames, your message is visible only when the mouse is over the borders that separate the frames. Thus, in order to guarantee visibility of a message in a framed document, you should set defaultStatus for all frames in the document.
defaultStatus is used to display semipermanent messages in the status line. To display transient messages, use the status property.
| Window.focus( ) | give keyboard focus to a top-level window |
JavaScript 1.1
window.focus( )
The focus( ) method gives keyboard focus to the top-level browser window specified by the Window object. If the Window object is a frame, keyboard focus is given to the frame and to the top-level window that contains that frame.
On most platforms, a top-level window is brought forward to the top of the window stack when it is given focus.
| Window.forward( ) | go forward to next document |
window.forward( )
Calling forward( ) makes the browser display the next document in window, exactly as if the user had clicked on the window's Forward button.
Note that for framed documents, there may be differences between the behavior of Window.forward( ) and History.forward( ).
| Window.handleEvent( ) | pass an event to the appropriate handler |
window.handleEvent(event) document.handleEvent(event) layer.handleEvent(event) htmlElement.handleEvent(event)
Whatever value is returned by the event handler that is invoked to handle event.
handleEvent( ) is a method of the Window, Document, and Layer classes and of all HTML elements that support event handlers. When invoked on any object o, handleEvent( ) determines the type of its event argument and passes that Event object to the appropriate handler of o.
| Window.home( ) | display the home page |
window.home( )
Calling home( ) makes the browser display its own configured home page, as if the user had clicked the browser's Home button.
| Window.moveBy( ) | move a window to a relative position |
window.moveBy(dx, dy)
moveBy( ) moves the window to the relative position specified by dx and dy. For security reasons, browsers may restrict scripts so they cannot move a window off the screen.
| Window.moveTo( ) | move a window to an absolute position |
JavaScript 1.2
window.moveTo(x, y)
moveTo( ) moves the window so its upper-left corner is at the position specified by x and y. For security resasons, browsers may restrict this method so it cannot move a window offscreen.
| Window.name | the name of a window |
JavaScript 1.0; read/write in JavaScript 1.1
window.name
The name property is a string that specifies the name of window. This property is read-only in JavaScript 1.0 and read/write in JavaScript 1.1. The name of a top-level window is initially specified by the name argument of the Window.open( ) method. The name of a frame is initially specified by the name attribute of the <frame> HTML tag.
The name of a top-level window or frame may be used as the value of a target attribute of an <a> or <form> tag. Using the target attribute in this way specifies that the hyperlinked document or the results of form submission should be displayed in the named window.
The initial window opened by the browser and any windows opened with the New Web Browser menu item initially have no name (i.e., name == ""), so these windows cannot be addressed with a target attribute from a separate top-level window. In JavaScript 1.1, you can set the name attribute to remedy this situation.
| Window.navigate( ) | load a new URL |
window.navigate(url)
The Window.navigate( ) method of Internet Explorer loads the specified url into the specified window ("navigates to" the url).
navigate( ) is not supported by Netscape. The same function can be accomplished both in Netscape and IE by assigning the desired url to the location property of the desired window.
| Window.onblur | the handler invoked when the window loses keyboard focus |
JavaScript 1.1
<body onblur="handler" ... > <frameset onblur="handler" ... > window.onblur
The onblur property of a Window specifies an event handler function that is invoked when the window loses keyboard focus.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onblur attribute of the <body> or <frameset> tags.
In the Netscape 4 event model, the onblur handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
If your web page has animation, you can use the onblur( ) event handler to stop the animation when the window doesn't have the input focus. In theory, if the window doesn't have the focus, the user probably can't see it or isn't paying attention to it.
Window.blur( ), Window.focus( ), Window.onfocus; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Window.onerror | the handler invoked when a JavaScript error occurs |
JavaScript 1.1; buggy in Netscape 6/6.1
You register an onerror event handler like this:
window.onerror=handler-func
The browser invokes the handler like this:
window.onerror(message, url, line)
true if the handler has handled the error and JavaScript should take no further action; false if JavaScript should post the default error message dialog box for this error.
The onerror property of the Window object specifies an error handler function that is invoked when a JavaScript error occurs in code executing in that window. By default, JavaScript displays an error dialog box when an error occurs. You can customize error handling by providing your own onerror event handler.
You define an onerror event handler for a window by setting the onerror property of a Window object to an appropriate function. Note that unlike other event handlers in JavaScript, the onerror handler cannot be defined in an HTML tag.
When the onerror handler is invoked, it is passed three arguments: a string specifying the error message, a string specifying the URL of the document in which the error occurred, and a number that specifies the line number at which the error occurred. An error handling function may do anything it wants with these arguments: it may display its own error dialog box or log the error in some way, for example. When the error handling function is done, it should return true if it has completely handled the error and wants JavaScript to take no further action or false if it has merely noted or logged the error in some fashion and still wants JavaScript to display the error message in its default dialog box.
Note that while this event handler returns true to tell the browser to take no further action, most Form and form element event handlers return false to prevent the browser from performing some action, such as submitting a form. This inconsistency can be confusing.
You can turn off error handling entirely for a window by setting the onerror property of the window to a function that returns true and does nothing else. You can restore the default error-handling behavior (the dialog box) by setting onerror to a function that returns false and does nothing else.
This event handler is correctly triggered by errors in Netscape 6 and Netscape 6.1, but the values passed as the message, URL, and line number arguments are incorrect, so although you can use it to detect the occurrence of an error, you cannot use it to obtain any useful information about the error.
| Window.onfocus | the handler invoked when a window is given focus |
<body onfocus="handler" ... > <frameset onfocus="handler" ... > window.onfocus
The onfocus property of a Window specifies an event handler function that is invoked when the window is given keyboard focus.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onfocus attribute of the <body> or <frameset> tags.
In the Netscape 4 event model, the onfocus handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
If your web page has animation, you can use the onfocus event handler to start the animation and the onblur handler to stop it, so it runs only when the user is paying attention to the window.
Window.blur( ), Window.focus( ), Window.onblur; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Window.onload | the handler invoked when a document finishes loading |
<body onload="handler" ... > <frameset onload="handler" ... > window.onload
The onload property of a Window specifies an event handler function that is invoked when a document or frameset is completely loaded into its window or frame.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onload attribute of the <body> or <frameset> tags.
When the onload event handler is invoked, you can be certain that the document has fully loaded, and therefore that all scripts within the document have executed, all functions within scripts are defined, and all forms and other document elements have been parsed and are available through the Document object.
If any of your document's event handlers depend on the document being fully loaded, you should check that it is loaded before executing those handlers. If the network connection were to stall out after a button appeared in the document but before the parts of the document that the button relied on were loaded, the user would get unintended behavior or an error message after clicking the button. One good way to verify that the document is loaded is to use the onload handler to set a variable -- loaded, for example -- to true and to check the value of this variable before doing anything that depends on the complete document being loaded.
Window.onunload; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Window.onmove | the handler invoked when a window is moved |
Netscape 4; not supported on Netscape 4 Unix platforms
<body onmove="handler" ... > <frameset onmove="handler" ... > window.onmove
The onmove property of the Window object specifies an event handler function that is invoked when the user moves a top-level window to a new position on the screen.
The initial value of this property is a function that contains the JavaScript statements specified by the onmove attribute of the HTML <body> or <frameset> tag that defined the window. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
The onmove handler function is passed an Event object as an argument. The properties of this object contain information about the new position of the window.
| Window.onresize | the handler invoked when a window is resized |
<body onresize="handler" ... > <frameset onresize="handler" ... > window.onresize
The onresize property of the Window object specifies an event handler function that is invoked when the user changes the size of the window or frame.
The initial value of this property is a function that contains the JavaScript statements specified by the onresize attribute of the HTML <body> or <frameset> tag that defined the window. When an event handler function is defined by an HTML attribute, it is executed in the scope of element rather than in the scope of the containing window.
In the Netscape 4 event model, the onresize handler function is passed an Event object as an argument. In the IE event model, no argument is passed, but the applicable Event object is available as the event property of the Window object that contains the element.
In Netscape, the new size of the window is available from the width and height properties of the Event object.
| Window.onunload | the handler invoked when the browser leaves a page |
<body onunload="handler" ... > <frameset onunload="handler" ... > window.onunload
The onunload property of a Window specifies an event handler function that is invoked when the browser "unloads" a document or frameset in preparation for loading a new one.
The initial value of this property is a function that contains the semicolon-separated JavaScript statements specified by the onunload attribute of the <body> or <frameset> tags. The onunload event handler provides the opportunity to perform any necessary cleanup of the browser state before a new document is loaded.
When the browser leaves a site using frames, the onunload handler of the frameset is invoked before the onunload handler for each of the frames. This is the reverse of the order in which the onload event handler is invoked.
The onunload( ) handler is invoked when the user has instructed the browser to leave the current page and move somewhere else. Therefore, it is usually inappropriate to delay the loading of the desired new page by popping up dialog boxes (with Window.confirm( ) or Window.prompt( ), for example) from an onunload event handler.
Window.onload; Chapter 19; Event, EventListener, and EventTarget in the DOM reference section
| Window.open( ) | open a new browser window or locate a named window |
JavaScript 1.0; enhanced in JavaScript 1.1
window.open(url, name, features, replace)
A reference to a Window object, which may be a newly created or an already existing one, depending on the name argument.
The open( ) method looks up an existing window or opens a new browser window. If the name argument specifies the name of an existing window, a reference to that window is returned. The returned window displays the URL specified by url, but the features argument is ignored. This is the only way in JavaScript to obtain a reference to a window which is known only by name.
If the name argument is not specified, or if no window with that name already exists, the open( ) method creates a new browser window. The created window displays the URL specified by url and has the name specified by name and the size and controls specified by features (the format of this argument is described in the next section). If url is the empty string, open( ) opens a blank window.
The name argument specifies a name for the new window. This name may contain only alphanumeric characters and the underscore character. It may be used as the value of the target attribute of an <a> or <form> tag in HTML to force documents to be displayed in the window.
In JavaScript 1.1, when you use Window.open( ) to load a new document into a named window, you can pass the replace argument to specify whether the new document has its own entry in the window's browsing history or whether it replaces the history entry of the current document. If replace is true, the new document replaces the old. If this argument is false or is not specified, the new document has its own entry in the Window's browsing history. This argument provides functionality much like that of the Location.replace( ) method.
Don't confuse Window.open( ) with Document.open( ) -- the two methods perform very different functions. For clarity in your code, you may want to use Window.open( ) instead of open( ). In event handlers defined as HTML attributes, open( ) is usually interpreted as Document.open( ), so in this case, you must use Window.open( ).
The features argument is a comma-separated list of features that will appear in the window. If this optional argument is empty or not specified, all features are present in the window. On the other hand, if features specifies any one feature, any features that do not appear in the list do not appear in the window. The string should not contain any spaces or other whitespace. Each element in the list has the format:
feature[=value]
For most features, the value is yes or no. For these features, the equals sign and the value may be omitted -- if the feature appears, yes is assumed, and if it doesn't, no is assumed. For the width and height features, value is required and must specify a size in pixels.
The available features and their meanings are:
Location.replace( ), Window.close( ), the closed and opener properties of Window
| Window.print( ) | print the document |
Netscape 4, Internet Explorer 5
window.print( )
Calling print( ) prints the current document, exactly as if the user had clicked the browser's Print button.
| Window.prompt( ) | get string input in a dialog box |
JavaScript 1.0
window.prompt(message, default)
The string entered by the user, the empty string if the user did not enter a string, or null if the user clicked Cancel.
The prompt( ) method displays the specified message in a dialog box that also contains a text input field and OK, Clear, and Cancel buttons. Platform-dependent graphics in the dialog box help indicate to the user that her input is desired.
If the user clicks the Cancel button, prompt( ) returns null. If the user clicks the Clear button, prompt( ) erases any current text in the input field. If the user clicks the OK button, prompt( ) returns the value currently displayed in the input field.
The dialog box that is displayed by the prompt( ) method is modal -- that is, it blocks all user input to the main browser window until the user dismisses the dialog box by clicking on the OK or Cancel buttons. Since this method returns a value depending on the user's response to the dialog box, JavaScript execution pauses in the call to prompt( ), and subsequent statements are not executed until the user responds to the dialog box.
| Window.releaseEvents( ) | stop capturing events |
window.releaseEvents(eventmask) document.releaseEvents(eventmask) layer.releaseEvents(eventmask)
The releaseEvents( ) method of the Window, Document, and Layer objects performs the opposite action of the captureEvents( ) method of those classes. In the Netscape 4 event model, releaseEvents( ) specifies that the window, document, or layer should no longer capture events of the types specified by eventmask. See the "Event.TYPE" reference page for a list of the constants that can be used in the eventmask argument.
Event, Window.captureEvents( ), Window.handleEvent( ), Window.routeEvent( ); Chapter 19; EventTarget.removeEventListener( ) in the DOM reference section
| Window.resizeBy( ) | resize a window by a relative amount |
window.resizeBy(dw, dh)
resizeBy( ) resizes window by the relative amounts specified by dh and dw. For security reasons, the browser may restrict this method so it makes either the width or height of the window less than 100 pixels.
| Window.resizeTo( ) | resize a window |
JavaScript 1.2
window.resizeTo(width, height)
resizeTo( ) resizes window so it is width pixels wide and height pixels high. For security reasons, the browser may restrict this method so that neither width nor height is smaller than 100 pixels.
| Window.routeEvent( ) | pass a captured event to the next handler |
window.routeEvent(event) document.routeEvent(event) layer.routeEvent(event)
Whatever value was returned by the handler to which the event was routed.
routeEvent( ) is a method of the Window, Document, and Layer classes, and it behaves the same for all three. When a captured Event object, event, is passed to an event handler of window, document, or layer, that handler may choose to pass the event on to the next interested event handler, if any. If the window, document, or layer contains some other window (frame), document, or layer that has also used captureEvents( ) to register interest in events of that type, the event is routed to the appropriate handler on that window, document, or layer object.
On the other hand, if there is no containing window, document, or layer object that has expressed interest in the event, routeEvent( ) passes the event object to the appropriate event handler of the object on which the event originated. The combination of captureEvents( ) and routeEvent( ) forms the basis of the "trickle-down" event model of Netscape 4.
Window.captureEvents( ), Window.handleEvent( ), Window.releaseEvents( ); Chapter 19
| Window.scroll( ) | scroll a document in a window |
JavaScript 1.1; deprecated in JavaScript 1.2
window.scroll(x, y)
The scroll( ) method moves the window's document within the window so the specified x- and y-coordinates of the document appear in the upper-left corner of the window.
The X-coordinate increases to the right, and the Y-coordinate increases down the page. Thus, scroll(0,0) always places the top-left corner of the document in the top-left corner of the window.
In JavaScript 1.2, the scrollTo( ) and scrollBy( ) methods are preferred over scroll( ).
| Window.scrollBy( ) | scroll the document by a relative amount |
window.scrollBy(dx, dy)
scrollBy( ) scrolls the document displayed in window by the relative amounts specified by dx and dy.
| Window.scrollTo( ) | scroll the document |
JavaScript 1.2
window.scrollTo(x, y)
scrollTo( ) scrolls the document displayed within window so the point in the document specified by the x- and y-coordinates is displayed in the upper-left corner, if possible.
scrollTo( ) is preferred over the JavaScript 1.1 Window.scroll( ) method, which does the same thing but has an inadequately descriptive name.
| Window.setInterval( ) | periodically execute specified code |
JavaScript 1.2; IE 4 supports only one of the two forms
window.setInterval(code, interval) window.setInterval(func, interval,args...)
A value that can be passed to Window.clearInterval( ) to cancel the periodic execution of code or func.
setInterval( ) repeatedly executes the JavaScript statements specified in the string code, at intervals of interval milliseconds.
In Netscape 4, but not IE 4, a function may be passed as the first argument instead of a string. In this form of setInterval( ), the specified function, func, is repeatedly invoked, at intervals of interval milliseconds. Any additional argument values, args, passed to setInterval( ) are passed as arguments to each invocation of func( ).
In both forms, the setInterval( ) method returns a value that can later be passed to Window.clearInterval( ) to stop code or func from being repeatedly executed.
setInterval( ) is related to setTimeout( ). Use setTimeout( ) when you want to defer the execution of code but do not want it to be repeatedly executed.
| Window.setTimeout( ) | defer execution of code |
window.setTimeout(code, delay)
An opaque value ("timeout id") that can be passed to the clearTimeout( ) method to cancel the execution of code.
The setTimeout( ) method defers the execution of the JavaScript statements in the string code for delay milliseconds. Once the specified number of milliseconds has elapsed, the statements in code are executed normally. Note that they are executed only once. To execute code repeatedly, code must itself contain a call to setTimeout( ) to register itself to be executed again. In JavaScript 1.2, you can use Window.setInterval( ) to register code that is executed at periodic intervals.
The statements in the string code are executed in the context of window; i.e., window is the current window for those statements. If more than one statement appears in code, the statements must be separated by semicolons.
| Window.status | specify a transient status-line message |
JavaScript 1.0
window.status
status is a read/write string property that specifies a transient message to appear in the window's status line. The message generally appears only for a limited amount of time -- until it is overwritten by another message or until the user moves the mouse to some other area of the window, for example. When a message specified with status is erased, the status line returns to its default blank state or to the default message specified by the defaultStatus property.
Although only top-level windows have status lines, you can also set the status property of frames. Doing so displays the specified message in the top-level window's status line. Transient messages set by frames are visible regardless of which frame currently has focus or which frame the mouse is currently in. This behavior differs from that of the defaultStatus property.
status is used to display transient messages in the status line. To display semipermanent messages, use the defaultStatus property.
In general, setting the status property is useful only from event handlers and in code fragments deferred with the Window.setTimeout( ) method. If you set status directly from a script, the message is not visible to the user. It is not displayed right away, and when it is displayed, it is likely to be immediately overwritten by a browser message such as "Document: done".
If you want to set the status property in the onmouseover event handler of a hypertext link, you must return true from that event handler because when the mouse goes over a link, the default action is to display the URL of that link, thereby overwriting any status message set by the event handler. By returning true from the event handler, you cancel this default action and leave your own status message displayed (until the mouse moves off the link).
| Window.stop( ) | stop loading the document |
Netscape 4
window.stop( )
Calling stop( ) stops the browser from loading the current document, exactly as if the user had clicked the browser's Stop button.
|  | |
| IV. Client-Side JavaScript Reference |  | V. W3C DOM Reference |
Copyright © 2003 O'Reilly & Associates. All rights reserved.