19.1 Introduction

Because the Web is a dynamic medium, SVG supports the
ability to change vector graphics over time. SVG content can be
animated in the following ways:

Using SVG's
animation elements. SVG document fragments can describe
time-based modifications to the document's elements. Using
the various animation elements, you can define motion paths,
fade-in or fade-out effects, and objects that grow, shrink,
spin or change color.

Using the SVG DOM. The SVG DOM
conforms to key aspects of the "Document Object Model (DOM)
Level 1" [DOM1] and
"Document Object Model (DOM) Level 2" [DOM2]
specifications. Every attribute and style sheet setting is
accessible to scripting, and SVG offers a set of additional
DOM interfaces to support efficient animation via scripting.
As a result, virtually any kind of animation can be achieved.
The timer facilities in scripting languages such as
ECMAScript can be used to start up and control the
animations. (See example
below.)

SVG has been designed to allow future versions of SMIL
[SMIL1] to use
animated or static SVG content as media components.

In the future, it is expected that future versions of
SMIL will be modularized and that components of it could be
used in conjunction with SVG and other XML grammars to
achieve animation effects.

19.2 Animation elements

19.2.1 Overview

SVG's animation elements were developed in collaboration
with the W3C Synchronized Multimedia (SYMM) Working Group,
developers of the Synchronized Multimedia Integration Language
(SMIL) 1.0 Specification [SMIL1].

The SYMM Working Group, in collaboration with the SVG
Working Group, has authored the SMIL Animation specification [
SMILANIM], which represents a general-purpose XML animation
feature set. SVG incorporates the animation features defined in
the SMIL Animation specification and provides some SVG-specific
extensions.

19.2.2 Relationship to SMIL Animation

SVG is a host language in terms of SMIL Animation and
therefore introduces additional constraints and features as
permitted by that specification. Except for any SVG-specific
rules explicitly mentioned in this specification, the normative
definition for SVG's animation elements and attributes is the
SMIL Animation [
SMILANIM] specification.

SVG supports the following four animation elements which are
defined in the SMIL Animation specification:

SVG allows any feature from SVG's path data syntax to be
specified in a path attribute to the 'animateMotion' element
(SMIL Animation only allows a subset of SVG's path data
syntax within a path
attribute)

SVG adds a rotate attribute to the 'animateMotion' to control
whether an object is automatically rotated so that its
x-axis points in the same direction (or opposite direction)
as the directional tangent vector of the motion path

For compatibility with other aspects of the language, SVG
uses URI references via
an xlink:href attribute to identify
the elements which are to be targets of the animations.

SMIL Animation requires that the host language define the
meaning for document begin and the
document end. Since an
'svg' is sometimes the root of the XML document tree
and other times can be a component of a parent XML grammar, the
document begin for a given SVG document fragment is
defined to be the exact time at which the
'svg' element's SVGLoad event is
triggered. The document end of an SVG document
fragment is the point at which the document fragment has been
released and is no longer being processed by the user agent.
However, nested 'svg' elements within an SVG
document do not constitute document fragments in this sense,
and do not define a separate document begin; all times within
the nested SVG fragment are relative to the document time
defined for the root 'svg' element.

For SVG, the term presentation
time indicates the position in the timeline relative
to the document begin of a given document
fragment.

SVG defines more constrained error processing than is
defined in the SMIL Animation [
SMILANIM] specification. SMIL Animation defines error
processing behavior where the document continues to run in
certain error situations, whereas all animations within an SVG
document fragment will stop in the event of any error within
the document (see Error
processing).

19.2.3 Animation elements example

Example anim01 below
demonstrates each of SVG's five animation elements.

A URI
reference to the element which is the target of this
animation and which therefore will be modified over
time.
The target element must be part of the current
SVG document fragment.
<uri> must point to exactly one target element which
is capable of being the target of the given animation. If
<uri> points to multiple target elements, if the
given target element is not capable of being a target of
the given animation, or if the given target element is not
part of the current SVG document fragment, then the
document is in error (see Error
processing).
If the xlink:href attribute
is not provided, then the target element will be the
immediate parent element of the current animation
element.
Refer to the descriptions of the individual animation
elements for any restrictions on what types of elements can
be targets of particular types of animations.
Except for any SVG-specific rules explicitly mentioned in
this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: Specifying the animation target.

