Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-base-animations.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Animations}
12 \label{section-base-animations}
13
14 \begin{pgfmodule}{animations}
15 This module contains the basic layer support of animations, which is
16 documented in the following.
17 \end{pgfmodule}
18
19 This section described the basic layer support of animations, the \tikzname\
20 support is described in Section~\ref{section-tikz-animations}. As always,
21 \tikzname\ mainly converts syntactic constructs (like the special colon or
22 quote syntax) to appropriate basic layer commands, which are documented here.
23 Note, however, that while many attributes and options are the same on both
24 layers, some things are handled differently on the basic layer.
25
26
27 \subsection{Overview}
28
29 An \emph{animation} changes the way some part of a graphic looks like over
30 time. The archetypical animation is, of course, a \emph{movement} of node, but
31 a change of, say, the opacity of a path is also an animation. \pgfname\ allows
32 you to specify such animations using a set of commands and keys that are
33 documented in the following.
34 %
35 \begin{codeexample}[
36 preamble={\usepgfmodule{animations}},
37 animation list={0.5,1,1.5,2},
38 ]
39 \tikz {
40 \pgfanimateattribute{opacity}{
41 whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
42 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
43 }
44 \end{codeexample}
45
46 Differently from other packages, the animations created by \pgfname\ are not
47 precomputed sequences of pictures that are displayed in rapid succession.
48 Rather, an animation created by \pgfname\ consists mainly of an annotation in
49 the output that a certain attribute of a certain object should change over time
50 in some specific way when the object is displayed. It is the job of the
51 document viewer application to actually compute and display the animation.
52 Interestingly, this means that animations neither increase the size of the
53 output files noticeably nor does it put a special burden on \TeX. The hard and
54 complicated calculations are done by the viewer application, not by \TeX\ and
55 \pgfname.
56
57 Only few viewer applications and formats are currently ``up to the job'' of
58 displaying animations. In particular, the popular \textsc{pdf} format does
59 \emph{not} allow one to specify animations in this way (one can partly ``fake''
60 animations at the high price of including a great number of precomputed
61 pictures and using JavaScript in special viewers, but this is really not the
62 same thing as what \pgfname\ does). Indeed, currently only the \textsc{svg}
63 format allows one to specify animations in a sensible way. Thus, \pgfname's
64 animations will only be displayed when \textsc{svg} is used as output format.
65
66 Because of the shortcomings of the other formats and, also, for purposes of
67 printing and depicting animations in a sequential manner, \pgfname\ also allows
68 you to create ``snapshots'' of animations. As an example, the following code
69 shows how the same drawing is shown at different ``time snapshots'':
70 %
71 \begin{codeexample}[
72 width=3.9cm,
73 preamble={\usetikzlibrary{animations}
74 \def\pgfname{\textsc{pgf}}
75 }]
76 \tikz [make snapshot of=0.5s] \scoped :rotate = { 0s = "0", 2s = "90" }
77 \node [draw=blue, very thick] {\pgfname};
78 \tikz [make snapshot of=1s] \scoped :rotate = { 0s = "0", 2s = "90" }
79 \node [draw=blue, very thick] {\pgfname};
80 \tikz [make snapshot of=1.5s] \scoped :rotate = { 0s = "0", 2s = "90" }
81 \node [draw=blue, very thick] {\pgfname};
82 \tikz [make snapshot of=2s] \scoped :rotate = { 0s = "0", 2s = "90" }
83 \node [draw=blue, very thick] {\pgfname};
84 \end{codeexample}
85
86
87 \subsection{Animating an Attribute}
88
89 \subsubsection{The Main Command}
90
91 Creating an animation is done using the command |\pgfanimateattribute|, which
92 takes a to-be-animated attribute and options specifying the timeline:
93
94 \begin{command}{\pgfanimateattribute\marg{attribute}\marg{options}}
95 Adds an animation of the \meta{attribute} of a future \emph{object} to the
96 current graphic. Attributes are things like the ``fill opacity'' or the
97 transformation matrix or the line width.
98
99 The \meta{options} are keys that configure how the attribute changes over
100 time. Using the |entry| key multiple times, you specify which value the
101 chosen attribute should have at different points in time. Unless special
102 keys are used, ``outside'' the specified timeline the animation has no
103 effect:
104 %
105 \begin{codeexample}[
106 preamble={\usepgfmodule{animations}},
107 animation list={0.5,1,1.5,2,2.5},
108 ]
109 \tikz {
110 \pgfanimateattribute{opacity}{
111 whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
112 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
113 }
114 \end{codeexample}
115
116 Other keys, like |repeats|, allow you to specify how the animation behaves
117 ``as a whole''. These keys are documented later in this section.
118
119
120 \medskip
121 \textbf{The Attributes}
122
123 In detail, the |\pgfanimateattribute| command opens a \TeX-scope, looks up
124 the \emph{type} values of the specified \meta{attribute} have (if you wish
125 to animate the |opacity| of an object, the type is ``scalar'' meaning that
126 entries must be scalar numbers; when you animate the |fill| attribute, the
127 type is ``color'' and values must be colors, and so on), and then executes
128 the \meta{options} with the path prefix |/pgf/animation|. Finally, an
129 appropriate system layer command |\pgfsysanimate...| is called to create
130 the actual animation and the scope is closed.
131
132 The following \meta{attributes} are permissible:
133
134 \begin{tabular}{ll}
135 \emph{Attribute} & \emph{Type} \\
136 |draw|, |fill| & color \\
137 |line width| & dimension \\
138 |motion| & scalar \\
139 |opacity|, |fill opacity|, |draw opacity| & scalar \\
140 |path| & path \\
141 |rotate| & scalar \\
142 |scale| & scaling \\
143 |softpath| & softpath \\
144 |translate| & point \\
145 |view| & viewbox \\
146 |visible| & boolean \\
147 |stage| & boolean \\
148 |xskew|, |yskew| & scalar \\
149 \end{tabular}
150
151 These attributes are detailed in Sections
152 \ref{section-base-animation-painting}
153 to~\ref{section-base-animation-views}, but here is a quick overview:
154 %
155 \begin{itemize}
156 \item |draw| and |fill| refer to the color used to draw (stroke) and
157 fill paths in an object, respectively. Typical values for this
158 attribute are |red| or |black!10|.
159 \item |line width| is, of course, the line width used in an object.
160 Typical values are |0.4pt| or |1mm|. Note that you (currently)
161 cannot use keys like |thin| or |thick| here, but this may change in
162 the future.
163 \item |motion| is a slightly special attribute: It allows you to
164 specify a path along which the object should be moved (using the
165 |along| key). The values given to the |entry| key for this
166 attribute refer to a \emph{fraction of the distance along the
167 path}. See the |along| key for details.
168 \item |opacity| and the variants |fill opacity| and |draw opacity|
169 animate the opacity of an object. Allowed values range between 0
170 and 1.
171 \item |path| allows you to animate a path (it will morph). The
172 ``values'' are now paths themselves. See
173 Section~\ref{section-base-animation-paths} for details.
174 \item |rotate| refers to a rotation of the object. Values for the
175 |entry| key are the rotation angles like |0| or |90|.
176 \item |scale| refers to the scaling of the object. Values are either
177 single scalars values (like |1| or |1.5|) or two numbers separated
178 by a comma (like |1,1.5| or |0.5,2|), referring to the $x$-scaling
179 and $y$-scaling.
180 \item |softpath| is a special case of the |path| attribute, see
181 Section~\ref{section-base-animation-paths} once more.
182 \item |translate| shifts the object by a certain vector. Values are
183 points like |\pgfpoint{1cm}{2cm}|.
184 \item |view| allows you to animate the view box of a view, see
185 Section~\ref{section-base-animation-views} for details.
186 \item |visible| refers to the visibility of an object. Allowed values
187 are |true| and |false|.
188 \item |stage| is identical to |visible|, but when the object is not
189 animated, it will be hidden by default.
190 \item |xskew| and |yskew| skew the object. Attributes are angles like
191 |0| or |45| or even |90|.
192 \end{itemize}
193
194
195 \medskip
196 \textbf{The Target Object}
197
198 As stated earlier, the \meta{options} are used to specify the object whose
199 attribute for which an animation should be added to the picture. Indeed,
200 you \emph{must} specify the object explicitly using the |whom| key and you
201 must do so \emph{before} the object is created. Note that, in contrast, in
202 \textsc{svg} you can specify an animation more or less anywhere and then
203 use hyper-references to link the animation to the to-be-animated object;
204 \pgfname\ insists that you specify the animation before the object. This is
205 a bit of a bother in some situations, but it is the only way to ensure that
206 \pgfname\ has a fighting chance to attach some additional code to the
207 object (which is necessary for almost all animations of the transformation
208 matrix).
209
210 \begin{key}{/pgf/animation/whom=\meta{id}\opt{|.|\meta{type}}}
211 You \emph{must} use this key once which each call of the
212 |\pgfanimateattribute| command. The \meta{id} and the optional
213 \meta{type} (which is whatever follows the first dot) will be passed to
214 |\pgfidrefnextuse|, see that command for details.
215 \end{key}
216
217 As explained in the introduction of this chapter, an ``animation'' is just
218 a bit of special text in the output document asking a viewer application to
219 animate the object at some later time. The |\pgfanimateattribute| command
220 inserts this special text immediately, even though it refers to an object
221 created only later on. Normally, this is not a problem, but the special
222 text should be on the same page as the to-be-animated object. To ensure
223 this, it suffices to call |\pgfanimateattribute| no earlier than the
224 beginning of the |pgfpicture| containing the object.
225
226
227 \medskip
228 \textbf{Naming the Animation}
229
230 You can assign a name to an animation for later (or early) reference. In
231 particular, it is possible to begin \emph{another} animation relative to
232 the beginning or end of this animation and for referencing this animation
233 must be assigned a name. See the |of| and |of next| keys for details.
234
235 \begin{key}{/pgf/animation/name=\meta{name}}
236 Assigns a name to the animation by which it can be referenced using the
237 |of| and |of next| keys in another animation.
238 %
239 \begin{codeexample}[
240 preamble={\usepgfmodule{animations}},
241 animation list={.5,1,1.5,2,2.5,3,3.5,4,4.5,5,5.5,6},
242 ]
243 \tikz [very thick] {
244 \pgfanimateattribute{rotate}{
245 whom = node, begin on = {end, of next = my move animation, delay = 1s},
246 entry = {0s}{0}, entry = {2s}{90}, begin snapshot = 3s, }
247 \pgfanimateattribute{translate}{
248 name = my move animation, whom = node, begin on = {click},
249 entry = {0s}{\pgfpointorigin}, entry = {2s}{\pgfpoint{0cm}{-5mm}} }
250 \node (node) [fill = blue!20, draw = blue, circle] {Here!};
251 }
252 \end{codeexample}
253 \end{key}
254 \end{command}
255
256 \begin{command}{\pgfanimateattributecode\marg{attribute}\marg{code}}
257 The command works like |\pgfanimateattribute|, only instead of
258 \meta{options} you specify some \meta{code} whose job is to setup the
259 options.
260 \end{command}
261
262
263 \subsubsection{Specifying the Timeline}
264
265 The core key for specifying how an attribute varies over time is the |entry|
266 key:
267 %
268 \begin{key}{/pgf/animation/entry=\marg{time}\marg{value}}
269 You use this key repeatedly to specify the different values that the
270 \meta{attribute} should have over time. At the \meta{time} specified, the
271 \meta{attribute} will have the value specified as \meta{value}:
272 %
273 \begin{codeexample}[
274 preamble={\usepgfmodule{animations}},
275 animation list={.5,1,1.5,2},
276 ]
277 \tikz {
278 \pgfanimateattribute{rotate}{
279 whom = node, begin on = {click},
280 entry = {0s}{0}, entry = {1s}{90}, entry = {1.1s}{45}, entry = {2s}{90}
281 }
282 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
283 }
284 \end{codeexample}
285
286 You need to call |entry| once for each time in the timeline for which you
287 want to specify a \meta{value} explicitly. Between these times, the values
288 get interpolated (see below for details). You need to specify the
289 \meta{time}s in non-decreasing order (it is permissible and sometimes also
290 necessary to specify the same time twice, namely to create a ``jump'' of
291 the value of some attribute).
292
293 The \meta{time} is parsed using the command |\pgfparsetime| described
294 later.
295
296
297 \medskip
298 \textbf{Start and end of the timeline.}
299 The first and last times of the timeline are a bit special: The timeline
300 starts on the first time and the duration of the timeline is the difference
301 between the first and last time. ``Starting'' on the start time actually
302 means that any beginnings (see the |begin| and |end| keys) get offset by
303 the start time; similarly end times are offset by this value.
304
305
306 \medskip
307 \textbf{Syntax of the values.}
308 The syntax of the \meta{value} varies according to the type of the
309 \meta{attribute}. In detail, these are:
310
311 \begin{tabular}{lp{12cm}}
312 \emph{Type} & \emph{Syntax} \\
313 color & Standard color syntax like |red| or |black!10| \\
314 scalar & A value parsed using |\pgfmathparse| \\
315 dimension & A dimension parsed using |\pgfmathparse| \\
316 path & A sequence of path construction commands \\
317 softpath & A sequence of soft path construction commands \\
318 scaling & A scalar value or a pair of scalar values separated by a comma \\
319 point & A \pgfname-point like |\pgfpoint{1cm}{5mm}| \\
320 viewbox & Two \pgfname-points \\
321 boolean & |true| or |false| \\
322 \end{tabular}
323
324
325 \medskip
326 \textbf{Interpolation between key times.}
327 You use the |entry| key repeatedly, namely once for each ``key time'',
328 which is a time point for which you specify the value of the attribute
329 explicitly. Between these key times, the attribute's value is interpolated.
330 Normally, this is just a linear interpolation, but you can influence this
331 using the following keys, see Section~\ref{section-anim-smooth} for
332 details.
333
334 \begin{key}{/pgf/animations/exit control=\marg{time fraction}\marg{value fraction}}
335 Same as |/tikz/animate/options/exit control|.
336 %
337 \begin{codeexample}[
338 preamble={\usepgfmodule{animations}},
339 animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}},
340 ]
341 \tikz {
342 \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
343 \pgfanimateattribute{translate}{
344 whom = node, begin on = {click},
345 exit control={1}{0},
346 entry = {0s}{\pgfpointorigin},
347 linear, % revert to default
348 entry = {1s}{\pgfpoint{0cm}{-5mm}},
349 entry control={0}{1},
350 entry = {2s}{\pgfpoint{0cm}{-10mm}} }
351 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
352 }
353 \end{codeexample}
354 \end{key}
355
356 \begin{key}{/pgf/animations/entry control=\marg{time fraction}\marg{value fraction}}
357 Works like |exit control|.
358 \end{key}
359
360 \begin{key}{/pgf/animations/linear}
361 A shorthand for |exit control={0}{0}, entry control={1}{1}|. This will
362 (re)install a linear curve.
363 \end{key}
364
365 \begin{key}{/pgf/animations/stay}
366 Same as |/tikz/animate/options/stay|.
367 %
368 \begin{codeexample}[
369 preamble={\usepgfmodule{animations}},
370 animation list={0.5,1,1.5,2,2.5},
371 ]
372 \tikz {
373 \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
374 \pgfanimateattribute{translate}{
375 whom = node, begin on = {click},
376 entry = {0s}{\pgfpointorigin},
377 stay,
378 entry = {1s}{\pgfpoint{0cm}{-5mm}},
379 linear,
380 entry = {2s}{\pgfpoint{0cm}{-10mm}},
381 entry = {3s}{\pgfpoint{0cm}{-15mm}} }
382 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
383 }
384 \end{codeexample}
385 \end{key}
386
387 \begin{key}{/pgf/animations/jump}
388 Same as |/tikz/animate/options/jump|.
389 %
390 \begin{codeexample}[
391 preamble={\usepgfmodule{animations}},
392 animation list={0.5,1,1.5,2},
393 ]
394 \tikz {
395 \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
396 \pgfanimateattribute{translate}{
397 whom = node, begin on = {click},
398 entry = {0s}{\pgfpointorigin},
399 jump,
400 entry = {1s}{\pgfpoint{0cm}{-1cm}},
401 linear,
402 entry = {2s}{\pgfpoint{0cm}{-2cm}} }
403 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
404 }
405 \end{codeexample}
406 \end{key}
407 \end{key}
408
409 When the time of an animation lies outside the timeline specified by the
410 |entry| keys, no animation is present. This means that the value of the
411 attribute is the object's scope is used instead. Using the following key, you
412 can set this value directly:
413
414 \begin{key}{/tikz/animations/base=\meta{value}}
415 The syntax of the \meta{value} is the same as for the |entry| key. The
416 \meta{value} is installed as the value of the object's attribute whenever
417 the timeline is not active. This makes it easy to specify the value of an
418 attribute when the animation is ``not running''.
419 %
420 \begin{codeexample}[
421 preamble={\usepgfmodule{animations}},
422 animation list={-1,0,1,2,3},
423 ]
424 \tikz {
425 \pgfanimateattribute{rotate}{
426 whom = node, begin on = {click},
427 entry = {0s}{90}, entry = {2s}{180},
428 base = 45
429 }
430 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
431 }
432 \end{codeexample}
433 %
434 \end{key}
435
436 It may happen that there is more than one timeline active that is ``trying to
437 modify'' a given attribute. In this case, the following rules are used to
438 determine, which timeline ``wins'':
439 %
440 \begin{enumerate}
441 \item If no animation is active at the current time (all animation either
442 have not yet started or they have already ended), then the base value
443 given in the animation encountered last in the code is used. (If there
444 are no base values, the attribute is taken from the surrounding scope.)
445 \item If there are several active animations, the one that has started last
446 is used and the its value is used.
447 \item If there are several active animations that have started at the same
448 time, the one that comes last in the code is used.
449 \end{enumerate}
450
451 Note that these rules do not apply to transformations of the canvas since these
452 are always additive (or, phrased differently, they are always all active and
453 the effects accumulate).
454
455 \begin{command}{\pgfparsetime\marg{time}}
456 This command works like |\pgfmathparse| (indeed, it calls is internally),
457 but returns the result in the macro |\pgftimeresult| rather than
458 |\pgfmathresult|. Furthermore, the following changes are installed:
459 %
460 \begin{itemize}
461 \item The postfix operator |s| is added, which has no effect.
462 \item The postfix operator |ms| is added, which divides a number by
463 1000, so |2ms| equals 0.002s.
464 \item The postfix operator |min| is added, which multiplies a number by
465 60.
466 \item The postfix operator |h| is added, which multiplies a number by
467 3600.
468 \item The infix operator |:| is redefined, so that it multiplies its
469 first argument by 60 and adds the second. This implies that |1:20|
470 equals 80s and |01:00:00| equals 3600s.
471 \item The parsing of octal numbers is switched off to allow things like
472 |01:08| for 68s.
473 \end{itemize}
474 \end{command}
475
476
477 \subsubsection{``Anti-Animations'': Snapshots}
478
479 There are a number of situations in which you want the ``opposite'' of an
480 animation to happen: You want to create a ``still image''. For instance, when
481 you want to print an animation you will typically wish to show one or more
482 ``temporal snapshots'' of the animation. Also, you may wish to specify a value
483 for an object when it is \emph{not} being animated.
484
485 Let us start with creating a snapshot:
486
487 \begin{command}{\pgfsnapshot\marg{time}}
488 When this command is used inside a \TeX\ scope, the behavior of
489 |\pgfanimateattribute| changes: Instead of adding an animation to the
490 object and the attribute, the object's attribute is set to value it would
491 have during the animation at time \meta{time}. Note that when this command
492 is used in a \TeX\ scope, no animation is created and no support by the
493 driver is needed (so, it works with \textsc{pdf}).
494 %
495 \begin{codeexample}[preamble={\usetikzlibrary{animations}}]
496 \tikz [make snapshot of=1s,
497 animate = { myself: = {
498 :rotate = { 0s = "0", 2s = "90" },
499 :color = { 0s = "red", 2s = "green" },
500 :line width = { 0s = "0mm", 4s = "4mm" }
501 }}]
502 \node [fill=black!20, draw] { Node };
503 \end{codeexample}
504
505
506 \medskip\textbf{Timing and Events.}
507 The timeline of an animation normally starts at a ``moment |0s|'' and the
508 \meta{time} is considered relative to this time. For instance, if a
509 timeline contains, say, the settings |entry={2s}{0}| and |entry={3s}{10}|
510 and \marg{time} is set to |2.5s|, then the value the attribute will get is
511 5.
512
513 It is, however, also possible to specify that animations begin and end at
514 certain times relative to events like a |click| event. \emph{These events
515 are not relevant with respect to snapshots.} However, there is one key that
516 allows you to specify the beginning of the snapshot timeline:
517 %
518 \begin{key}{/tikz/animations/begin snapshot=\meta{begin time}}
519 When this key is used inside the options of |\pgfanimateattribute|,
520 with respect to snapshots, the timeline begins at \meta{begin time}.
521 This means that, if the snapshot time is set to \meta{time} and the
522 beginning of the snapshot's timeline is set to \meta{begin time}, the
523 attribute is set to the value of the timeline at time $\meta{time} -
524 \meta{begin time}$.
525
526 The idea is that when you make a snapshot of several animations and all
527 of them have started at different times because of different events,
528 you use |begin snapshot| with each object and attribute to directly
529 specify when these different events have happened.
530 \end{key}
531
532 Note that the |end| keys have no effect with snapshots, that is, with a
533 snapshot all animations always run till the end of the timeline (which may
534 or may not be ``forever'').
535
536
537 \medskip\textbf{Limitations.}
538 For snapshots, the value an animation has at time \meta{time} must be
539 computed by \TeX. While in many cases this is easy to achieve, in some
540 cases this is not trivial such as a timeline for a path with repeats plus
541 smoothing via splines. An additional complication is the fact that an
542 animation may be specified at a place far removed from the actual
543 to-be-animated object. For these reasons, certain limitations apply to
544 snapshots:
545 %
546 \begin{itemize}
547 \item The |begin| and |begin on| keys have no effect (but
548 |begin snapshot| has one.
549 \item The |end| and |end on| keys have no effect.
550 \item The |current value| may not be used in a timeline (since
551 \pgfname\ cannot really determine this value).
552 \item The |accumulating| specification may not be used with paths,
553 views, or motions.
554 \item Since the timing computations are done using \TeX\ code, they are
555 not necessarily stable. For instance, when a time interval is very
556 small and there are many repeats or when a spline is very
557 complicated, the calculated values may not be fully accurate.
558 \end{itemize}
559 \end{command}
560
561 \begin{command}{\pgfsnapshotafter\marg{time}}
562 This command works exactly like |\pgfsnapshot| only the ``moment'' that
563 \meta{time} refers to is conceptually $\meta{time} + \epsilon$: When
564 timeline specifies several values for \meta{time}, this command will select
565 the last value at \meta{time}, while |\pgfsnapshot| will select the first
566 value at \meta{time}. Similarly, when a timeline ends at \meta{time},
567 |\pgfsnapshot| will select the last value of the timeline while
568 |\pgfsnapshotafter| will not apply the animation any more:
569 %
570 \begin{codeexample}[preamble={\usepgfmodule{animations}}]
571 \foreach \t in {0,1,2,3,4} {
572 \pgfsnapshot{\t}
573 \tikz :rotate = { 0s = "0", 2s = "90", 2s = "180", 4s = "270" }
574 \node [draw=blue, very thick] {f}; }
575 \end{codeexample}
576 %
577 \begin{codeexample}[preamble={\usepgfmodule{animations}}]
578 \foreach \t in {0,1,2,3,4} {
579 \pgfsnapshotafter{\t}
580 \tikz :rotate = { 0s = "0", 2s = "90", 2s = "180", 4s = "270" }
581 \node [draw=blue, very thick] {f}; }
582 \end{codeexample}
583 %
584 \end{command}
585
586
587 \subsection{Animating Color, Opacity, Visibility, and Staging}
588 \label{section-base-animation-painting}
589
590 \begin{animateattribute}{fill}
591 You can animate the color of the target object of an animation using the
592 attributes |fill| or |draw|, which animate the fill color and the drawing
593 (stroking) color, respectively. To animate both the fill and draw color,
594 you need to create two animations, one for each.
595 %
596 \begin{codeexample}[
597 preamble={\usepgfmodule{animations}},
598 animation list={0.5,1,1.5,2},
599 ]
600 \tikz {
601 \pgfanimateattribute{fill}{
602 whom = node.background, begin on = {click},
603 entry = {0s}{white}, entry = {2s}{red} }
604 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
605 }
606 \end{codeexample}
607 %
608 \end{animateattribute}
609
610 \begin{animateattribute}{draw}
611 \begin{codeexample}[
612 preamble={\usepgfmodule{animations}},
613 animation list={0.5,1,1.5,2},
614 ]
615 \tikz {
616 \pgfanimateattribute{draw}{
617 whom = node.background, begin on = {click},
618 entry = {0s}{white}, entry = {2s}{red} }
619 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
620 }
621 \end{codeexample}
622 \end{animateattribute}
623
624 When the target of a color animation is a scope, you animate the color ``used
625 in this scope'' for filling or stroking. However, when an object inside the
626 scope has its color set explicitly, this color overrules the color of the
627 scope:
628 %
629 \begin{codeexample}[
630 preamble={\usepgfmodule{animations}},
631 animation list={0.5,1,1.5,2},
632 animation bb={(1.5,-0.75) rectangle (3,0.75)},
633 ]
634 \tikz {
635 \pgfanimateattribute{fill}{
636 whom = example, begin on = {click, of next=node},
637 entry = {0s}{white}, entry = {2s}{red} }
638 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
639 \begin{scope}[name = example]
640 \fill (1.5,-0.75) rectangle ++ (1,1);
641 \fill [blue] (2,-0.25) rectangle ++ (1,1);
642 \end{scope}
643 }
644 \end{codeexample}
645
646 Note that in certain cases, a graphic scope may contain graphic objects with
647 their colors set explicitly ``in places where you do not expect it'': In
648 particular, a node normally consists at least of a background path and a text.
649 For both the text and for the background path, colors will be set for the text
650 and also for the path explicitly. This means that when you pick the fill
651 attribute of a node as the target of an animation, you will \emph{not} animate
652 the color of the background path in case this color has been set explicitly.
653 Instead, you must choose the background path of the node as the target of the
654 animation. Fortunately, this is easy to achieve since when the background path
655 of a node is created, the identifier type is set to |background|, which in turn
656 allows you to access it as \meta{node}|.background| through the |whom| key.
657
658 The text of a node also gets it color set explicitly, which means that a change
659 of the node's scope's color has no effect on the text color. Instead, you must
660 choose \meta{name}|.text| as the target (or, if the node has more parts, use
661 the name of the part as the identifier type instead of |text|).
662 %
663 \begin{codeexample}[
664 preamble={\usepgfmodule{animations}},
665 animation list={0.5,1,1.5,2},
666 animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
667 ]
668 \tikz {
669 \pgfanimateattribute{fill}{
670 whom = example, begin on = {click, of next=node},
671 entry = {0s}{white}, entry = {2s}{red} }
672 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
673 \node at (2,0) (example) [fill = blue!20, circle] {No effect}; }
674 \end{codeexample}
675
676 \begin{codeexample}[
677 preamble={\usepgfmodule{animations}},
678 animation list={0.5,1,1.5,2},
679 animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
680 ]
681 \tikz {
682 \pgfanimateattribute{fill}{
683 whom = example.background, begin on = {click, of next=node},
684 entry = {0s}{white}, entry = {2s}{red} }
685 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
686 \node at (2,0) (example) [fill = blue!20, circle] {Effect}; }
687 \end{codeexample}
688
689 \begin{codeexample}[
690 preamble={\usepgfmodule{animations}},
691 animation list={0.5,1,1.5,2},
692 animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
693 ]
694 \tikz {
695 \pgfanimateattribute{fill}{
696 whom = example.text, begin on = {click, of next=node},
697 entry = {0s}{white}, entry = {2s}{red} }
698 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
699 \node at (2,0) (example) [fill = blue!20, circle, font=\huge] {Text}; }
700 \end{codeexample}
701
702 Similarly to the color, you can also set the opacity used for filling and for
703 drawing. You specify the opacity using a number between 0 (transparent) and 1
704 (opaque).
705
706 \begin{animateattribute}{fill opacity}
707 \begin{codeexample}[
708 preamble={\usepgfmodule{animations}},
709 animation list={0.5,1,1.5,2},
710 ]
711 \tikz {
712 \pgfanimateattribute{fill opacity}{
713 whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
714 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
715 }
716 \end{codeexample}
717 \end{animateattribute}
718
719 \begin{animateattribute}{draw opacity}
720 \begin{codeexample}[
721 preamble={\usepgfmodule{animations}},
722 animation list={0.5,1,1.5,2},
723 ]
724 \tikz {
725 \pgfanimateattribute{draw opacity}{
726 whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
727 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
728 }
729 \end{codeexample}
730 \end{animateattribute}
731
732 \begin{animateattribute}{opacity}
733 Unlike colors, where there is no joint attribute for filling and stroking,
734 there is a single |opacity| attribute in addition to the above two
735 attributes. If supported by the driver, it treats the graphic object to
736 which it is applied as a transparency group. In essence, ``this attribute
737 does what you want'' at least in most situations.
738 %
739 \begin{codeexample}[
740 preamble={\usepgfmodule{animations}},
741 animation list={0.5,1,1.5,2},
742 ]
743 \tikz {
744 \pgfanimateattribute{opacity}{
745 whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
746 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
747 }
748 \end{codeexample}
749 %
750 \end{animateattribute}
751
752 \begin{animateattribute}{visible}
753 The difference between the |visible| attribute and an opacity of |0| is
754 that an invisible object cannot be clicked and does not need to be
755 rendered. The (only) two possible values for this attribute are |false| and
756 |true|.
757 %
758 \begin{codeexample}[
759 preamble={\usepgfmodule{animations}},
760 animation list={1,2,3,4},
761 ]
762 \tikz {
763 \pgfanimateattribute{visible}{
764 whom = node, begin on = {click}, entry = {0s}{false}, entry = {2s}{false} }
765 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
766 }
767 \end{codeexample}
768 %
769 \end{animateattribute}
770
771 \begin{animateattribute}{stage}
772 This attribute is the same as the |visible| attribute, only |base=false| is
773 set by default. This means that the object is \emph{only} visible when you
774 explicitly during the time the entries are set to |true|. The idea behind
775 the name ``stage'' is that the object is normally ``off stage'' and when
776 you explicitly set the ``stage attribute'' to |true| the object ``enters''
777 the stage and ``leaves'' once more when it is no longer ``on stage''.
778 %
779 \begin{codeexample}[
780 preamble={\usepgfmodule{animations}},
781 animation list={-1,0,1,2,3},
782 animation bb={(1.3,-0.7) rectangle (2.7,0.7)},
783 ]
784 \tikz {
785 \pgfanimateattribute{stage}{
786 whom = example, begin on = {click, of next=node},
787 entry = {0s}{true}, entry = {2s}{true} }
788 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
789 \node at (2,0) (example) [fill = blue!20, circle] {Effect}; }
790 \end{codeexample}
791 %
792 \end{animateattribute}
793
794
795 \subsection{Animating Paths and their Rendering}
796 \label{section-base-animation-paths}
797
798 You can animate the appearance of a path in the following ways:
799
800 \begin{animateattribute}{line width}
801 \begin{codeexample}[
802 preamble={\usepgfmodule{animations}},
803 animation list={0.5,1,1.5,2},
804 ]
805 \tikz [very thick] {
806 \pgfanimateattribute{line width}{
807 whom = node, begin on = {click}, entry = {0s}{1pt}, entry = {2s}{5mm} }
808 \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
809 }
810 \end{codeexample}
811 %
812 The possible values passed to the |entry| key are, of course, dimensions.
813 \end{animateattribute}
814
815 \begin{animateattribute}{dash}
816 \begin{codeexample}[
817 preamble={\usepgfmodule{animations}},
818 animation list={0.5,1,1.5,2},
819 ]
820 \tikz {
821 \pgfanimateattribute{dash}{
822 whom = node, begin on = {click}, entry = {0s}{{{10pt}{1pt}}{0pt}},
823 entry = {2s}{{{1pt}{10pt}}{0pt}} }
824 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
825 }
826 \end{codeexample}
827 %
828 \begin{codeexample}[
829 preamble={\usepgfmodule{animations}},
830 animation list={0.5,1,1.5,2},
831 ]
832 \tikz {
833 \pgfanimateattribute{dash}{
834 whom = node, begin on = {click}, entry = {0s}{{{1cm}{1pt}}{0pt}},
835 entry = {2s}{{{1cm}{1pt}}{1cm}} }
836 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
837 }
838 \end{codeexample}
839 %
840 To specify the dash pattern, you specify a sequence of ``on and off''
841 dimensions; see |\pgfsetdash| for details. Note that you \emph{must}
842 specify the same number of elements in all patterns of a timeline: You
843 cannot specify that the dash pattern for |1s| is |{1pt}{2pt}| and for |2s|
844 is |{1pt}{3pt}{2pt}| since the number of elements would differ. In
845 particular, you cannot (sensibly) use |current value| for the first entry
846 since this corresponds to an empty dash pattern (even when you have
847 specified a dash pattern for the target object: this pattern will not be
848 attached to the to-be-animated scope or object but to a surrounding scope
849 and, thus, the to-be-animated scope will not have any dash pattern
850 installed).
851 \end{animateattribute}
852
853 \begin{animateattribute}{path}
854 You can animate the path itself:
855 %
856 \begin{codeexample}[
857 preamble={\usepgfmodule{animations}},
858 animation list={0.5,1,1.5,2},
859 ]
860 \tikz {
861 \pgfanimateattribute{path}{
862 whom = node.background.path, begin on = {click, of next=node},
863 entry = {0s}{\pgfpathellipse{\pgfpointorigin}
864 {\pgfpointxy{1}{0}}{\pgfpointxy{0}{1.5}}},
865 entry = {2s}{\pgfpathellipse{\pgfpointxy{.5}{0}}
866 {\pgfpointxy{.5}{.5}}{\pgfpointxy{0.25}{.25}}}}
867 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
868 }
869 \end{codeexample}
870 %
871 The path is specified by giving path construction commands as in the above
872 example. They will be executed in a special protected scope to ensure that
873 they have only little side effects.
874
875 As for the dash pattern, you must ensure that all paths in the timeline
876 have the same structure (same sequence of path construction commands); only
877 the coordinates may differ. In particular, you cannot say that the path at
878 |1s| is a rectangle using |\pgfpathrectangle| and at |2s| is a circle using
879 |\pgfpathcircle|. Instead, you would have to ensure that at both times that
880 path consists of appropriate Bézier curves.
881
882 Unlike the dash pattern, the to-be-animated object is, indeed, the path
883 itself and not some special scope. This means that you can use the
884 |current value| for the start path. However, this also means that you
885 really must pick \emph{the path object} as the target of the animation. In
886 conjunction with \tikzname, this will be an object of type |path| as in the
887 above example.
888
889 When a path is animated, it cannot have ``normal'' arrows attached to it
890 since due to the way \pgfname\ adds arrow tips to paths, these would not
891 ``move along'' with the path (you get an error message if you try).
892 However, it still \emph{is} possible to add arrow tips to an animated path,
893 only you need to use the |arrows| key described next.
894
895 Concerning the bounding box computation of the path, a bounding box for all
896 paths mentioned for any time point is used as the overall bounding box.
897 \end{animateattribute}
898
899 \begin{key}{/pgf/animation/arrows=\meta{start tip spec}|-|\meta{end tip spec}}
900 This key specifies arrow tips during the animation of the path. The syntax
901 for the arrow tips is the same syntax as the |\pgfsetarrow| command or
902 \tikzname's |arrows| key. The specified start and end arrow tips are
903 rendered as ``markers'', which are added to the path \emph{only} during the
904 animation. The markers are rotated along with the path in exactly the same
905 way as normal arrow tips would be. To be precise, the rules used for the
906 computation of where arrow tips go and in which direction they head is not
907 always the same for ``static'' arrow tips (arrow tips added to a normal
908 path) and the ``dynamic'' arrow tips based on markers; namely when the
909 paths are very short or closed. For this reason, you should add arrow tips
910 to animated paths only when the paths are ``nice and simple'' in the sense
911 that they consist of a single segment whose ends are reasonably long.
912
913 In addition to adding the arrow tips to the path during the animation, the
914 path gets shortened as necessary to compensate for the extend of the arrow
915 tips. However, for this to work, the arrow tips have to be specified before
916 path values are specified (since the shortening is done immediately when a
917 path value is parsed).
918 %
919 \begin{codeexample}[
920 preamble={\usepgfmodule{animations}},
921 animation list={0,1,2,3,4},
922 animation bb={(0.9,-0.1)rectangle(2.1,1.1)},
923 ]
924 \tikz {
925 \pgfanimateattribute{path}{
926 whom = p.path, begin on = {click, of next=node}, arrows = ->,
927 entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}}
928 \pgfpathlineto{\pgfpoint{2cm}{1cm}}},
929 entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}}
930 \pgfpathlineto{\pgfpoint{2cm}{5mm}}}}
931 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
932 \draw [very thick, blue, name=p] (1,0.5) -- (2,0.5);
933 }
934 \end{codeexample}
935
936 Note that the markers that visualize the arrow tips are rendered only once
937 per animation. In consequence, ``bending'' arrow tips cannot be rendered
938 correctly: As a path ``morphs'' a bend arrow tip needs not only to rotate
939 along, but must actually ``bend along'', which is not supported (neither by
940 \pgfname\ nor by \textsc{svg}).
941
942 As pointed out earlier, an animated path cannot have ``static'' arrow tips.
943 However, when you specify a |base| value, which is the path used whenever
944 there is no active animation, \emph{will} use the arrow tips. As a result,
945 you can use this to animate a path with an arrow tip:
946 %
947 \begin{codeexample}[
948 preamble={\usepgfmodule{animations}},
949 animation list={0,1,2,3,4},
950 animation bb={(0.9,-0.1)rectangle(2.1,1.1)},
951 ]
952 \tikz {
953 \pgfanimateattribute{path}{
954 whom = p.path, begin on = {click, of next=node}, arrows = ->,
955 base = {\pgfpathmoveto{\pgfpoint{1cm}{5mm}}
956 \pgfpathlineto{\pgfpoint{2cm}{5mm}}},
957 entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}}
958 \pgfpathlineto{\pgfpoint{2cm}{1cm}}},
959 entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}}
960 \pgfpathlineto{\pgfpoint{2cm}{5mm}}}}
961 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
962 \draw [very thick, blue, name=p];
963 }
964 \end{codeexample}
965 %
966 \end{key}
967
968 \begin{key}{/pgf/animation/shorten >=\meta{dimension}}
969 Just like the normal \tikzname\ key |shorten >|, this key specifies an
970 extra shortening of to-be-animated paths. Whenever a path is parsed as a
971 value for a path animation, it gets shortened at the end by the
972 \meta{dimension} (and, additionally, by the length of the attached arrow
973 tip). Just like the |arrows| key, this key must be given before the path
974 entries are specified.
975 %
976 \begin{codeexample}[
977 preamble={\usepgfmodule{animations}},
978 animation list={0,1,2,3,4},
979 animation bb={(0.9,-0.1)rectangle(2.1,1.1)},
980 ]
981 \tikz {
982 \pgfanimateattribute{path}{
983 whom = p.path, begin on = {click, of next=node}, arrows = ->,
984 shorten > = 2mm,
985 base = {\pgfpathmoveto{\pgfpoint{1cm}{5mm}}
986 \pgfpathlineto{\pgfpoint{2cm}{5mm}}},
987 entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}}
988 \pgfpathlineto{\pgfpoint{2cm}{1cm}}},
989 entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}}
990 \pgfpathlineto{\pgfpoint{2cm}{5mm}}}}
991 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
992 \draw (0.9,-0.1) grid (2.1,1.1);
993 \draw [help lines] (0.9,-0.1) grid[step=1mm] (2.1,1.1);
994 \draw [very thick, blue, name=p];
995 }
996 \end{codeexample}
997 %
998 \end{key}
999
1000 \begin{key}{/pgf/animation/shorten <=\meta{dimension}}
1001 Works like |shorten >|.
1002 \end{key}
1003
1004
1005 \subsection{Animating Transformations and Views}
1006 \label{section-base-animation-views}
1007
1008 In order to animate the canvas transformation matrix, you do not animate an
1009 attribute called ``|transform|'' (or something similar). Rather, there are
1010 several keys that all manipulate the canvas transformation matrix in different
1011 ways. These keys, taken in appropriate combination, allow you to achieve any
1012 particular canvas transformation matrix. All keys that animate the
1013 transformation matrix \emph{always} accumulate.
1014
1015 Some, but not all, of these keys also have an effect on the bounding box
1016 computation: The |translate| and |motion| attribute change the computation of
1017 the bounding box in such a way that it is chosen large enough as to include the
1018 whole picture during all stages of the animation (however, if there are
1019 multiple transformations active at the same time, the computation may not be
1020 correct). In contrast, |scale|, |rotate| and |skew| animations change the
1021 canvas transformation, but are ignored for the bounding box computation. When
1022 in doubt, please set the bounding box explicitly.
1023
1024 Let us start with the basic keys that allow you to change the canvas
1025 transformation matrix directly:
1026
1027 \begin{animateattribute}{scale}
1028 The |scale| attribute adds an animation of the scaling:
1029 %
1030 \begin{codeexample}[
1031 preamble={\usepgfmodule{animations}},
1032 animation list={0.5,1,1.5,2},
1033 ]
1034 \tikz [very thick] {
1035 \pgfanimateattribute{scale}{
1036 whom = node, begin on = {click},
1037 entry = {0s}{0.5}, entry = {2s}{0.75,1.5} }
1038 \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
1039 }
1040 \end{codeexample}
1041 %
1042 The values passed to the |entry| key must either be single scalar values or
1043 a pair of such numbers separated by a comma (which then refer to the $x$-
1044 and $y$-scaling).
1045 \end{animateattribute}
1046
1047 \begin{animateattribute}{rotate}
1048 The |rotate| key adds an animation of the rotation:
1049 %
1050 \begin{codeexample}[
1051 preamble={\usepgfmodule{animations}},
1052 animation list={0.5,1,1.5,2},
1053 ]
1054 \tikz [very thick] {
1055 \pgfanimateattribute{rotate}{
1056 whom = node, begin on = {click},
1057 entry = {0s}{45}, entry = {2s}{90} }
1058 \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
1059 }
1060 \end{codeexample}
1061 %
1062 The values are scalar values representing a rotation in degrees.
1063 \end{animateattribute}
1064
1065 \begin{animateattribute}{xskew}
1066 The |xskew| and |yskew| keys (and also |skew x| and |skew y|, which are
1067 aliases) add an animation of the skew (given in degrees, not as a slant):
1068 %
1069 \begin{codeexample}[
1070 preamble={\usepgfmodule{animations}},
1071 animation list={0.5,1,1.5,2},
1072 ]
1073 \tikz [very thick] {
1074 \pgfanimateattribute{xskew}{
1075 whom = node, begin on = {click}, entry = {0s}{0}, entry = {2s}{45} }
1076 \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
1077 }
1078 \end{codeexample}
1079 %
1080 The values are scalar values.
1081 \end{animateattribute}
1082
1083 \begin{animateattribute}{yskew}
1084 See |xskew|.
1085 \end{animateattribute}
1086
1087 \begin{animateattribute}{skew x}
1088 An alias of |xskew|.
1089 \end{animateattribute}
1090
1091 \begin{animateattribute}{skew y}
1092 An alias of |yskew|.
1093 \end{animateattribute}
1094
1095 \begin{animateattribute}{translate}
1096 The |translate| key adds an animation of the translation (shift):
1097 %
1098 \begin{codeexample}[
1099 preamble={\usepgfmodule{animations}},
1100 animation list={0.5,1,1.5,2},
1101 ]
1102 \tikz [very thick] {
1103 \pgfanimateattribute{translate}{
1104 whom = node, begin on = {click},
1105 entry = {0s}{\pgfpointorigin}, entry = {2s}{\pgfpoint{5mm}{-5mm}} }
1106 \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
1107 }
1108 \end{codeexample}
1109 %
1110 The values are \pgfname-points.
1111
1112 Unlike for the previous canvas transformations, for this key the bounding
1113 box computation is changed: All points in the to-be-animated scope do not
1114 only contribute to the normal bounding box, but they also contribute
1115 shifted by all points in the entry list. The effect is that a bounding box
1116 is computed that encompasses the animated scope at all stages.
1117 \end{animateattribute}
1118
1119 For all of these attributes, the following key is of importance:
1120 %
1121 \begin{key}{/pgf/animation/origin=\meta{pgf point}}
1122 An animation of the canvas transformation is added to all other
1123 transformations from surrounding or interior scopes. This means that, in
1124 particular, the origin of a canvas transformation is, by default, the
1125 origin of the canvas of the scope surrounding the transformation object.
1126
1127 For some canvas animations, like a rotation or a scaling, you will
1128 typically wish to use a different origin (like the center of an object that
1129 is to be rotated or scaled). You can achieve this effect by surrounding the
1130 object by a scope that shifts the canvas to the desired origin, followed by
1131 a scope whose transformation matrix you animate, followed by a scope that
1132 shifts back the canvas.
1133
1134 The |origin| key simplifies this process by allowing you to specify the
1135 origin of the transformation directly. Internally, however, all this key
1136 does is to create the above-mentioned scopes with the necessary shifts.
1137 %
1138 \begin{codeexample}[
1139 preamble={\usepgfmodule{animations}},
1140 animation list={0.5,1,1.5,2},
1141 ]
1142 \tikz [very thick] {
1143 \pgfanimateattribute{rotate}{
1144 whom = node, begin on = {click},
1145 origin = \pgfpoint{-5mm}{0mm}, entry = {0s}{0}, entry = {2s}{90} }
1146 \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
1147 }
1148 \end{codeexample}
1149 %
1150 \end{key}
1151
1152 \begin{animateattribute}{motion}
1153 A second way of changing the canvas transformation matrix is to use the
1154 |motion| attribute:
1155 %
1156 \begin{codeexample}[
1157 preamble={\usepgfmodule{animations}},
1158 animation list={0.5,1,1.5,2},
1159 ]
1160 \tikz [very thick] {
1161 \pgfanimateattribute{motion}{
1162 whom = node, begin on = {click},
1163 along = \pgfpathcircle{\pgfpointorigin}{5mm},
1164 entry = {0s}{.25}, entry = {2s}{.5} }
1165 \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
1166 \end{codeexample}
1167
1168 Just like the |translate| attribute, this key also changes the bounding box
1169 computation.
1170 %
1171 \begin{key}{/pgf/animation/along=\meta{path}}
1172 This key must be used with |motion| attribute to specify a path along
1173 which the transformation matrix will be ``moved'' (that is, a shift
1174 transformation will be added to the different points on the path).
1175
1176 The values passed to the |entry| key specify fractions of the distance
1177 along the \meta{path}. That means, when you provide a value of |0|, you
1178 reference the start point of the path, a value of |1| references the
1179 end of the path and |0.5| referenced the point halfway along the path.
1180 %
1181 \begin{codeexample}[
1182 preamble={\usepgfmodule{animations}},
1183 animation list={0.25,0.5,0.75,1,1.25,1.5,1.75,2,2.25,2.5},
1184 ]
1185 \tikz [very thick] {
1186 \pgfanimateattribute{motion}{
1187 whom = node, begin on = {click},
1188 along = \pgfpathmoveto{\pgfpointorigin}
1189 \pgfpathlineto{\pgfpoint{0mm}{5mm}},
1190 entry = {0s}{0}, entry = {1s}{0.5}, entry = {2s}{0.25}, entry={3s}{1} }
1191 \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
1192 \end{codeexample}
1193 \end{key}
1194
1195 \begin{key}{/pgf/animation/rotate along=\meta{Boolean} (default true)}
1196 When set to |true|, the |along| key additionally adds a rotation that
1197 varies in such a way that a tangent to the path always points right.
1198 %
1199 \begin{codeexample}[
1200 preamble={\usepgfmodule{animations}},
1201 animation list={0.5,1,1.5,2},
1202 ]
1203 \tikz [very thick] {
1204 \pgfanimateattribute{motion}{
1205 whom = node, begin on = {click},
1206 rotate along = true,
1207 along = \pgfpathmoveto {\pgfpointorigin}
1208 \pgfpathcurveto{\pgfpoint{5mm}{0cm}}{\pgfpoint{5mm}{0cm}}
1209 {\pgfpoint{5mm}{5mm}},
1210 entry = {0s}{0}, entry = {2s}{1} }
1211 \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
1212 \end{codeexample}
1213 \end{key}
1214 \end{animateattribute}
1215
1216 The final method of changing the transformation matrix is to animate a
1217 \emph{view.}
1218
1219 \begin{animateattribute}{view}
1220 A view is a canvas transformation that shifts and scales the canvas in such
1221 a way that a certain rectangle ``matches'' another rectangle: The idea is
1222 that you ``look through'' a ``window'' (the view) and ``see'' a certain
1223 area of the canvas. View animation do not allow you to do anything that
1224 cannot also be done using the |translate| and |scale| keys in combination,
1225 but it often much more natural to animate which area of a graphic you wish
1226 to see than to compute and animate a scaling and shift explicitly.
1227
1228 In order to use a view, you first need to create a view, which is done
1229 using a |{pgfviewboxscope}|, see Section~\ref{section-base-view}, which is
1230 used by the |views| library internally. You can then animate the view using
1231 the |view| attribute. The values passed to the |entry| key must be two
1232 \pgfname-points, each surrounded by parentheses.
1233 %
1234 \begin{codeexample}[
1235 preamble={\usepgfmodule{animations}
1236 \usetikzlibrary{views}},
1237 animation list={0.5,1,1.5,2},
1238 animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
1239 ]
1240 \tikz [very thick] {
1241 \pgfanimateattribute{view}{
1242 whom = me.view, begin on = {click, of next=node}, freeze at end,
1243 entry = {0s}{{\pgfpoint{0mm}{0mm}}{\pgfpoint{20mm}{20mm}}},
1244 entry = {2s}{{\pgfpoint{10mm}{10mm}}{\pgfpoint{15mm}{15mm}}} }
1245 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
1246
1247 \draw [green!50!black] (1.2,-0.8) rectangle (2.7,0.8);
1248 \begin{scope}[name = me, view = {(0,0) (2,2) at (1.2,-0.8) (2.7,0.8)}]
1249 \draw [red] (10mm,10mm) rectangle (15mm,15mm);
1250 \node at (10mm,10mm) [circle, fill=red, text=white, font=\tiny] {red};
1251 \end{scope}
1252 }
1253 \end{codeexample}
1254
1255 \begin{codeexample}[
1256 width=2cm,
1257 preamble={\usepgfmodule{animations}
1258 \usetikzlibrary{views}},
1259 ]
1260 \tikz [very thick] {
1261 \pgfanimateattribute{view}{
1262 whom = me.view, begin on = {click, of next=n1}, freeze at end,
1263 entry = {0s}{\pgfpoint{0mm}{0mm}}{\pgfpoint{2cm}{2cm}},
1264 entry = {2s}{{\pgfpoint{5mm}{5mm}}{\pgfpoint{15mm}{20mm}}} }
1265 \pgfanimateattribute{view}{
1266 whom = me.view, begin on = {click, of next=n2}, freeze at end,
1267 entry = {0s}{\pgfpoint{0mm}{0mm}}{\pgfpoint{2cm}{2cm}},
1268 entry = {2s}{{\pgfpoint{10mm}{10mm}}{\pgfpoint{15mm}{15mm}}} }
1269 \node (n1) at (0,0) [fill = blue!20, draw = blue, circle] {Zoom blue};
1270 \node (n2) at (2,0) [fill = blue!20, draw = blue, circle] {Zoom red};
1271
1272 \draw [green!50!black] (4,0) rectangle (6,2);
1273 \begin{scope}[name = me, view = {(0,0) (2,2) at (4,0) (6,2)}]
1274 \draw [blue] (5mm,5mm) rectangle (15mm,20mm);
1275 \node at (5mm,5mm) [circle, fill=blue, text=white] {blue};
1276
1277 \draw [red] (10mm,10mm) rectangle (15mm,15mm);
1278 \node at (10mm,10mm) [circle, fill=red, text=white, font=\tiny] {red};
1279 \end{scope}
1280 }
1281 \end{codeexample}
1282 %
1283 \end{animateattribute}
1284
1285
1286 \subsection{Commands for Specifying Timing: Beginnings and Endings}
1287
1288 Using the |entry| key repeatedly, you specify a timeline: The \meta{time} used
1289 with the first use of the |entry| key in a timeline is the start time and the
1290 \meta{time} in the last |entry| key is the stop time. However, this leaves open
1291 then question of when the whole timeline is to be started: The moment the
1292 document is opened? When the page is displayed? When the user scrolls to the
1293 to-be-animated object? When some other object is clicked? The key |begin|, and
1294 also the key |end|, allow you to specify answers to these questions.
1295
1296 \begin{key}{/pgf/animation/begin=\meta{time}}
1297 This key specifies when the ``moment |0s|'' should be relative to the
1298 moment when the current graphic is first displayed. You can use this key
1299 multiple times, in this case the timeline is restarted for each of the
1300 times specified (if it is already running, it will be reset). If no |begin|
1301 key is given at all, the effect is the same as if |begin=0s| had been
1302 specified.
1303
1304 It is permissible to set \meta{time} to a negative value.
1305 \end{key}
1306
1307 \begin{key}{/pgf/animation/end=\meta{time}}
1308 This key will truncate the timeline so that it ends \meta{time} after the
1309 display of the graphic, provided the timeline begins before the specified
1310 end time. For instance, if you specify a timeline starting at 2\,s and
1311 ending at 5\,s and you set |begin| to 1\,s and |end| to 4\,s, the timeline
1312 will run, relative to the moment when the graphic is displayed from 3\,s to
1313 4\,s.
1314 %
1315 \begin{codeexample}[preamble={\usepgfmodule{animations}},width=3cm]
1316 \tikz [very thick] {
1317 \pgfanimateattribute{rotate}{
1318 whom = node, begin = 2s, end = 4s,
1319 entry = {1s}{0}, entry = {2s}{90}, entry = {3s}{180}, entry = {4s}{270} }
1320 \node (node) [fill = blue!20, draw = blue, circle] {Turn after 3s!}; }
1321 \end{codeexample}
1322 %
1323 \end{key}
1324
1325 It is not immediately clear what should happen with the attribute of an object
1326 when an animation ends: Should it revert to its original value ``as if there
1327 had never been an animation'' or should it ``stay at the last value''? The
1328 following key governs what should happen:
1329
1330 \begin{key}{/pgf/animation/freeze at end=\meta{true or false} (default true, initially false)}
1331 When set to |true|, whenever a timeline ends (either because the last time
1332 of timeline has been reached or because an |end| or |end of| key have ended
1333 it prematurely), the last value the attribute had because of the animation
1334 ``stays put''. When set to |false|, which is the initial value, once an
1335 animation ends, its effect will be removed ``as if it never happened''.
1336 %
1337 \begin{codeexample}[
1338 preamble={\usepgfmodule{animations}},
1339 animation list={0,1,2,3,4},
1340 ]
1341 \tikz [very thick] {
1342 \pgfanimateattribute{rotate}{
1343 whom = node, begin on = {click}, freeze at end = false,
1344 entry = {0s}{0}, entry = {2s}{90} }
1345 \node (node) [fill = blue!20, draw = blue, circle] {Here!}; }
1346 \end{codeexample}
1347 %
1348 \begin{codeexample}[
1349 preamble={\usepgfmodule{animations}},
1350 animation list={0,1,2,3,4},
1351 ]
1352 \tikz [very thick] {
1353 \pgfanimateattribute{rotate}{
1354 whom = node, begin on = {click}, freeze at end,
1355 entry = {0s}{0}, entry = {2s}{90} }
1356 \node (node) [fill = blue!20, draw = blue, circle] {Here!}; }
1357 \end{codeexample}
1358 %
1359 \end{key}
1360
1361 Instead of specifying the beginning of the timeline relative to the moment to
1362 to-be-animated graphic is displayed, you can also set the ``moment |0s|'' to
1363 the moment a specific \emph{event} happens using the following key:
1364
1365 \begin{key}{/pgf/animation/begin on=\meta{options}}
1366 Has the same effect as |/tikz/animate/option/begin on|, see
1367 Section~\ref{section-anim-begin-end}.
1368 \end{key}
1369
1370 When you use |begin on| to start an animation when a certain event is
1371 triggered, it is not clear what should happen when the event is triggered
1372 \emph{again}. Should this be ignored completely? Should it only be ignored
1373 while the animation is running? The following key allows you to specify when
1374 should happen:
1375
1376 \begin{key}{/pgf/animation/restart=\meta{choice} (default true)}
1377 Has the same effect as |/tikz/animate/option/restart|, see
1378 Section~\ref{section-anim-begin-end}.
1379 \end{key}
1380
1381 Just like |begin on| specifies when a timeline begins relative to some event,
1382 the |end on| allows you to stop is early when some event happens:
1383
1384 \begin{key}{/pgf/animation/end on=\meta{options}}
1385 Works exactly like |begin on|, one possible end of the timeline is
1386 specified using the \meta{options}.
1387 \end{key}
1388
1389
1390 \subsection{Commands for Specifying Timing: Repeats}
1391
1392 Normally, a timeline is displayed once and then ends. You can, however, request
1393 that the timeline should be repeated a certain number of times or indefinitely.
1394
1395 \begin{key}{/pgf/animation/repeats=\meta{specification}}
1396 Use this key to specify that the timeline animation should repeat at the
1397 end. The \meta{specification} must consist of two parts, each of which may
1398 be empty. The first part is one of the following:
1399 %
1400 \begin{itemize}
1401 \item Empty, in which case the timeline repeats forever.
1402 %
1403 \begin{codeexample}[
1404 preamble={\usepgfmodule{animations}},
1405 animation list={1,2,3,4,5},
1406 ]
1407 \tikz [very thick] {
1408 \pgfanimateattribute{rotate}{
1409 whom = node, begin on = {click}, repeats,
1410 entry = {0s}{0}, entry = {2s}{90} }
1411 \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
1412 \end{codeexample}
1413 %
1414 \item A \meta{number} (like |2| or |3.25|), in which case the timeline
1415 repeats \meta{number} times.
1416 %
1417 \begin{codeexample}[
1418 preamble={\usepgfmodule{animations}},
1419 animation list={1,2,3,4,5},
1420 ]
1421 \tikz [very thick] {
1422 \pgfanimateattribute{rotate}{
1423 whom = node, begin on = {click}, repeats = 1.75,
1424 entry = {0s}{0}, entry = {2s}{90} }
1425 \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
1426 \end{codeexample}
1427 %
1428 \item The text ``|for| \meta{time}'' (like |for 2s| or |for 300ms|), in
1429 which case the timeline repeats however often necessary so that it
1430 stops exactly after \meta{time}.
1431 %
1432 \begin{codeexample}[
1433 preamble={\usepgfmodule{animations}},
1434 animation list={1,2,3,4,5},
1435 ]
1436 \tikz [very thick] {
1437 \pgfanimateattribute{rotate}{
1438 whom = node, begin on = {click}, repeats = for 3.5s,
1439 entry = {0s}{0}, entry = {2s}{90} }
1440 \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
1441 \end{codeexample}
1442 \end{itemize}
1443 %
1444 The second part of the specification must be one of the following:
1445 %
1446 \begin{itemize}
1447 \item Empty, in which case each time the timeline is restarted, the
1448 attribute's value undergoes the same series of values it did
1449 previously.
1450 \item The text |accumulating|. This has the effect that each time the
1451 timeline is restarted, the attribute values specified by the
1452 timeline are \emph{added} to the value from the previous
1453 iteration(s). A typical example is an animation that shifts a scope
1454 by, say, 1\,cm over a time of 1\,s. Now, if you repeat this five
1455 times, normally the scope will shift 1\,cm for 1\,s then ``jump
1456 back'', shift again, jump back, and so on for five times. In
1457 contrast, when the repeats are accumulating, the scope will move by
1458 5\,cm over 5\,s in total.
1459 %
1460 \begin{codeexample}[
1461 preamble={\usepgfmodule{animations}},
1462 animation list={1,2,3,4,5},
1463 ]
1464 \tikz [very thick] {
1465 \pgfanimateattribute{rotate}{
1466 whom = node, begin on = {click}, repeats = accumulating,
1467 entry = {0s}{0}, entry = {2s}{90} }
1468 \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
1469 \end{codeexample}
1470 %
1471 \begin{codeexample}[
1472 preamble={\usepgfmodule{animations}},
1473 animation list={1,2,3,4,5},
1474 ]
1475 \tikz [very thick] {
1476 \pgfanimateattribute{rotate}{
1477 whom = node, begin on = {click}, repeats = 2 accumulating,
1478 entry = {0s}{0}, entry = {2s}{90} }
1479 \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
1480 \end{codeexample}
1481 \end{itemize}
1482 \end{key}
1483
1484 \begin{key}{/pgf/animation/repeat=\meta{specification}}
1485 This is an alias for |repeats|.
1486 \end{key}
1487
1488
1489 %%% Local Variables:
1490 %%% mode: latex
1491 %%% TeX-master: "pgfmanual"
1492 %%% End: