SVG Essentials/Animating and Scripting SVG - Revision history

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Fri, 07 Mar 2008 13:40:50 GMT

Initial conversion from Docbook

←Older revision

Revision as of 13:40, 7 March 2008

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Fri, 07 Mar 2008 12:51:41 GMT

Initial conversion from Docbook

←Older revision

Revision as of 12:51, 7 March 2008

Evanlenz: 1 revision(s)

Evanlenz — Thu, 06 Mar 2008 23:40:39 GMT

1 revision(s)

←Older revision

Revision as of 23:40, 6 March 2008

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Thu, 06 Mar 2008 23:33:32 GMT

Initial conversion from Docbook

←Older revision

Revision as of 23:33, 6 March 2008

Evanlenz: 1 revision(s)

Evanlenz — Thu, 06 Mar 2008 22:52:48 GMT

1 revision(s)

←Older revision

Revision as of 22:52, 6 March 2008

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Thu, 06 Mar 2008 22:38:57 GMT

Initial conversion from Docbook

←Older revision

Revision as of 22:38, 6 March 2008

Evanlenz: 1 revision(s)

Evanlenz — Thu, 06 Mar 2008 22:22:08 GMT

1 revision(s)

←Older revision

Revision as of 22:22, 6 March 2008

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Thu, 06 Mar 2008 22:21:01 GMT

Initial conversion from Docbook

←Older revision		Revision as of 22:21, 6 March 2008
Line 45:		Line 45:
	'''Figure 11-1. Beginning of animation'''		'''Figure 11-1. Beginning of animation'''

-	[[Image:SVG ~~Essentials/I_11_tt235~~.png\|Beginning of animation]]	+	[[Image:SVG Essentials_I_11_tt235.png\|Beginning of animation]]
	</div>		</div>

Line 51:		Line 51:
	'''Figure 11-2. Ending of animation'''		'''Figure 11-2. Ending of animation'''

-	[[Image:SVG ~~Essentials/I_11_tt236~~.png\|Ending of animation]]	+	[[Image:SVG Essentials_I_11_tt236.png\|Ending of animation]]
	</div>		</div>

Line 95:		Line 95:
	'''Figure 11-3. Stages of multi-object animation'''		'''Figure 11-3. Stages of multi-object animation'''

-	[[Image:SVG ~~Essentials/I_11_tt237~~.png\|Stages of multi-object animation]]	+	[[Image:SVG Essentials_I_11_tt237.png\|Stages of multi-object animation]]
	</div>		</div>

Line 125:		Line 125:
	'''Figure 11-4. Stages of synchronized animations'''		'''Figure 11-4. Stages of synchronized animations'''

-	[[Image:SVG ~~Essentials/I_11_tt238~~.png\|Stages of synchronized animations]]	+	[[Image:SVG Essentials_I_11_tt238.png\|Stages of synchronized animations]]
	</div>		</div>

Line 275:		Line 275:
	'''Figure 11-5. animateTransform -- before and after'''		'''Figure 11-5. animateTransform -- before and after'''

-	[[Image:SVG ~~Essentials/I_11_tt241~~.png\|animateTransform -- before and after]]	+	[[Image:SVG Essentials_I_11_tt241.png\|animateTransform -- before and after]]
	</div>		</div>

Line 297:		Line 297:
	'''Figure 11-6. Multiple animateTransforms -- before and after'''		'''Figure 11-6. Multiple animateTransforms -- before and after'''

-	[[Image:SVG ~~Essentials/I_11_tt242~~.png\|Multiple animateTransforms -- before and after]]	+	[[Image:SVG Essentials_I_11_tt242.png\|Multiple animateTransforms -- before and after]]
	</div>		</div>

Line 340:		Line 340:
	'''Figure 11-7. animateMotion along a complex path'''		'''Figure 11-7. animateMotion along a complex path'''

-	[[Image:SVG ~~Essentials/I_11_tt243~~.png\|animateMotion along a complex path]]	+	[[Image:SVG Essentials_I_11_tt243.png\|animateMotion along a complex path]]
	</div>		</div>

Line 366:		Line 366:
	'''Figure 11-8. animateMotion along a complex path with auto-rotation'''		'''Figure 11-8. animateMotion along a complex path with auto-rotation'''

-	[[Image:SVG ~~Essentials/I_11_tt244~~.png\|animateMotion along a complex path with auto-rotation]]	+	[[Image:SVG Essentials_I_11_tt244.png\|animateMotion along a complex path with auto-rotation]]
	</div>		</div>

Line 484:		Line 484:
	'''Figure 11-9. Screenshots of different selections'''		'''Figure 11-9. Screenshots of different selections'''

-	[[Image:SVG ~~Essentials/I_11_tt245~~.png\|Screenshots of different selections]]	+	[[Image:SVG Essentials_I_11_tt245.png\|Screenshots of different selections]]
	</div>		</div>

Line 581:		Line 581:
	'''Figure 11-10. Screenshot of color sliders'''		'''Figure 11-10. Screenshot of color sliders'''

-	[[Image:SVG ~~Essentials/I_11_tt246~~.png\|Screenshot of color sliders]]	+	[[Image:SVG Essentials_I_11_tt246.png\|Screenshot of color sliders]]
	</div>		</div>

Line 700:		Line 700:
	'''Figure 11-11. Screenshot of labeled color sliders'''		'''Figure 11-11. Screenshot of labeled color sliders'''

-	[[Image:SVG ~~Essentials/I_11_tt251~~.png\|Screenshot of labeled color sliders]]	+	[[Image:SVG Essentials_I_11_tt251.png\|Screenshot of labeled color sliders]]
	</div>		</div>

Line 869:		Line 869:
	'''Figure 11-12. Screenshot of HTML and SVG interaction'''		'''Figure 11-12. Screenshot of HTML and SVG interaction'''

-	[[Image:SVG ~~Essentials/I_11_tt260~~.png\|Screenshot of HTML and SVG interaction]]	+	[[Image:SVG Essentials_I_11_tt260.png\|Screenshot of HTML and SVG interaction]]
	</div>		</div>

Line 879:		Line 879:
	'''Figure 11-13. Screenshot of two stages of scripting with animation'''		'''Figure 11-13. Screenshot of two stages of scripting with animation'''

-	[[Image:SVG ~~Essentials/I_11_tt261~~.png\|Screenshot of two stages of scripting with animation]]	+	[[Image:SVG Essentials_I_11_tt261.png\|Screenshot of two stages of scripting with animation]]
	</div>		</div>

Line 1,079:		Line 1,079:
	'''Figure 11-14. Beginning and ending of scripted path change'''		'''Figure 11-14. Beginning and ending of scripted path change'''

-	[[Image:SVG ~~Essentials/I_11_tt263~~.png\|Beginning and ending of scripted path change]]	+	[[Image:SVG Essentials_I_11_tt263.png\|Beginning and ending of scripted path change]]
	</div>		</div>

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Tue, 04 Mar 2008 22:37:00 GMT

Initial conversion from Docbook

New page

{{SVG Essentials/TOC}}
Up to this point we have produced static images; once constructed, they never change. In this chapter, we will examine two methods of making graphic images move. The first method, animation, is movement that is controlled by you, the author. The second method, scripting, lets the person viewing the graphic interact with and modify the image.

In [[SVG Essentials/Filters|Chapter 10]] we suggested that filters should be used as a means to enhance a graphic's message, not as an end in themselves. This suggestion is even more crucial with animation. Drunk with the power of animation, you will be tempted to turn your every graphic into an all-dancing, all-singing, Broadway spectacular. As long as your goal is experimentation, this is fine. If your goal is to convey a message, however, nothing is worse than gratuitous use or overuse of animation. Let me state this clearly: nobody except the company CEO is interested in repeated viewing of a spinning, flashing, color-changing, strobe-lit version of the company logo.

In this chapter, our message ''is'' the animation, so most of our examples will be remarkably free of any content. We will, of course, avoid gratuitous and overwrought animation as much as possible.

== Animation Basics ==

The animation features of SVG are based on the World Wide Web Consortium's Synchronized Multimedia Integration Language Level 2 (SMIL2) specification ''http://www.w3.org/TR/smil20/''. In this system, you specify the starting and ending values of the attribute, color, motion, or transformation that you wish to animate; the time at which the animation should begin; and the duration of the animation. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-1|Example 11-1]] shows this in action.