19.2.5 Attributes to identify the target attribute or
property for an animation

The following attributes identify the target attribute or
property for the given
target element whose value changes over time.

Specifies the name of the target attribute. An XMLNS
prefix may be used to indicate the XML namespace for the
attribute. The prefix will be interpreted in the scope of
the current (i.e., the referencing) animation
element.
Except for any SVG-specific rules explicitly mentioned in
this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: Specifying the animation target.

attributeType = "CSS |
XML | auto"

Specifies the namespace in which the target attribute and
its associated values are defined. The attribute value is
one of the following (values are case-sensitive):

"CSS"

This specifies that the value of "attributeName" is
the name of a CSS property defined as animatable in
this specification.

"XML"

This specifies that the value of "attributeName" is
the name of an XML attribute defined in the default XML
namespace for the target element. If the value for
attributeName has an XMLNS prefix, the
implementation must use the associated namespace as
defined in the scope of the target element. The
attribute must be defined as animatable in this
specification.

"auto"

The implementation should match the
attributeName to an attribute for the target
element. The implementation must first search through
the list of CSS properties for a matching property
name, and if none is found, search the default XML
namespace for the element.

19.2.6 Attributes to control the timing of the
animation

The following attributes are common to all animation
elements and control the timing of the animation, including
what causes the animation to start and end, whether the
animation runs repeatedly, and whether to retain the end state
the animation once the animation ends.

For SMIL Animation, this describes the element
begin as an offset from an implicit syncbase. For SVG,
the implicit syncbase begin is defined to be relative
to the document begin. SInce the document end in SVG is
always undetermined, a negative offset value in SVG is
always an error.

Describes a syncbase
and an optional offset from that syncbase. The element
begin is defined relative to the begin or active end of
another animation. A
syncbase consists of an ID reference to another
animation element followed by either begin
or end to identify whether to synchronize
with the beginning or active end of the referenced
animation element.

Describes an event and an optional offset that
determine the element begin. The animation begin is
defined relative to the time that the event is raised.
The list of event-symbols available for a given
event-base element is the list of event attributes
available for the given element as defined by the SVG DTD, with the one difference
that the leading 'on' is removed from the event name
(i.e., the animation event name is 'click', not
'onclick'). A list of all events supported by SVG can
be found in Complete
list of supported events. Details of event-based
timing are described in
SMIL Animation: Unifying Event-based and Scheduled
Timing.

Except for any SVG-specific rules explicitly mentioned in
this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'begin' attribute.

Specifies the length of the simple duration in presentation time. Value
must be greater than 0.

"media"

Specifies the simple duration as the intrinsic
media duration. This is only valid for elements that
define media.
(For SVG's
animation elements, if
"media" is specified, the attribute will be
ignored.)

"indefinite"

Specifies the simple duration as indefinite.

If the animation does not have a
dur attribute, the simple duration is indefinite.
Note that interpolation will not work if the simple
duration is indefinite (although this may still be useful
for 'set' elements). Except
for any SVG-specific rules explicitly mentioned in this
specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'dur' attribute.

A value of "indefinite"
specifies that the end of the animation will be
determined by a "endElement()" method call (the animation
DOM methods are described in DOM
interfaces).
Except for any SVG-specific rules explicitly mentioned
in this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
description of
SMIL Animation: 'end' attribute.

Specifies the length of the minimum value of the
active duration, measured in local time.
Value must be greater than 0.

"media"

Specifies the minimum value of the active duration
as the intrinsic media duration. This is only valid for
elements that define media. (For SVG's animation
elements, if
"media" is specified, the attribute will be
ignored.)

The default value for min
is "0". This does not constrain the active duration at
all.
Except for any SVG-specific rules explicitly mentioned
in this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'min' attribute.

