Javascript [Electronic resources] : The Definitive Guide (4th Edition) نسخه متنی

Availability

Availability

Inherits from/Overrides

Inherits from

Title and Short Description

Every reference entry begins with a four-part title block like that
above. The entries are alphabetized by title. The short description,
shown below 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.

Availability

The availability information is shown in the upper-right corner of
the title block. This information 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.

Inherits from

If a class inherits
from a superclass, that information is shown in the lower-right
corner of the title block. 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.

Synopsis

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.

Arguments

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.

arg1

The arguments are described in a list here. This is the description
for argument arg1, for example.

arg2

And this is the description for argument
arg2.

Returns

This section explains the method's return value. If the method
does not return a value, this subsection is omitted.

Constructor

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.

Properties

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.

prop1

This is documentation for property prop1,
including its type, its purpose or meaning, and whether it is
read-only or read/write.

prop2

This is the same for prop2.

Methods

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.

Event Handlers

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.

HTML Syntax

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.

Description

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.

Example

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.

Bugs

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.

See Also

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.