<div id="svgess-CHP-11-EX-1">
'''Example 11-1. The incredible shrinking rectangle'''

<rect x="10" y="10" width="200" height="20" stroke="black" fill="none"> '''[1]'''
<animate '''[2]'''
attributeName="width" '''[3]'''
attributeType="XML" '''[4]'''
from="200" to="20" '''[5]'''
begin="0s" dur="5s" '''[6]'''
fill="freeze" /> '''[7]'''
</rect> '''[8]'''

</div>

<tt>'''[1]'''</tt> A <tt><rect></tt> element ''without'' the ending <tt>/></tt>. The animation will be contained within the element.

<tt>'''[2]'''</tt> Begin specification of animation

<tt>'''[3]'''</tt> Specify the attribute whose value should change over time.

<tt>'''[4]'''</tt> Width is an XML attribute in the <tt><rect></tt> element. The other common value of <tt>attributeType</tt> is <tt>CSS</tt>, indicating that the property we want to change is a CSS property. If you leave this off, the default value of <tt>auto</tt> is used; it searches through CSS properties first and then XML attributes.

<tt>'''[5]'''</tt> The starting and ending values for the attribute. In this example, the starting value is 200 and the ending value is 20.<ref>There is also a <tt>by</tt> attribute, which you may use instead of <tt>to</tt>; it is an offset that is added to the starting <tt>from</tt> value; the result is the ending value.</ref>

<tt>'''[6]'''</tt> The beginning and duration times for the animation. In this example, we measure time in seconds, specified by the <tt>s</tt> after the number. For more details, see [[SVG Essentials/Animating and Scripting SVG#How Time Is Measured|Section 11.2]].

<tt>'''[7]'''</tt> After the five-second duration, keep the attribute at its end value. If you remove this line, the attribute will return to its original value of 200 after the five-second animation has finished. This is the SMIL <tt>fill</tt> attribute, which tells the animation engine how to fill up the remaining time. Don't confuse it with SVG's <tt>fill</tt> attribute, which tells SVG how to paint an object.

<tt>'''[8]'''</tt> We have to close the <tt><rect></tt> element, since it is now a container element.

[[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-1|Figure 11-1]] and [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-2|Figure 11-2]] show the beginning and ending stages of the animation. They can't do justice to the actual effect, so we strongly recommend that you download the Adobe SVG Viewer plugin and try the example. Type it into a file, enclosed in the appropriate <tt><?xml?></tt> and <tt><svg></tt> tags, and open it within your browser.

<div id="svgess-CHP-11-FIG-1">
'''Figure 11-1. Beginning of animation'''

[[Image:SVG Essentials/I_11_tt235.png|Beginning of animation]]
</div>

<div id="svgess-CHP-11-FIG-2">
'''Figure 11-2. Ending of animation'''

[[Image:SVG Essentials/I_11_tt236.png|Ending of animation]]
</div>

Let's move on to a more ambitious example. In [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-2|Example 11-2]] we'll start with a 20-by-20 green square that will grow to 250-by-200 over the space of 8 seconds. For the first three seconds, the opacity of the green will increase, then decrease for the next three seconds. Note that <tt>fill-opacity</tt> is referred to with <tt>attributeType="CSS"</tt> since it was set in a <tt>style</tt>.

<div id="svgess-CHP-11-EX-2">
'''Example 11-2. Multiple animations on a single object'''

<rect x="10" y="10" width="20" height="20"
style="stroke: black; fill: green; style: fill-opacity: 0.25;">
<animate attributeName="width" attributeType="XML"
from="20" to="250" begin="0s" dur="8s" fill="freeze"/>
<animate attributeName="height" attributeType="XML"
from="20" to="200" begin="0s" dur="8s" fill="freeze"/>
<animate attributeName="fill-opacity" attributeType="CSS"
from="0.25" to="1" begin="0s" dur="3s" fill="freeze"/>
<animate attributeName="fill-opacity" attributeType="CSS"
from="1" to="0.25" begin="3s" dur="3s" fill="freeze"/>
</rect>
</div>

Our last simple example, [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-3|Example 11-3]], animates a square and a circle. The square will expand from 20-by-20 to 120-by-120 over the space of eight seconds. Two seconds after the beginning of the animation, the circle's radius will start expanding from 20 to 50 over the space of four seconds. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-3|Figure 11-3]] shows a combined screenshot of the animation at four times: zero seconds, when the animation begins; two seconds, when the circle starts to grow; six seconds, when the circle finishes growing; and eight seconds, when the animation is finished.

<div id="svgess-CHP-11-EX-3">
'''Example 11-3. Simple animation of multiple objects'''

<rect x="10" y="10" width="20" height="20"
style="stroke: black; fill: #cfc;">
<animate attributeName="width" attributeType="XML"
begin="0s" dur="8s" from="20" to="120" fill="freeze"/>
<animate attributeName="height" attributeType="XML"
begin="0s" dur="8s" from="20" to="120" fill="freeze"/>
</rect>

<circle cx="70" cy="70" r="20"
style="fill: #ccf; stroke: black;">
<animate attributeName="r" attributeType="XML"
begin="2s" dur="4s" from="20" to="50" fill="freeze"/>
</circle>
</div>

<div id="svgess-CHP-11-FIG-3">
'''Figure 11-3. Stages of multi-object animation'''

[[Image:SVG Essentials/I_11_tt237.png|Stages of multi-object animation]]
</div>

== How Time Is Measured ==

SVG's animation clock starts ticking when the SVG has finished loading, and it stops ticking when the user leaves the page. You may specify a beginning or duration for a particular animation segment as a numeric value in one of these ways:

* A full clock value in hours, minutes, and seconds (<tt>1:20:23</tt>).
* A partial clock value in minutes and seconds (<tt>2:15</tt>).
* A time value followed by a "metric," which is one of <tt>h</tt> (hours), <tt>min</tt> (minutes), <tt>s</tt> (seconds), or <tt>ms</tt> (milliseconds), for example <tt>dur="3.5s"</tt> <tt>begin="1min"</tt>. If no metric is specified, the default is seconds. You may not put any whitespace between the value and the metric.

You may also tie an animation's beginning time to the beginning or end of another animation. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-4|Example 11-4]] shows two circles; the second one will start expanding as soon as the first one has stopped shrinking. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-4|Figure 11-4]] shows the important stages of the animation.

<div id="svgess-CHP-11-EX-4">
'''Example 11-4. Synchronization of animations'''

<circle cx="60" cy="60" r="30" style="fill: #f9f; stroke: gray;">
<animate '''id="c1"''' attributeName="r" attributeType="XML"
begin="0s" dur="4s" from="30" to="10" fill="freeze"/>
</circle>

<circle cx="120" cy="60" r="10" style="fill: #9f9; stroke: gray;">
<animate attributeName="r" attributeType="XML"
begin="'''c1.end'''" dur="4s" from="10" to="30" fill="freeze"/>
</circle>
</div>

<div id="svgess-CHP-11-FIG-4">
'''Figure 11-4. Stages of synchronized animations'''

[[Image:SVG Essentials/I_11_tt238.png|Stages of synchronized animations]]
</div>

It is also possible to add an offset to this synchronization. To make an animation start two seconds after another animation, you would use a construction of the form <tt>begin="otherAnim.end+2s"</tt>. (You may add whitespace around the plus sign.) The offset must be positive; to make an animation's start point <tt>begin="otherAnim.end-2s"</tt> would require the computer to look into the future, and there is no such thing as Psychic Vector Graphics. In [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-5|Example 11-5]], the second circle begins to grow one and a fourth seconds after the first circle begins shrinking.

<div id="svgess-CHP-11-EX-5">
'''Example 11-5. Synchronization of animations with offsets'''

<circle cx="60" cy="60" r="30" style="fill: #f9f; stroke: gray;">
<animate '''id="c1"''' attributeName="r" attributeType="XML"
begin="0s" dur="4s" from="30" to="10" fill="freeze"/>
</circle>

<circle cx="120" cy="60" r="10" style="fill: #9f9; stroke: gray;">
<animate attributeName="r" attributeType="XML"
begin="'''c1.begin+1.25s'''" dur="4s" from="10" to="30" fill="freeze"/>
</circle>
</div>