Specifies the length of the maximum value of the
active duration, measured in local time.
Value must be greater than 0.

"media"

Specifies the maximum value of the active duration
as the intrinsic media duration. This is only valid for
elements that define media. (For SVG's animation
elements, if
"media" is specified, the attribute will be
ignored.)

There is no default value for
max. This does not constrain the active duration
at all.
Except for any SVG-specific rules explicitly mentioned
in this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'max' attribute.

restart : "always" | "whenNotActive" | "never"

always

The animation can be restarted at any
time.
This is the default value.

whenNotActive

The animation can only be restarted when it is not
active (i.e. after the active end). Attempts to restart
the animation during its active duration are
ignored.

never

The element cannot be restarted for the remainder
of the current simple duration of the parent time
container. (In the case of SVG, since the parent time
container is the SVG document fragment, then the
animation cannot be restarted for the remainder of the
document duration.)

Except for any SVG-specific rules explicitly mentioned in
this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'restart' attribute.

repeatCount : numeric value | "indefinite"

Specifies the number of iterations of the animation
function. It can have the following attribute values:

numeric value

This is a (base 10) "floating point" numeric value
that specifies the number of iterations. It can include
partial iterations expressed as fraction values. A
fractional value describes a portion of the
simple duration. Values must be greater than
0.

"indefinite"

The animation is defined to repeat indefinitely
(i.e. until the document ends).

The animation effect
F(t) is defined to freeze the effect value at the
last value of the active duration. The animation effect
is "frozen" for the remainder of the document duration
(or until the animation is restarted - see
SMIL Animation: Restarting animation ).

remove

The animation effect is removed (no longer applied)
when the active duration of the animation is over.
After the active end of the animation, the animation no
longer affects the target (unless the animation is
restarted - see
SMIL Animation: Restarting animation ).
This is the default value.

Except for any SVG-specific rules explicitly mentioned in
this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'fill' attribute.

The SMIL Animation [
SMILANIM] specification defines the detailed processing
rules associated with the above attributes. Except for any
SVG-specific rules explicitly mentioned in this
specification, the SMIL Animation [
SMILANIM] specification is the normative definition of
the processing rules for the above attributes.

Clock
values

Clock values have the same syntax as in SMIL Animation [
SMILANIM], which is repeated here:

Fractional values are just (base 10) floating point
definitions of seconds. Thus:

00.5s = 500 milliseconds
00:00.005 = 5 milliseconds

19.2.7 Attributes that define animation values over
time

The following attributes are common to elements
'animate', 'animateMotion', 'animateColor' and 'animateTransform'. These
attributes define the values that are assigned to the target
attribute or property over time. The attributes below provide
control over the relative timing of keyframes and the
interpolation method between discrete values.

Specifies the interpolation mode for the animation. This
can take any of the following values. The default mode is
"linear", however if the attribute does not support
linear interpolation (e.g. for strings), the
calcMode attribute is ignored and discrete
interpolation is used.

discrete

This specifies that the animation function will
jump from one value to the next without any
interpolation.

linear

Simple linear interpolation between values is used
to calculate the animation function. Except for 'animateMotion', this
is the default calcMode.

paced

Defines interpolation to produce an even pace of
change across the animation. This is only supported for
values that define a linear numeric range, and for
which some notion of "distance" between points can be
calculated (e.g. position, width, height, etc.). If
"paced" is specified, any
keyTimes or keySplines will be
ignored. For 'animateMotion', this
is the default calcMode.

spline

Interpolates from one value in the
values list to the next according to a time
function defined by a cubic Bézier spline. The
points of the spline are defined in the
keyTimes attribute, and the control points for
each interval are defined in the
keySplines attribute.

A semicolon-separated list of one or more values.
Vector-valued attributes are supported using the vector
syntax of the attributeType domain. Except for
any SVG-specific rules explicitly mentioned in this
specification, the normative definition for this attribute
is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'values' attribute.

keyTimes=
"<list>"

