not a nested browsing context. If no suitable
handler can be found, jump to the next step (fallback).
(Fallback.) The object
element
doesn't represent anything except what the element's contents represent,
ignoring any leading param
element
children. This is the element's fallback
content.
In the absence of other factors (such as style sheets), user agents must
show the user what the object
element
represents. Thus, the contents of object
elements act as fallback content, to be used only when referenced
resources can't be shown (e.g. because it returned a 404 error). This
allows multiple object
elements to be
nested inside each other, targeting multiple user agents with different
capabilities, with the user agent picking the best one it supports.
The usemap
attribute, if present while the object
element represents an image, can indicate
that the object has an associated image map. The
attribute must be ignored if the object
element doesn't represent an image.
The object
element supports dimension attributes.
The DOM attributes data
, type
, and useMap
each must reflect the respective content attributes of the same
name.
param
elementobject
element,
before any prose content.
name
value
interface HTMLParamElement : HTMLElement { attribute DOMString name; attribute DOMString value; };
The param
element defines parameters
for handlers invoked by object
elements.
The name
attribute gives the name of the parameter.
The value
attribute gives the value of the parameter.
Both attributes must be present. They may have any value.
If both attributes are present, and if the parent element of the
param
is an object
element, then the element defines a parameter with the given
name/value pair.
The DOM attributes name
and value
must both reflect the respective content attributes of the same
name.
video
elementsrc
attribute: transparent.
src
attribute: one or more source
elements, then, transparent.
src
poster
autoplay
start
loopstart
loopend
end
playcount
controls
width
height
interface HTMLVideoElement : HTMLMediaElement { attribute long width; attribute long height; readonly attribute unsigned long videoWidth; readonly attribute unsigned long videoHeight; attribute DOMString poster; };
A video
element represents a video or
movie.
Content may be provided inside the video
element. User agents should not show this
content to the user; it is intended for older Web browsers which do not
support video
, so that legacy video
plugins can be tried, or to show text to the users of these older browser
informing them of how to access the video contents.
In particular, this content is not fallback content intended to address accessibility concerns. To make video content accessible to the blind, deaf, and those with other physical or cognitive disabilities, authors are expected to provide alternative media streams and/or to embed accessibility aids (such as caption or subtitle tracks) into their media streams.
The video
element is a media element whose media data is
ostensibly video data, possibly with associated audio data.
The src
, autoplay
, start
, loopstart
,
loopend
,
end
, playcount
, and
controls
attributes are the
attributes common to all media elements.
The video
element supports dimension attributes.
The poster
attribute gives the address of an image file that the user agent can show
while no video data is available. The attribute, if present, must contain
a URI (or IRI).
The poster
DOM
attribute must reflect the poster
content attribute.
The videoWidth
DOM attribute
must return the native width of the video in CSS pixels. The videoHeight
DOM attribute must return the native height of the video in CSS pixels. In
the absence of resolution information defining the mapping of pixels in
the video to physical dimensions, user agents may assume that one pixel in
the video corresponds to one CSS pixel. If no video data is available,
then the attributes must return 0.
When no video data is available (the element's networkState
attribute is either EMPTY
, LOADING
, or LOADED_METADATA
), video
elements represent either the image given
by the poster
attribute, or nothing.
When a video
element is actively playing, it represents the frame of video at
the continuously increasing "current" position. When the current
playback position changes such that the last frame rendered is no
longer the frame corresponding to the current playback
position in the video, the new frame must be rendered. Similarly, any
audio associated with the video must, if played, be played synchronised
with the current playback position, at the
specified volume with the
specified mute state.
When a video
element is paused, the element represents
the frame of video corresponding to the current playback position, or, if that is not
available yet (e.g. because the video is seeking or buffering), the last
rendered frame of video.
When a video
element is neither actively playing nor paused (e.g. when seeking or stalled), the
element represents the last frame of the video to have been rendered.
Which frame in a video stream corresponds to a particular playback position is defined by the video stream's format.
Video content should be rendered inside the element's playback area such that the video content is shown centered in the playback area at the largest possible size that fits completely within it, with the video content's aspect ratio being preserved. Thus, if the aspect ratio of the playback area does not match the aspect ratio of the video, the video will be shown letterboxed. Areas of the element's playback area that do not contain the video represent nothing.
In addition to the above, the user agent may provide messages to the user (such as "buffering", "no video loaded", "error", or more detailed information) by overlaying text or icons on the video or other areas of the element's playback area, or in another appropriate manner.
User agents that cannot render the video may instead make the element represent a link to an external video playback utility or to the video data itself.
User agents should provide controls to enable or disable the display of closed captions associated with the video stream, though such features should, again, not interfere with the page's normal rendering.
User agents may allow users to view the video content in manners more
suitable to the user (e.g. full-screen or in an independent resizable
window). As for the other user interface features, controls to enable this
should not interfere with the page's normal rendering unless the user
agent is exposing a user interface. In such an independent context,
however, user agents may make full user interfaces visible, with, e.g.,
play, pause, seeking, and volume controls, even if the controls
attribute is absent.
User agents may allow video playback to affect system features that could interfere with the user's experience; for example, user agents could disable screensavers while video playback is in progress.
User agents should not provide a public API to cause videos to be shown full-screen. A script, combined with a carefully crafted video file, could trick the user into thinking a system-modal dialog had been shown, and prompt the user for a password. There is also the danger of "mere" annoyance, with pages launching full-screen videos when links are clicked or pages navigated. Instead, user-agent specific interface features may be provided to easily allow the user to obtain a full-screen playback mode.
video
elementsUser agents may support any video and audio codecs and container formats.
It would be helpful for interoperability if all browsers could support the same codecs. However, there are no known codecs that satisfy all the current players: we need a codec that is known to not require per-unit or per-distributor licensing, that is compatible with the open source development model, that is of sufficient quality as to be usable, and that is not an additional submarine patent risk for large companies. This is an ongoing issue and this section will be updated once more information is available.
Certain user agents might support no codecs at all, e.g. text browsers running over SSH connections.
audio
elementsrc
attribute: transparent.
src
attribute: one or more source
elements, then, transparent.
src
autoplay
start
loopstart
loopend
end
playcount
controls
interface HTMLAudioElement : HTMLMediaElement { // no members };
An audio
element represents a sound
or audio stream.
Content may be provided inside the audio
element. User agents should not show this
content to the user; it is intended for older Web browsers which do not
support audio
, so that legacy audio
plugins can be tried, or to show text to the users of these older browser
informing them of how to access the audio contents.
In particular, this content is not fallback content intended to address accessibility concerns. To make audio content accessible to the deaf or to those with other physical or cognitive disabilities, authors are expected to provide alternative media streams and/or to embed accessibility aids (such as transcriptions) into their media streams.
The audio
element is a media element whose media data is
ostensibly audio data.
The src
, autoplay
, start
, loopstart
,
loopend
,
end
, playcount
, and
controls
attributes are the
attributes common to all media elements.
When an audio
element is actively playing, it must have its audio data played
synchronised with the current playback position, at
the specified volume with the
specified mute state.
When an audio
element is not actively playing, audio must not play for the
element.
audio
elementsUser agents may support any audio codecs and container formats.
User agents must support the WAVE container format with audio encoded using the PCM format.
Media elements implement the following interface:
interface HTMLMediaElement : HTMLElement {
// error state
readonly attribute MediaError error;
// network state
attribute DOMString src;
readonly attribute DOMString currentSrc;
const unsigned short EMPTY = 0;
const unsigned short LOADING = 1;
const unsigned short LOADED_METADATA = 2;
const unsigned short LOADED_FIRST_FRAME = 3;
const unsigned short LOADED = 4;
readonly attribute unsigned short networkState;
readonly attribute float bufferingRate;
readonly attribute TimeRanges buffered;
void load();
// ready state
const unsigned short DATA_UNAVAILABLE = 0;
const unsigned short CAN_SHOW_CURRENT_FRAME = 1;
const unsigned short CAN_PLAY = 2;
const unsigned short CAN_PLAY_THROUGH = 3;
readonly attribute unsigned short readyState;
readonly attribute boolean seeking;
// playback state
attribute float currentTime;
readonly attribute float duration;
readonly attribute boolean paused;
attribute float defaultPlaybackRate;
attribute float playbackRate;
readonly attribute TimeRanges played;
readonly attribute TimeRanges seekable;
readonly attribute boolean ended;
attribute boolean autoplay;
void play();
void pause();
// looping
attribute float start;
attribute float end;
attribute float loopStart;
attribute float loopEnd;
attribute unsigned long playCount;
attribute unsigned long currentLoop;
// cue ranges
void addCueRange(in DOMString className, in float start, in float end, in boolean pauseOnExit, in VoidCallback enterCallback, in VoidCallback exitCallback);
void removeCueRanges(in DOMString className);
// controls
attribute boolean controls;
attribute float volume;
attribute boolean muted;
};
The media element attributes, src
, autoplay
, start
, loopstart
,
loopend
,
end
, playcount
, and
controls
,
apply to all media elements.
They are defined in this section.
Media elements are used to present audio data, or video and audio data, to the user. This is referred to as media data in this section, since this section applies equally to media elements for audio or for video. The term media resource is used to refer to the complete set of media data, e.g. the complete video file, or complete audio file.
All media elements have an
associated error status, which records the last error the element
encountered since the load()
method was last invoked. The error
attribute, on getting, must
return the MediaError
object
created for this last error, or null if there has not been an error.
interface MediaError { const unsigned short MEDIA_ERR_ABORTED = 1; const unsigned short MEDIA_ERR_NETWORK = 2; const unsigned short MEDIA_ERR_DECODE = 3; readonly attribute unsigned short code; };
The code
attribute of a MediaError
object
must return the code for the error, which must be one of the following:
MEDIA_ERR_ABORTED
(numeric value 1)
MEDIA_ERR_NETWORK
(numeric value 2)
MEDIA_ERR_DECODE
(numeric value 3)
The src
content
attribute on media elements
gives the address of the media resource (video, audio) to show. The
attribute, if present, must contain a URI (or IRI).
If the src
attribute of a media element that is already in a
document and whose networkState
is in the EMPTY
state is added,
changed, or removed, the user agent must implicitly invoke the load()
method on the media element as soon as all other scripts have
finished executing. Any exceptions raised must be ignored.
If a src
attribute is specified, the resource it
specifies is the media resource that will be used.
Otherwise, the resource specified by the first suitable source
element child of the media element is the one used.
The src
DOM
attribute on media elements
must reflect the content attribute of the same
name.
To pick a media resource for a media element, a user agent must use the following steps:
If the media element has a src
, then the address
given in that attribute is the address of the media
resource; jump to the last step.
Otherwise, let candidate be the first source
element child in the media element, or null if there is no such child.
If either:
src
attribute, or
type
attribute and
that attribute's value, when parsed as a MIME type, does not represent
a type that the user agent can render (including any codecs described
by the codec
parameter), or [RFC2046] [RFC4281]
media
attribute
and that attribute's value, when processed according to the rules for
media queries, does not match the current environment, [MQ]
...then the candidate is not suitable; go to the next step.
Otherwise, the address given in that candidate
element's src
attribute is the address of the media resource;
jump to the last step.
Let candidate be the next source
element child in the media element, or null if there are no more such
children.
If candidate is not null, return to step 3.
There is no media resource. Abort these steps.
Let the address of the chosen media resource be the one that was found before jumping to this step.
A source
element with no
src
attribute is
assumed to be the last source
element
— any source
elements after it
are ignored (and are invalid).
The currentSrc
DOM attribute
must return the empty string if the media element's
networkState
has the value EMPTY, and the absolute URL of the
chosen media resource otherwise.
As media elements interact
with the network, they go through several states. The networkState
attribute, on
getting, must return the current network state of the element, which must
be one of the following values:
EMPTY
(numeric
value 0)
LOADING
(numeric value 1)
currentSrc
attribute), but none of the
metadata has yet been obtained and therefore all the other attributes are
still in their initial states.
LOADED_METADATA
(numeric value 2)
LOADED_FIRST_FRAME
(numeric value 3)
LOADED
(numeric value 4)
The algorithm for the load()
method defined below describes exactly when
the networkState
attribute changes value.
All media elements have a begun flag, which must begin in the false state, a loaded-first-frame flag, which must begin in the false state, and an autoplaying flag, which must begin in the true state.
When the load()
method on a media element is invoked, the user agent
must run the following steps. Note that this algorithm might get aborted,
e.g. if the load()
method itself is invoked again.
Any already-running instance of this algorithm for this element must be aborted. If those method calls have not yet returned, they must finish the step they are on, and then immediately return.
If the element's begun flag is true, then the begun flag must be set to false, the error
attribute must
be set to a new MediaError
object
whose code
attribute is set to MEDIA_ERR_ABORTED
, and the user agent
must synchronously fire a progress event called
abort
at the media element.
The error
attribute must be set to null, the loaded-first-frame flag must be set to
false, and the autoplaying flag must be set
to true.
The playbackRate
attribute must be set to
the value of the defaultPlaybackRate
attribute.
If the media element's networkState
is not set to EMPTY, then the following
substeps must be followed:
networkState
attribute must be set to
EMPTY.
readyState
is not set to DATA_UNAVAILABLE
, it must be set to
that state.
paused
attribute is false, it must be set to
true.
seeking
is true, it must be set to false.
currentLoop
DOM attribute must be set to
0.emptied
at the media
element.
The user agent must pick a media resource for
the media element. If that fails, the method must
raise an INVALID_STATE_ERR
exception, and abort these
steps.
The networkState
attribute must be set to LOADING.
The currentSrc
attribute starts returning the
new value.
The user agent must then set the begun flag to
true and fire a progress event called
begin
at the media element.
The method must return, but these steps must continue.
Playback of any previously playing media resource for this element stops.
If a download is in progress for the media element, the user agent should stop the download.
The user agent must then begin to download the chosen media resource. The rate of the download may be throttled, however, in response to user preferences (including throttling it to zero until the user indicates that the download can start), or to balance the download with other connections sharing the same bandwidth.
While the download is progressing, the user agent must fire a progress event called progress
at the
element every 350ms (±200ms) or for every byte received, whichever
is least frequent.
If at any point the user agent has received no data for more than
about three seconds, the user agent must fire a
progress event called stalled
at the element.
User agents may allow users to selectively block or slow media data downloads. When a media element's download has been blocked, the user agent must act as if it was stalled (as opposed to acting as if the connection was closed).
The user agent may use whatever means necessary to download the resource (within the constraints put forward by this and other specifications); for example, reconnecting to the server in the face of network errors, using HTTP partial range requests, or switching to a streaming protocol. The user agent must only consider a resource erroneous if it has given up trying to download it.
DNS errors and HTTP 4xx and 5xx errors (and equivalents in other protocols) must cause the user agent to execute the following steps. User agents may also follow these steps in response to other network errors of similar severity.
error
attribute must be set to a new MediaError
object whose code
attribute
is set to MEDIA_ERR_NETWORK
.
error
at the media element.
networkState
attribute must be
switched to the EMPTY
value and the user agent must fire a simple
event called emptied
at the element.
The server returning a file of the wrong kind (e.g. one that that
turns out to not be pure audio when the media
element is an audio
element),
or the file using unsupported codecs for all the data, must cause the
user agent to execute the following steps. User agents may also
execute these steps in response to other codec-related fatal errors,
such as the file requiring more resources to process than the user
agent can provide in real time.
error
attribute must be set to a new MediaError
object whose code
attribute
is set to MEDIA_ERR_DECODE
.
error
at the media element.
networkState
attribute must be
switched to the EMPTY
value and the user agent must fire a simple
event called emptied
at the element.
The download is aborted by the user, e.g. because the user navigated
the browsing context to another page, the user agent must execute the
following steps. These steps are not followed if the load()
method itself
is reinvoked, as the steps above handle that particular kind of abort.
error
attribute must be set to a new MediaError
object whose code
attribute
is set to MEDIA_ERR_ABORT
.
abort
at the media element.
networkState
attribute has the value
LOADING
,
the element's networkState
attribute must be
switched to the EMPTY
value and the user agent must fire a simple
event called emptied
at the element. (If the networkState
attribute has a value
greater than LOADING
, then this doesn't happen; the
available data, if any, will be playable.)
The server returning data that is partially usable but cannot be optimally rendered must cause the user agent to execute the following steps.
The user agent must follow these substeps:
The current playback position must be set to the effective start.
The networkState
attribute must be set
to LOADED_METADATA
.
A number of attributes, including duration
,
buffered
, and played
, become
available.
The user agent will fire a simple
event called durationchange
at the element at
this point.
The user agent must fire a simple event
called loadedmetadata
at the element.
The user agent must follow these substeps:
The networkState
attribute must be set
to LOADED_FIRST_FRAME
.
The readyState
attribute must change to
CAN_SHOW_CURRENT_FRAME
.
The loaded-first-frame flag must be set to true.
The user agent must fire a simple event
called loadedfirstframe
at the
element.
The user agent must fire a simple event
called canshowcurrentframe
at the
element.
When the user agent has completed the download of the entire media resource, it must move on to the next step.
If the download completes without errors, the begun
flag must be set to false, the networkState
attribute must be set to
LOADED
, and
the user agent must fire a progress event called
load
at the element.
If a media element whose networkState
has the value EMPTY
is inserted into a
document, user agents must implicitly invoke the load()
method on the media element as soon as all other scripts have
finished executing. Any exceptions raised
must be ignored.
The bufferingRate
attribute
must return the average number of bits received per second for the current
download over the past few seconds. If there is no download in progress,
the attribute must return 0.
The buffered
attribute must return
a static normalised TimeRanges
object that represents the ranges of the media
resource, if any, that the user agent has downloaded, at the time the
attribute is evaluated.
Typically this will be a single range anchored at the zero point, but if, e.g. the user agent uses HTTP range requests in response to seeking, then there could be multiple ranges.
The duration
attribute must return
the length of the media resource, in seconds. If no
media data is available, then the attributes must
return 0. If media data is available but the length
is not known, the attribute must return the Not-a-Number (NaN) value. If
the media resource is known to be unbounded (e.g. a
streaming radio), then the attribute must return the positive Infinity
value.
When the length of the media resource changes
(e.g. from being unknown to known, or from indeterminate to known, or from
a previously established length to a new length) the user agent must, once
any running scripts have finished, fire a simple
event called durationchange
at the media element.
Media elements have a current playback position, which must initially be zero. The current position is a time.
The currentTime
attribute must,
on getting, return the current playback position,
expressed in seconds. On setting, the user agent must seek to the new value (which might raise an
exception).
The start
content attribute gives the offset into the media
resource at which playback is to begin. The default value is the
default start position of the media resource, or 0
if not enough media data has been obtained yet to
determine the default start position or if the resource doesn't specify a
default start position.
The effective start is the smaller of
the start
DOM
attribute and the end of the media resource.
The loopstart
content attribute
gives the offset into the media resource at which
playback is to begin when looping a clip. The default value of the loopstart
content attribute is the value of the start
DOM attribute.
The effective loop start is the
smaller of the loopStart
DOM attribute and the end of the
media resource.
The loopend
content attribute gives an offset into the media
resource at which playback is to jump back to the loopstart
, when
looping the clip. The default value of the loopend
content
attribute is the value of the end
DOM attribute.
The effective loop end is the
greater of the start
, loopStart
, and loopEnd
DOM
attributes, except if that is greater than the end of the media resource, in which case that's its value.
The end
content
attribute gives an offset into the media resource at
which playback is to end. The default value is infinity.
The effective end is the greater of
the start
, loopStart
, and
end
DOM
attributes, except if that is greater than the end of the media resource, in which case that's its value.
The start
,
loopstart
, loopend
, and end
attributes must, if specified, contain value time offsets. To get the time
values they represent, user agents must use the rules
for parsing time offsets.
The start
, loopStart
, loopEnd
, and end
DOM attributes must reflect the start
, loopstart
, loopend
, and end
content attributes on the media element respectively.
The playcount
content attribute
gives the number of times to play the clip. The default value is 1.
The playCount
DOM attribute must
reflect the playcount
content attribute on the media element. The value must be limited to only positive non-zero numbers.
The currentLoop
attribute must
initially have the value 0. It gives the index of the current loop. It is
changed during playback as described below.
When any of the start
, loopStart
, loopEnd
, end
, and playCount
DOM attributes change value
(either through content attribute mutations reflecting into the DOM
attribute, or direct mutations of the DOM attribute), the user agent must
apply the following steps:
If the playCount
DOM attribute's value is less
than or equal to the currentLoop
DOM attribute's value, then
the currentLoop
DOM attribute's value must be
set to playCount
-1 (which will make the
current loop the last loop).
If the media element's networkState
is in the EMPTY
state or the
LOADING
state, then the user agent must at this point abort these steps.
If the currentLoop
is zero, and the current playback position is before the effective start, the user agent must seek to the effective start.
If the currentLoop
is greater than zero, and the
current playback position is before the effective loop start, the user agent must
seek to the effective loop start.
If the currentLoop
is less than playCount
-1, and the current playback position is after the effective loop end, the user agent must seek to the effective loop start, and increase currentLoop
by 1.
If the currentLoop
is equal to playCount
-1, and the current playback position is after the effective end, the user agent must seek to the effective end and then the looping will
end.
Media elements have a ready state, which describes to what degree they are ready to be rendered at the current playback position. The possible values are as follows; the ready state of a media element at any particular time is the greatest value describing the state of the element:
DATA_UNAVAILABLE
(numeric value 0)
networkState
attribute is less than LOADED_FIRST_FRAME
are always in the
DATA_UNAVAILABLE
state.
CAN_SHOW_CURRENT_FRAME
(numeric value 1)
DATA_UNAVAILABLE
state. In video, this
corresponds to the user agent having data from the current frame, but not
the next frame. In audio, this corresponds to the user agent only having
audio up to the current playback position, but no
further.
CAN_PLAY
(numeric value 2)
DATA_UNAVAILABLE
state. In video, this
corresponds to the user agent having data for the current frame and the
next frame. In audio, this corresponds ot the user agent having data
beyond the current playback position.
CAN_PLAY_THROUGH
(numeric value 3)
DATA_UNAVAILABLE
state, and, in
addition, the user agent estimates that data is being downloaded at a
rate where the current playback position, if it
were to advance at the rate given by the defaultPlaybackRate
attribute,
would not overtake the available data before playback reaches the effective end of the media
resource on the last loop.
When the ready state of a media element whose
networkState
is not EMPTY
changes, the user
agent must follow the steps given below:
DATA_UNAVAILABLE
The user agent must fire a simple event called
dataunavailable
at the element.
CAN_SHOW_CURRENT_FRAME
If the element's loaded-first-frame
flag is true, the user agent must fire a simple
event called canshowcurrentframe
event.
The first time the networkState
attribute switches to this
value, the loaded-first-frame flag is
false, and the event is fired by the algorithm described
above for the load()
method, in conjunction with other steps.
CAN_PLAY
The user agent must fire a simple event called
canplay
.
CAN_PLAY_THROUGH
The user agent must fire a simple event called
canplaythrough
event. If the autoplaying flag is true, and the paused
attribute is
true, and the media element has an autoplay
attribute specified, then the user agent must also set the paused
attribute to
false and fire a simple event called play
.
It is possible for the ready state of a media element to jump
between these states discontinuously. For example, the state of a media
element whose leaded-first-frame flag is false can jump
straight from DATA_UNAVAILABLE
to CAN_PLAY_THROUGH
without passing through
the CAN_SHOW_CURRENT_FRAME
and CAN_PLAY
states,
and thus without firing the canshowcurrentframe
and canplay
events. The
only state that is guarenteed to be reached is the CAN_SHOW_CURRENT_FRAME
state, which
is reached as part of the load()
method's processing.
The readyState
DOM attribute
must, on getting, return the value described above that describes the
current ready state of the media element.
The autoplay
attribute is a boolean attribute. When present, the algorithm
described herein will cause the user agent to automatically begin playback
of the media resource as soon as it can do so
without stopping.
The autoplay
DOM attribute must reflect the content attribute of the same name.
The paused
attribute represents whether the media element is
paused or not. The attribute must initially be true.
A media element is said to be actively playing when its paused
attribute is
false, the readyState
attribute is either CAN_PLAY
or CAN_PLAY_THROUGH
, the element has not ended playback, playback has not stopped due to errors, and the element has not paused for user interaction.
A media element is said to have ended playback when the element's networkState
attribute is LOADED_METADATA
or greater, the current playback position is equal to the effective end of the media
resource, and the currentLoop
attribute is equal to
playCount
-1.
A media element is said to have stopped due to errors when the element's networkState
attribute is LOADED_METADATA
or greater, and the user
agent encounters a non-fatal error
during the processing of the media data, and due to
that error, is not able to play the content at the current playback position.
A media element is said to have paused for user interaction when its paused
attribute is
false, the readyState
attribute is either CAN_PLAY
or CAN_PLAY_THROUGH
and the user agent has
reached a point in the media resource where the user
has to make a selection for the resource to continue.
It is possible for a media element to have both ended playback and paused for user interaction at the same time.
When a media element is actively playing and its owner Document
is an active document, its current playback position must increase monotonically
at playbackRate
units of media time per unit
time of wall clock time. If this value is not 1, the user agent may apply
pitch adjustments to any audio component of the media
resource.
Media resources might be internally scripted or interactive. Thus, a media element could play in a non-linear fashion. If this happens, the user agent must act as if the algorithm for seeking was used whenever the current playback position changes in a discontinuous fashion (so that the relevant events fire).
When a media element that is actively playing stops playing because its readyState
attribute changes to a value lower than CAN_PLAY
, without the element having ended playback, or playback having stopped due to errors, or playback having paused for user interaction, the user agent must fire a simple event called timeupdate
at the
element, and then must fire a simple event called
waiting
at the
element.
When a media element that is actively playing stops playing because it has paused for user interaction, the user agent must fire a simple event called timeupdate
at the
element.
When currentLoop
is less than playCount
-1 and the current playback position reaches the effective loop end, then the user agent must
seek to the effective loop start, increase currentLoop
by 1, and fire a simple event called timeupdate
.
When currentLoop
is equal to the playCount
-1 and the current playback position reaches the effective end, then the user agent must
follow these steps:
The user agent must stop playback.
The ended
attribute becomes true.
The user agent must fire a simple event called
timeupdate
at the element.
The user agent must fire a simple event called
ended
at the
element.
The defaultPlaybackRate
attribute gives the desired speed at which the media
resource is to play, as a multiple of its intrinsic speed. The
attribute is mutable, but on setting, if the new value is 0.0, a
NOT_SUPPORTED_ERR
exception must be raised instead of the
value being changed. It must initially have the value 1.0.
The playbackRate
attribute
gives the speed at which the media resource plays,
as a multiple of its intrinsic speed. If it is not equal to the defaultPlaybackRate
, then the
implication is that the user is using a feature such as fast forward or
slow motion playback. The attribute is mutable, but on setting, if the new
value is 0.0, a NOT_SUPPORTED_ERR
exception must be raised
instead of the value being changed. Otherwise, the playback must change
speed (if the element is actively playing). It
must initially have the value 1.0.
When the defaultPlaybackRate
or playbackRate
attributes change value
(either by being set by script or by being changed directly by the user
agent, e.g. in response to user control) the user agent must, once any
running scripts have finished, fire a simple event
called ratechange
at the media element.
When the play()
method on a media element is invoked, the user agent
must run the following steps.
If the media element's networkState
attribute has the value EMPTY, then the user agent must
invoke the load()
method and wait for it to return. If that raises an exception, that
exception must be reraised by the play()
method.
If the playback has ended,
then the user agent must set currentLoop
to zero and seek to the effective
start.
The playbackRate
attribute must be set to
the value of the defaultPlaybackRate
attribute.
If the media element's paused
attribute is
true, it must be set to false.
The media element's autoplaying flag must be set to false.
The method must then return.
If the second step above involved a seek, the user agent will
fire a simple event called timeupdate
at the
media element.
If the third step above caused the playbackRate
attribute to change value,
the user agent will fire a simple event called
ratechange
at the media element.
If the fourth step above changed the value of paused
, the user agent
must fire a simple event called play
at the media element.
When the pause()
method is invoked, the user agent must run the following steps:
If the media element's networkState
attribute has the value EMPTY, then the user agent must
invoke the load()
method and wait for it to return. If that raises an exception, that
exception must be reraised by the pause()
method.
If the media element's paused
attribute is
false, it must be set to true.
The media element's autoplaying flag must be set to false.
The method must then return.
If the second step above changed the value of paused
, the user
agent must first fire a simple event called timeupdate
at
the element, and then fire a simple event called
pause
at the
element.
When a media element is removed from a
Document
, the user agent must
act as if the pause()
method had been invoked.
Media elements that are actively playing while not in a
Document
must not play any video, but
should play any audio component. Media elements must not stop playing just
because all references to them have been removed; only once a media
element to which no references exist has reached a point where no further
audio remains to be played for that element (e.g. because the element is
paused or because the end of the clip has been reached) may the element be
garbage collected.
If the media element's ownerDocument
stops being an active
document, then the playback will stop until
the document is active again.
The ended
attribute must return true if the media element has
ended playback, and false otherwise.
The played
attribute must return a static normalised
TimeRanges
object that represents the ranges of the media resource, if any, that the user agent has so far
rendered, at the time the attribute is evaluated.
The seeking
attribute must initially have the value false.
When the user agent is required to seek to a particular new playback position in the media resource, it means that the user agent must run the following steps:
If the media element's networkState
is less than LOADED_METADATA
, then the user agent
must raise an INVALID_STATE_ERR
exception (if the seek was
in response to a DOM method call or setting of a DOM attribute), and
abort these steps.
If currentLoop
is 0, let min be the effective
start. Otherwise, let it be the effective loop start.
If currentLoop
is equal to the value of
playCount
, let max be
the effective end. Otherwise, let
it be the effective loop end.
If the new playback position is more than max, let it be max.
If the new playback position is less than min, let it be min.
If the (possibly now changed) new playback
position is not in one of the ranges given in the seekable
attribute, then the user agent must raise an INDEX_SIZE_ERR
exception (if the seek was in response to a DOM method call or setting
of a DOM attribute), and abort these steps.
The current playback position must be set to the given new playback position.
The seeking
DOM attribute must be set to true.
The user agent must fire a simple event called
timeupdate
at the element.
As soon as the user agent has established whether or not the media data for the new playback
position is available, and, if it is, decoded enough data to play
back that position, the seeking
DOM attribute must be set to false.
The seekable
attribute must return
a static normalised TimeRanges
object that represents the ranges of the media
resource, if any, that the user agent is able to seek to, at the time
the attribute is evaluated, notwithstanding the looping attributes (i.e.
the effective start and effective end, etc, don't affect the seeking
attribute).
If the user agent can seek to anywhere in the media resource, e.g. because it a simple movie file and
the user agent and the server support HTTP Range requests, then the
attribute would return an object with one range, whose start is the time
of the first frame (typically zero), and whose end is the same as the time
of the first frame plus the duration
attribute's value (which would equal
the time of the last frame).
Media elements have a set of cue ranges. Each cue range is made up of the following information:
The addCueRange(className, start, end, pauseOnExit, enterCallback, exitCallback)
method must, when called, add a
cue range to the media
element, that cue range having the class name className, the start time start (in
seconds), the end time end (in seconds), the "pause"
boolean with the same value as pauseOnExit, the
"enter" callback enterCallback, the "exit" callback
exitCallback, and an "active" boolean that is true if
the current playback position is equal to or
greater than the start time and less than the end time, and false
otherwise.
The removeCueRanges(className)
method must, when called, remove
all the cue ranges of the media element which have the class name className.
When the current playback position of a media element changes (e.g. due to playback or seeking), the user agent must run the following steps. If the current playback position changes while the steps are running, then the user agent must wait for the steps to complete, and then must immediately rerun the steps. (These steps are thus run as often as possible or needed — if one iteration takes a long time, this can cause certain ranges to be skipped over as the user agent rushes ahead to "catch up".)
Let current ranges be an ordered list of cue ranges, initialised to contain all the cue ranges of the media element whose start times are less than or equal to the current playback position and whose end times are greater than the current playback position, in the order they were added to the element.
Let other ranges be an ordered list of cue ranges, initialised to contain all the cue ranges of the media element that are not present in current ranges, in the order they were added to the element.
If none of the cue ranges in current ranges have their "active" boolean set to "false" (inactive) and none of the cue ranges in other ranges have their "active" boolean set to "true" (active), then abort these steps.
If the time was reached through the usual monotonic increase of the
current playback position during normal playback, the user agent must
then fire a simple event called timeupdate
at
the element. (In the other cases, such as explicit seeks, relevant
events get fired as part of the overall process of changing the current
playback position.)
If the time was reached through the usual monotonic increase of the
current playback position during normal playback, and there are cue ranges in other ranges that have both their "active" boolean and
their "pause" boolean set to "true", then immediately act as if the
element's pause()
method had been invoked. (In the other
cases, such as explicit seeks, playback is not paused by exiting a cue
range, even if that cue range has its "pause" boolean set to "true".)
Invoke all the non-null "exit" callbacks for all of the cue ranges in other ranges that have their "active" boolean set to "true" (active), in list order.
Invoke all the non-null "enter" callbacks for all of the cue ranges in current ranges that have their "active" boolean set to "false" (inactive), in list order.
Set the "active" boolean of all the cue ranges in the current ranges list to "true" (active), and the "active" boolean of all the cue ranges in the other ranges list to "false" (inactive).
Invoking a callback (an object implementing the VoidCallback
interface) means calling its
handleEvent()
method.
interface VoidCallback { void handleEvent(); };
The handleEvent
method
of objects implementing the VoidCallback
interface is the entrypoint
for the callback represented by the object.
In the ECMAScript DOM binding, the ECMAScript native
Function
type must implement the VoidCallback
interface such that invoking
the handleEvent()
method of that interface on the object from
another language binding invokes the function itself. In the ECMAScript
binding itself, however, the handleEvent()
method of the
interface is not directly accessible on Function
objects.
Such functions, when invoked, must be called at the scope of the browsing context.
The controls
attribute is a boolean attribute. If the attribute is present, or if
scripting is disabled, then the user agent
should expose a user interface to the user. This user
interface should include features to begin playback, pause playback, seek
to an arbitrary position in the content (if the content supports arbitrary
seeking), change the volume, and show the media content in manners more
suitable to the user (e.g. full-screen video or in an independent
resizable window). Other controls may also be made available.
If the attribute is absent, then the user agent should avoid making a user interface available that could conflict with an author-provided user interface. User agents may make the following features available, however, even when the attribute is absent:
User agents may provide controls to affect playback of the media resource (e.g. play, pause, seeking, and volume controls), but such features should not interfere with the page's normal rendering. For example, such features could be exposed in the media element's context menu.
Where possible (specifically, for starting, stopping, pausing, and unpausing playback, for muting or changing the volume of the audio, and for seeking), user interface features exposed by the user agent must be implemented in terms of the DOM API described above, so that, e.g., all the same events fire.
The controls
DOM attribute must reflect the content attribute of the same name.
The volume
attribute must return the playback volume of any audio portions of the media element, in the range 0.0 (silent) to 1.0
(loudest). Initially, the volume must be 0.5, but user agents may remember
the last set value across sessions, on a per-site basis or otherwise, so
the volume may start at other values. On setting, if the new value is in
the range 0.0 to 1.0 inclusive, the attribute must be set to the new value
and the playback volume must be correspondingly adjusted as soon as
possible after setting the attribute, with 0.0 being silent, and 1.0 being
the loudest setting, values in between increasing in loudness. The range
need not be linear. The loudest setting may be lower than the system's
loudest possible setting; for example the user could have set a maximum
volume. If the new value is outside the range 0.0 to 1.0 inclusive, then,
on setting, an INDEX_SIZE_ERR
exception must be raised
instead.
The muted
attribute must return true if the audio channels are muted and false
otherwise. On setting, the attribute must be set to the new value; if the
new value is true, audio playback for this media
resource must then be muted, and if false, audio playback must then be
enabled.
Whenever either the muted
or volume
attributes are changed, after any running
scripts have finished executing, the user agent must fire a simple event called volumechange
at the media element.
Objects implementing the TimeRanges
interface represent a list of
ranges (periods) of time.
interface TimeRanges { readonly attribute unsigned long length; float start(in unsigned long index); float end(in unsigned long index); };
The length
DOM attribute must
return the number of ranges represented by the object.
The start(index)
method must return the position of the
start of the indexth range represented by the object,
in seconds measured from the start of the timeline that the object covers.
The end(index)
method must return the position of the
end of the indexth range represented by the object, in
seconds measured from the start of the timeline that the object covers.
These methods must raise INDEX_SIZE_ERR
exceptions if
called with an index argument greater than or equal to
the number of ranges represented by the object.
When a TimeRanges
object is said
to be a normalised TimeRanges
object, the ranges it represents must obey the following criteria:
In other words, the ranges in such an object are ordered, don't overlap, and don't touch (adjacent ranges are folded into one bigger range).
The timelines used by the objects returned by the buffered
, seekable
and played
DOM attributes
of media elements must be the
same as that element's media resource's timeline.
The following events fire on media elements as part of the processing model described above:
| Event name | Interface | Dispatched when... | Preconditions |
|---|---|---|---|
begin
| ProgressEvent [PROGRESS]
| The user agent begins fetching the media data,
synchronously during the load() method call.
| networkState equals LOADING
|
progress
| ProgressEvent [PROGRESS]
| The user agent is fetching media data. | networkState is more than EMPTY and less than
LOADED
|
loadedmetadata
| Event
| The user agent is fetching media data, and the media resource's metadata has just been received. | networkState equals LOADED_METADATA
|
loadedfirstframe
| Event
| The user agent is fetching media data, and the media resource's first frame has just been received. | networkState equals LOADED_FIRST_FRAME
|
load
| ProgressEvent [PROGRESS]
| The user agent finishes downloading the entire media resource. | networkState equals LOADED
|
abort
| ProgressEvent [PROGRESS]
| The user agent stops fetching the media data
before it is completely downloaded. This can be fired synchronously
during the load()
method call.
| error is an
object with the code MEDIA_ERR_ABORTED . networkState equals either EMPTY or LOADED , depending
on when the download was aborted.
|
error
| ProgressEvent [PROGRESS]
| An error occurs while fetching the media data. | error is an
object with the code MEDIA_ERR_NETWORK_ERROR
or higher. networkState equals either EMPTY or LOADED , depending
on when the download was aborted.
|
emptied
| Event
| A media element whose networkState was previously not in the
EMPTY state has
just switched to that state (either because of a fatal error during
load that's about to be reported, or because the load() method was
reinvoked, in which case it is fired synchronously during the load() method call).
| networkState is EMPTY ; all the DOM
attributes are in their initial states.
|
stalled
| ProgressEvent
| The user agent is trying to fetch media data, but data is unexpectedly not forthcoming. | |
play
| Event
| Playback has begun. Fired after the play method has returned.
| paused is
newly false.
|
pause
| Event
| Playback has been paused. Fired after the pause method has
returned.
| paused is
newly true.
|
waiting
| Event
| Playback has stopped because the next frame is not available, but the user agent expects that frame to become available in due course. | readyState is either DATA_UNAVAILABLE or CAN_SHOW_CURRENT_FRAME , and
paused is
false. Either seeking is true, or the current playback position is not contained in any
of the ranges in buffered . It is possible for playback to
stop for two other reasons without paused being false, but those two reasons do
not fire this event: maybe playback ended, or playback stopped
due to errors.
|
timeupdate
| Event
| The current playback position changed in an interesting way, for example discontinuously. | |
ended
| Event
| Playback has stopped because the end of the media resource was reached. | currentTime equals the effective end; ended is true.
|
dataunavailable
| Event
| The user agent cannot render the data at the current playback position because data for the current frame is not immediately available. | The readyState attribute is newly equal to
DATA_UNAVAILABLE .
|
canshowcurrentframe
| Event
| The user agent cannot render the data after the current playback position because data for the next frame is not immediately available. | The readyState attribute is newly equal to
CAN_SHOW_CURRENT_FRAME .
|
canplay
| Event
| The user agent can resume playback of the media data, but estimates that if playback were to be started now, the media resource could not be rendered at the current playback rate up to its end without having to stop for further buffering of content. | The readyState attribute is newly equal to
CAN_PLAY .
|
canplaythrough
| Event
| The user agent estimates that if playback were to be started now, the media resource could be rendered at the current playback rate all the way to its end without having to stop for further buffering. | The readyState attribute is newly equal to
CAN_PLAY_THROUGH .
|
ratechange
| Event
| Either the defaultPlaybackRate or the playbackRate attribute has just been
updated.
| |
durationchange
| Event
| The duration attribute has just been updated.
| |
volumechange
| Event
| Either the volume attribute or the muted attribute has
changed. Fired after the relevant attribute's setter has returned.
|
Talk about making sure interactive media files (e.g. SVG) don't have access to the container DOM (XSS potential); talk about not exposing any sensitive data like metadata from tracks in the media files (intranet snooping risk)
source
elementsrc
type
media
interface HTMLSourceElement : HTMLElement { attribute DOMString src; attribute DOMString type; attribute DOMString media; };
The source
element allows authors to
specify multiple media
resources for media
elements.
The src
attribute
gives the address of the media resource. The value
must be a URI (or IRI). This attribute must be present.
The type
attribute gives the type of the media resource, to
help the user agent determine if it can play this media
resource before downloading it. Its value must be a MIME type. The
codecs
parameter may be specified and might be
necessary to specify exactly how the resource is encoded. [RFC2046] [RFC4281]
The following list shows some examples of how to use the codecs=
MIME parameter in the type
attribute.
<source src="video.mp4" type="video/mp4; codecs="avc1.42E01E, mp4a.40.2"">
<source src="video.mp4" type="video/mp4; codecs="avc1.58A01E, mp4a.40.2"">
<source src="video.mp4" type="video/mp4; codecs="avc1.4D401E, mp4a.40.2"">
<source src="video.mp4" type="video/mp4; codecs="avc1.64001E, mp4a.40.2"">
<source src="video.mp4" type="video/mp4; codecs="mp4v.20.8, mp4a.40.2"">
<source src="video.mp4" type="video/mp4; codecs="mp4v.20.240, mp4a.40.2"">
<source src="video.3gp" type="video/3gpp; codecs="mp4v.20.8, samr"">
<source src="video.ogv" type="video/ogg; codecs="theora, vorbis"">
<source src="video.ogv" type="video/ogg; codecs="theora, speex"">
<source src="audio.oga" type="audio/ogg; codecs=vorbis">
<source src="audio.oga" type="audio/ogg; codecs=speex">
<source src="audio.oga" type="audio/ogg; codecs=flac">
<source src="video.ogv" type="video/ogg; codecs="dirac, vorbis"">
<source src="video.mkv" type="video/x-matroska; codecs="theora, vorbis"">
The media
attribute gives the intended media type of the media
resource, to help the user agent determine if this media resource is useful to the user before downloading
it. Its value must be a valid media query. [MQ]
Either the type
attribute, the media
attribute or both, must be specified,
unless this is the last source
element
child of the parent element.
If a source
element is inserted into
a media element that is already in a document and
whose networkState
is in the EMPTY
state, the user
agent must implicitly invoke the load()
method on the media
element as soon as all other scripts have finished executing. Any
exceptions raised must be ignored.
The DOM attributes src
, type
, and media
must reflect the respective content attributes of the same
name.
canvas
elementwidth
height
interface HTMLCanvasElement : HTMLElement { attribute unsigned long width; attribute unsigned long height; DOMString toDataURL(); DOMString toDataURL(in DOMString type); DOMObject getContext(in DOMString contextId); };
The canvas
element represents a
resolution-dependent bitmap canvas, which can be used for rendering
graphs, game graphics, or other visual images on the fly.
Authors should not use the canvas
element in a document when a more suitable element is available. For
example, it is inappropriate to use a canvas
element to render a page heading: if the
desired presentation of the heading is graphically intense, it should be
marked up using appropriate elements (typically h1
) and then styled using CSS and supporting
technologies such as XBL.
When authors use the canvas
element,
they should also provide content that, when presented to the user, conveys
essentially the same function or purpose as the bitmap canvas. This
content may be placed as content of the canvas
element. The contents of the canvas
element, if any, are the element's fallback content.
In interactive visual media with scripting enabled, the canvas element is an embedded element with a dynamically created image.
In non-interactive, static, visual media, if the canvas
element has been previously painted on
(e.g. if the page was viewed in an interactive visual medium and is now
being printed, or if some script that ran during the page layout process
painted on the element), then the canvas
element must be treated as embedded content with the current image and size.
Otherwise, the element's fallback content must be
used instead.
In non-visual media, and in visual media with scripting
disabled, the canvas
element's
fallback content must be used instead.
The canvas
element has two attributes
to control the size of the coordinate space: width
and height
. These attributes, when
specified, must have values that are valid non-negative integers. The rules for parsing non-negative integers must be used to
obtain their numeric values. If an attribute is missing, or if parsing its
value returns an error, then the default value must be used instead. The
width
attribute
defaults to 300, and the height
attribute defaults to 150.
The intrinsic dimensions of the canvas
element equal the size of the coordinate
space, with the numbers interpreted in CSS pixels. However, the element
can be sized arbitrarily by a style sheet. During rendering, the image is
scaled to fit this layout size.
The size of the coordinate space does not necessarily represent the size of the actual bitmap that the user agent will use internally or during rendering. On high-definition displays, for instance, the user agent may internally use a bitmap with two device pixels per unit in the coordinate space, so that the rendering remains at high quality throughout.
The canvas must initially be fully transparent black.
Whenever the width
and height
attributes are set (whether to a new
value or to the previous value), the bitmap and any associated contexts
must be cleared back to their initial state and reinitialised with the
newly specified coordinate space dimensions.
The width
and
height
DOM
attributes must reflect the content attributes of
the same name.
Only one square appears to be drawn in the following example:
// canvas is a reference to a <canvas> element var context = canvas.getContext('2d'); context.fillRect(0,0,50,50); canvas.setAttribute('width', '300'); // clears the canvas context.fillRect(0,100,50,50); canvas.width = canvas.width; // clears the canvas context.fillRect(100,0,50,50); // only this square remains
To draw on the canvas, authors must first obtain a reference to a context using the getContext(contextId)
method of the canvas
element.
This specification only defines one context, with the name "2d
". If getContext()
is called with that exact string for its contextId
argument, then the UA must return a reference to an object implementing
CanvasRenderingContext2D
.
Other specifications may define their own contexts, which would return
different objects.
Vendors may also define experimental contexts using the syntax
vendorname-context
,
for example, moz-3d
.
When the UA is passed an empty string or a string specifying a context that it does not support, then it must return null. String comparisons must be literal and case-sensitive.
A future version of this specification will probably define a
3d
context (probably based on the OpenGL ES API).
The toDataURL()
method must,
when called with no arguments, return a data:
URI
containing a representation of the image as a PNG file. [PNG].
The toDataURL(type)
method (when called with one or
more arguments) must return a data:
URI containing a
representation of the image in the format given by type. The possible values are MIME types with no
parameters, for example image/png
, image/jpeg
,
or even maybe image/svg+xml
if the implementation actually
keeps enough information to reliably render an SVG image from the canvas.
Only support for image/png
is required. User agents may
support other types. If the user agent does not support the requested
type, it must return the image using the PNG format.
User agents must convert the provided type to lower case before
establishing if they support that type and before creating the
data:
URI.
When trying to use types other than image/png
,
authors can check if the image was really returned in the requested format
by checking to see if the returned string starts with one the exact
strings "data:image/png,
" or "data:image/png;
". If it does, the image is PNG, and thus
the requested type was not supported.
Arguments other than the type must be ignored, and
must not cause the user agent to raise an exception (as would normally
occur if a method was called with the wrong number of arguments). A future
version of this specification will probably allow extra parameters to be
passed to toDataURL()
to allow authors to more
carefully control compression settings, image metadata, etc.
Security: To prevent information leakage, the
toDataURL()
and getImageData()
methods should raise a security exception if the canvas has ever had an
image painted on it whose origin is different from
that of the script calling the method.
When the getContext()
method of a canvas
element is invoked with 2d
as the argument, a CanvasRenderingContext2D
object is returned.
There is only one CanvasRenderingContext2D
object per canvas, so calling the getContext()
method with the 2d
argument a second time
must return the same object.
The 2D context represents a flat cartesian surface whose origin (0,0) is at the top left corner, with the coordinate space having x values increasing when going right, and y values increasing when going down.
interface CanvasRenderingContext2D { // back-reference to the canvas readonly attribute HTMLCanvasElement canvas; // state void save(); // push state on state stack void restore(); // pop state stack and restore state // transformations (default transform is the identity matrix) void scale(in float x, in float y); void rotate(in float angle); void translate(in float x, in float y); void transform(in float m11, in float m12, in float m21, in float m22, in float dx, in float dy); void setTransform(in float m11, in float m12, in float m21, in float m22, in float dx, in float dy); // compositing attribute float globalAlpha; // (default 1.0) attribute DOMString globalCompositeOperation; // (default source-over) // colors and styles attribute DOMObject strokeStyle; // (default black) attribute DOMObject fillStyle; // (default black) CanvasGradient createLinearGradient(in float x0, in float y0, in float x1, in float y1); CanvasGradient createRadialGradient(in float x0, in float y0, in float r0, in float x1, in float y1, in float r1); CanvasPattern createPattern(in HTMLImageElement image, DOMString repetition); CanvasPattern createPattern(in HTMLCanvasElement image, DOMString repetition); // line caps/joins attribute float lineWidth; // (default 1) attribute DOMString lineCap; // "butt", "round", "square" (default "butt") attribute DOMString lineJoin; // "round", "bevel", "miter" (default "miter") attribute float miterLimit; // (default 10) // shadows attribute float shadowOffsetX; // (default 0) attribute float shadowOffsetY; // (default 0) attribute float shadowBlur; // (default 0) attribute DOMString shadowColor; // (default transparent black) // rects void clearRect(in float x, in float y, in float w, in float h); void fillRect(in float x, in float y, in float w, in float h); void strokeRect(in float x, in float y, in float w, in float h); // path API void beginPath(); void closePath(); void moveTo(in float x, in float y); void lineTo(in float x, in float y); void quadraticCurveTo(in float cpx, in float cpy, in float x, in float y); void bezierCurveTo(in float cp1x, in float cp1y, in float cp2x, in float cp2y, in float x, in float y); void arcTo(in float x1, in float y1, in float x2, in float y2, in float radius); void rect(in float x, in float y, in float w, in float h); void arc(in float x, in float y, in float radius, in float startAngle, in float endAngle, in boolean anticlockwise); void fill(); void stroke(); void clip(); boolean isPointInPath(in float x, in float y); // drawing images void drawImage(in HTMLImageElement image, in float dx, in float dy); void drawImage(in HTMLImageElement image, in float dx, in float dy, in float dw, in float dh); void drawImage(in HTMLImageElement image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh); void drawImage(in HTMLCanvasElement image, in float dx, in float dy); void drawImage(in HTMLCanvasElement image, in float dx, in float dy, in float dw, in float dh); void drawImage(in HTMLCanvasElement image, in float sx, in float sy, in float sw, in float sh, in float dx, in float dy, in float dw, in float dh); // pixel manipulation ImageData getImageData(in float sx, in float sy, in float sw, in float sh); void putImageData(in ImageData imagedata, in float dx, in float dy); // drawing text is not supported in this version of the API // (there is no way to predict what metrics the fonts will have, // which makes fonts very hard to use for painting) }; interface CanvasGradient { // opaque object void addColorStop(in float offset, in DOMString color); }; interface CanvasPattern { // opaque object }; interface ImageData { readonly attribute long int width; readonly attribute long int height; readonly attribute int[] data; };
The canvas
attribute must
return the canvas
element that the
context paints on.
Each context maintains a stack of drawing states. Drawing states consist of:
strokeStyle
, fillStyle
,
globalAlpha
, lineWidth
,
lineCap
,
lineJoin
, miterLimit
, shadowOffsetX
, shadowOffsetY
, shadowBlur
, shadowColor
, globalCompositeOperation
.
The current path and the current bitmap are not part of the
drawing state. The current path is persistent, and can only be reset using
the beginPath()
method. The current bitmap is
a property of the
canvas, not the context.
The save()
method must push a copy of the current drawing state onto the drawing
state stack.
The restore()
method must pop
the top entry in the drawing state stack, and reset the drawing state it
describes. If there is no saved state, the method must do nothing.
The transformation matrix is applied to coordinates when creating shapes and paths.
When the context is created, the transformation matrix must initially be the identity transform. It may then be adjusted using the transformation methods.
The transformation matrix can become infinite, at which point nothing is drawn anymore.
The transformations must be performed in reverse order. For instance, if a scale transformation that doubles the width is applied, followed by a rotation transformation that rotates drawing operations by a quarter turn, and a rectangle twice as wide as it is tall is then drawn on the canvas, the actual result will be a square.
The scale(x, y)
method must add the
scaling transformation described by the arguments to the transformation
matrix. The x argument represents the scale factor in
the horizontal direction and the y argument represents
the scale factor in the vertical direction. The factors are multiples. If
either argument is Infinity the transformation matrix must be marked as
infinite instead of the method throwing an exception.
The rotate(angle)
method must add the rotation
transformation described by the argument to the transformation matrix. The
angle argument represents a clockwise rotation angle
expressed in radians.
The translate(x, y)
method must add the translation
transformation described by the arguments to the transformation matrix.
The x argument represents the translation distance in
the horizontal direction and the y argument represents
the translation distance in the vertical direction. The arguments are in
coordinate space units. If either argument is Infinity the transformation
matrix must be marked as infinite instead of the method throwing an
exception.
The transform(m11,
m12, m21, m22,
dx, dy)
method must
multiply the current transformation matrix with the matrix described by:
| m11 | m21 | dx |
| m12 | m22 | dy |
| 0 | 0 | 1 |
If any of the arguments are Infinity the transformation matrix must be marked as infinite instead of the method throwing an exception.
The setTransform(m11, m12, m21, m22, dx, dy)
method must reset the current transform to
the identity matrix, and then invoke the transform(m11, m12, m21, m22, dx, dy)
method with the same
arguments. If any of the arguments are Infinity the transformation matrix
must be marked as infinite instead of the method throwing an exception.
All drawing operations are affected by the global compositing
attributes, globalAlpha
and globalCompositeOperation
.
The globalAlpha
attribute
gives an alpha value that is applied to shapes and images before they are
composited onto the canvas. The value must be in the range from 0.0 (fully
transparent) to 1.0 (no additional transparency). If an attempt is made to
set the attribute to a value outside this range, the attribute must retain
its previous value. When the context is created, the globalAlpha
attribute must initially have
the value 1.0.
The globalCompositeOperation
attribute sets how shapes and images are drawn onto the existing bitmap,
once they have had globalAlpha
and the current transformation
matrix applied. It must be set to a value from the following list. In the
descriptions below, the source image, A, is the shape
or image being rendered, and the destination image, B,
is the current state of the bitmap.
source-atop
source-in
source-out
source-over
(default)
destination-atop
source-atop
but
using the destination image instead of the source image and vice versa.
destination-in
source-in
but using
the destination image instead of the source image and vice versa.
destination-out
source-out
but
using the destination image instead of the source image and vice versa.
destination-over
source-over
but
using the destination image instead of the source image and vice versa.lighter
copy
xor
vendorName-operationName
These values are all case-sensitive — they must be used exactly as shown. User agents must only recognise values that exactly match the values given above.
The operators in the above list must be treated as described by the Porter-Duff operator given at the start of their description (e.g. A over B). [PORTERDUFF]
On setting, if the user agent does not recognise the specified value, it
must be ignored, leaving the value of globalCompositeOperation
unaffected.
When the context is created, the globalCompositeOperation
attribute must initially have the value source-over
.
The strokeStyle
attribute
represents the color or style to use for the lines around shapes, and the
fillStyle
attribute
represents the color or style to use inside the shapes.
Both attributes can be either strings, CanvasGradient
s, or CanvasPattern
s. On setting, strings must
be parsed as CSS <color> values and the color assigned, and CanvasGradient
and CanvasPattern
objects must be assigned
themselves. [CSS3COLOR] If the value is a
string but is not a valid color, or is neither a string, a CanvasGradient
, nor a CanvasPattern
, then it must be ignored,
and the attribute must retain its previous value.
On getting, if the value is a color, then the serialisation of the color must be
returned. Otherwise, if it is not a color but a CanvasGradient
or CanvasPattern
, then the respective
object must be returned. (Such objects are opaque and therefore only
useful for assigning to other attributes or for comparison to other
gradients or patterns.)
The serialisation of a color for a color
value is a string, computed as follows: if it has alpha equal to 1.0, then
the string is a lowercase six-digit hex value, prefixed with a "#"
character (U+0023 NUMBER SIGN), with the first two digits representing the
red component, the next two digits representing the green component, and
the last two digits representing the blue component, the digits being in
the range 0-9 a-f (U+0030 to U+0039 and U+0061 to U+0066). Otherwise, the
color value has alpha less than 1.0, and the string is the color value in
the CSS rgba()
functional-notation format: the
literal string rgba
(U+0072 U+0067 U+0062 U+0061)
followed by a U+0028 LEFT PARENTHESIS, a base-ten integer in the range
0-255 representing the red component (using digits 0-9, U+0030 to U+0039,
in the shortest form possible), a literal U+002C COMMA and U+0020 SPACE,
an integer for the green component, a comma and a space, an integer for
the blue component, another comma and space, a U+0030 DIGIT ZERO, a U+002E
FULL STOP (representing the decimal point), one or more digits in the
range 0-9 (U+0030 to U+0039) representing the fractional part of the alpha
value, and finally a U+0029 RIGHT PARENTHESIS.
When the context is created, the strokeStyle
and fillStyle
attributes must initially have the string value #000000
.
There are two types of gradients, linear gradients and radial gradients,
both represented by objects implementing the opaque CanvasGradient
interface.
Once a gradient has been created (see below), stops are placed along it to define how the colors are distributed along the gradient. The color of the gradient at each stop is the color specified for that stop. Between each such stop, the colors and the alpha component must be linearly interpolated over the RGBA space without premultiplying the alpha value to find the color to use at that offset. Before the first stop, the color must be the color of the first stop. After the last stop, the color must be the color of the last stop. When there are no stops, the gradient is transparent black.
The addColorStop(offset, color)
method on
the CanvasGradient
interface
adds a new stop to a gradient. If the offset is less
than 0 or greater than 1 then an INDEX_SIZE_ERR
exception
must be raised. If the color cannot be parsed as a CSS
color, then a SYNTAX_ERR
exception must be raised. Otherwise,
the gradient must have a new stop placed, at offset offset relative to the whole gradient, and with the color
obtained by parsing color as a CSS <color>
value. If multiple stops are added at the same offset on a gradient, they
must be placed in the order added, with the first one closest to the start
of the gradient, and each subsequent one infinitesimally further along
towards the end point (in effect causing all but the first and last stop
added at each point to be ignored).
The createLinearGradient(x0, y0, x1, y1)
method takes four arguments, representing
the start point (x0, y0) and end
point (x1, y1) of the gradient, in
coordinate space units, and must return a linear CanvasGradient
initialised with that
line.
Linear gradients must be rendered such that at and before the starting point on the canvas the color at offset 0 is used, that at and after the ending point the color at offset 1 is used, and that all points on a line perpendicular to the line that crosses the start and end points have the color at the point where those two lines cross (with the colors coming from the interpolation described above).
If x0 = x1 and y0 = y1, then the linear gradient must paint nothing.
The createRadialGradient(x0, y0, r0, x1, y1, r1)
method takes six arguments, the first
three representing the start circle with origin (x0,
y0) and radius r0, and the last
three representing the end circle with origin (x1,
y1) and radius r1. The values are
in coordinate space units. The method must return a radial CanvasGradient
initialised with those
two circles. If either of r0 or r1
are negative, an INDEX_SIZE_ERR
exception must be raised.
Radial gradients must be rendered by following these steps:
Let x(ω) = (x1-x0)ω + x0
Let y(ω) = (y1-y0)ω + y0
Let r(ω) = (r1-r0)ω + r0
Let the color at ω be the color of the gradient at offset 0.0 for all values of ω less than 0.0, the color at offset 1.0 for all values of ω greater than 1.0, and the color at the given offset for values of ω in the range 0.0 ≤ ω ≤ 1.0
For all values of ω where r(ω) > 0, starting with the value of ω nearest to positive infinity and ending with the value of ω nearest to negative infinity, draw the circumference of the circle with radius r(ω) at position (x(ω), y(ω)), with the color at ω, but only painting on the parts of the canvas that have not yet been painted on by earlier circles in this step for this rendering of the gradient.
If x0 = x1 and y0 = y1 and r0 = r1, then the radial gradient must paint nothing.
This effectively creates a cone, touched by the two circles defined in the creation of the gradient, with the part of the cone before the start circle (0.0) using the color of the first offset, the part of the cone after the end circle (1.0) using the color of the last offset, and areas outside the cone untouched by the gradient (transparent black).
Gradients must only be painted where the relevant stroking or filling effects requires that they be drawn.
Support for actually painting gradients is optional. Instead of painting
the gradients, user agents may instead just paint the first stop's color.
However, createLinearGradient()
and createRadialGradient()
must always
return objects when passed valid arguments.
Patterns are represented by objects implementing the opaque CanvasPattern
interface.
To create objects of this type, the createPattern(image,
repetition)
method is used. The first argument gives the
image to use as the pattern (either an HTMLImageElement
or an HTMLCanvasElement
). Modifying this
image after calling the createPattern()
method must not
affect the pattern. The second argument must be a string with one of the
following values: repeat
, repeat-x
, repeat-y
, no-repeat
. If the empty string or null is specified, repeat
must be assumed. If an unrecognised value is given,
then the user agent must raise a SYNTAX_ERR
exception. User
agents must recognise the four values described above exactly (e.g. they
must not do case folding). The method must return a CanvasPattern
object suitably
initialised.
The image argument must be an instance of an
HTMLImageElement
or HTMLCanvasElement
. If the image is of the wrong type, the implementation must raise a
TYPE_MISMATCH_ERR
exception. If the image
argument is an HTMLImageElement
object whose complete
attribute is false, then the
implementation must raise an INVALID_STATE_ERR
exception.
Patterns must be painted so that the top left of the first image is
anchored at the origin of the coordinate space, and images are then
repeated horizontally to the left and right (if the repeat-x
string was specified) or vertically up and down (if the
repeat-y
string was specified) or in all four directions all
over the canvas (if the repeat
string was specified). The
images are not be scaled by this process; one CSS pixel of the image must
be painted on one coordinate space unit. Of course, patterns must only
actually painted where the stroking or filling effect requires that they
be drawn, and are affected by the current transformation matrix.
Support for patterns is optional. If the user agent doesn't support
patterns, then createPattern()
must return null.
The lineWidth
attribute
gives the default width of lines, in coordinate space units. On setting,
zero and negative values must be ignored, leaving the value unchanged.
When the context is created, the lineWidth
attribute must initially have the
value 1.0
.
The lineCap
attribute defines
the type of endings that UAs shall place on the end of lines. The three
valid values are butt
, round
, and
square
. The butt
value means that the end of
each line is a flat edge perpendicular to the direction of the line. The
round
value means that a semi-circle with the diameter equal
to the width of the line is then added on to the end of the line. The
square
value means that at the end of each line is a
rectangle with the length of the line width and the width of half the line
width, placed flat against the edge perpendicular to the direction of the
line. On setting, any other value than the literal strings
butt
, round
, and square
must be
ignored, leaving the value unchanged.
When the context is created, the lineCap
attribute must initially have the value
butt
.
The lineJoin
attribute
defines the type of corners that that UAs will place where two lines meet.
The three valid values are round
, bevel
, and
miter
.
On setting, any other value than the literal strings round
,
bevel
and miter
must be ignored, leaving the
value unchanged.
When the context is created, the lineJoin
attribute must initially have the
value miter
.
The round
value means that a filled arc connecting the
corners on the outside of the join, with the diameter equal to the line
width, and the origin at the point where the inside edges of the lines
touch, must be rendered at joins. The bevel
value means that
a filled triangle connecting those two corners with a straight line, the
third point of the triangle being the point where the lines touch on the
inside of the join, must be rendered at joins. The miter
value means that a filled four- or five-sided polygon must be placed at
the join, with two of the lines being the perpendicular edges of the
joining lines, and the other two being continuations of the outside edges
of the two joining lines, as long as required to intersect without going
over the miter limit.
The miter length is the distance from the point where the lines touch on the inside of the join to the intersection of the line edges on the outside of the join. The miter limit ratio is the maximum allowed ratio of the miter length to the line width. If the miter limit would be exceeded, then a fifth line must be added to the polygon, connecting the two outside lines, such that the distance from the inside point of the join to the point in the middle of this fifth line is the maximum allowed value for the miter length.
The miter limit ratio can be explicitly set using the miterLimit
attribute.
On setting, zero and negative values must be ignored, leaving the value
unchanged.
When the context is created, the miterLimit
attribute must initially have the
value 10.0
.
All drawing operations are affected by the four global shadow attributes.
The shadowColor
attribute
sets the color of the shadow.
When the context is created, the shadowColor
attribute initially must be
fully-transparent black.
On getting, the serialisation of the color must be returned.
On setting, the new value must be parsed as a CSS <color> value and the color assigned. If the value is not a valid color, then it must be ignored, and the attribute must retain its previous value. [CSS3COLOR]
The shadowOffsetX
and
shadowOffsetY
attributes specify the distance that the shadow will be offset in the
positive horizontal and positive vertical distance respectively. Their
values are in coordinate space units. They are not affected by the current
transformation matrix.
When the context is created, the shadow offset attributes initially have
the value 0
.
On getting, they must return their current value. On setting, the attribute being set must be set to the new value.
The shadowBlur
attribute
specifies the size of the blurring effect. (The units do not map to
coordinate space units, and are not affected by the current transformation
matrix.)
When the context is created, the shadowBlur
attribute must initially have the
value 0
.
On getting, the attribute must return its current value. On setting, if the value is greater than or equal to zero, then the attribute must be set to the new value; otherwise, the new value is ignored.
Support for shadows is optional. When they are supported, then, when shadows are drawn, they must be rendered as follows:
Let A be the source image for which a shadow is being created.
Let B be an infinite transparent black bitmap, with a coordinate space and an origin identical to A.
Copy the alpha channel of A to B, offset by shadowOffsetX
in the positive x direction, and shadowOffsetY
in the positive y direction.
If shadowBlur
is greater than 0:
If shadowBlur
is less than 8, let σ be half the value of shadowBlur
; otherwise, let σ be the square root of multiplying the value of
shadowBlur
by 2.
Perform a 2D Gaussian Blur on B, using σ as the standard deviation.
User agents may limit values of σ to an implementation-specific maximum value to avoid exceeding hardware limitations during the Gaussian blur operation.
Set the red, green, and blue components of every pixel in B to the red, green, and blue components (respectively)
of the color of shadowColor
.
Multiply the alpha component of every pixel in B
by the alpha component of the color of shadowColor
.
The shadow is in the bitmap B, and is rendered as part of the drawing model described below.
There are three methods that immediately draw rectangles to the bitmap. They each take four arguments; the first two give the x and y coordinates of the top left of the rectangle, and the second two give the width w and height h of the rectangle, respectively.
The current transformation matrix must be applied to the following four coordinates, which form the path that must then be closed to get the specified rectangle: (x, y), (x+w, y), (x+w, y+h), (x, y+h).
Shapes are painted without affecting the current path, and are subject
to clipping paths, and, with
the exception of clearRect()
, also shadow effects, global alpha, and global composition
operators.
Negative values for width and height must cause the implementation to
raise an INDEX_SIZE_ERR
exception.
The clearRect()
method must
clear the pixels in the specified rectangle that also intersect the
current clipping path to a fully transparent black, erasing any previous
image. If either height or width are zero, this method has no effect.
The fillRect()
method must
paint the specified rectangular area using the fillStyle
.
If either height or width are zero, this method has no effect.
The strokeRect()
method
must stroke the specified rectangle's path using the strokeStyle
, lineWidth
,
lineJoin
, and (if appropriate) miterLimit
attributes. If both height and
width are zero, this method has no effect, since there is no path to
stroke (it's a point). If only one of the two is zero, then the method
will draw a line instead (the path for the outline is just a straight line
along the non-zero dimension).
The context always has a current path. There is only one current path, it is not part of the drawing state.
A path has a list of zero or more subpaths. Each subpath consists of a list of one or more points, connected by straight or curved lines, and a flag indicating whether the subpath is closed or not. A closed subpath is one where the last point of the subpath is connected to the first point of the subpath by a straight line. Subpaths with fewer than two points are ignored when painting the path.
Initially, the context's path must have zero subpaths.
The coordinates given in the arguments to these methods must be transformed according to the current transformation matrix before applying the calculations described below and before adding any points to the path.
The beginPath()
method must
empty the list of subpaths so that the context once again has zero
subpaths.
The moveTo(x, y)
method must create a
new subpath with the specified point as its first (and only) point.
The closePath()
method must
do nothing if the context has no subpaths. Otherwise, it must mark the
last subpath as closed, create a new subpath whose first point is the same
as the previous subpath's first point, and finally add this new subpath to
the path. (If the last subpath had more than one point in its list of
points, then this is equivalent to adding a straight line connecting the
last point back to the first point, thus "closing" the shape, and then
repeating the last moveTo()
call.)
New points and the lines connecting them are added to subpaths using the methods described below. In all cases, the methods only modify the last subpath in the context's paths.
The lineTo(x, y)
method must do
nothing if the context has no subpaths. Otherwise, it must connect the
last point in the subpath to the given point (x, y) using a straight line, and must then add the given point
(x, y) to the subpath.
The quadraticCurveTo(cpx, cpy, x, y)
method must do nothing if the context has
no subpaths. Otherwise it must connect the last point in the subpath to
the given point (x, y) using a
quadratic Bézier curve with control point (cpx,
cpy), and must then add the given point (x, y) to the subpath. [BEZIER]
The bezierCurveTo(cp1x, cp1y, cp2x,
cp2y, x, y)
method must do nothing if the context has
no subpaths. Otherwise, it must connect the last point in the subpath to
the given point (x, y) using a
cubic Bézier curve with control points (cp1x,
cp1y) and (cp2x, cp2y). Then, it must add the point (x,
y) to the subpath. [BEZIER]
The arcTo(x1, y1, x2, y2, radius)
method must do
nothing if the context has no subpaths. If the context does have
a subpath, then the behaviour depends on the arguments and the last point
in the subpath.
Let the point (x0, y0) be the last point in the subpath. Let The Arc be the shortest arc given by circumference of the circle that has one point tangent to the line defined by the points (x0, y0) and (x1, y1), another point tangent to the line defined by the points (x1, y1) and (x2, y2), and that has radius radius. The points at which this circle touches these two lines are called the start and end tangent points respectively.
If the point (x2, y2) is on the line defined by the points (x0, y0) and (x1, y1) then the method must do nothing, as no arc would satisfy the above constraints.
Otherwise, the method must connect the point (x0, y0) to the start tangent point by a straight line, then connect the start tangent point to the end tangent point by The Arc, and finally add the start and end tangent points to the subpath.
Negative or zero values for radius must cause the
implementation to raise an INDEX_SIZE_ERR
exception.
The arc(x, y, radius, startAngle, endAngle, anticlockwise)
method draws an arc. If the
context has any subpaths, then the method must add a straight line from
the last point in the subpath to the start point of the arc. In any case,
it must draw the arc between the start point of the arc and the end point
of the arc, and add the start and end points of the arc to the subpath.
The arc and its start and end points are defined as follows:
Consider a circle that has its origin at (x, y) and that has radius radius. The points at startAngle and endAngle along the circle's circumference, measured in radians clockwise from the positive x-axis, are the start and end points respectively. The arc is the path along the circumference of this circle from the start point to the end point, going anti-clockwise if the anticlockwise argument is true, and clockwise otherwise.
Negative or zero values for radius must cause the
implementation to raise an INDEX_SIZE_ERR
exception.
The rect(x, y, w, h)
method must create a new subpath containing
just the four points (x, y), (x+w, y), (x+w, y+h), (x, y+h), with those four points connected by straight lines, and
must then mark the subpath as closed. It must then create a new subpath
with the point (x, y) as the only
point in the subpath.
Negative values for w and h must
cause the implementation to raise an INDEX_SIZE_ERR
exception.
The fill()
method must fill each subpath of the current path in turn, using fillStyle
,
and using the non-zero winding number rule. Open subpaths must be
implicitly closed when being filled (without affecting the actual
subpaths).
The stroke()
method must stroke
each subpath of the current path in turn, using the strokeStyle
, lineWidth
,
lineJoin
, and (if appropriate) miterLimit
attributes.
Paths, when filled or stroked, must be painted without affecting the current path, and must be subject to transformations, shadow effects, global alpha, clipping paths, and global composition operators.
The transformation is applied to the path when it is drawn, not when the path is constructed. Thus, a single path can be constructed and then drawn according to different transformations without recreating the path.
The clip()
method must create a new clipping path by
calculating the intersection of the current clipping path and the area
described by the current path, using the non-zero winding number rule.
Open subpaths must be implicitly closed when computing the clipping path,
without affecting the actual subpaths.
When the context is created, the initial clipping path is the rectangle with the top left corner at (0,0) and the width and height of the coordinate space.
The isPointInPath(x, y)
method must return
true if the point given by the x and y coordinates passed to the method, when treated as
coordinates in the canvas' coordinate space unaffected by the current
transformation, is within the area of the canvas that would be filled if
the current path was to be filled; and must return false otherwise.
To draw images onto the canvas, the drawImage
method can be
used.
This method is overloaded with three variants: drawImage(image, dx, dy)
, drawImage(image, dx, dy, dw, dh)
, and drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh)
. (Actually it is overloaded with six; each of
those three can take either an HTMLImageElement
or an HTMLCanvasElement
for the image argument.) If not specified, the dw and dh arguments default to the
values of sw and sh, interpreted
such that one CSS pixel in the image is treated as one unit in the canvas
coordinate space. If the sx, sy,
sw, and sh arguments are omitted,
they default to 0, 0, the image's intrinsic width in image pixels, and the
image's intrinsic height in image pixels, respectively.
The image argument must be an instance of an
HTMLImageElement
or HTMLCanvasElement
. If the image is of the wrong type, the implementation must raise a
TYPE_MISMATCH_ERR
exception. If one of the sy, sw, sw, and
sh arguments is outside the size of the image, or if
one of the dw and dh arguments is
negative, the implementation must raise an INDEX_SIZE_ERR
exception. If the image argument is an HTMLImageElement
object whose complete
attribute is false, then the
implementation must raise an INVALID_STATE_ERR
exception.
When drawImage()
is invoked, the specified region
of the image specified by the source rectangle (sx,
sy, sw, sh)
must be painted on the region of the canvas specified by the destination
rectangle (dx, dy, dw, dh), after applying the current
transformation matrix.
When a canvas is drawn onto itself, the drawing model requires the source to be copied before the image is drawn back onto the canvas, so it is possible to copy parts of a canvas onto overlapping parts of itself.
Images are painted without affecting the current path, and are subject to shadow effects, global alpha, clipping paths, and global composition operators.
The getImageData(sx, sy, sw, sh)
method must return an ImageData
object representing the underlying
pixel data for the area of the canvas denoted by the rectangle which has
its top left corner at the (sx, sy) coordinate, and that has width sw
and height sh. Pixels outside the canvas must be
returned as transparent black. Pixels must be returned as
non-premultiplied alpha values.
ImageData
objects must be
initialised so that their width
attribute is set to
w, the number of physical device pixels per row in the
image data, their height
attribute is set to
h, the number of rows in the image data, and the data
attribute is
initialised to an array of h×w×4 integers. The pixels must be represented in this
array in left-to-right order, row by row, starting at the top left, with
each pixel's red, green, blue, and alpha components being given in that
order. Each component of each device pixel represented in this array must
be in the range 0..255, representing the 8 bit value for that component.
At least one pixel must be returned.
The values of the data
array may be changed (the length of the
array, and the other attributes in ImageData
objects, are all read-only). On
setting, JS undefined
values must be converted to zero. Other
values must first be converted to numbers using JavaScript's ToNumber
algorithm, and if the result is not a number, a
TYPE_MISMATCH_ERR
exception must be raised. If the result is
less than 0, it must be clamped to zero. If the result is more than 255,
it must be clamped to 255. If the number is not an integer, it must be
rounded to the nearest integer using the IEEE 754r roundTiesToEven
rounding mode. [ECMA262] [IEEE754R]
The width and height (w and h) might be different from the sw and sh arguments to the function, e.g. if the canvas is backed by a high-resolution bitmap.
If the getImageData(sx, sy, sw, sh)
method is called with either the sw or sh arguments set to zero or
negative values, the method must raise an INDEX_SIZE_ERR
exception.
The putImageData(imagedata, dx, dy)
method must take the given ImageData
structure, and place it at the
specified location (dx, dy) in the
canvas coordinate space, mapping each pixel represented by the ImageData
structure into one device pixel.
If the first argument to the method is not an object whose [[Class]]
property is ImageData
, but all of
the following conditions are true, then the method must treat the first
argument as if it was an ImageData
object (and thus not raise the TYPE_MISMATCH_ERR
exception):
width
and height
attributes with integer values and a data
attribute whose value is an enumerable list
of values that are either JS Numbers or the JS value
undefined
.
ImageData
object's width
is greater
than zero.
ImageData
object's height
is
greater than zero.
ImageData
object's width
multiplied
by its height
multiplied by 4 is equal to the number
of entries in the ImageData
object's data
property.
In the data
property, undefined values must be treated as zero, any numbers below zero
must be clamped to zero, any numbers above 255 must be clamped to 255, and
any numbers that are not integers must be rounded to the nearest integer
using the IEEE 754r roundTiesToEven rounding mode. [IEEE754R]
The handling of pixel rounding when the specified coordinates do not exactly map to the device coordinate space is not defined by this specification, except that the following must result in no visible changes to the rendering:
context.putImageData(context.getImageData(x, y, w, h), x, y);
...for any value of x and y. In
other words, while user agents may round the arguments of the two methods
so that they map to device pixel boundaries, any rounding performed must
be performed consistently for both the getImageData()
and putImageData()
operations.
The current path, transformation matrix, shadow attributes, global alpha, clipping path, and global composition
operator must not affect the getImageData()
and putImageData()
methods.
The data returned by getImageData()
is at the resolution of
the canvas backing store, which is likely to not be one device pixel to
each CSS pixel if the display used is a high resolution display. Thus,
while one could create an ImageData
object, one would not necessarily know what resolution the canvas
expected (how many pixels the canvas wants to paint over one coordinate
space unit pixel).
In the following example, the script first obtains the size of the
canvas backing store, and then generates a few new ImageData
objects which can be used.
// canvas is a reference to a <canvas> element // (note: this example uses JavaScript 1.7 features) var context = canvas.getContext('2d'); var backingStore = context.getImageData(0, 0, canvas.width, canvas.height); var actualWidth = backingStore.width; var actualHeight = backingStore.height; function CreateImageData(w, h) { return { height: h, width: w, data: [i for (i in function (n) { for (let i = 0; i < n; i += 1) yield 0 }(w*h*4)) ] }; } // create a blank slate var data = CreateImageData(actualWidth, actualHeight); // create some plasma FillPlasma(data, 'green'); // green plasma // add a cloud to the plasma AddCloud(data, actualWidth/2, actualHeight/2); // put a cloud in the middle // paint the plasma+cloud on the canvas context.putImageData(data, 0, 0); // support methods function FillPlasma(data, color) { ... } function AddCload(data, x, y) { ... }
Here is an example of using getImageData()
and putImageData()
to implement an edge
detection filter.
<!DOCTYPE HTML> <html> <head> <title>Edge detection demo</title> <script> var image = new Image(); function init() { image.onload = demo; image.src = "image.jpeg"; } function demo() { var canvas = document.getElementsByTagName('canvas')[0]; var context = canvas.getContext('2d'); // draw the image onto the canvas context.drawImage(image, 0, 0); // get the image data to manipulate var input = context.getImageData(0, 0, canvas.width, canvas.height); // edge detection // notice that we are using input.width and input.height here // as they might not be the same as canvas.width and canvas.height // (in particular, they might be different on high-res displays) var w = input.width, h = input.height; var inputData = input.data; var outputData = new Array(w*h*4); for (var y = 1; y < h-1; y += 1) { for (var x = 1; x < w-1; x += 1) { for (var c = 0; c < 3; c += 1) { var i = (y*w + x)*4 + c; outputData[i] = 127 + -inputData[i - w*4 - 4] - inputData[i - w*4] - inputData[i - w*4 + 4] + -inputData[i - 4] + 8*inputData[i] - inputData[i + 4] + -inputData[i + w*4 - 4] - inputData[i + w*4] - inputData[i + w*4 + 4]; } outputData[(y*w + x)*4 + 3] = 255; // alpha } } // put the image data back after manipulation var output = { width: w, height: h, data: outputData }; context.putImageData(output, 0, 0); } </script> </head> <body onload="init()"> <canvas></canvas> </body> </html>
When a shape or image is painted, user agents must follow these steps, in the order given (or act as if they do):
Render the shape or image, creating image A, as described in the previous sections. For shapes, the current fill, stroke, and line styles must be honoured, and the stroke must itself also be subjected to the current transformation matrix.
If shadows are supported:
Render the shadow from image A, using the current shadow styles, creating image B.
Multiply the alpha component of every pixel in B
by globalAlpha
.
Within the clipping path, composite B over the current canvas bitmap using the current composition operator.
Multiply the alpha component of every pixel in A
by globalAlpha
.
Within the clipping path, composite A over the current canvas bitmap using the current composition operator.
The canvas
APIs must perform colour
correction at only two points: when rendering images with their own gamma
correction information onto the canvas, to convert the image to the color
space used by the canvas (e.g. using the drawImage()
method with an HTMLImageElement
object), and when
rendering the actual canvas bitmap to the output device.
Thus, in the 2D context, colors used to draw shapes onto the canvas will
exactly match colors obtained through the getImageData()
method.
The toDataURL()
method must not include color
space information in the resource returned.
In user agents that support CSS, the color space used by a canvas
element must match the color space used
for processing any colors for that element in CSS.
map
elementid
global
attribute has special requirements on this element.
interface HTMLMapElement : HTMLElement { readonly attribute HTMLCollection areas; readonly attribute HTMLCollection images; };
The map
element, in conjuction with any
area
element descendants, defines an image map.
There must always be an id
attribute present on map
elements.
The areas
attribute
must return an HTMLCollection
rooted at the map
element, whose filter
matches only area
elements.
The images
attribute must return an HTMLCollection
rooted at the
Document
node, whose filter matches only img
and object
elements that are associated with this map
element according to the image map processing model.
area
elementmap
element ancestor.
alt
coords
shape
href
target
ping
rel
media
hreflang
type
interface HTMLAreaElement : HTMLElement { attribute DOMString alt; attribute DOMString coords; attribute DOMString shape; attribute DOMString href; attribute DOMString target; attribute DOMString ping; attribute DOMString rel; readonly attribute DOMTokenList relList; attribute DOMString media; attribute DOMString hreflang; attribute DOMString type; };
The area
element represents either a
hyperlink with some text and a corresponding area on an image map, or a dead area on an image map.
If the area
element has an href
attribute, then
the area
element represents a hyperlink; the alt
attribute, which must then be
present, specifies the text.
However, if the area
element has no
href
attribute, then the area represented by the element cannot be selected,
and the alt
attribute
must be omitted.
In both cases, the shape
and coords
attributes specify the area.
The shape
attribute is an enumerated attribute. The
following table lists the keywords defined for this attribute. The states
given in the first cell of the the rows with keywords give the states to
which those keywords map. Some of the keywords are non-conforming, as
noted in the last column.
| State | Keywords | Notes |
|---|---|---|
| Circle state | circ
| Non-conforming |
circle
| ||
| Default state | default
| |
| Polygon state | poly
| |
polygon
| Non-conforming | |
| Rectangle state | rect
| |
rectangle
| Non-conforming |
The attribute may be ommited. The missing value default is the rectangle state.
The coords
attribute must, if specified, contain a valid list of
integers. This attribute gives the coordinates for the shape described
by the shape
attribute. The processing for this attribute is described as part of the
image map processing model.
In the circle state,
area
elements must have a coords
attribute
present, with three integers, the last of which must be non-negative. The
first integer must be the distance in CSS pixels from the left edge of the
image to the center of the circle, the second integer must be the distance
in CSS pixels from the top edge of the image to the center of the circle,
and the third integer must be the radius of the circle, again in CSS
pixels.
In the default
state state, area
elements must not
have a coords
attribute.
In the polygon state,
area
elements must have a coords
attribute with
at least six integers, and the number of integers must be even. Each pair
of integers must represent a coordinate given as the distances from the
left and the top of the image in CSS pixels respectively, and all the
coordinates together must represent the points of the polygon, in order.
In the rectangle
state, area
elements must have a
coords
attribute
with exactly four integers, the first of which must be less than the
third, and the second of which must be less than the fourth. The four
points must represent, respectively, the distance from the left edge of
the image to the top left side of the rectangle, the distance from the top
edge to the top side, the distance from the left edge to the right side,
and the distance from the top edge to the bottom side, all in CSS pixels.
When user agents allow users to follow hyperlinks created using the area
element, as described in the next section,
the href
,
target
and
ping
attributes
decide how the link is followed. The rel
, media
, hreflang
, and type
attributes may
be used to indicate to the user the likely nature of the target resource
before the user follows the link.
The target
, ping
, rel
, media
, hreflang
, and type
attributes
must be omitted if the href
attribute is not present.
The activation behavior of area
elements is to run the following steps:
DOMActivate
event in
question is not trusted (i.e. a
click()
method call was
the reason for the event being dispatched), and the area
element's target
attribute is ... then raise an INVALID_ACCESS_ERR
exception.
area
element, if any.
One way that a user agent can enable users to follow
hyperlinks is by allowing area
elements
to be clicked, or focussed and activated by the keyboard. This will cause the aforementioned activation behavior to be invoked.
The DOM attributes alt
, coords
, shape
, href
, target
, ping
, rel
, media
, hreflang
, and type
, each must reflect the respective content attributes of the same
name.
The DOM attribute relList
must reflect the rel
content attribute.
An image map allows geometric areas on an image to be associated with hyperlinks.
An image, in the form of an img
element
or an object
element representing an
image, may be associated with an image map (in the form of a map
element) by specifying a usemap
attribute on the
img
or object
element. The usemap
attribute, if specified, must be a valid hashed ID reference to a map
element.
If an img
element or an object
element representing an image has a usemap
attribute specified, user agents must
process it as follows:
First, rules for parsing a hashed ID reference
to a map
element must be followed. This
will return either an element (the map) or null.
If that returned null, then abort these steps. The image is not associated with an image map after all.
Otherwise, the user agent must collect all the area
elements that are descendants of the map. Let those be the areas.
Having obtained the list of area
elements that form the image map (the areas),
interactive user agents must process the list in one of two ways.
If the user agent intends to show the text that the img
element represents, then it must use the
following steps.
In user agents that do not support images, or that have
images disabled, object
elements cannot
represent images, and thus this section never applies (the fallback content is shown instead). The following
steps therefore only apply to img
elements.
Remove all the area
elements in areas that have no href
attribute.
Remove all the area
elements in areas that have no alt
attribute, or whose alt
attribute's value is
the empty string, if there is another area
element in areas with
the same value in the href
attribute and with a non-empty alt
attribute.
Each remaining area
element in areas represents a hyperlink.
Those hyperlinks should all be made available to the user in a manner
associated with the text of the img
or
input
element.
In this context, user agents may represent area
and img
elements with no specified alt
attributes, or
whose alt
attributes are the empty string or some
other non-visible text, in a user-agent-defined fashion intended to
indicate the lack of suitable author-provided text.
If the user agent intends to show the image and allow interaction with
the image to select hyperlinks, then the image must be associated with a
set of layered shapes, taken from the area
elements in areas, in
reverse tree order (so the last specified area
element in the map is the
bottom-most shape, and the first element in the map,
in tree order, is the top-most shape).
Each area
element in areas must be processed as follows to obtain a shape to
layer onto the image:
Find the state that the element's shape
attribute represents.
Use the rules for parsing a list of integers to
parse the element's coords
attribute, if it is present, and let
the result be the coords list. If the attribute is
absent, let the coords list be the empty list.
If the number of items in the coords list is less
than the minimum number given for the area
element's current state, as per the
following table, then the shape is empty; abort these steps.
| State | Minimum number of items |
|---|---|
| Circle state | 3 |
| Default state | 0 |
| Polygon state | 6 |
| Rectangle state | 4 |
Check for excess items in the coords list as per
the entry in the following list corresponding to the shape
attribute's
state:
If the shape
attribute represents the rectangle state, and the first number in
the list is numerically less than the third number in the list, then
swap those two numbers around.
If the shape
attribute represents the rectangle state, and the second number in
the list is numerically less than the fourth number in the list, then
swap those two numbers around.
If the shape
attribute represents the circle state, and the third number in
the list is less than or equal to zero, then the shape is empty; abort
these steps.
Now, the shape represented by the element is the one described for the
entry in the list below corresponding to the state of the shape
attribute:
Let x be the first number in coords, y be the second number, and r be the third number.
The shape is a circle whose center is x CSS pixels from the left edge of the image and x CSS pixels from the top edge of the image, and whose radius is r pixels.
The shape is a rectangle that exactly covers the entire image.
Let xi be the (2i)th entry in coords, and yi be the (2i+1)th entry in coords (the first entry in coords being the one with index 0).
Let the coordinates be (xi, yi), interpreted in CSS pixels measured from the top left of the image, for all integer values of i from 0 to (N/2)-1, where N is the number of items in coords.
The shape is a polygon whose vertices are given by the coordinates, and whose interior is established using the even-odd rule. [GRAPHICS]
Let x1 be the first number in coords, y1 be the second number, x2 be the third number, and y2 be the fourth number.
The shape is a rectangle whose top-left corner is given by the coordinate (x1, y1) and whose bottom right corner is given by the coordinate (x2, y2), those coordinates being interpreted as CSS pixels from the top left corner of the image.
For historical reasons, the coordinates must be interpreted relative
to the displayed image, even if it stretched using CSS or the
image element's width
and height
attributes.
Mouse clicks on an image associated with a set of layered shapes per the
above algorithm must be dispatched to the top-most shape covering the
point that the pointing device indicated (if any), and then, must be
dispatched again (with a new Event
object) to the image
element itself. User agents may also allow individual area
elements representing hyperlinks to be selected and activated (e.g. using a
keyboard); events from this are not also propagated to the image.
Because a map
element (and
its area
elements) can be associated with
multiple img
and object
elements, it is possible for an area
element to correspond to multiple focusable
areas of the document.
Image maps are live; if the DOM is mutated, then the user agent must act as if it had rerun the algorithms for image maps.
The width
and
height
attributes
on img
, embed
, object
,
and video
elements may be specified to
give the dimensions of the visual content of the element (the width and
height respectively, relative to the nominal direction of the output
medium), in CSS pixels. The attributes, if specified, must have values
that are valid positive non-zero integers.
The specified dimensions given may differ from the dimensions specified in the resource itself, since the resource may have a resolution that differs from the CSS pixel resolution. (On screens, CSS pixels have a resolution of 96ppi, but in general the CSS pixel resolution depends on the reading distance.) If both attributes are specified, then the ratio of the specified width to the specified height must be the same as the ratio of the logical width to the logical height in the resource. The two attributes must be omitted if the resource in question does not have both a logical width and a logical height.
To parse the attributes, user agents must use the rules for parsing dimension values. This will return either an integer length, a percentage value, or nothing. The user agent requirements for processing the values obtained from parsing these attributes are described in the rendering section. If one of these attributes, when parsing, returns no value, it must be treated, for the purposes of those requirements, as if it was not specified.
The width
and height
DOM attributes
on the embed
, object
, and video
elements must reflect the content
attributes of the same name.
table
elementcaption
element, followed by either zero or
more colgroup
elements, followed
optionally by a thead
element,
followed optionally by a tfoot
element, followed by either zero or more tbody
elements or one or more tr
elements, followed optionally by a tfoot
element (but there can only be one
tfoot
element child in total).
interface HTMLTableElement : HTMLElement {
attribute HTMLTableCaptionElement caption;
HTMLElement createCaption();
void deleteCaption();
attribute HTMLTableSectionElement tHead;
HTMLElement createTHead();
void deleteTHead();
attribute HTMLTableSectionElement tFoot;
HTMLElement createTFoot();
void deleteTFoot();
readonly attribute HTMLCollection tBodies;
readonly attribute HTMLCollection rows;
HTMLElement insertRow(in long index);
void deleteRow(in long index);
};
The table
element represents data with
more than one dimension (a table).
we need some editorial text on how layout tables are bad practice and non-conforming
The children of a table
element must
be, in order:
Zero or one caption
elements.
Zero or more colgroup
elements.
Zero or one thead
elements.
Zero or one tfoot
elements, if the
last element in the table is not a tfoot
element.
Either:
Zero or one tfoot
element, if there
are no other tfoot
elements in the
table.
The table
element takes part in the table model.
The caption
DOM attribute must return, on getting, the first caption
element child of the table
element. On setting, if the new value is a
caption
element, the first caption
element child of the table
element, if any, must be removed, and the
new value must be inserted as the first node of the table
element. If the new value is not a caption
element, then a
HIERARCHY_REQUEST_ERR
DOM exception must be raised instead.
The createCaption()
method
must return the first caption
element
child of the table
element, if any;
otherwise a new caption
element must
be created, inserted as the first node of the table
element, and then returned.
The deleteCaption()
method
must remove the first caption
element
child of the table
element, if any.
The tHead
DOM
attribute must return, on getting, the first thead
element child of the table
element. On setting, if the new value is a
thead
element, the first thead
element child of the table
element, if any, must be removed, and the
new value must be inserted immediately before the first element in the
table
element that is neither a caption
element nor a colgroup
element, if any, or at the end of the
table otherwise. If the new value is not a thead
element, then a
HIERARCHY_REQUEST_ERR
DOM exception must be raised instead.
The createTHead()
method must
return the first thead
element child of
the table
element, if any; otherwise a
new thead
element must be created and
inserted immediately before the first element in the table
element that is neither a caption
element nor a colgroup
element, if any, or at the end of the
table otherwise, and then that new element must be returned.
The deleteTHead()
method must
remove the first thead
element child of
the table
element, if any.
The tFoot
DOM
attribute must return, on getting, the first tfoot
element child of the table
element. On setting, if the new value is a
tfoot
element, the first tfoot
element child of the table
element, if any, must be removed, and the
new value must be inserted immediately before the first element in the
table
element that is neither a caption
element, a colgroup
element, nor a thead
element, if any, or at the end of the
table if there are no such elements. If the new value is not a tfoot
element, then a
HIERARCHY_REQUEST_ERR
DOM exception must be raised instead.
The createTFoot()
method must
return the first tfoot
element child of
the table
element, if any; otherwise a
new tfoot
element must be created and
inserted immediately before the first element in the table
element that is neither a caption
element, a colgroup
element, nor a thead
element, if any, or at the end of the
table if there are no such elements, and then that new element must be
returned.
The deleteTFoot()
method must
remove the first tfoot
element child of
the table
element, if any.
The tBodies
attribute must return an HTMLCollection
rooted at the table
node, whose filter matches only tbody
elements that are children of the table
element.
The rows
attribute
must return an HTMLCollection
rooted at the table
node, whose filter
matches only tr
elements that are either
children of the table
element, or
children of thead
, tbody
, or tfoot
elements that are themselves children of
the table
element. The elements in the
collection must be ordered such that those elements whose parent is a
thead
are included first, in tree
order, followed by those elements whose parent is either a table
or tbody
element, again in tree order, followed finally by those elements whose
parent is a tfoot
element, still in
tree order.
The behaviour of the insertRow(index)
method depends on the state of the
table. When it is called, the method must act as required by the first
item in the following list of conditions that describes the state of the
table and the index argument:
rows
collection:
INDEX_SIZE_ERR
exception.
rows
collection has zero elements in it, and the table
has no tbody
elements in it:
tbody
element, then create a tr
element, then
append the tr
element to the tbody
element, then append the tbody
element to the table
element, and finally return the tr
element.
rows
collection has zero elements in it:
tr
element,
append it to the last tbody
element in
the table, and return the tr
element.
rows
collection:
tr
element,
and append it to the parent of the last tr
element in the rows
collection. Then, the newly created tr
element must be returned.
tr
element,
insert it immediately before the indexth tr
element in the rows
collection, in the same parent, and finally
must return the newly created tr
element.
The deleteRow(index)
method must remove the indexth element in the rows
collection from its parent. If index is less than zero or greater than or equal to the
number of elements in the rows
collection, the method must instead raise an
INDEX_SIZE_ERR
exception.
caption
elementtable
element.
HTMLElement
.
The caption
element represents the
title of the table
that is its parent,
if it has a parent and that is a table
element.
The caption
element takes part in
the table model.
colgroup
elementtable
element, after
any caption
elements and before any
thead
, tbody
, tfoot
,
and tr
elements.
col
elements.
span
interface HTMLTableColElement : HTMLElement { attribute unsigned long span; };
The colgroup
element represents a
group of one or more columns in the table
that is its parent, if it has a parent and
that is a table
element.
If the colgroup
element contains no
col
elements, then the element may have a
span
content
attribute specified, whose value must be a valid
non-negative integer greater than zero. Its default value, which must
be used if parsing the attribute as a non-negative integer returns
either an error or zero, is 1.
The colgroup
element and its span
attribute take
part in the table model.
The span
DOM
attribute must reflect the content attribute of the
same name, with the exception that on setting, if the new value is 0, then
an INDEX_SIZE_ERR
exception must be raised.
col
elementcolgroup
element
that doesn't have a span
attribute.
span
HTMLTableColElement
,
same as for colgroup
elements. This
interface defines one member, span
.
If a col
element has a parent and that
is a colgroup
element that itself has
a parent that is a table
element, then
the col
element represents one or more columns in the column group represented by that colgroup
.
The element may have a span
content attribute specified,
whose value must be a valid non-negative integer
greater than zero. Its default value, which must be used if parsing the
attribute as a non-negative integer returns either an error or zero,
is 1.
The col
element and its span
attribute take part
in the table model.
The span
DOM
attribute must reflect the content attribute of the
same name, with the exception that on setting, if the new value is 0, then
an INDEX_SIZE_ERR
exception must be raised.
tbody
elementtable
element, after
any caption
, colgroup
, and thead
elements, but only if there are no
tr
elements that are children of the
table
element.
tr
elements
interface HTMLTableSectionElement : HTMLElement { readonly attribute HTMLCollection rows; HTMLElement insertRow(in long index); void deleteRow(in long index); };
The HTMLTableSectionElement
interface is also used for thead
and
tfoot
elements.
The tbody
element represents a block of rows that consist of a body of data for the parent
table
element, if the tbody
element has a parent and it is a table
.
The tbody
element takes part in the table model.
The rows
attribute
must return an HTMLCollection
rooted at the element, whose filter matches only tr
elements that are children of the element.
The insertRow(index)
method must, when invoked on an element
table section, act as follows:
If index is less than -1 or greater than the number
of elements in the rows
collection, the method must raise an
INDEX_SIZE_ERR
exception.
If index is equal to -1 or equal to the number of
items in the rows
collection, the method must create a tr
element, append it to the element table section, and
return the newly created tr
element.
Otherwise, the method must create a tr
element, insert it as a child of the table section
element, immediately before the indexth tr
element in the rows
collection, and finally must return the
newly created tr
element.
The deleteRow(index)
method must remove the indexth element in the rows
collection from its parent. If index is less than zero or greater than or equal to the
number of elements in the rows
collection, the method must instead raise an
INDEX_SIZE_ERR
exception.
thead
elementtable
element, after
any caption
, and colgroup
elements and before any tbody
, tfoot
,
and tr
elements, but only if there are no
other thead
elements that are children
of the table
element.
tr
elements
HTMLTableSectionElement
, as
defined for tbody
elements.
The thead
element represents the block of rows that consist of the column labels (headers) for
the parent table
element, if the
thead
element has a parent and it is a
table
.
The thead
element takes part in the
table model.
tfoot
elementtable
element, after
any caption
, colgroup
, and thead
elements and before any tbody
and tr
elements, but only if there are no other tfoot
elements that are children of the
table
element.
table
element, after
any caption
, colgroup
, thead
, tbody
,
and tr
elements, but only if there are no
other tfoot
elements that are children
of the table
element.
tr
elements
HTMLTableSectionElement
, as
defined for tbody
elements.
The tfoot
element represents the block of rows that consist of the column summaries (footers)
for the parent table
element, if the
tfoot
element has a parent and it is a
table
.
The tfoot
element takes part in the
table model.
tr
elementthead
element.
tbody
element.
tfoot
element.
table
element, after
any caption
, colgroup
, and thead
elements, but only if there are no
tbody
elements that are children of the
table
element.
td
or th
elements
interface HTMLTableRowElement : HTMLElement {
readonly attribute long rowIndex;