Now that we know about synchronizing animations, we can introduce the <tt>end</tt> attribute, which sets an end time for an animation. This is ''not'' a substitute for the <tt>dur</tt> attribute! The following animation will start six seconds after the page loads, and will last for twelve seconds or until an animation named <tt>otherAnim</tt> ends; whichever comes first.

<animate attributeName="width" attributeType="XML"
begin="6s" dur="12s" '''end="otherAnim.end"'''
from="10" to="100" fill="freeze"/>

You can, of course, set the value of <tt>end</tt> to a number; this is useful for halting an animation partway through so that you can see if everything is in the right place. This is how we were able to create [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-3|Figure 11-3]]. The following animation starts at six seconds, and should last for twelve seconds, but is halted at nine seconds.

<animate attributeName="width" attributeType="XML"
begin="6s" dur="12s" '''end="9s"'''
from="10" to="100" fill="freeze"/>

== Repeated Action ==

The animations we've produced so far occur exactly once; we set <tt>fill</tt> to <tt>freeze</tt> to keep the final stage of the animation. If we want to have the object return to its pre-animation state, we omit the attribute. (This is equivalent to setting <tt>fill</tt> to the default value of <tt>remove</tt>.)

Two other attributes allow you to repeat an animation. The first of them, <tt>repeatCount</tt>, is set to an integer value telling how many times you want a particular animation to repeat. The second, <tt>repeatDur</tt>, is set to a time telling how long the repetition should last. If you want an animation to repeat until the user leaves the page, set either <tt>repeatCount</tt> or <tt>repeatDur</tt> to the value <tt>indefinite</tt>. The animation in [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-6|Example 11-6]] shows two circles. The upper circle moves from left to right in two repetitions of five seconds each. The second circle moves from right to left for a total of eight seconds.

<div id="svgess-CHP-11-EX-6">
'''Example 11-6. Example of repeated animation'''

<circle cx="60" cy="60" r="30" style="fill: none; stroke: red;">
<animate attributeName="cx" attributeType="XML"
begin="0s" dur="5s" '''repeatCount="2"'''
from="60" to="260" fill="freeze"/>
</circle>

<circle cx="260" cy="130" r="30" style="fill: #ccf; stroke: black;">
<animate attributeName="cx" attributeType="XML"
begin="0s" dur="5s" '''repeatDur="8s"'''
from="260" to="60" fill="freeze"/>
</circle>
</div>

Just as it was possible to synchronize an animation with the beginning or ending of another animation, we can tie the start of one animation to the start of a specific repetition of another animation. You give the first animation an <tt>id</tt>, then set the <tt>begin</tt> of the second animation to <tt>''id''</tt> <tt>.repeat(</tt> <tt>''count''</tt> <tt>)</tt>, where <tt>''count''</tt> is a number beginning at zero for the first repetition. In [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-7|Example 11-7]], we have an upper circle moving from left to right three times, requiring five seconds for each repetition. The lower square will go right to left only once, and will not begin until halfway through the second repetition. (We use an offset to achieve this effect.)

<div id="svgess-CHP-11-EX-7">
'''Example 11-7. Synchronizing an animation with a repetition'''

<circle cx="60" cy="60" r="30"
style="fill: none; stroke: red;">
<animate '''id="circle-anim"''' attributeName="cx" attributeType="XML"
begin="0s" dur="5s" '''repeatCount="3"'''
from="60" to="260" fill="freeze"/>
</circle>

<rect x="230" y="100" width="60" height="60"
style="fill: #ccf; stroke: black;">
<animate attributeName="x" attributeType="XML"
begin="'''circle-anim.repeat(1) + 2.5s'''" dur="5s"
from="230" to="30" fill="freeze"/>
</rect>
</div>

== The set Element ==

All of these animations have modified numeric values over time. You may want to set a non-numeric attribute or property though. For example, you might want an initially invisible text item to become visible at a certain time; there's no real need for both a <tt>from</tt> and <tt>to</tt>. Thus, we have the convenient shorthand of the <tt><set></tt> element, which needs only a <tt>to</tt> attribute and the proper timing information. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-8|Example 11-8]] shrinks a circle down to zero, then reveals text one-half second after the circle is gone.

<div id="svgess-CHP-11-EX-8">
'''Example 11-8. Example of set element'''

<circle cx="60" cy="60" r="30" style="fill: #ff9; stroke: gray;">
<animate id="c1" attributeName="r" attributeType="XML"
begin="0s" dur="4s" from="30" to="0" fill="freeze"/>
</circle>

<text text-anchor="middle" x="60" y="60" style="visibility: hidden;">
'''<set attributeName="visibility" attributeType="CSS"'''
''' to="visible" begin="4.5s" dur="1s" fill="freeze"/>'''
All gone!
</text>
</div>

== The animateColor Element ==

The <tt><animate></tt> element doesn't work with colors, since a color is not represented as a simple numeric value. Instead, the special <tt><animateColor></tt> element fills that purpose. Its <tt>from</tt> and <tt>to</tt> attributes are color values, as described in [[SVG Essentials/Basic Shapes|Chapter 3]], in [[SVG Essentials/Basic Shapes#stroke Color|Section 3.2.2]]. In [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-9|Example 11-9]] we animate the fill and stroke colors of a circle, changing the fill from light yellow to red and the gray outline to blue. Both animations start two seconds after the page loads; this gives you time to see the original colors.

<div id="svgess-CHP-11-EX-9">
'''Example 11-9. Example of animateColor'''

<circle cx="60" cy="60" r="30"
style="fill: #ff9; stroke: gray; stroke-width: 10;">
<animateColor attributeName="fill"
begin="2s" dur="4s" from="#ff9" to="red" fill="freeze"/>
<animateColor attributeName="stroke"
begin="2s" dur="4s" from="gray" to="blue" fill="freeze"/>
</circle>
</div>

<div class="note">
'''Note'''

If you have several animations for a particular object, one animation can refer to the previous one with the keyword <tt>prev</tt>. We could rewrite the preceding example as [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-10|Example 11-10]]. Tying two related animations together with <tt>prev</tt> lets you change them both by editing just the first one.
</div>

<div id="svgess-CHP-11-EX-10">
'''Example 11-10. Use of the prev keyword in animation'''

<circle cx="60" cy="60" r="30"
style="fill: #ff9; stroke: gray; stroke-width: 10;">
<animateColor attributeName="fill"
begin="2s" dur="4s" from="#ff9" to="red" fill="freeze"/>
<animateColor attributeName="stroke"
begin="'''prev.begin'''" dur="4s" from="gray" to="blue" fill="freeze"/>
</circle>
</div>

== The animateTransform Element ==

Just as <tt><animate></tt> doesn't work with colors, it doesn't work with rotate, translate, scale, or skew transformations either, since they're all "wrapped up" inside the <tt>transform</tt> attribute. The <tt><animateTransform></tt> element comes to the rescue. You set its <tt>attributeName</tt> to <tt>transform</tt>. The <tt>type</tt> attribute's value then specifies the transformation whose values should change (one of <tt>translate</tt>, <tt>scale</tt>, <tt>rotate</tt>, <tt>skewX</tt>, or <tt>skewY</tt>). The <tt>from</tt> and <tt>to</tt> values are specified as appropriate for the transform that you're animating.

[[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-11|Example 11-11]] stretches a rectangle from normal scale to a scale of four times in the horizontal direction and two times in the vertical direction. Note that we've centered the rectangle around the origin so it doesn't move as it scales; we place it inside a <tt><g></tt> so it can be translated to a more convenient location. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-5|Figure 11-5]] shows the beginning and end of the animation.

<div id="svgess-CHP-11-EX-11">
'''Example 11-11. Example of animateTransform'''

<g transform="translate(120,60)">
<rect x="-10" y="-10" width="20" height="20"
style="fill: #ff9; stroke: black;">
<animateTransform attributeType="XML"
'''attributeName="transform" type="scale"'''
from="1" to="4 2"
begin="0s" dur="4s" fill="freeze"/>
Stretch
</rect>
</g>
</div>

<div id="svgess-CHP-11-FIG-5">
'''Figure 11-5. animateTransform -- before and after'''

[[Image:SVG Essentials/I_11_tt241.png|animateTransform -- before and after]]
</div>