A semicolon-separated list of time values used to control
the pacing of the animation. Each time in the list
corresponds to a value in the values
attribute list, and defines when the value is used in the
animation function. Each time value in the
keyTimes list is specified as a floating point
value between 0 and 1 (inclusive), representing a
proportional offset into the simple duration of the
animation element.

If a list of keyTimes is specified, there
must be exactly as many values in the
keyTimes list as in the values
list.

Each successive time value must be greater than or equal
to the preceding time value.

The keyTimes list semantics depends upon
the interpolation mode:

For linear and spline animation, the first
time value in the list must be 0, and the last time
value in the list must be 1. The keyTime
associated with each value defines when the value is
set; values are interpolated between the
keyTimes.

For discrete animation, the first time value in the
list must be 0. The time associated with each value
defines when the value is set; the animation function
uses that value until the next time defined in
keyTimes.

If the interpolation mode is "paced", the
keyTimes attribute is ignored.

If there are any errors in the keyTimes
specification (bad values, too many or too few values),
the document fragment is in error (see error
processing).

If the simple duration is indefinite, any
keyTimes specification will be ignored.

A set of Bézier control points associated with
the keyTimes list, defining a cubic
Bézier function that controls interval pacing. The
attribute value is a semicolon separated list of control
point descriptions. Each control point description is a set
of four values: x1 y1 x2 y2, describing the
Bézier control points for one time segment. The
keyTimes values that define the associated
segment are the Bézier "anchor points", and the
keySplines values are the control points.
Thus, there must be one fewer sets of control points than
there are keyTimes.

The values must all be in the range 0 to 1.

This attribute is ignored unless the calcMode
is set to "spline".

If there are any errors in the keySplines
specification (bad values, too many or too few values), the
document fragment is in error (see error
processing).

Specifies the starting value of the animation.
Except for any SVG-specific rules explicitly mentioned in
this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'from' attribute.

to =
"<value>"

Specifies the ending value of the animation.
Except for any SVG-specific rules explicitly mentioned in
this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'to' attribute.

by =
"<value>"

Specifies a relative offset value for the
animation.
Except for any SVG-specific rules explicitly mentioned in
this specification, the normative definition for this
attribute is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'by' attribute.

The SMIL Animation [
SMILANIM] specification defines the detailed processing
rules associated with the above attributes. Except for any
SVG-specific rules explicitly mentioned in this
specification, the SMIL Animation [
SMILANIM] specification is the normative definition of
the processing rules for the above attributes.

The animation values specified in the animation element
must be legal values for the specified attribute. Leading and
trailing white space, and white space before and after
semicolon separators, will be ignored.

All values specified must be legal values for the
specified attribute (as defined in the associated namespace).
If any values are not legal, the document fragment is in
error (see error
processing).

If a list of values is used, the animation will apply the
values in order over the course of the animation. If a list
of values is specified, any from,
to and by attribute values are ignored.

The following figure illustrates the interpretation of the
keySplines attribute. Each diagram illustrates
the effect of keySplines settings for a single
interval (i.e. between the associated pairs of values in the
keyTimes and values lists.). The
horizontal axis can be thought of as the input value for the
unit progress of interpolation within the interval -
i.e. the pace with which interpolation proceeds along the
given interval. The vertical axis is the resulting value for
the unit progress, yielded by the
keySplines function. Another way of describing this is
that the horizontal axis is the input unit time for
the interval, and the vertical axis is the output unit
time. See also the section
Timing and real-world clock times.

It is frequently useful for repeated animations to build
upon the previous results, accumulating with each interation.
The following example causes the rectangle to continue to grow
with each repeat of the animation:

At the end of the first repetition, the rectangle has a
width of 30 pixels. At the end of the second repetition, the
rectangle has a width of 40 pixels. At the end of the fifth
repetition, the rectangle has a width of 70 pixels.

19.2.9 Inheritance

SVG allows both attributes and properties to be animated. If
a given attribute or property is inheritable by descendants,
then animations on a parent element such as a
'g' element has the effect of propagating the
attribute or property animation values to descendant elements
as the animation proceeds; thus, descendant elements can
inherit animated attributes and properties from their
ancestors.

