79
HTMLFormControlsCollection
a array-like object of form controls
HTMLCollection
HTMLFormControlsCollection is a specialized HTMLCollection used by Form elements to
represent collections of form controls. Like HTMLCollection, you can index it numerically,
like an array, or treat it like an object and index it with the names or IDs of form controls.
HTML forms often have multiple controls (usually radio buttons or checkboxes) that have
the same value for their
name
attribute, and an HTMLFormControlsCollection handles this
differently than an ordinary HTMLCollection would.
When you read a property of an HTMLFormControlsCollection, and the form contains more
than one element that has that property as its name, the HTMLFormControlsCollection re-
turns an array-like object of all form controls that share the name. In addition, the returned
array-like object has a
value
property that returns the
value
attribute of the first checked radio
button with that name. You can even set this
value
property to check the radio button with
the corresponding value.
HTMLOptionsCollection
a collection of Option elements
HTMLCollection
HTMLOptionsCollection is a specialized HTMLCollection that represents the
Option
ele-
ments within a
Select
element. It overrides the
namedItem()
method to handle multiple Option
elements with the same name, and it defines methods for adding and removing elements. For
historical reasons, HTMLOptionsCollection defines a writable
length
property that you can
set to truncate or extend the collection.
Properties
unsigned long length
This property returns the number of elements in the collection. Unlike the
length
prop-
erty of a regular HTMLCollection, however, this one is not read-only. If you set it to a
value smaller than its current value, the collection of Option elements is truncated, and
those that are no longer in the collection are removed from the containing Select element.
If you set
length
to a value larger than its current value, empty
<option/>
elements are
created and added to the Select element and to the collection.
long selectedIndex
The index of the first selected Option in the collection, or -1 if no Option is selected. You
can set this property to change the selected item.
Methods
void add(Element option, [any before])
Insert the
option
(which must be an
<option>
or
<optgroup>
element) into this collection (and
into the Select element) at the position specified by
before
. If
before
is null, insert it at the
end. If
before
is an integer index, insert it before the item that is currently at that index. If
before
is another Element, insert the
option
before that element.
HTMLFormControlsCollection
938 | Client-Side JavaScript Reference
93
Element item(unsigned long index)
HTMLOptionsCollection inherits this method from HTMLCollection. It returns the element
at the specified
index
or
null
if
index
is out of bounds. You can also index the collection
directly with square brackets instead of calling this method explicitly.
object namedItem(string name)
This method returns all Option elements in the collection that have the specified name or ID.
If no elements match, it returns
null
. If one Option element matches, it returns that element.
If more than one element matches, it returns a NodeList of those elements. Note that you can
index an HTMLOptionsCollection directly, using
name
as a property name instead of calling
this method explicitly.
void remove(long index)
This method removes the
<option>
element at the specified
index
in the collection. If invoked
with no argument or with an argument that is out of bounds, it may remove the first element
in the collection.
IFrame
an HTML <iframe>
Node, Element
An IFrame object represents an
<iframe>
element in an HTML document. If you look up an
<iframe>
using
getElementById()
or a similar query function, you’ll get an IFrame object. If,
however, you access the
<iframe>
through the
frames
property of the Window object, or by
using the name of the
<iframe>
as a property of the containing window, the object you obtain
is the Window object that the
<iframe>
represents.
Properties
readonly Document contentDocument
The document contained in this
<iframe>
element. If the document displayed in the
<iframe>
is from a different origin, the same-origin policy (§13.6.2) will prevent access
to this document.
readonly Window contentWindow
The Window object of the
<iframe>
. (The
frameElement
of that Window object will be a
reference back to this IFrame object.)
string height
The height, in CSS pixels, of the
<iframe>
. This property mirrors the HTML
height
attribute.
string name
The name of the
<iframe>
. This property mirrors the HTML
name
attribute, and its value
can be used as the
target
of
Link
and
Form
objects.
readonly DOMSettableTokenList sandbox
This property mirrors the HTML5
sandbox
attribute and allows it to be queried and set
as a string or as a set of individual tokens.
IFrame
Client-Side JavaScript Reference | 939
Client-Side
JavaScript
Reference
88
The
sandbox
attribute specifies that the browser should impose additional security re-
strictions on untrusted content displayed in an
<iframe>
. If the
sandbox
attribute is present
but empty, the
<iframe>
content will be treated as if it was from a distinct origin, will not
be allowed to run scripts, will not be allowed to display forms, and will not be allowed
to change the location of its containing window. The
sandbox
attribute can also be set to
a space-separated list of tokens, each of which lifts one of those additional security re-
strictions. The valid tokens are “allow-same-origin”, “allow-scripts”, “allow-forms”, and
“allow-top-navigation”.
The
sandbox
attribute is not yet widely implemented at the time of this writing. See an
HTML reference for further details.
boolean seamless
This property mirrors the HTML
seamless
attribute. If
true
, the browser should render
the content of the
<iframe>
so that it appears to be part of the containing document. This
means, in part, that the browser must apply the CSS styles of the containing document
to the content of the
<iframe>
.
The
seamless
attribute was introduced as part of HTML5 and is not yet widely imple-
mented at the time of this writing.
string src
This property mirrors the
src
attribute of the
<iframe>
: it specifies the URL of the framed
content.
string srcdoc
This property mirrors the
srcdoc
HTML attribute and specifies the content of the
<iframe>
as a string. The
srcdoc
attribute was recently introduced as part of HTML5 and
is not yet implemented at the time of this writing.
string width
The width, in CSS pixels, of the
<iframe>
. This property mirrors the HTML
width
attribute.
Image
an <img> in an HTML document
Node, Element
An Image object represents an image embedded in an HTML document with an
<img>
tag.
The images that appear in a document are collected in the
document.images[]
array.
The
src
property of the Image object is the most interesting one. When you set this property,
the browser loads and displays the image specified by the new value. This allows visual effects
such as image rollovers and animations. See §21.1 for examples.
You can create offscreen Image objects by simply creating new
<img>
elements with
document.createElement()
or with the
Image()
constructor. Note that this constructor does
not have an argument to specify the image to be loaded: to load an image, simply set the
src
property of your Image object. To actually display the image, insert the Image object into
the document.
Image
940 | Client-Side JavaScript Reference
82
Constructor
new Image([unsigned long width, unsigned long height])
You can create a new Image as you would create any HTML element with
docu
ment.createElement()
. For historical reasons, however, client-side JavaScript also defines the
Image()
constructor to do the same thing. If the
width
or
height
arguments are specified, they
set the
width
and
height
attributes of the
<img>
tag.
Properties
In addition to the properties listed here, Image elements also expose the following HTML
attributes as JavaScript properties:
alt
,
usemap
,
ismap
.
readonly boolean complete
true
if no image
src
was specified or if the image has been completely downloaded.
false
otherwise.
unsigned long height
The on-screen height at which the image is displayed, in CSS pixels. Set this to change
the height of the image.
readonly unsigned long naturalHeight
The intrinsic height of the image.
readonly unsigned long naturalWidth
The intrinsic width of the image.
string src
The URL of the image. Setting this property causes the specified image to load. If the
Image object has been inserted into the document, the new image will be displayed.
unsigned long width
The width, in CSS pixels, at which the image is actually displayed on the screen. You can
set this to change the on-screen size of the image.
ImageData
an array of pixel data from a <canvas>
An ImageData object holds the red, green, blue, and alpha (transparency) components of a
rectangular region of pixels. Obtain an ImageData object with the
createImageData()
or
getImageData()
methods of the CanvasRenderingContext2D object of a
<canvas>
tag.
The
width
and
height
properties specify the dimensions of the rectangle of pixels. The
data
property is an array that holds the pixel data. Pixels appear in the
data[]
array in left-to-right
and top-to-bottom order. Each pixel consists of four byte values that represent the R, G, B,
and A components, in that order. Thus, the color components for a pixel at
(x,y)
within an
ImageData object
image
can be accessed like this:
var offset = (x + y*image.width) * 4;
var red = image.data[offset];
var green = image.data[offset+1];
ImageData
Client-Side JavaScript Reference | 941
Client-Side
JavaScript
Reference
74
var blue = image.data[offset+2];
var alpha = image.data[offset+3];
The
data[]
array is not a true JavaScript array, but an optimized array-like object whose
elements are integers between 0 and 255. The elements are read/write, but the length of
the array is fixed. For any ImageData object
i
,
i.data.length
will always equal
i.width * i.height * 4
.
Properties
readonly byte[] data
A read-only reference to a read/write array-like object whose elements are bytes.
readonly unsigned long height
The number of rows of image data.
readonly unsigned long width
The number of pixels per row of data.
Input
an HTML <input> element
Node, Element, FormControl
An Input object represents an HTML form
<input>
element. Its appearance and behavior
depends on its
type
attribute: an Input element might represent a simple text input field, a
checkbox, a radio box, a button, or a file selection element, for example. Because an
<input>
element can represent so many kinds of form controls, the Input element is one of
the most complicated. See §15.9 for an overview of HTML forms and form elements. Note
that some of the important properties of the Input element (such as
type
,
value
,
name
, and
form
) are documented in
FormControl
.
Properties
In addition to the properties listed here, Input elements also implement all of the properties
defined by
Element
and
FormControl
. The properties marked with an asterisk in this list are
newly defined by HTML5 and are not yet, at the time of this writing, widely implemented.
string accept
When
type
is “file”, this property is a comma-separated list of MIME types that specify
the types of files that may be selected. The strings “audio/*”, “video/*”, and “image/*”
are also legal. Mirrors the
accept
attribute.
string autocomplete
True if the browser can prefill this Input element with a value from a previous session.
Mirrors that
autocomplete
attribute. See also the
autocomplete
property of
Form
.
boolean checked
For checkable input elements, this property specifies whether the element is “checked”
or not. Setting this property changes the visual appearance of the input element.
Input
942 | Client-Side JavaScript Reference
Documents you may be interested
Documents you may be interested