If you intend to animate more than one transformation, you must use the <tt>additive</tt> attribute. The default value of <tt>additive</tt> is <tt>replace</tt>, which replaces the specified transformation in the object being animated. This won't work in a series of animations, since the second animation would override the first one. By setting <tt>additive</tt> to <tt>sum</tt>, SVG will accumulate the transformations. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-12|Example 11-12]] stretches and rotates the rectangle; the before and after pictures are in [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-6|Figure 11-6]].

<div id="svgess-CHP-11-EX-12">
'''Example 11-12. Example of multiple animateTransform elements'''

<rect x="-10" y="-10" width="20" height="20"
style="fill: #ff9; stroke: black;">
<animateTransform attributeName="transform" attributeType="XML"
type="scale" from="1" to="4 2"
'''additive="sum"''' begin="0s" dur="4s" fill="freeze"/>
<animateTransform attributeName="transform" attributeType="XML"
type="rotate" from="0" to="45"
'''additive="sum"''' begin="0s" dur="4s" fill="freeze"/>
</rect>
</div>

<div id="svgess-CHP-11-FIG-6">
'''Figure 11-6. Multiple animateTransforms -- before and after'''

[[Image:SVG Essentials/I_11_tt242.png|Multiple animateTransforms -- before and after]]
</div>

== The animateMotion Element ==

By using <tt>translate</tt> with the <tt><animateTransform></tt> element, you can cause an object to animate along a straight-line path. The <tt><animateMotion></tt> element lets you do this as well; additionally, it allows you to animate an object along an arbitrary path.

If you insist on using <tt><animateMotion></tt> for straight-line motion, you simply set the <tt>from</tt> and <tt>to</tt> attributes, assigning them each a pair of (''x'', ''y'') coordinates. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-13|Example 11-13]] moves a grouped circle and rectangle from (0,0) to (60,30).

<div id="svgess-CHP-11-EX-13">
'''Example 11-13. Animation along a linear path'''

<g>
<rect x="0" y="0" width="30" height="30" style="fill: #ccc;"/>
<circle cx="30" cy="30" r="15" style="fill: #cfc; stroke: green;"/>
<animateMotion from="0,0" to="60,30" dur="4s" fill="freeze"/>
</g>
</div>

If you want a more complex path to follow, use the <tt>path</tt> attribute instead; its value is in the same format as the <tt>d</tt> attribute in the <tt><path></tt> element. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-14|Example 11-14]], adapted from the SVG specification, animates a triangle along a cubic Bézier curve path.

<div id="svgess-CHP-11-EX-14">
'''Example 11-14. Animation along a complex path'''


<path d="M50,125 C 100,25 150,225, 200, 125"
style="fill: none; stroke: blue;"/>


<path d="M-10,-3 L10,-3 L0,-25z" style="fill: yellow; stroke: red;">
<animateMotion
'''path="M50,125 C 100,25 150,225, 200, 125"'''
dur="6s" fill="freeze"/>
</path>
</div>

As you can see in [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-7|Figure 11-7]], the triangle stays upright throughout its entire path.

<div id="svgess-CHP-11-FIG-7">
'''Figure 11-7. animateMotion along a complex path'''

[[Image:SVG Essentials/I_11_tt243.png|animateMotion along a complex path]]
</div>

If you would prefer that the object tilt so its x-axis is always parallel to the slope of the path, just add the <tt>rotate</tt> attribute with a value of <tt>auto</tt> to the <tt><animateMotion></tt> element. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-15|Example 11-15]] shows the SVG and [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-8|Figure 11-8]] shows screenshots taken at various stages of the animation.

<div id="svgess-CHP-11-EX-15">
'''Example 11-15. Animation along a complex path with auto-rotation'''


<path d="M50,125 C 100,25 150,225, 200, 125"
style="fill: none; stroke: blue;"/>


<path d="M-10,-3 L10,-3 L0,-25z" style="fill: yellow; stroke: red;" >
<animateMotion
'''path="M50,125 C 100,25 150,225, 200, 125"'''
'''rotate="auto"'''
dur="6s" fill="freeze"/>
</path>
</div>

<div id="svgess-CHP-11-FIG-8">
'''Figure 11-8. animateMotion along a complex path with auto-rotation'''

[[Image:SVG Essentials/I_11_tt244.png|animateMotion along a complex path with auto-rotation]]
</div>

Put simply, when you leave off the <tt>rotate</tt> attribute, you get the default value of zero, and the object acts like a hot-air balloon floating along the path. If you set <tt>rotate</tt> to <tt>auto</tt>, the object acts like a car on a roller coaster, tilting up and down as the path does.

You can also set <tt>rotate</tt> to a numeric value, which will set the rotation of the object throughout the animation. Thus, if you wanted an object rotated 45 degrees no matter what direction the path took, you'd use <tt>rotate="45"</tt>.

In [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-15|Example 11-15]], we drew the path in blue so that it was visible, and then duplicated the path in the <tt><animateMotion></tt> element. You can avoid this duplication by adding an <tt><mpath></tt> element within the <tt><animateMotion></tt> element. The <tt><mpath></tt> will contain an <tt>xlink:href</tt> attribute that references the path you want to use. This also comes in handy when you have one path you wish to use to animate multiple objects. Here's the preceding example, rewritten as [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-16|Example 11-16]], using <tt><mpath></tt>.

<div id="svgess-CHP-11-EX-16">
'''Example 11-16. Motion along a complex path using mpath'''

<path '''id="cubicCurve"''' d="M50,125 C 100,25 150,225, 200, 125"
style="fill: none; stroke: blue;"/>

<path d="M-10,-3 L10,-3 L0,-25z" style="fill: yellow; stroke: red;" >
<animateMotion dur="6s" rotate="auto" fill="freeze">
'''<mpath xlink:href="#cubicCurve"/>'''
</animateMotion>
</path>
</div>

== Using Links in SVG ==

To this point, you, the author of the SVG document, have made all the decisions about a graphic. You decide what a static image should look like, and if there are any animations, you decide when they start and stop. In this section, we will see how to hand some of that control over to the person who is viewing your document.

The easiest sort of interactivity to provide is linking, accomplished with the <tt><a></tt> element. By enclosing a graphic in this element, it becomes active; when clicked, you go to the URL specified in the <tt>xlink:href</tt> attribute. You can link to another SVG file or, depending upon your environment, a web page. In [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-17|Example 11-17]], clicking the word "Cat" will link to an SVG drawing of a cat; clicking the red, green, and blue shapes will link to the World Wide Web Consortium's SVG page. All the items within the second link are individually linked to the same destination, not the entire bounding box. When you test this example and move the cursor between the shapes, you will see that those areas are not linked.

<div id="svgess-CHP-11-EX-17">
'''Example 11-17. Links in SVG'''

<nowiki>
<a xlink:href="cat.svg">
<text x="100" y="30" style="font-size: 12pt;">Cat</text>
</a>

<a xlink:href="http://www.w3.org/SVG/">
<circle cx="50" cy="70" r="20" style="fill: red;"/>
<rect x="75" y="50" width="40" height="40" style="fill: green;"/>
<path d="M120 90, 140 50, 160 90 Z" style="fill: blue;"/>
</a></nowiki>
</div>

It's worth noting that <tt>xlink:href</tt> has a namespace prefix; though this attribute is duplicated in the SVG specification, it belongs to the XLink specification. The SVG DTD handles the namespace declaration.

== Scripting SVG ==

The next step up from linking — and it's a big step — is scripting. You can write a program in ECMA Script (the European Computer Manufacturer's Association standard version of what is commonly called JavaScript) to interact with an SVG graphic. Interaction occurs when graphic objects respond to events.

Objects can respond to mouse events associated with clicking the mouse button: <tt>click</tt>, <tt>mousedown</tt>, and <tt>mouseup</tt>;<ref>A <tt>click</tt> event is defined as a <tt>mousedown</tt> followed by a <tt>mouseup</tt>; all three are different events, and cannot be used synonymously.</ref> events associated with moving the mouse: <tt>mouseover</tt> (the mouse pointer is within the object), <tt>mouseout</tt> (the mouse pointer leaves the object), and <tt>mousemove</tt>; events associated with an object's status: <tt>load</tt> (the object has been fully parsed and is ready to render); and the non-standardized events associated with pressing keys: <tt>keydown</tt> and <tt>keyup</tt>.

<div class="note">
'''Note'''

The names listed here are the names of the events. We'll be using attributes to specify the functions which should handle the events. These event handler attributes begin with the word <tt>on</tt>. Thus, <tt>onclick</tt> is an attribute whose value specifies a function that handles a <tt>click</tt> event.
</div>