19.2.10 The 'animate'
element

The 'animate' element is
used to animate a single attribute or property over time. For
example, to make a rectangle repeatedly fade away over 5
seconds, you can specify:

Except for any SVG-specific rules explicitly mentioned in
this specification, the normative definition for this element
is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'animate' element.

19.2.11 The 'set'
element

The 'set' element provides
a simple means of just setting the value of an attribute for a
specified duration. It supports all attribute types, including
those that cannot reasonably be interpolated, such as string
and boolean values. The 'set'
element is non-additive. The additive and accumulate attributes
are not allowed, and will be ignored if specified.

Except for any SVG-specific rules explicitly mentioned in
this specification, the normative definition for this element
is the SMIL Animation [
SMILANIM] specification. In particular, see
SMIL Animation: 'set' element.

The motion path, expressed in the same format and
interpreted the same way as the
d= attribute on the
'path' element. The effect of a motion path
animation is to add a supplemental transformation matrix
onto the CTM for the referenced object which causes a
translation along the x- and y-axes of the current user
coordinate system by the computed X and Y values computed
over time.

keyPoints = "<list-of-numbers>"

keyPoints takes a
semicolon-separated list of floating point values between 0
and 1 and indicates how far along the motion path the
object shall move at the moment in time specified by
corresponding keyTimes
value. Distance calculations use the user agent's distance along the
path algorithm. Each progress value in the list
corresponds to a value in the keyTimes
attribute list.
If a list of keyPoints is specified, there
must be exactly as many values in the
keyPoints list as in the keyTimes
list.
If there are any errors in the keyPoints
specification (bad values, too many or too few values),
then the document is in error (see Error
processing).

rotate = "<angle> | auto |
auto-reverse"

auto indicates that the
object is rotated over time by the angle of the direction
(i.e., directional tangent vector) of the motion path.
auto-reverse indicates that
the object is rotated over time by the angle of the
direction (i.e., directional tangent vector) of the motion
path plus 180 degrees. An actual angle value can also be
given, which represents an angle relative to the x-axis of
current user coordinate system. The rotate attribute adds a
supplemental transformation matrix onto the CTM to apply a
rotation transformation about the origin of the current
user coordinate system. The rotation transformation is
applied after the supplemental translation transformation
that is computed due to the
path attribute. The default value is 0.

origin = "default"

The origin attribute is
defined in the SMIL Animation specification [
SMILANIM-ATTR-ORIGIN]. It has no effect in SVG.

For 'animateMotion', the
specified values for from,
by, to and
values consists of x, y coordinate pairs, with a
single comma and/or white space separating the x coordinate
from the y coordinate. For example,
from="33,15" specifies an x coordinate value of 33 and a y coordinate value of 15.

If provided, the values attribute must
consists of a list of x, y coordinate pairs. Coordinate values
are separated by at least one white space character or a comma.
Additional white space around the separator is allowed. For
example,
values="10,20;30,20;30,40" or
values="10mm,20mm;30mm,20mm;30mm,40mm". Each coordinate
represents a length.
Attributes from,
by, to and
values specify a shape on the current canvas which
represents the motion path.

Two options are available which allow definition of a motion
path using any of SVG's path
data commands:

the 'mpath' sub-element provides
the ability to reference an external
'path' element as the definition of the motion
path.

Note that SVG's path data
commands can only contain values in user space, whereas
from, by,
to and values can specify coordinates in
user space or using unit identifiers. See Units.

The various (x,y) points of the shape provide a supplemental
transformation matrix onto the CTM for the referenced object
which causes a translation along the x- and y-axes of the
current user coordinate system by the (x,y) values of the shape
computed over time. Thus, the referenced object is translated
over time by the offset of the motion path relative to the
origin of the current user coordinate system. The supplemental
transformation is applied on top of any transformations due to
the target element's transform attribute or any
animations on that attribute due to 'animateTransform' elements on
the target element.

The additive and accumulate attributes apply to
'animateMotion' elements.
Multiple 'animateMotion'
elements all simultaneously referencing the same target element
can be additive with respect to each other; however, the
transformations which result from the 'animateMotion' elements are always
supplemental to any transformations due to the target element's
transform attribute or any 'animateTransform'
elements.

The default calculation mode (calcMode) for animateMotion is "paced". This will
produce constant velocity motion along the specified path. Note
that while animateMotion elements can be additive, it is
important to observe that the addition of two or more "paced"
(constant velocity) animations might not result in a combined
motion animation with constant velocity.

When a path is combined with
"discrete", "linear" or "spline"
calcMode settings, and if attribute
keyPoints is not provided, the number of values is
defined to be the number of points defined by the path, unless
there are "move to" commands within the path. A "move to"
command within the path (i.e.
other than at the beginning of the
path description) A "move to" command does not count as
an additional point when dividing up the duration, or when
associating keyTimes, keySplines and
keyPoints values. When a
path is combined with a "paced"
calcMode setting, all "move to" commands are considered
to have 0 length (i.e. they always happen instantaneously), and
is not considered in computing the pacing.

For more flexibility in controlling the velocity along the
motion path, the keyPoints attribute provides
the ability to specify the progress along the motion path for
each of the keyTimes specified values. If
specified, keyPoints causes
keyTimes to apply to the values in keyPoints rather than the points
specified in the values
attribute array or the points on the
path attribute.

The override rules for
'animateMotion are as follows. Regarding the definition
of the motion path, the 'mpath' element overrides
the the path attribute, which
overrides values, which
overrides from/by/to. Regarding
determining the points which correspond to the keyTimes attributes, the keyPoints attribute overrides path, which overrides values, which overrides from/by/to.

At any time t within a motion path animation of
duration dur, the computed coordinate (x,y) along the
motion path is determined by finding the point (x,y) which is
t/dur distance along the motion path using the user
agent's distance along
the path algorithm.

The following example demonstrates the supplemental
transformation matrices that are computed during a motion path
animation.

The values attribute for the 'animateColor' element consists of
a semicolon-separated list of color values, with each color
value expressed in the above syntax.

Out of range color values can be provided, but user agent
processing will be implementation dependent. User agents should
clamp color values to allow color range values as late as
possible, but note that system differences might preclude
consistent behavior across different systems.

The 'color-interpolation' property
applies to color interpolations that result from 'animateColor' animations.

The values attribute for the 'animateTransform' element consists
of a semicolon-separated list of values, where each individual
value is expressed as described above for
from, by and
to.

If calcMode has the value paced, then a total "distance" for
each component of the transformation is calculated (e.g., for a
translate operation, a total distance is calculated for both
tx and ty) consisting of the sum of the
absolute values of the differences between each pair of values,
and the animation runs to produce a constant distance movement
for each individual component.

When an animation is active, the effect of non-additive
'animateTransform' (i.e.,
additive="replace") is to
replace the given attribute's value with the transformation
defined by the
'animateTransform'. The effect of additive (i.e., additive="sum") is to post-multiply
the transformation matrix corresponding to the transformation
defined by this
'animateTransform'. To illustrate:

In the code snippet above, because the both animations have
additive="replace", the first
animation overrides the transformation on the rectangle itself
and the second animation overrides the transformation from the
first animation; therefore, at time 5 seconds, the visual
result of the above two animations would be equivalent to the
following static rectangle:

In this code snippet, because the both animations have additive="sum", the first animation
post-multiplies its transformation to any transformations on
the rectangle itself and the second animation post-multiplies
its transformation to any transformation from the first
animation; therefore, at time 5 seconds, the visual result of
the above two animations would be equivalent to the following
static rectangle:

Each attribute or property within this specification
indicates whether or not it can be animated by SVG's animation
elements. Animatable attributes and properties are designated
as follows:

Animatable:
yes.

whereas attributes and properties that cannot be animated are
designated:

Animatable:
no.