To allow an object to respond to an event, you add an <tt>on</tt> <tt>''eventName''</tt> attribute to the element in question. The value of the attribute will be an ECMA Script statement, usually a function call. This function usually takes the reserved word <tt>evt</tt> as one of its parameters. <tt>evt</tt> has properties and methods that describe the event that has occurred. The three methods you will use most often are <tt>getTarget()</tt>, which returns a reference to the graphic object that is responding to this event, and <tt>getClientX()</tt> and <tt>getClientY()</tt>, which return the ''x''- and ''y''- coordinates of the mouse when the event occurred. A value of (0,0) indicates the upper left corner of the SVG viewport. These functions return the position in the viewer window regardless of any zoom or pan that the user may have done.

=== Changing Attributes of a Single Object ===

The simplest type of event handling is where an event occurring on object ''X'' modifies some attribute of that object. Let's look at [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-18|Example 11-18]], which makes a circle respond to the <tt>mouseover</tt> event by making the circle's radius larger. The circle will respond to the <tt>mouseout</tt> event by making the radius smaller.

<div id="svgess-CHP-11-EX-18">
'''Example 11-18. Basic scripting -- changing a single object'''

<script type="text/ecmascript"> '''[1]'''
<![CDATA[ '''[2]'''
function enlarge_circle(evt) '''[3]'''
{
var circle = evt.getTarget(); '''[4]'''

circle.setAttribute("r", 50); '''[5]'''
}

function shrink_circle(evt) '''[6]'''<nowiki>
{
var circle = evt.getTarget();

circle.setAttribute("r", 25);
}
// ]]> </nowiki>'''[7]'''
</script>

<circle cx="150" cy="100" r="25" fill="red" '''[8]'''
onmouseover="enlarge_circle(evt)" '''[9]'''
onmouseout="shrink_circle(evt)"/>

<text x="150" y="175" style="text-anchor: middle;">
Mouse over the circle to change its size.
</text>
</div>

<tt>'''[1]'''</tt> The beginning <tt><script></tt> tag indicates that you are preparing to leave the world of SVG/XML and enter the ECMA Script environment. The <tt>type</tt> attribute tells which scripting language you are using.

<tt>'''[2]'''</tt> In XML, the less than sign introduces a tag, and the ampersand symbol is used for escaping characters (see [[SVG Essentials/The XML You Need for SVG|Appendix A]] in [[SVG Essentials/The XML You Need for SVG#Entity References|Section A.2.5]]). Since ECMA Script isn't XML, we want to turn off this special behavior. The <tt><![CDATA[</tt> tells XML to stop treating the less than and ampersand symbols as special; they become ordinary content, which is the way ECMA Script likes it. This completes our exit from the SVG/XML world and immerses us in the ECMA Script environment.

<tt>'''[3]'''</tt> The first function, <tt>enlarge_circle</tt>, takes one parameter; the event that triggered the call.

<tt>'''[4]'''</tt> We use the <tt>evt.getTarget</tt> to return a reference to the graphic object that triggered the event, and store it in variable <tt>circle</tt>

<tt>'''[5]'''</tt> To change an attribute of a graphic object, call the object's <tt>setAttribute</tt> function with two parameters: the name of the attribute you wish to change, and its new value. <tt>setAttribute</tt> is a void function; it returns no value. There is a corresponding <tt>getAttribute</tt> function which takes as its parameter the name of the attribute; it returns a string representation of the attribute's current value. These functions are part of the DOM, or Document Object Model. The DOM is a standard API for accessing, modifying, and rearranging the elements in an XML document.

<tt>'''[6]'''</tt> This function, patterned exactly like the previous one, will set the <tt>r</tt> attribute of the event's target to 25.

<tt>'''[7]'''</tt> The <tt><nowiki>]]></nowiki></tt> ends the <tt><![CDATA[</tt> on the second line of the script. It returns the less than and ampersand to their special XML status, just in time for <tt></script></tt> on the next line, which leaves ECMA Script and returns you to the SVG/XML world. The leading slashes on line 16 introduce an ECMA Script comment, ensuring that the remainder of the line is not interpreted as part of the script. (This is not necessary with version 2.0 Adobe plugin, but other XML applications may require the slashes.)

<tt>'''[8]'''</tt> Since we will be setting an attribute to change the color, we specify the fill color with a presentation attribute. We can't use <tt>style</tt>, because its setting overrides the value of a presentation attribute.

<tt>'''[9]'''</tt> Here is our bridge between the SVG world and the ECMA Script world. The <tt>onmouseover</tt> event handler will call <tt>enlarge_circle</tt>, and the <tt>onmouseout</tt> event handler will call <tt>shrink_circle</tt>. In this context, <tt>evt</tt> is provided by the SVG viewer environment.

=== Changing Attributes of Multiple Objects ===

Sometimes you will want an event that occurs on object A to affect attributes of both object A and some other object B. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-19|Example 11-19]] shows possibly the world's crudest example of SVGcommerce. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-9|Figure 11-9]] shows a T-shirt whose size changes as the user clicks each labeled button. The currently selected size button is highlighted in light yellow.

<div id="svgess-CHP-11-FIG-9">
'''Figure 11-9. Screenshots of different selections'''

[[Image:SVG Essentials/I_11_tt245.png|Screenshots of different selections]]
</div>

<div id="svgess-CHP-11-EX-19">
'''Example 11-19. Changing multiple objects in a script'''

<svg width="400" height="250" viewBox="0 0 400 250"
'''onload="init(evt)"'''> '''[1]'''

<script type="text/ecmascript">
<![CDATA[

var scaleChoice = 1; '''[2]'''
var scaleFactor = new Array( 1.25, 1.5, 1.75 );

function init( evt )
{
transformShirt();
}

function setScale( n )
{
obj = svgDocument.getElementById( "scale" + scaleChoice ); '''[3]'''
obj.setAttribute( "fill", "white" );
scaleChoice = n;
obj = svgDocument.getElementById( "scale" + scaleChoice );
obj.setAttribute( "fill", "#ffc" );
transformShirt();
}

function transformShirt( )
{
var obj = svgDocument.getElementById( "shirt" ); '''[4]'''<nowiki>
obj.setAttribute( "transform",
"scale(" + scaleFactor[scaleChoice] + ")"
);
obj.setAttribute( "stroke-width",
1 / scaleFactor[scaleChoice] );
}

// ]]>
</script>

<defs>
<path id="shirt" </nowiki>'''[5]'''
d="M -6 -30, -32 -19, -25.5 -13, -22 -14, -22 30, 23 30,
23 -14, 26.5 -13, 33 -19, 7 -30
A 6.5 6 0 0 1 -6 -30"
fill="white" stroke="black"/> '''[6]'''
</defs>

<use xlink:href="#shirt" x="150" y="150"/>

<g '''onclick="setScale(0)"'''> '''[7]'''
<rect '''id="scale0"''' x="100" y="10" width="30" height="30"
fill="white" stroke="black"/>
<text x="115" y="30" text-anchor="middle">S</text>
</g>

<g onclick="setScale(1)">
<rect id="scale1" x="140" y="10" width="30" height="30"
fill="#ffc" stroke="black"/> '''[8]'''
<text x="155" y="30" text-anchor="middle">M</text>
</g>

<g onclick="setScale(2)">
<rect id="scale2" x="180" y="10" width="30" height="30"
fill="white" stroke="black"/>
<text x="195" y="30" text-anchor="middle">L</text>
</g>

</svg>
</div>

<tt>'''[1]'''</tt> As soon as the document finishes loading, the <tt>load</tt> event occurs, and the <tt>onload</tt> handler will call the <tt>init</tt> function, passing it the event information. Most scripts will use this event handler to make sure that all their variables are set up properly.

<tt>'''[2]'''</tt> This script works by keeping track of which button (S, M, or L) has been chosen, and indexing into the corresponding entry in the <tt>scaleFactor</tt> array. The default is index number one, medium.

<tt>'''[3]'''</tt> <tt>svgDocument</tt> is a reference to the entire SVG document, and we'll be using its properties and methods to access the parts of the document that we need. This entire script hinges on the use of the document's <tt>getElementById</tt> function. <tt>getElementById</tt> takes a string as its parameter, and returns the object which has that string as its <tt>id</tt>. The <tt>setScale</tt> function finds the currently chosen button and turns its fill color to white. It then updates the current choice, and changes that button's fill color to light yellow. Finally, it updates the image of the shirt.

<tt>'''[4]'''</tt> In addition, the <tt>transformShirt</tt> function calls on the document's <tt>getElementById</tt> to access the graphic object with <tt>id</tt> of <tt>shirt</tt>, and changes its <tt>transform</tt> attribute to the proper scale. It also sets the <tt>stroke-width</tt> to the reciprocal of the scaling factor so the stroke width of the shirt's border always equals one.

<tt>'''[5]'''</tt> Here's the shirt; it's centered around (0,0) so it will appear to expand around its center.

<tt>'''[6]'''</tt> Since we're changing the attributes in the script, we have to use presentation attributes here instead of styles. (If we used styles, they would override any attribute settings.)

<tt>'''[7]'''</tt> Each of the buttons will call the <tt>setScale</tt> function when clicked; the parameter gives the index for the scaling factor, and each button's <tt><rect></tt> element is named with the corresponding number at the end.

<tt>'''[8]'''</tt> The default button has a background set to light yellow when the document first loads.

=== Dragging Objects ===

Let us expand this example by adding "sliders" that can be dragged to set the color of the shirt, as shown in [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-10|Figure 11-10]].

<div id="svgess-CHP-11-FIG-10">
'''Figure 11-10. Screenshot of color sliders'''

[[Image:SVG Essentials/I_11_tt246.png|Screenshot of color sliders]]
</div>

We'll need a few more global variables in the script. The first of these, <tt>slideChoice</tt>, tells which slider (0, 1, or 2) is currently being dragged; its initial value is -1, meaning that no slider is active. We'll also use an array called <tt>rgb</tt> to hold the percent of red, green, and blue; the initial values are all 100, since the shirt is initially white.

var slideChoice = -1;
var rgb = new Array( 100, 100, 100);

We now draw the sliders themselves. The color bar and the slide indicator are drawn on a white background, and they are grouped together. The <tt>id</tt> attribute goes on the indicator <tt><line></tt> element, since its ''y''-coordinate will be changing. The event handlers will be attached to the enclosing <tt><g></tt> element. The group will then capture the mouse events that happen on any of its child elements. (This is why we drew the white background; the mouse will still track even if you drag outside the colored bar.)

<g onmousedown="startColorDrag(0)"
onmouseup="endColorDrag()"
onmousemove="doColorDrag(evt,0)"
transform="translate( 230, 10 )">
<rect x="-10" y="-5" width="40" height="110" style="fill: white;"/>
<rect x="5" y="0" width="10" height="100" style="fill: red;"/>
<line id="slide0" x1="0" y1="0" x2="20" y2="0"
style="stroke: gray; stroke-width: 2;"/>
</g>

<g onmousedown="startColorDrag(1)"
onmouseup="endColorDrag()"
onmousemove="doColorDrag(evt,1)"
transform="translate( 280, 10 )">
<rect x="-10" y="-5" width="40" height="110" style="fill: white;"/>
<rect x="5" y="0" width="10" height="100" style="fill: green;"/>
<line id="slide1" x1="0" y1="0" x2="20" y2="0"
style="stroke: gray; stroke-width: 2;"/>
</g>

<g onmousedown="startColorDrag(2)"
onmouseup="endColorDrag()"
onmousemove="doColorDrag(evt,2)"
transform="translate( 330, 10 )">
<rect x="-10" y="-5" width="40" height="110" style="fill: white;"/>
<rect x="5" y="0" width="10" height="100" style="fill: blue;"/>
<line id="slide2" x1="0" y1="0" x2="20" y2="0"
style="stroke: gray; stroke-width: 2;"/>
</g>

The corresponding functions are as follows:

/*
* Stop dragging the current slider (if any)
* and set the current slider to the one specified.
* (0 = red, 1 = green, 2 = blue)
*/
function startColorDrag( which )
{
endColorDrag( );
slideChoice = which;
}

/*
* Set slider choice to -1, indicating that no
* slider is begin dragged.
*/
function endColorDrag( )
{
slideChoice = -1;
}

/*
* Move the specified slider in response to the
* mousemove event.
*/
function doColorDrag( evt, which )
{
/*
* If no slider is active, or the event is on a
* slider other than the active one, do nothing
*/
if (slideChoice < 0 || slideChoice != which)
{
return;
}

/*
* Get the slider indicator line object, and the
* mouse position (relative to the top of the color bar)
*/
var obj = evt.getTarget();
var pos = evt.getClientY() - 10;

/* Clamp values to range 0..100 */
if (pos < 0) { pos = 0; }
if (pos > 100) { pos = 100; }

/* Move the slider line to the new mouse position */
obj = svgDocument.getElementById( "slide" + slideChoice );
obj.setAttribute("y1", pos );
obj.setAttribute("y2", pos );

/* Calculate the new color value for this slider */
rgb[slideChoice] = 100-pos;

/*
* Put together all the color values and
* change the shirt's color accordingly.
*/
var colorStr = "rgb(" + rgb[0] + "%," +
rgb[1] + "%," + rgb[2] + "%)";
obj = svgDocument.getElementById( "shirt" );
obj.setAttribute("fill", colorStr );
}

There's only one minor point to take care of — the document will respond to an <tt>onmouseup</tt> only if it occurs within the slider area. So, if you click the mouse on the red color bar, drag the mouse down to the shirt, then release the mouse button, the document will be unaware of it. When you then move the mouse over the red slider again, it will still follow the mouse. To solve this problem, we insert a transparent rectangle that completely covers the viewport, and have it respond to a mouseup event by calling <tt>stopColorDrag</tt>. It will be the first, and therefore bottom-most object in the graphic. To make the rectangle as unobtrusive as possible, it will be set to <tt>style="fill: none;"</tt>. "But wait," you interject. "A transparent area cannot respond to an event!" No, ordinarily it can't, but we can set the <tt>pointer-events</tt> attribute to <tt>visible</tt>, meaning that an object can respond to events as long as it is visible, no matter what its opacity.<ref>Other values for <tt>pointer-events</tt> let you respond to an object's events in the filled areas only (<tt>fill</tt>), outline areas only (<tt>stroke</tt>), or the fill and outline together (<tt>painted</tt>), whether visible or not. Corresponding attribute values of <tt>visibleFill</tt>, <tt>visibleStroke</tt>, and <tt>visiblePainted</tt> take the object's visibility into account as well.</ref>

<rect x="0" y="0" width="400" height="300" style="fill: none;"
onmouseup="endColorDrag()"
pointer-events="visible"/>

=== Modifying Text ===

Although the sliders do give us the interactivity we want, it's hard to judge the percentages by eye. We'd much prefer to show the percentages of red, green, and blue below each slider, as depicted in [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-11|Figure 11-11]].

<div id="svgess-CHP-11-FIG-11">
'''Figure 11-11. Screenshot of labeled color sliders'''

[[Image:SVG Essentials/I_11_tt251.png|Screenshot of labeled color sliders]]
</div>

Here's the SVG for the text underneath the red slider; the ones under the blue and green slider have <tt>id</tt>s of <tt>pct1</tt> and <tt>pct2</tt>. This element will go into a separate group from the color bar and slider line so that it does not also become clickable.

<text id="pct0" x="10" y="120"
style="font-size: 9pt; text-anchor: middle;">100%</text>

The number we want to change as we drag the mouse is not an attribute; it's the child of the <tt><text></tt> element, so we can't use <tt>setAttribute</tt> to modify the text. Instead, we have to create a new text node and insert it into the document tree in place of the old one. Here's the code that we add at the end of the <tt>doColorDrag</tt> function. The first line retrieves the <tt><text></tt> element. (The <tt>obj</tt> variable has already been declared, so we don't need to say <tt>var</tt> again.) The second line asks the document to create a new text node whose content is the percentage of the currently chosen slider. This text node needs to be placed in its proper location within the document tree. That's what the third line does; it replaces the first child of the text element with the newly created node.

obj = svgDocument.getElementById( "pct" + slideChoice );
var newText = svgDocument.createTextNode( rgb[slideChoice] + "%" );
obj.replaceChild( newText, obj.getFirstChild() );

<div class="note">
'''Note'''

You can do much more than simply modify the text in a document. You can remove elements, change their order, or even create new elements with attributes and add them to the document under script control. A list of the functions that manipulate the Document Object Model are listed in Appendix E of the World Wide Web Consortium's Document Object Model (DOM) Level 1 Specification at ''http://www.w3.org/TR/1998/REC-DOM-Level-1-19981001''. A detailed explanation of what the functions do can be found in the ''DOM Reference'' chapter of ''XML in a Nutshell'', by Elliotte Rusty Harold and W. Scott Means. Although the examples in that book use Java rather than ECMA Script, the explanations apply to both.
</div>

=== Interacting with an HTML Page ===

It is possible to embed an SVG graphic in a web page using the <tt><embed></tt> element. The relevant attributes are the <tt>src</tt> for the graphic (a URL), the <tt>width</tt> and <tt>height</tt> of the graphic, and the <tt>type</tt> attribute, which will be <tt>image/svg+xml</tt>. Once embedded, you can add code to the SVG script and the HTML page's script so they can communicate with one another.

Our goal in this example is to embed the preceding SVG example into a web page. This web page will have a form that lets users type in the red, green, and blue percentages. The values they enter will be reflected in the sliders. If they adjust the sliders, the values in the form fields will be updated accordingly.

Here is the HTML document, with references to the (as yet unwritten) <tt>updateSVG</tt> function. This function will take the input field number and the value currently within the input field.

<html>
<head>
<title>SVG and HTML</title>
</head>

<body bgcolor="white">
<h2>SVG and HTML</h2>

<div align="center">
<embed src="shirt_interact.svg"
width="400" height="250"
type="image/svg+xml" />

<form name="rgbForm">
Red: <input id="fld0" type="text" size="5" value="100"
onchange="updateSVG(0, this.value)" />% <br />
Green: <input id="fld1" type="text" size="5" value="100"
onchange="updateSVG(1, this.value)" />% <br />
Blue: <input id="fld2" type="text" size="5" value="100"
onchange="updateSVG(2, this.value)" />%
</form>
</div>
</body>
</html>

Here is the script that goes into the head of the HTML document. Function <tt>updateSVG</tt> checks to see that the input value is an integer (it will discard any decimal part), and, if so, calls <tt>setShirtColor</tt>. <tt>setShirtColor</tt> is actually a reference to a function that exists in the SVG document, and it will be the SVG document's responsibility to connect the function to this HTML reference.

Function <tt>updateHTMLField</tt> will be called from the SVG document's script. It will receive a form field number and a percent value, which it will display in the appropriate form field.

<script language="Javascript">

</script>

Let us now turn our attention to the SVG document. The parent of the document is the browser window in which it is embedded. We use the reserved word <tt>parent</tt> in the <tt>init</tt> function to connect the SVG document's <tt>svgSetShirtColor</tt> function to the HTML page's <tt>setShirtColor</tt> reference.

function init( evt )
{
'''parent.setShirtColor = svgSetShirtColor;'''
svgDocument = evt.getTarget().getOwnerDocument();
transformShirt();
}

Since there are now effectively two ways to set the color values, we'll make things more modular by rewriting <tt>doColorDrag</tt> to call the new <tt>svgSetShirtColor</tt> function:

function doColorDrag( evt, which )
{
/*
* If no slider is active, or the event is on a
* slider other than the active one, do nothing
*/
if (slideChoice < 0 || slideChoice != which)
{
return;
}

/*
* Get the slider indicator line object, and the
* mouse position (relative to the top of the color bar)
*/
var obj = evt.getTarget();
var pos = evt.getClientY() - 10;

/*
* Since pos=0 is at the 100% point on the scale,
* take 100-pos and send that to svgSetShirtColor
* along with the slider number.
*/
svgSetShirtColor( which, 100 - pos );
}

Function <tt>svgSetShirtColor</tt> will do what the remainder of <tt>doColorDrag</tt> used to do, with two major differences. It uses the slider number that it is given as the first parameter, not the global <tt>sliderChoice</tt> variable. The second parameter is now a percentage; in the original version it was the ''y''-position of the mouse. These are the sorts of changes you have to make when you decide to modularize simple code that was written for an ''ad-hoc'' example.

function svgSetShirtColor( which, percent )
{
var obj;
var colorStr;
var newText;

/* Clamp values to range 0..100 */
if (percent < 0) { percent = 0; }
if (percent > 100) { percent = 100; }

/* Move the slider line to the new mouse position */
obj = svgDocument.getElementById( "slide" + which );
'''obj.setAttribute("y1", 100-percent );'''
''' obj.setAttribute("y2", 100-percent );'''
''' rgb[which] = percent;'''

/*
* Put together all the color values and
* change the shirt's color accordingly.
*/
colorStr = "rgb(" + rgb[0] + "%," +
rgb[1] + "%," + rgb[2] + "%)";
obj = svgDocument.getElementById( "shirt" );
obj.setAttribute("fill", colorStr );

/*
* Change text to match slider position
*/
obj = svgDocument.getElementById( "pct" + which );
newText = svgDocument.createTextNode( rgb[which] + "%" );
obj.replaceChild( newText, obj.getFirstChild());
}

This code accomplishes the HTML to SVG communication. Our last step is to communicate from SVG back to HTML if the user decides to choose colors with the slider. Rather than continuously update the HTML fields, we have made the design decision to update the HTML when dragging stops. We add the boldface code to function <tt>endColorDrag</tt>. The result is shown in [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-12|Figure 11-12]]; the screenshot has been edited to eliminate unnecessary whitespace).

function endColorDrag( )
{
'''/*'''
''' * If a slider was being moved, send the slider number'''
''' * and its value back to the updateHTMLField function'''
''' * in the parent web browser window.'''
''' */'''
''' if (slideChoice >= 0)'''
''' {'''
''' parent.updateHTMLField( slideChoice, rgb[slideChoice] );'''
''' }'''

/* In any case, nobody's being dragged now */
slideChoice = -1;
}

<div id="svgess-CHP-11-FIG-12">
'''Figure 11-12. Screenshot of HTML and SVG interaction'''

[[Image:SVG Essentials/I_11_tt260.png|Screenshot of HTML and SVG interaction]]
</div>

=== Scripting and Animation Together ===

Scripting and animation can work together. You can start an animation in response to an event, and you can use the beginning, end, or repetition of an animation to invoke a function. [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-20|Example 11-20]] shows a trapezoid and a button. When you click the button, a message saying "Animation in progress" appears, and the trapezoid rotates 360 degrees. When it finishes rotating, the message disappears. Relevant screenshots are shown in [[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-13|Figure 11-13]].

<div id="svgess-CHP-11-FIG-13">
'''Figure 11-13. Screenshot of two stages of scripting with animation'''

[[Image:SVG Essentials/I_11_tt261.png|Screenshot of two stages of scripting with animation]]
</div>