SVG has a defined set of basic data types for its
various supported attributes and properties. For those
attributes and properties that can be animated, the following
table indicates which animation elements can be used to animate
each of the basic data types. If a given attribute or property
can take values of keywords (which are not additive) or numeric
values (which are additive), then additive animations are
possible if the subsequent animation uses a numeric value even
if the base animation uses a keyword value; however, if the
subsequent animation uses a keyword value, additive animation
is not possible.

Any deviation from the above table or other special note
about the animation capabilities of a particular attribute or
property is included in the section of the specification where
the given attribute or property is defined.

The above SVG file contains a single graphics element, a
text string that says "SVG". The animation loops for 5 seconds.
The text string starts out small and transparent and grows to
be large and opaque. Here is an explanation of how this example
works:

The onload="StartAnimation(evt)" attribute
indicates that, once the document has been fully loaded and
processed, invoke ECMAScript function
StartAnimation.

The 'script' element defines the ECMAScript which makes
the animation happen. The StartAnimation()
function is only called once to give a value to global
variable text_element and to make the initial
call to ShowAndGrowElement().
ShowAndGrowElement() is called every 50 milliseconds
and resets the transform and style
attributes on the text element to new values each time it is
called. At the end of ShowAndGrowElement, the
function tells the ECMAScript engine to call itself again
after 50 more milliseconds.

The 'g' element shifts the coordinate system so that the
origin is shifted toward the lower-left of the viewing area.
It also defines the fill color and font-size to use when
drawing the text string.

The 'text' element contains the text string and is the
element whose attributes get changed during the
animation.

If scripts are modifying the same attributes or properties
that are being animated by SVG's animation elements,
the scripts modify the base value for the animation. If a base
value is modified while an animation element is animating the
corresponding attribute or property, the animations are
required to adjust dynamically to the new base value.

If a script is modifying a property on the override style
sheet at the same time that an animation element is
animating that property, the result is
implementation-dependent; thus, it is recommended that this be
avoided.

19.5 DOM interfaces

The following two interfaces are from
SMIL Animation. They are included here for easy
reference:

Interface
ElementTimeControl

The ElementTimeControl
interface, part of the org.w3c.dom.smil module
and defined in
SMIL Animation: Supported interfaces, defines common
methods for elements which define animation behaviors
compatible with SMIL Animation.

Calling beginElement() causes the animation to
begin in the same way that an animation with event-based begin
timing begins. The effective begin time is the current
presentation time at the time of the DOM method call. Note that
beginElement() is subject to the
restart attribute in the same manner that event-based
begin timing is. If an animation is specified to disallow
restarting at a given point, beginElement()
methods calls must fail. Refer also to the section
Restarting animation.

Calling beginElementAt(seconds) has the same
behavior as beginElement(), except that the
effective begin time is offset from the current presentation
time by an amount specified as a parameter. Passing a negative
value for the offset causes the element to begin as for
beginElement(), but has the effect that the element
begins at the specified offset into its active duration. The
beginElementAt() method must also respect the
restart attribute. The restart semantics for a
beginElementAt() method call are evaluated at the
time of the method call, and not at the effective begin time
specified by the offset parameter.

Calling endElement() causes an animation to end
the active duration, just as end does. Depending
upon the value of the fill attribute, the
animation effect may no longer be applied, or it may be frozen
at the current effect. Refer also to the section
Freezing animations. If an animation is not currently
active (i.e. if it has not yet begun or if it is frozen), the
endElement() method will fail.

Calling endElementAt() causes an animation to
end the active duration, just as endElement()
does, but allows the caller to specify a positive offset, to
cause the element to end at a point in the future. Other than
delaying when the end actually happens, the semantics are
identical to those for endElement(). If
endElementAt() is called more than once while an element
is active, the end time specified by the last method call will
determine the end behavior.

Causes this element to begin the local timeline
(subject to restart constraints).

No
Parameters

Return
value

boolean

true if the method call was
successful and the element was begun.
false if the method call failed.
Possible reasons for failure include:

The element is already active and
cannot be restarted when it is active. The
restart attribute is set to
"whenNotActive".