<div class="note">
'''Note'''

The numbered callouts in the example are in conceptual order, not text order. I've found it easier to design the SVG first and add the scripting later. One advantage of this method is that I can see if the base drawing looks good before I start making it react to events.
</div>

<div id="svgess-CHP-11-EX-20">
'''Example 11-20. Scripting and Animation Together'''

<script type="text/ecmascript">
<![CDATA[

function init( evt )
{
/* initialization code goes here */
}

function setMessage( visStatus ) '''[1]'''<nowiki>
{
var message = svgDocument.getElementById( "message" );
message.setAttribute( "visibility", visStatus );
}

// ]]>
</script>

<g id="button"> </nowiki>'''[2]'''
<rect x="10" y="10" width="40" height="20" rx="4" ry="4"
style="fill: #ddd;"/>
<text x="30" y="25" style="text-anchor: middle;">Start</text>
</g>

<text id="message" x="60" y="25" visibility="hidden"> '''[3]'''
Animation in progress.
</text>

<g transform="translate(100, 60)">
<path d="M-25 -15, 0 -15, 25 15, -25 15 Z"
style="stroke: gray; fill: #699;">

<animateTransform id="trapezoid" attributeName="transform"
type="rotate" from="0" to="360"
begin="button.click" '''[4]'''
dur="6s"
onbegin="setMessage('visible')" '''[5]'''
onend="setMessage('hidden')"/>
</path>
</g>
</div>

<tt>'''[1]'''</tt> Here's the function, which takes the visibility status that was passed to it, and sets the message's <tt>visibility</tt> property accordingly.

<tt>'''[2]'''</tt> The start button is a simple rounded rectangle with text. The entire group gets the <tt>id</tt>.

<tt>'''[3]'''</tt> The message, initially hidden. Again, we use a presentation attribute here rather than a style, since we'll be modifying the attribute.

<tt>'''[4]'''</tt> Instead of giving the begin time for the animation in terms of seconds, we begin whenever a <tt>click</tt> event is detected on the <tt>button</tt> object. Since we're waiting for the event, we use <tt>click</tt> rather than the event handler attribute <tt>onclick</tt>.

<tt>'''[5]'''</tt> The next two lines ''are'' event handlers, so they begin with the prefix <tt>on</tt>. When the animation begins (<tt>onbegin</tt>), we call <tt>setMessage</tt> with the argument <tt>'visible'</tt>; when it ends (<tt>onend</tt>) we call the same function with the argument <tt>'hidden'</tt>.<ref>The event handler <tt>onrepeat</tt> is invoked each time an animation repeats after the first iteration.</ref>

=== Animation via Scripting ===

Because SMIL2 animation is integrated with SVG, your animations become part of the document structure. Since it's all XML, animated SVG documents remain easy for humans to read and for XML tools to process. The addition of scripting, as we showed in the preceding section, makes it possible to add some user interaction with an animation.

While animation can handle most of the things you'll want to move, there are some things the animation elements can't do easily. For example, it's hard to change a <tt><path></tt> dynamically. We're not talking about making an object move along a path (<tt><animateMotion></tt>); we want the path itself to change over time. The path isn't a transformation, so <tt><animateTransform></tt> won't work; in addition, it's not a simple numeric value, so we can't use <tt><animate></tt>. We'll have to use scripting instead.

[[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-21|Example 11-21]] uses scripting alone to repeatedly change the <tt>d</tt> attribute of the path over time. The key to doing animation via scripting is the <tt>setInterval</tt> function. <tt>setInterval</tt> sets an "alarm clock" to go off repeatedly at regular intervals. When the alarm goes off, the scripting engine performs the ECMA Script statements you want. The simplest form is:

''timer_variable'' =
setInterval( "''ECMA Script function''",
''interval time in milliseconds'');

This function returns a reference to the timer that it set. You should save that reference in a global variable so that other functions can access it. You call <tt>setInterval</tt> once, and, the <tt>''ECMA Script function''</tt> you've specified will be called every <tt>''interval''</tt> milliseconds. The repetition will continue until you call <tt>clearInterval(''timer_variable'')</tt>.

[[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-EX-21|Example 11-21]] shows a cubic Bézier curve. When the user clicks the start button, we'll move the control points every tenth of a second for five seconds (fifty movements in all). The control points will move towards each other in the ''x'' direction starting at five pixels per interval. They will move away from each other in the ''y'' direction at three-fourths of a pixel per interval. Note especially the boldfaced line and its commentary!

<div id="svgess-CHP-11-EX-21">
'''Example 11-21. Animating a path with scripting'''

<svg width="300" height="200" viewBox="0 0 300 200"
onload="init(evt)">
<script type="text/ecmascript">
<![CDATA[

/* Starting coordinates for both control points */
var cp1 = new Array( 100, 50 );
var cp2 = new Array( 200, 200 );

var moveLimit = 50; // total number of moves to make
var currentMove = 0; // current number of moves

var deltaX; // X movement amount
var deltaY; // Y movement amount

var delay = 100; // one-tenth second

var timer; // store the alarm clock

function init( evt )
{
/* do any global initialization here */
}

/*
* Initialize movement; set control points back to their
* starting positions, set the current number of moves
* to zero, and set an interval timer to move the
* control points every "delay" milliseconds.
*/
function setupMove()
{
var i;

currentMove = 0;
deltaX = 5; /* start X at five pixels per interval */
deltaY = 0.75; /* start Y at 3/4 pixels per interval */
setGraphicInfo();
timer = setInterval( "moveControlPoints()", delay );
}

function setGraphicInfo()
{
var obj;
var pathString;

/*
* Construct a path that describes a cubic
* Bezier curve using the current coordinates
* for the control points.
*/
pathString = "M 50 120 C " +
(cp1[0] + currentMove * deltaX) + " " +
(cp1[1] - currentMove * deltaY) + ", " +
(cp2[0] - currentMove * deltaX) + " " +
(cp2[1] + currentMove * deltaY) + ", " +
"250, 120";

obj = svgDocument.getElementById( "cubic" );
obj.setAttribute( "d", pathString );
}

function moveControlPoints()
{
currentMove++; // we've done one more move
setGraphicInfo(); // adjust the control points and path

/*
* If we have finished moving, clear the timer, which
* will stop the repeated wake-up calls.
*/
if (currentMove >= moveLimit)
{
clearInterval( timer );
}
}

function stopMovement()
{
clearInterval( timer );
}

'''/*'''
''' * setInterval expects its first argument to be found in'''
''' * the main window. We oblige it by creating a reference'''
''' * to this script's moveControlPoints function as a'''
''' * window property'''
''' */'''
'''window.moveControlPoints = moveControlPoints;'''<nowiki>

// ]]>
</script>

<g id="button" onclick="setupMove();">
<rect x="10" y="10" width="40" height="20" rx="4" ry="4"
style="fill: #ddd;"/>
<text x="30" y="25" style="text-anchor: middle;">Start</text>
</g>

<g id="button" onclick="stopMovement()">
<rect x="70" y="10" width="40" height="20" rx="4" ry="4"
style="fill: #ddd;"/>
<text x="90" y="25" style="text-anchor: middle;">Stop</text>
</g>

<path id="cubic" style="stroke: blue; fill: none;"
d="M 50 120 C 100 50, 200 200, 250 120" />

</svg></nowiki>
</div>

[[SVG Essentials/Animating and Scripting SVG#svgess-CHP-11-FIG-14|Figure 11-14]] shows the path in its initial and final states.

<div id="svgess-CHP-11-FIG-14">
'''Figure 11-14. Beginning and ending of scripted path change'''

[[Image:SVG Essentials/I_11_tt263.png|Beginning and ending of scripted path change]]
</div>

In this example, the <tt>moveControlPoints</tt> function didn't need any parameters. Let's say the function needed two parameters, <tt>pathColor</tt> and <tt>pathStrokeWidth</tt> To ensure that <tt>moveControlPoints</tt> got those parameters every time it was called, we would add them at the end of our call to set up the interval timer:

timer = setInterval("moveControlPoints()", delay,
pathColor, pathStrokeWidth );

<tt>setInterval</tt> <ref>Or its variant, <tt>setTimeout</tt>, which sets the timer to go off exactly once. The generic model for calling this function is:

''timer_variable'' = setTimeout( "''action_function( parameters )''", ''delay'' );

Use <tt>clearTimeout(</tt> <tt>''timer_variable''</tt> <tt>)</tt> to cancel a pending timer event.</ref> is the ''only'' safe way to script repeated actions with a delay interval. Using <tt>setInterval</tt> is like leaving a message with a desk clerk at a hotel to give you a wake-up call every hour; between calls you are free to sleep or do other things. In scripting terms, this kind of code leaves the computer free to do other tasks between actions:

function startGoodAction()
{
timer = setInterval( "doGoodAction()", delay );
}

function doGoodAction()
{
obj.setAttribute( "x", value );
value = value + increment;
repetitions = repetitions + 1;
if ( repetitions == limit )
{
clearInterval( timer );
}
}

Beginning programmers will often do something like this:

function doBadAction()
{
obj.setAttribute( "x", value );
value = value + increment;
if ( repetitions != limit )
{
waitCount = 0;
while (waitCount < waitLimit)
waitCount++;
doBadAction();
}
}

This technique is akin to constantly looking at your watch and asking, "Is it time yet?" This gives you no time to sleep or do anything else. In an SVG script, it gives the computer little chance to attend to other tasks. Additionally, this uses a ''recursive'' style, which, if not carefully controlled, can consume your system resources faster than you can say "Error: stack overflow."

Though the preceding example was a simple one, this technique has great power. If you choose to use scripting to do animation, you will then have available all the interactivity features of scripting; you can make animation dependent on mouse position or complex conditions involving multiple variables. If you're doing simple animation, we recommend that you use SVG's animation elements.
== Notes ==

<references/>