The element is active or has been
active and cannot be restarted. The
restart attribute is set to
"never".

Exceptions

DOMException

SYNTAX_ERR: The element was not defined
with the appropriate syntax to allow
beginElement calls.

beginElementAt

Causes this element to begin the local timeline
(subject to restart constraints), at the passed offset
from the current time when the method is called. If the
offset is >= 0, the semantics are equivalent to an
event-base begin with the specified offset. If the
offset is < 0, the semantics are equivalent to
beginElement(), but the element active duration is
evaluated as though the element had begun at the passed
(negative) offset from the current time when the method
is called.

Parameters

in floatoffset

The offset in seconds at which to begin the
element.

Return
value

boolean

true if the method call was
successful and the element was begun.
false if the method call failed.
Possible reasons for failure include:

The element is already active and
cannot be restarted when it is active. The
restart attribute is set to
"whenNotActive".

The element is active or has been
active and cannot be restarted. The
restart attribute is set to
"never".

Exceptions

DOMException

SYNTAX_ERR: The element was not defined
with the appropriate syntax to allow
beginElementAt calls.

endElement

Causes this element to end the local timeline.

No
Parameters

Return
value

boolean

true if the method call was
successful and the element was ended.
false if method call failed. Possible
reasons for failure include:

The element is not active.

Exceptions

DOMException

SYNTAX_ERR: The element was not defined
with the appropriate syntax to allow
endElement calls.

endElementAt

Causes this element to end the local timeline at the
specified offset from the current time when the method
is called.

Parameters

in floatoffset

The offset in seconds at which to end the
element. Must be >= 0.

Return
value

boolean

true if the method call was
successful and the element was ended.
false if the method call failed.
Possible reasons for failure include:

The element is not active.

Exceptions

DOMException

SYNTAX_ERR: The element was not defined
with the appropriate syntax to allow
endElementAt calls.

This event is raised when the element local timeline begins
to play. It will be raised each time the element begins the
active duration (i.e. when it restarts, but not when it
repeats). It may be raised both in the course of normal
(i.e. scheduled or interactive) timeline play, as well as
in the case that the element was begun with the
beginElement() or beginElementAt()
methods. Note that if an element is restarted while it is
currently playing, the element will raise an end event and
another begin event, as the element restarts.

Bubbles: No

Cancelable: No

Context Info: None

endEvent

This event is raised at the active end of the element. Note
that this event is not raised at the simple end of each
repeat. This event may be raised both in the course of
normal (i.e. scheduled or interactive) timeline play, as
well as in the case that the element was ended with the
endElement() or endElementAt()
methods. Note that if an element is restarted while it is
currently playing, the element will raise an end event and
another begin event, as the element restarts.

Bubbles: No

Cancelable: No

Context Info: None

repeatEvent

This event is raised when an element local timeline
repeats. It will be raised each time the element repeats,
after the first iteration.
The event provides a numerical indication of which repeat
iteration is beginning. The value is a 0-based integer, but
the repeat event is not raised for the first iteration and
so the observed values of the detail attribute will be
>= 1.

The view attribute identifies the
AbstractView [DOM2-VIEWS]
from which the event was generated.

readonlylongdetail

Specifies some detail information about the Event,
depending on the type of the event. For this event type,
indicates the repeat number for the animation.

Methods

initTimeEvent

The initTimeEvent method is used to initialize the
value of a TimeEvent created through the
DocumentEvent interface. This method may only be
called before the TimeEvent has been
dispatched via the dispatchEvent method,
though it may be called multiple times during that
phase if necessary. If called multiple times, the final
invocation takes precedence.

Unlike other SVG DOM interfaces, the SVG DOM does not
specify convenience DOM properties corresponding to the various
language attributes on SVG's animation elements. Specification
of these convenience properties in a way that will be
compatible with future versions of SMIL Animation is expected
in a future version of SVG. The current method for accessing
and modifying the attributes on the animation elements is to
use the standard getAttribute,
setAttribute, getAttributeNS and
setAttributeNS defined in DOM2.