Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-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-tikz-animations}
13
14 \begin{tikzlibrary}{animations}
15 This library must be loaded in order to use animations with \tikzname.
16 \end{tikzlibrary}
17
18
19 \subsection{Introduction}
20
21 An \emph{animation} changes the appearance of some part of a graphic over time.
22 The archetypical animation is, of course, a \emph{movement} of some part of a
23 picture, but a change of, say, the opacity of a path is also an animation.
24 \tikzname\ allows you to specify such animations using special keys and
25 notations.
26 %
27 \begin{codeexample}[
28 preamble={\usetikzlibrary{animations}},
29 width=8cm,
30 animation list={0.7,1.4,2.1,2.8},
31 animation scale=.25,
32 ]
33 \begin{tikzpicture}[
34 animate/orbit/.style 2 args = {
35 myself:shift = {
36 along = {
37 (0,0) circle [radius=#1]
38 } sloped in #2s/10,
39 repeats }} ]
40
41 \node :color = {0s = "orange",
42 2s = "red",
43 4s = "orange",
44 repeats}
45 {Sun};
46
47 \begin{scope}[animate={orbit={2.5cm}{365}}]
48 \node {Earth};
49 \node [animate={orbit={1cm}{28}}] {Moon};
50 \end{scope}
51
52 \useasboundingbox (-3.8,-3.8) (3.8,3.8);
53 \end{tikzpicture}
54 \end{codeexample}
55
56 Adding an animation to a \tikzname\ picture is done as follows:
57 %
58 \begin{enumerate}
59 \item \emph{Before} or \emph{in the options of} the to-be-animated object
60 you specify the object together with an \emph{attribute} that you wish
61 to animate. Attributes are things like the fill color or the line width
62 or the position of the object.
63 \item You specify \emph{when} this attribute should have \emph{which}
64 values using a so-called \emph{timeline}. This is just a curve that
65 specifies for each point in time which value the attribute should have.
66 \item You can additionally use further options to configure the animation,
67 for instance you can specify that the animation should repeat or that
68 it should only start when a certain object is clicked.
69 \end{enumerate}
70
71 As a simple example, let us move a circle within thirty seconds by three
72 centimeters to the left:
73 %
74 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
75 \tikz \draw :xshift = {0s = "0cm", 30s = "-3cm", repeats} (0,0) circle (5mm);
76 \end{codeexample}
77
78 As can be seen, a special syntax is used in several places: Entries with a
79 colon such as |:xshift| specify an attribute, values are specified in quotation
80 marks. This syntax will be explained in more detail later on.
81
82
83 \subsubsection{Animations Change Attributes}
84
85 Before we plunge into the details of how animations are specified, it is
86 important to understand what \tikzname\ actually does when creating an
87 animation: It does \emph{not} (as all other animation packages do) precompute a
88 sequence of pictures that are later somehow displayed in rapid succession.
89 Neither does it insert an external video into the document. Rather, a
90 \tikzname\ animation is just an ``annotation'' in the output that a certain
91 attribute of a certain object should change over time in some specific way when
92 the object is displayed. It is the job of the document viewer application to
93 actually compute and display the animation. The big advantage of this approach
94 is that animations neither increase the output file sizes noticeably nor do
95 they really slow down \TeX: The hard and complicated calculations are done by
96 the viewer application. The disadvantage is, of course, that a document viewer
97 application must understand the annotations and actually compute and display
98 the animations. The \textsc{svg} format is a format for which this is possible,
99 the popular \textsc{pdf} format is not. For the \textsc{svg} format, there are
100 actually different possible ways of ``formulating'' the animations (using
101 \textsc{smil} or \textsc{css} or JavaScript) and they have different advantages
102 and disadvantages.
103
104 To make a long story short: \tikzname\ animations currently work only with
105 \textsc{svg} output (and use the \textsc{smil} ``flavor'' of describing
106 animations). In future, it may well happen that other ``flavor'' of describing
107 animations will be added, but it is very unlikely that \textsc{pdf} will ever
108 support animations in a useful way.
109
110 It is, however, possible to create ``snapshots'' of an animation and insert
111 these into \textsc{pdf} files (or any other kind of file including \textsc{svg}
112 files), see Section~\ref{section-anim-snap} for details. Snapshots are also
113 useful for creating ``printed versions'' of animations and all of the small
114 sequences of pictures in the manual that are used for showing what an animation
115 key does have been creating using snapshots.
116
117
118 \subsubsection{Limitations of the Animation System}
119
120 There are a certain limitations of the animation system that you should keep in
121 mind when considering how and when to use it:
122 %
123 \begin{enumerate}
124 \item As pointed out earlier, animations require a specific output format
125 (currently only \textsc{svg} is supported).
126 \item It is extremely difficult to animate ``lines between moving nodes''
127 correctly. Consider code like |\draw(a)--(b);| where |a| and |b| are
128 nodes. Now, when you animate the position of~|(a)|, the line connecting
129 |(a)| and |(b)| will, unfortunately, not ``move along'' automatically
130 (but it is easy to move the whole group of |(a)|, |(b)|, and the
131 connecting line as whole). You must ``cheat'' and introduce some
132 ``virtual'' nodes, which leads to rather complex and bloated code.
133 \item Animations are taken into consideration for bounding box computations,
134 but only for shifts, not for rotations, scaling, or skewing and also
135 possibly not when multiple shifts are active at the same time for the
136 same object.
137 \end{enumerate}
138
139
140 \subsubsection{Concepts: (Graphic) Objects}
141
142 During an animation an attribute of a certain ``object'' changes over time. The
143 term ``object'' is deliberately a bit vague since there are numerous different
144 ``things'' whose attributes can change. In detail, the following objects have
145 attributes that can be animated:
146 %
147 \begin{enumerate}
148 \item Nodes, which are created by the |\node| command (and, also,
149 internally by commands such as |\graph|). For nodes, different parts of
150 the node can be animated separately; for instance, you can animate the
151 color of the background path, but also the color of the text, and also
152 the color of the foreground path (though most nodes do not have a
153 foreground path) and also the color of different text parts (though
154 only few nodes have multiple text parts).
155 \item Graphic scopes, which are created by numerous command, including the
156 |{scope}| environment, the |\scopes| command, but also |\tikz| itself
157 creates a graphic scope and so does each node and even each path.
158 \item View boxes, which can only be created using the |views| library.
159 \item Paths, which you create using the |\path| command or commands like
160 |\draw| that call |\path| internally. However, the (usually background)
161 path of a node can also be animated. Note that ``animating the path''
162 really means that the path itself should change over time; in essence,
163 you can ``warp'' a path over time.
164 \end{enumerate}
165
166 In all of these cases, you must either specify the animation inside the
167 object's options using |animate| or use the |name| key to name the object and,
168 then, refer to it in an |animate|. For nodes you can, of course, use the
169 |(|\meta{node name}|)| syntax to name the node. Recall that you must
170 \emph{always} specify the animation \emph{before} the object is created; it is
171 not possible to animate an already created object.
172
173 There is a special syntax for choosing the object of an animation, see
174 Section~\ref{section-anim-syntax-obj}, but you can also use the |object| key to
175 choose them directly, see Section~\ref{section-anim-def-obj}.
176
177
178 \subsubsection{Concepts: Attributes}
179
180 In addition to the to-be-animated object, you must also choose an
181 \emph{attribute} that you wish to animate. Attributes are things like the color
182 of an object, the position, but also things like the line width. The syntax for
183 choosing attributes and the list of attributes will be explained in detail
184 later on.
185
186 Most attributes correspond directly to attributes that are directly supported
187 by the backend driver (\textsc{svg}), but this is not always the case. For
188 instance, for a node, \tikzname\ differentiates between the fill color, the
189 draw (stroke) color, and the text color, while \textsc{svg} treats the text
190 color are a special case of the fill color. \tikzname\ will do some internal
191 mappings to ensure that you can animate the ``\tikzname\ attributes'' even when
192 they are not directly supported.
193
194 The same syntax that is used for specifying object is also used to specify
195 attributes, see Section~\ref{section-anim-syntax-obj}, but you could also set
196 them directly using the |attribute| key see
197 Section~\ref{section-anim-def-attr}.
198
199
200 \subsubsection{Concepts: Timelines}
201
202 Once an object and an attribute have been chosen, a \emph{timeline} needs to be
203 established. This is, essentially, a curve that specifies for each ``moment in
204 time'' which value the attribute should have.
205
206 A timeline has a \emph{start} and an \emph{end}, but the start need not be the
207 ``moment zero'' (we will come to that) and may even be negative, while the end
208 may be at infinity. You specify the timeline by specifying for certain points
209 in time what the value is at that moment; for all other moments the value is
210 then interpolated. For instance, if you specify that the attribute |:xshift|
211 (the ``horizontal position'' of the object) is 0\,mm at time 5\,s and 10\,mm at
212 time 10\,s, then at 7.5\,s it will be 5\,mm and at 9\,s it will be 8\,mm
213 (assuming a linear interpolation). The resulting optical effect will be that
214 the object \emph{smoothly moves} by one centimeter to the right over a period
215 of five seconds, starting five seconds after ``moment zero''.
216
217 Now, what is the ``moment zero'', the ``beginning of an animation''? If nothing
218 else is specified, an animation starts immediately when the graphic is shown
219 and this is the moment zero relative to which the timeline is measured.
220 However, it is also possible to change this. In particular, you can specify
221 that the moment zero is when a particular \emph{event} occurs such as the user
222 clicking on another object or another animation ending or starting.
223
224 The interpolation of values is not always a straightforward affair. Firstly,
225 for certain kinds of values is not clear how an interpolation should be
226 computed. How does one interpolate between two paths? Between the colors red
227 and green? Between the values |"true"| and |"false"|? In these cases, one must
228 define carefully what the interpolation should be. Secondly, you may wish to
229 use a non-linear interpolation, which is useful for ``easing'' motions: The
230 visual effect of the movement specified above is that the object sits still
231 from moment $0$ for five seconds, then there is an ``infinite acceleration''
232 causing the object to suddenly move at the speed of 2\,mm per second, then
233 there is no acceleration at all for five seconds, causing the object to move
234 for one centimeter, followed by an ``infinite negative acceleration'' that
235 makes the object come to a full stop. As a viewer you experience these infinite
236 accelerations as ``unrealistic'', spoiling the effect of watching a (virtual)
237 physical process. Non-linear interpolations allow you to avoid this effect.
238
239 Just as for specifying objects and attributes, there is also a special syntax
240 for specifying times and values.
241
242
243 \subsection{Creating an Animation}
244
245 \subsubsection{The Animate Key}
246
247 In order to animate a picture, you create timelines for all objects and
248 attributes that change during the animation. The key |animate| is used for
249 creating these timelines.
250
251 \begin{key}{/tikz/animate=\meta{animation specification}}
252 You must place all specifications of animations inside uses of |animate|.
253 You can, and usually should, place the specification of all timelines of a
254 single picture inside a single use of this key since it will reset the time
255 and the fork time (explained in Section~\ref{section-anim-def-times}). You
256 can, however, use this key several times, in principle. Note that if you
257 animate the same attribute of the same object in two different uses of
258 |animate|, two separate timelines will result (and complicated rules are
259 used to determine which one ``wins'' in case they specify conflicting
260 values for the attribute at different times).
261
262 The key can be used at all places where a \tikzname\ key is used; typically
263 you will use it with a |{scope}| environment, inside the options of a node,
264 or directly with the |\tikz| command:
265 %
266 \begin{codeexample}[
267 preamble={\usetikzlibrary{animations}},
268 animation list = {0.5,1,1.5,2},
269 ]
270 \tikz \node [fill, text = white, animate = {
271 myself:fill = {0s = "red", 2s = "blue", begin on = click }}] {Click me};
272 \end{codeexample}
273 %
274 \begin{codeexample}[
275 preamble={\usetikzlibrary{animations}},
276 animation list = {0.5,1,1.5,2},
277 ]
278 \tikz [animate = {a node:fill = {0s = "red", 2s = "blue",
279 begin on = click}}]
280 \node (a node) [fill, text = white] {Click me};
281 \end{codeexample}
282
283 The details of what, exactly, happens in the \meta{animation specification}
284 will be described in the rest of this section. However, basically, an
285 \meta{animation specification} is just a sequence of normal \tikzname\
286 key--value pairs that get executed with the path prefix |/tikz/animate| and
287 with some special syntax handlers installed. In particular, you can define
288 styles for this key path and use them. For instance, we can define a
289 |shake| animation like this:
290 %
291 \begin{codeexample}[width=4cm,preamble={\usetikzlibrary{animations}}]
292 \tikzset{
293 animate/shake/.style = {myself:xshift = { begin on=click,
294 0s = "0mm", 50ms = "#1", 150ms = "-#1", 250ms = "#1", 300ms = "0mm" }}}
295 \tikz \node [fill = blue!20, draw=blue, very thick, circle,
296 animate = {shake = 1mm}] {Shake};
297 \tikz \node [fill = blue!20, draw=blue, very thick, circle,
298 animate = {shake = 2mm}] {SHAKE};
299 \end{codeexample}
300
301 Note that, as stressed earlier, you can only use the |animate| key to
302 specify animations for objects that do not yet exist. The node and object
303 names mentioned in a specification always refer to ``upcoming'' objects;
304 already existing objects of the same name are not influenced.
305
306 You can use the |name| key inside |animate| to ``name'' the animation. Once
307 named, you can later reference the animation in other animations; for
308 instance, you can say that another animation should start when the present
309 animation has ended.
310 \end{key}
311
312
313 \subsubsection{Timeline Entries}
314
315 The ``job'' of the options passed to the |animate| key is to specify the
316 timelines of the animation of (a part of) a picture. For each object and each
317 attribute there may or may not be a timeline and, if present, the timeline
318 consist of sequences of pairs of times and values. Thus, the most basic entity
319 of an animation specification is a tuple consisting of five parts, which are
320 selected by five different keys:
321 %
322 \begin{itemize}
323 \item |object| for selecting the object,
324 \item |attribute| for selecting the attribute,
325 \item |id| for selecting the timeline id (explained in
326 Section~\ref{section-anim-def-id}),
327 \item |time| for selecting a time, and
328 \item |value| for selecting a value.
329 \end{itemize}
330 %
331 When all of these parts have been set up (using the above keys, which will be
332 explained in more detail in a moment), you can use the following key to create
333 an entry:
334
335 \begin{key}{/tikz/animate/entry}
336 Each time this key is used in the options of |animate|, \tikzname\ checks
337 whether the five keys |object|, |attribute|, |id|, |time|, and |value| are
338 set. If one of them is not set, nothing happens. (The |id| key is set to
339 the value |default| by default, all other keys must be set explicitly.)
340
341 If all of these keys are set, a \emph{time--value} pair is created and
342 added to the timeline of attribute of the object. Additionally, all options
343 starting with |/tikz/animate/options/|, which also influence the timeline
344 like |begin on|, are also added to the timeline of the object--attribute
345 pair.
346 %
347 \begin{codeexample}[
348 preamble={\usetikzlibrary{animations}},
349 animation list={0.5,1,1.5,2},
350 ]
351 \tikz [animate = {
352 object = node, attribute = fill, time = 0s, value = red, entry,
353 object = node, attribute = fill, time = 2s, value = blue, entry,
354 object = node, attribute = fill, begin on = click, entry}]
355 \node (node) [fill, text=white] { Click me };
356 \end{codeexample}
357 %
358 In the above example, it would not have been necessary the specify the
359 object and the attribute in each line, they retain their values unless they
360 are overwritten. Thus, we could also have written:
361 %
362 \begin{codeexample}[
363 preamble={\usetikzlibrary{animations}},
364 animation list={0.5,1,1.5,2},
365 ]
366 \tikz [animate = {
367 object = node, attribute = fill, time = 0s, value = red, entry,
368 time = 2s, value = blue, entry,
369 begin on = click, entry}]
370 \node (node) [fill, text=white] { Click me };
371 \end{codeexample}
372 %
373 Note, however, that in both examples we actually add the time--value pair
374 $(2\mathrm{s}, \mathrm{blue})$ twice since the |time| and |value| keys also
375 retain their settings and, thus, for the third |entry| they have the same
376 values as before and a new pair is added. While this superfluous pair is
377 not a problem in the example (it has no visual effect), we will see later
378 on how such pairs can be avoided by using the |scope| key.
379
380 A sequence of calls of |entry| can freely switch between objects and
381 attributes (that is, between timelines), but the times for any given
382 timeline must be given in non-decreasing order:
383 %
384 \begin{codeexample}[
385 preamble={\usetikzlibrary{animations}},
386 animation list={0.5,1,1.5,2},
387 ]
388 \tikz [animate = {
389 object = node, attribute = fill, time = 0s, value = red, entry,
390 object = node2, attribute = draw, entry,
391 object = node, attribute = fill, time = 2s, value = blue, entry,
392 object = node2, attribute = draw, entry,
393 object = node, attribute = fill, begin on = click, entry,
394 object = node2, attribute = draw, begin on = click, entry}] {
395 \node (node) [fill, text=white] { Node 1 };
396 \node (node2) [draw, ultra thick] at (0,-1) { Node 2 };
397 }
398 \end{codeexample}
399 %
400 In the above example, we could not have exchanged the first two lines of
401 the |animate| options with the third and fourth line since the values for
402 time |0s| must come before the values for time |2s|.
403 \end{key}
404
405 In the following, we have a closer look at the five keys the influence the
406 |entry| key and then have a look at ways of grouping keys more easily.
407
408
409 \subsubsection{Specifying Objects}
410 \label{section-anim-def-obj}
411
412 You use the |object| key to select the object(s) to which the next use of
413 |entry| applies. There is also a special syntax for this, which is explained in
414 Section~\ref{section-anim-syntax-obj}.
415
416 \begin{key}{/tikz/animate/object=\meta{list of objects}}
417 The \meta{list of objects} is a comma-separated list of strings of the form
418 \meta{object}\opt{|.|\meta{type}}. All of the objects in the list are
419 selected as to-be-animate object for the next use of the |entry| key. The
420 objects referred to by \meta{object} will be the \emph{next} objects with
421 the |name| key set to \meta{object}. You can apply the |name| key to nodes
422 (where you can also use the special parentheses-syntax and put the name in
423 parentheses, it has the same effect), but also to scopes and paths. (The
424 |name path| key is not the same as |name|; it is an older key from the
425 intersections package and not related.)
426 %
427 \begin{codeexample}[
428 preamble={\usetikzlibrary{animations}},
429 animation list={0.5,1,1.5,2},
430 ]
431 \tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue",
432 begin on = click }}] {
433 \node (a) [fill, text = white, minimum width=1.5cm] at (0,1cm) {a};
434 \node (b) [fill, text = white, minimum width=1.5cm] at (0,5mm) {b};
435 \node (c) [fill, text = white, minimum width=1.5cm] at (0,0mm) {c}; }
436 \end{codeexample}
437 %
438 \begin{codeexample}[
439 preamble={\usetikzlibrary{animations}},
440 animation list={0.5,1,1.5,2},
441 ]
442 \tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue",
443 begin on = click },
444 object = c, :fill = {0s = "green", 2s = "blue",
445 begin on = click } }] {
446 \scoped [name = a, yshift=1cm] \fill (0,0) rectangle (1.5cm,2mm);
447 \scoped [name = b, yshift=5mm] \fill (0,0) rectangle (1.5cm,2mm);
448 \scoped [name = c, yshift=0mm] \fill (0,0) rectangle (1.5cm,2mm); }
449 \end{codeexample}
450
451 If the \meta{object} name is never used later in the file, no animation is
452 created.
453
454 The \meta{object} may also be the special text |myself|. In this case, the
455 referenced object is the scope or object to which the |animate| key is
456 given. If an object is named |myself| (as in |\node (myself) ...|), you
457 cannot reference this node using the |object| key, |myself| \emph{always}
458 refers to the object where the |animate| key is given (of course, you can
459 animate the node named |myself| by placing the |animate| key inside the
460 options of this node; you only cannot ``remotely'' add an animation to it).
461
462 The \meta{object} may be followed by a dot and a \emph{type}. This is needed
463 in rare cases where you want to animate only a special ``part'' of an
464 object that is not accessible in other ways. Normally, \tikzname\ takes
465 care of choosing these types automatically, you only need to set these ``if
466 you know what you are doing''.
467 \end{key}
468
469
470 \subsubsection{Specifying Attributes}
471 \label{section-anim-def-attr}
472
473 \begin{key}{/tikz/animate/attribute=\meta{list of attributes}}
474 The list of attributes must be a comma-separated list of attribute names.
475 The timelines specified later will apply to all of these attributes (and to
476 all objects previously selected using |object|). Possible attributes
477 include colors, positions, line width, but even the paths themselves. The
478 exact list of possible attributes is documented in
479 Section~\ref{section-anim-attrs}.
480 %
481 \begin{codeexample}[
482 preamble={\usetikzlibrary{animations}},
483 animation list={0.5,1,1.5,2},
484 ]
485 \tikz [animate = {attribute = fill, n: = { 0s = "red", 2s = "blue",
486 begin on = click } }]
487 \node (n) [fill, text = white] {The node};
488 \end{codeexample}
489 \end{key}
490
491
492 \subsubsection{Specifying IDs}
493 \label{section-anim-def-id}
494
495 \begin{key}{/tikz/animate/id=\meta{id} (initially default)}
496 Timelines are use to defined how the values of an attribute of an object
497 change over time. In many cases, you will have at most one timeline for
498 each object--attribute pair, but, sometimes, you may wish to have more than
499 one timeline for the same object and the same attribute. For instance, you
500 might have a timeline that specifies a changing |shift| of a node in some
501 direction and, at the same time, another timeline that specifies an
502 additional |shift| in some other direction(s). The problem is that there is
503 only one |shift| attribute and it would be difficult to compute the joint
504 effect of the two timelines.
505
506 For this purpose, timelines are actually identified not only by the
507 object--attribute pair but, in reality, by the triple consisting of the
508 object, the attribute, and the value of this key. We can now specify two
509 separate timelines:
510 %
511 \begin{codeexample}[
512 preamble={\usetikzlibrary{animations}},
513 animation list={0.5,1,1.5,2},
514 ]
515 \tikz [animate = {
516 id = 1, n:shift = { 0s = "{(0,0)}", 2s = "{(0,5mm)}", begin on = click },
517 id = 2, n:shift = { 0s = "{(0,0)}", 2s = "{(5mm,0)}", begin on = click }
518 }]
519 \node (n) [fill = blue!20, draw=blue, very thick] {The node};
520 \end{codeexample}
521
522 The default value of |id| is |default|.
523 \end{key}
524
525 Because of the possibility of creating multiple timelines for the same
526 attribute, it may happen that there is more than one timeline active that is
527 ``trying to modify'' a given attribute. In this case, the following rules are
528 used to determine, which timeline ``wins'':
529 %
530 \begin{enumerate}
531 \item If no animation is active at the current time (all animation either
532 have not yet started or they have already ended), then the |base| value
533 given in the animation encountered last in the code is used. (If there
534 are no base values, the attribute is taken from the surrounding scope
535 and the animations have ``no effect''.)
536 \item If there are several active animations, the one that has started last
537 is used and its value is used.
538 \item If there are several active animations that have started at the same
539 time, the one that comes last in the code is used.
540 \end{enumerate}
541
542 Note that these rules do not apply to transformations of the canvas since these
543 are always additive (or, phrased differently, they are always all active and
544 the effects accumulate).
545
546
547 \subsubsection{Specifying Times}
548 \label{section-anim-def-times}
549
550 \begin{key}{/tikz/animate/time=\meta{time}\opt{|later|}}
551 Sets the time for the next time--value pair in a call of |entry| to
552 \meta{time} plus the current fork time. The text |later| is optional. Both
553 ``fork times'' and the optional |later| will be explained in a moment.
554
555 \medskip\textbf{Time Parsing.}
556 The \meta{time} is parsed using the command |\pgfparsetime|, which is
557 essentially the same as the usual math parser of \tikzname, and the result
558 is interpreted as a time in seconds. Thus, a \meta{time} of |2+3| means ``5
559 seconds'' and a \meta{time} of |2*(2.1)| means ``4.2 seconds''. (You could
560 even specify silly times like |1in|, which results in the time ``72.27
561 seconds''. Please do not do that.) The ``essentially'' refers to the fact
562 that some extras are installed when the time parser is running:
563 %
564 \begin{itemize}
565 \item The postfix operator |s| is added, which has no effect. Thus,
566 when you write |5s| you get the same results as |5|, which is
567 exactly 5 seconds as desired.
568 \item The postfix operator |ms| is added, which divides a number by
569 1000, so |2ms| equals 0.002s.
570 \item The postfix operator |min| is added, which multiplies a number by
571 60.
572 \item The postfix operator |h| is added, which multiplies a number by
573 3600.
574 \item The infix operator |:| is redefined, so that it multiplies its
575 first argument by 60 and adds the second. This implies that |1:20|
576 equals 80s and |01:00:00| equals 3600s.
577 \item The parsing of octal numbers is switched off to allow things like
578 |01:08| for 68s.
579 \end{itemize}
580
581 Note that you cannot use the colon syntax for times in things like
582 |01:20 = "0"| would (falsely) be interpreted as: ``For the object named |01|
583 and its attribute named |20|, do something.'' You can, however, use |01:20|
584 in arguments to the |time| key, meaning that you would have to write
585 instead: |time = 1:20, "0"|, possibly surround by a |scope|.
586
587 \medskip\textbf{Relative Times.}
588 You can suffix a |time| key with ``|later|''. In this case, the \meta{time}
589 is interpreted as an offset to the time in the previous use of the time
590 key:
591 %
592 \begin{codeexample}[
593 preamble={\usetikzlibrary{animations}},
594 animation list={0.5,1,1.5,2},
595 ]
596 \tikz \node :fill = { begin on = click,
597 0s = "white",
598 500ms later = "red",
599 500ms later = "green", % same as 1s = "-5mm"
600 500ms later = "blue"} % same as 1.5s = "-2.5mm"
601 [fill=blue!20, draw=blue, very thick, circle] {Click me};
602 \end{codeexample}
603
604 In reality, the offset is not taken to just any previous use of the |time|
605 key, but to the most recent use of this key or of the |resume| key in the
606 current local \TeX\ scope. Here is an example:
607 %
608 \begin{codeexample}[code only]
609 time = 2s,
610 time = 1s later, % same as time = 3s
611 time = 500ms later, % same as time = 3.5s
612 time = 4s,
613 time = 1s later, % same as time = 5s
614 scope = { % opens a local scope
615 time = 1s later, % same as time = 6s
616 time = 10s
617 time = 1s later % same as time = 11s
618 }, % closes the scope, most recent time is 5s once more
619 time = 2s later % same as time = 7s
620 \end{codeexample}
621
622 \medskip\textbf{Fork Times.}
623 The time meant by the value \meta{time} passed to the |time| key is not
624 used directly. Rather, \tikzname\ adds the current \emph{fork time} to it,
625 which is |0s| by default. You can change the fork time using the following
626 key:
627 %
628 \begin{key}{/tikz/animate/fork=\meta{t} (default 0s later)}
629 Sets the fork time for the local scope to \meta{t} and sets the current
630 time to |0s|. In this scope, when you use ``absolute'' times like |0s|
631 or |2s|, you actually refer to later times that have started as
632 \meta{t}.
633
634 One application of forks is in the definition of keys that add a
635 certain part to a longer animation. Consider for instance the
636 definition of a |highlight| key:
637 %
638 \begin{codeexample}[
639 preamble={\usetikzlibrary{animations}},
640 animation list={1.05,1.1,1.15,1.2,2.05,2.1,2.15,2.2},
641 ]
642 \tikz [animate/highlight/.style = {
643 scope = { fork = #1,
644 :fill = { 0s = "black", 0.1s = "white", 0.2s = "black"} }
645 }]
646 \node [animate = { myself: = {
647 :fill = { 0s = "black", begin on = click },
648 highlight = 1s, highlight = 2s } },
649 fill = blue, text=white, very thick, circle] { Click me };
650 \end{codeexample}
651 %
652 In the above example, we could also have written |0.1s later| instead
653 of |0.2s| and, indeed, the whole style could have been defined using
654 only times with |later|, eliminating the need for the |fork| key.
655 However, using forks you can specify absolute times for things
656 happening in a conceptual ``subprocess'' and also relative times. The
657 name |fork| for the key is also borrowed from operating system theory,
658 where a ``fork'' is the spawning of an independent process.
659 \end{key}
660
661 \medskip\textbf{Remembering and Resuming Times.}
662 When you have a complicated animation with a long timeline, you will
663 sometimes wish to start some animation when some other animation has
664 reached a certain moment; but this moment is only reached through heavy use
665 of |later| times and/or forks. In such situations, the following keys are
666 useful:
667 %
668 \begin{key}{/tikz/animate/remember=\meta{macroname}}
669 This key stores the current time (the time of the last use of the
670 |time| key) globally in the macro \meta{macroname}. This time will
671 include the offset of the fork time:
672 %
673 \begin{codeexample}[code only]
674 time = 2s,
675 fork = 2s later, % fork time is now 4s
676 time = 1s, % local time is 1s, absolute time is 5s (1s + fork time)
677 time = 1s later, % local time is 2s, absolute time is 6s (2s + fork time)
678 remember = \mytime % \mytime is now 6s
679 \end{codeexample}
680 \end{key}
681 %
682 \begin{key}{/tikz/animate/resume=\meta{absolute time}}
683 The \meta{absolute time} is evaluated using |\pgfparsetime| and, then,
684 the current time is set to the resulting time minus the fork time. When
685 the \meta{absolute time} is a macro previously set using |remember|,
686 the net effect of this is that we return to the exact ``moment'' in the
687 global time line when |remember| was used.
688 %
689 \begin{codeexample}[code only]
690 fork = 4s,
691 time = 1s,
692 remember = \mytime % \mytime is now 5s
693 fork = 2s, % fork time is now 2s, local time is 0s
694 resume = \mytime % fork time is still 2s, local time is 3s
695 \end{codeexample}
696 %
697 Using resume you can easily implement a ``join'' operation for forked
698 times. You simply remember the times at the ends of the forks and then
699 resume the maximum time of these remembered times:
700 %
701 \begin{codeexample}[code only]
702 scope = {
703 fork,
704 time = 1s later,
705 ...
706 remember = \forka
707 },
708 scope = {
709 fork,
710 time = 5s later,
711 ...
712 remember = \forkb
713 },
714 scope = {
715 fork,
716 time = 2s later,
717 ...
718 remember = \forkc
719 },
720 resume = {max(\forka,\forkb,\forkc)} % "join" the three forks
721 \end{codeexample}
722 \end{key}
723 \end{key}
724
725
726 \subsubsection{Values}
727 \label{section-anim-def-values}
728
729 \begin{key}{/tikz/animate/value=\meta{value}}
730 This key sets the value of the next time--value pair created by |entry| to
731 \meta{value}. The syntax of the \meta{value} is not fixed, it depends on
732 the type of the attribute. For instance, for an attribute like |opacity|
733 the \meta{value} must be an expression that can be evaluated to a number
734 between 0 and 1; for the attribute |color| the \meta{value} must, instead,
735 be a color; and so on. Take care that when a value contains a comma, you
736 must surround it by braces as in |"{(1,1)}"|.
737
738 The allowed texts for the \meta{value} is always the same as the one you
739 would pass to the \tikzname\ option of the same name. For instance, since
740 the \tikzname\ option |shift| expects a coordinate, you use coordinates as
741 \meta{value} with the usual \tikzname\ syntax (including all sorts of
742 extensions, the animation system calls the standard \tikzname\ parsing
743 routines). The same is true of dimensions, scalar values, colors, and so
744 on.
745
746 In addition to the values normally use for setting the attribute, you can
747 also (sometimes) use the special text |current value| as \meta{value}. This
748 means that the value of the point in the timeline should be whatever the
749 value the attribute has at the beginning of the timeline. For instance,
750 when you write
751 %
752 \begin{codeexample}[code only]
753 animate = { obj:color = { 0s = "current value", 2s = "white" } }
754 \end{codeexample}
755 %
756 the color of |obj| will change from whatever color it currently has to
757 white in two seconds. This is especially useful when several animations are
758 triggered by user events and the current color of |obj| cannot be
759 determined beforehand.
760
761 There are several limitations on the use of the text |current value|, which
762 had to be imposed partly because of the limited support of this feature in
763 \textsc{svg}:
764 %
765 \begin{itemize}
766 \item You can use |current value| only with the first time in a
767 timeline.
768 \item You can only have two times in a timeline that starts with
769 |current value|.
770 \item You cannot use |current value| for timelines of which you wish to
771 take a snapshot.
772 \end{itemize}
773 \end{key}
774
775
776 \subsubsection{Scopes}
777 \label{section-anim-scopes}
778
779 When you specify multiple timelines at the same time, it is often useful and
780 sometimes even necessary to have keys be set only locally. The following key
781 makes this easy:
782
783 \begin{key}{/tikz/animate/scope=\meta{options}}
784 Executed the \meta{options} inside a \TeX\ scope. In particular, all
785 settings made inside the scope have no effect after the end of the |scope|.
786 %
787 \begin{codeexample}[
788 preamble={\usetikzlibrary{animations}},
789 animation list={0.5,1,1.5,2},
790 ]
791 \tikz \node [animate = { myself: = { begin on = click,
792 scope = { attribute = fill, repeats = 3, 0s = "red", 2s = "red!50" },
793 scope = { attribute = draw, 0s = "red", 2s = "red!50" }
794 }},
795 fill=blue!20, draw=blue, very thick, circle] {Click me};
796 \end{codeexample}
797
798 Without the use of the |scope| key, the |repeats| key would also affect the
799 draw attribute.
800 \end{key}
801
802 While the |scope| key is useful for structuring timeline code, it also keeps
803 the current time local to the scope, that is, if you use something like
804 |1s later| after the scope, this will refer to one second after the last use of
805 |time| \emph{before} the scope. The times set inside the |scope| do not matter.
806 While this is desirable effect for forks, you may also sometimes wish to
807 synchronize the local time after the scope with the last time reached in the
808 scope. The following key makes this easy:
809
810 \begin{key}{/tikz/animate/sync=\meta{options}}
811 A shorthand for |scope={| \meta{options} |, remember=\temp},resume=\temp|
812 where |\temp| is actually an internal name. The effect is that after a
813 |sync| the local time just continues as if the scope where not present --
814 but regarding everything else the effects are local to the |sync| scope.
815 \end{key}
816
817
818 \subsection{Syntactic Simplifications}
819 \label{section-anim-syntax-animate}
820
821 In the previous subsection we saw how timelines can be created by specifying
822 the individual entries of the timelines sequentially. However, most of the time
823 you will wish to use a simpler syntax that makes it easier to specify
824 animations. This syntax is only available inside the |animate| key (it is
825 switched on at the beginning) and consists of three ``parts'': The colon
826 syntax, the time syntax, and the quote syntax.
827
828
829 \subsubsection{The Colon Syntax I: Specifying Objects and Attributes}
830 \label{section-anim-syntax-obj}
831
832 Inside the \meta{animation specification} passed to the |animate| key, you can
833 specify an object and an attribute of this object using the following syntax,
834 whose use is detected by the presence of a colon inside a key:
835 %
836 \begin{quote}
837 \normalfont
838 \opt{\meta{object name(s)}}|:|\opt{\meta{attribute(s)}}
839 |={|\meta{options}|}|
840
841 or
842
843 \opt{\meta{object
844 name(s)}}|:|\opt{\meta{attribute(s)}}|_|\opt{\meta{id}}
845 |={|\meta{options}|}|
846 \end{quote}
847 %
848 In the place to the left of an equal sign, where you would normally use a key,
849 you can instead place an object name and an attribute separated by a colon.
850 Additionally, the attribute may be followed by an underscore and an \meta{id},
851 which identifies the timeline (see Section~\ref{section-anim-def-id}).
852
853 Each of these values may be missing, in which case it is not changed from its
854 previous value.
855
856 The effect of the above code is the same as:
857 %
858 \begin{quote}
859 \normalfont
860 |sync = { object = |\meta{objects}|, attribute = |\meta{attribute}|, id = |\meta{id}|, |\meta{options}|, entry }|
861 \end{quote}
862 %
863 although when the object, the attribute, or the id is left empty in the colon
864 syntax, the corresponding setting will be missing in the above call of |sync|.
865 Note that because of the |sync| the last time used inside the \meta{options}
866 will be available afterwards as the last time. Also note that an |entry| is
867 added at the end, so any settings of keys like |begin| or |repeats| inside the
868 \meta{options} will get added to the timeline.
869
870 Let us now have a look at some examples. First, we set the \meta{object name}
871 to |mynode| and |othernode| and the \meta{attribute} to |opacity| and to
872 |color|:
873 %
874 \begin{codeexample}[code only]
875 animate = {
876 mynode:opacity = { 0s = "1", 5s = "0" },
877 mynode:color = { 0s = "red", 5s = "blue" },
878 othernode:opacity = { 0s = "1", 5s = "0" },
879 }
880 \end{codeexample}
881
882 Next, we do the same, but ``in two steps'': First, we set the object to
883 |mynode|, but leave the attribute open and, then, set the attribute, but leave
884 the object:
885 %
886 \begin{codeexample}[code only]
887 animate = {
888 mynode: = {
889 :opacity = { 0s = "1", 5s = "0" },
890 :color = { 0s = "red", 5s = "blue" }
891 },
892 othernode:opacity = { 0s = "1", 5s = "0" },
893 }
894 \end{codeexample}
895 %
896 Note how both in |mynode:| and in |:opacity| and |:color| you must provide the
897 colon. Its presence signals that an object--attribute pair is being specified;
898 only now either the object or the attribute is missing.
899
900 We can also do it the other way round:
901 %
902 \begin{codeexample}[code only]
903 animate = {
904 :opacity = {
905 mynode: = { 0s = "1", 5s = "0" },
906 othernode: = { 0s = "1", 5s = "0" }
907 },
908 mynode:color = { 0s = "red", 5s = "blue" }
909 }
910 \end{codeexample}
911 %
912 Finally, if several objects should get the exact same values, we can also group
913 them:
914 %
915 \begin{codeexample}[code only]
916 animate = {
917 {mynode,othernode}:opacity = { 0s = "1", 5s = "0" },
918 mynode:color = { 0s = "red", 5s = "blue" }
919 }
920 \end{codeexample}
921
922 As mentioned earlier, all references to objects will be interpreted to future
923 objects, never to objects already created. Furthermore, also as mentioned
924 earlier, \tikzname\ allows you to specify |myself| as \meta{object}, which is
925 interpreted as the scope or node where the |animate| is given (you cannot
926 animate a node or scope named |myself|, this special name always refers to the
927 current node). In order to have all attributes refer to the current object, you
928 write:
929 %
930 \begin{codeexample}[code only]
931 \begin{scope} [animate = {
932 myself: = { % Animate the attribute of the scope
933 :opacity = { ... },
934 :xshift = { ... }
935 }
936 }]
937 ...
938 \end{scope}
939 \end{codeexample}
940
941 The list of permissible attributes is given in
942 Section~\ref{section-anim-attrs}.
943
944
945 \subsubsection{The Colon Syntax II: Animating Myself}
946
947 A frequent use of the |animate| key is for animating attributes of the current
948 object |myself|. In these cases, it is a bit length to write
949 %
950 \begin{codeexample}[code only]
951 [animate = { myself: = { :some attribute = {...} } } ]
952 \end{codeexample}
953 %
954 \noindent in the options of a node or a scope. For this reason, \tikzname\
955 allows you to use a special syntax with nodes and scopes:
956 %
957 \begin{enumerate}
958 \item In a \meta{node specification}, which is everything following a
959 |node| command up to the content of the node (which is surrounded by
960 curly braces), you can write
961 %
962 \begin{quote}
963 |:some attribute = {|\meta{options}|}|
964 \end{quote}
965 %
966 and this will have the same effect as if you had written
967 %
968 \begin{quote}
969 |[animate = { myself: = { :some attribute = {|\meta{options}|}}}]|
970 \end{quote}
971 %
972 Note that you can use this syntax repeatedly, but each use creates a
973 new use of the |animate| key, resulting in a new timeline. In order to
974 create complex timelines for several objects, use the |animate| key.
975 \item For the commands |\tikz|, |\scoped| and the environments
976 |{tikzpicture}| and |{scope}|, when they are followed immediately by
977 %
978 \begin{quote}
979 |:some attribute = {|\meta{options}|}|
980 \end{quote}
981 %
982 then
983 %
984 \begin{quote}
985 |animate = { myself: = { :some attribute = {|\meta{options}|}}}|
986 \end{quote}
987 %
988 is added to the options of the command or scope. Again, you can use the
989 syntax repeatedly. Note that when an opening square bracket is
990 encountered, this special parsing stops.
991 \end{enumerate}
992
993 Let us have a look at some examples. First, we use the syntax to set the fill
994 opacity of a node:
995 %
996 \begin{codeexample}[
997 preamble={\usetikzlibrary{animations}},
998 animation list={0.5,1,1.5,2},
999 ]
1000 \tikz \node
1001 :fill opacity = { 0s="1", 2s="0", begin on=click }
1002 [fill = blue!20, draw = blue, ultra thick, circle] {Here!};
1003 \end{codeexample}
1004 %
1005 Next, we additionally rotate the node:
1006 %
1007 \begin{codeexample}[
1008 preamble={\usetikzlibrary{animations}},
1009 animation list={0.5,1,1.5,2},
1010 ]
1011 \tikz \node
1012 :fill opacity = { 0s="1", 2s="0", begin on=click }
1013 :rotate = { 0s="0", 2s="90", begin on=click }
1014 [fill = blue!20, draw = blue, ultra thick, circle] {Here!};
1015 \end{codeexample}
1016 %
1017 Note that there is no comma between consecutive uses of the colon syntax in
1018 this case. We could have exchanged the order of the options and the uses of the
1019 colon syntax:
1020 %
1021 \begin{codeexample}[
1022 preamble={\usetikzlibrary{animations}},
1023 animation list={0.5,1,1.5,2},
1024 ]
1025 \tikz \node
1026 :fill opacity = { 0s="1", 2s="0", begin on=click }
1027 [fill = blue!20, draw = blue, ultra thick, circle]
1028 :rotate = { 0s="0", 2s="90", begin on=click } {Here!};
1029 \end{codeexample}
1030
1031 We can also use the special syntax with the |\tikz| command itself:
1032 %
1033 \begin{codeexample}[
1034 preamble={\usetikzlibrary{animations}},
1035 animation list={0.5,1,1.5,2},
1036 ]
1037 \tikz :fill opacity = { 0s="1", 2s="0", begin on=click }
1038 :rotate = { 0s="0", 2s="90", begin on=click }
1039 [ultra thick]
1040 \node [fill = blue!20, draw = blue, circle] {Here!};
1041 \end{codeexample}
1042
1043 Note that we could \emph{not} have moved the |[ultra thick]| options before
1044 |:rotate| since the options in square brackets end the special parsing.
1045
1046
1047 \subsubsection{The Time Syntax: Specifying Times}
1048
1049 For each object--attribute pair you must specify the \emph{timeline} of the
1050 attribute. This is a curve that specifies for each ``moment in time'' which
1051 value the attribute should have. In the simplest case, you specify such a
1052 time--value pair as follows:
1053 %
1054 \begin{quote}
1055 \normalfont
1056 \meta{time} |="|\meta{value}|"|
1057 \end{quote}
1058
1059 When you specify time--value pairs, you must specify the times in chronological
1060 order (so earlier times come first), but you may specify the same time several
1061 times (this is useful in situations where you have a ``jump'' from one value to
1062 another at a certain moment in time: you first specify the value ``from which
1063 the attribute jumps'' and then you specify the value ``to which the attribute
1064 jumps'' for the same moment).
1065
1066 The above syntax is just a special case of a more general situation. Let us
1067 start with the times. The general syntax for specifying times is as follows:
1068 %
1069 \begin{quote}
1070 \normalfont
1071 \meta{time} \opt{|=| \meta{options}}
1072 \end{quote}
1073
1074 Here, \meta{time} is a text that ``looks like a time'', which means that:
1075 %
1076 \begin{enumerate}
1077 \item It is not a key and does not contain a colon and does not start with
1078 a quotation mark.
1079 \item It starts with a digit, a plus or minus sing, a dot, or a
1080 parenthesis.
1081 \end{enumerate}
1082
1083 If these two things are the case, the above code is transformed to the
1084 following call:
1085 %
1086 \begin{quote}
1087 \normalfont
1088 |sync = {time = |\meta{time}|, |\meta{options}|, entry}|
1089 \end{quote}
1090
1091
1092 \subsubsection{The Quote Syntax: Specifying Values}
1093
1094 We saw already in several examples that values are put in quotation marks
1095 (similar to the way this is done in \textsc{xml}). This quote syntax is as
1096 follows:
1097 %
1098 \begin{quote}
1099 \normalfont
1100 |"|\meta{value}|"| \opt{|base|} \opt{|=| \meta{options}}
1101 \end{quote}
1102
1103 This syntax is triggered whenever a key starts with a quotation mark%
1104 \footnote{Of catcode 12 for those knowledgeable of such things.} (and note that
1105 when the \meta{value} contains a comma, you have to surround it by curly braces
1106 \emph{inside} the quotation marks as in |"{(1,1)}"|). Then, the following code
1107 is executed:
1108 %
1109 \begin{quote}
1110 \normalfont
1111 |sync = {value = |\meta{value}|, |\meta{options}|, entry}|
1112 \end{quote}
1113
1114 This means that when you write |1s = "red"|, what actually happens is that
1115 \tikzname\ executes the following:
1116 %
1117 \begin{codeexample}[code only]
1118 sync = { time = 1s, sync = { value = red, entry }, entry }
1119 \end{codeexample}
1120 %
1121 Note that the second entry has no effect since no value is specified and the
1122 |entry| key only ``takes action'' when both a time and a value have been
1123 specified. Thus, only the innermost |entry| does, indeed, create a time--value
1124 pair as desired.
1125
1126 In addition to the above, if you have added |base| after the closing quote, the
1127 following gets executed before the above |sync|:
1128 %
1129 \begin{quote}
1130 \normalfont
1131 |base = {value = |\meta{value}|}|
1132 \end{quote}
1133
1134 This makes it easy to specify base values for timelines.
1135
1136 Interestingly, instead of |1s="red"| you can also write |"red"=1s|. Let us now
1137 have a look at situations where this can be useful.
1138
1139
1140 \subsubsection{Timesheets}
1141
1142 Using the |sync| key or using the three different syntactic constructs
1143 introduced earlier (the color syntax, the time syntax, the value syntax), you
1144 can organize the specification of an animation in different ways. Basically,
1145 the two most useful ways are the following:
1146 %
1147 \begin{enumerate}
1148 \item You first select an object and an attribute for which you wish to
1149 establish a timeline and then provide the time--value pairs in a
1150 sequence:
1151 %
1152 \begin{codeexample}[code only]
1153 animate = {
1154 obj:color = {
1155 0s = "red",
1156 2s = "blue",
1157 1s later = "green",
1158 1s later = "green!50!black",
1159 10s = "black"
1160 }
1161 }
1162 \end{codeexample}
1163 %
1164 When you specify timelines for several attributes of the same object,
1165 you can group these together:
1166 %
1167 \begin{codeexample}[code only]
1168 animate = {
1169 obj: = {
1170 :color = { 0s = "red", 2s = "green" },
1171 :opacity = { 0s = "1", 2s = "0" }
1172 }
1173 }
1174 \end{codeexample}
1175 %
1176 In this way of specifying animations the ``object comes first''.
1177 \item Alternatively, you can also group the animation by time and, for each
1178 ``moment'' (known as \emph{keyframes}) you specify which values the
1179 attributes of the object(s) have:
1180 %
1181 \begin{codeexample}[code only]
1182 animate = {
1183 0s = {
1184 obj:color = "red",
1185 obj:opacity = "1"
1186 },
1187 2s = {
1188 obj:color = "green",
1189 obj:opacity = "0"
1190 }
1191 }
1192 \end{codeexample}
1193 %
1194 Naturally, in this case it would have been better to ``move the object
1195 outside'':
1196 %
1197 \begin{codeexample}[code only]
1198 animate = {
1199 obj: = {
1200 0s = {
1201 :color = "red",
1202 :opacity = "1"
1203 },
1204 2s = {
1205 :color = "green",
1206 :opacity = "0"
1207 }
1208 }
1209 }
1210 \end{codeexample}
1211 %
1212 When there are several objects involved, we can mix all of these
1213 approaches:
1214 %
1215 \begin{codeexample}[code only]
1216 animate = {
1217 0s = {
1218 obj: = {
1219 :color = "red",
1220 :opacity = "1"
1221 },
1222 main node: = {
1223 :color = "black"
1224 }
1225 },
1226 2s = {
1227 obj: = {
1228 :color = "green",
1229 :opacity = "0"
1230 },
1231 main node: = {
1232 :color = "white"
1233 }
1234 }
1235 }
1236 \end{codeexample}
1237 %
1238 \end{enumerate}
1239
1240
1241 \subsection{The Attributes That Can Be Animated}
1242 \label{section-anim-attrs}
1243
1244 The following \meta{attributes} are permissible (actually, the attribute names
1245 do not include a colon, but since they will almost always be used with the
1246 colon syntax, it makes it easier to identify them):
1247 %
1248 \begin{itemize}
1249 \itemsep0pt
1250 \item |:dash phase|
1251 \item |:dash pattern|
1252 \item |:dash|
1253 \item |:draw opacity|
1254 \item |:draw|
1255 \item |:fill opacity|
1256 \item |:fill|
1257 \item |:line width|
1258 \item |:opacity|
1259 \item |:position|
1260 \item |:path|
1261 \item |:rotate|
1262 \item |:scale|
1263 \item |:stage|
1264 \item |:text opacity|
1265 \item |:text|
1266 \item |:translate|
1267 \item |:view|
1268 \item |:visible|
1269 \item |:xscale|
1270 \item |:xshift|
1271 \item |:xskew|
1272 \item |:xslant|
1273 \item |:yscale|
1274 \item |:yshift|
1275 \item |:yskew|
1276 \item |:yslant|
1277 \end{itemize}
1278
1279 These attributes are detailed in the following sections, but here is a quick
1280 overview of those that do not have a \tikzname\ key of the same name (and which
1281 thus do not just animate the attribute set using this key):
1282 %
1283 \begin{itemize}
1284 \item |:shift| allows you to add an animated shifting of the canvas, just
1285 like \tikzname's |shift| key. However, in conjunction with the |along|
1286 key, you can also specify the shifting along a path rather than via a
1287 timeline of coordinates.
1288 \item |:position| works similar to |:shift|, only the coordinates are not
1289 relative movements (no ``shifts''), but refer to ``absolute positions''
1290 in the picture.
1291 \item |:path| allows you to animate a path (it will morph). The ``values''
1292 are now paths themselves.
1293 \item |:view| allows you to animate the view box of a view.
1294 \item |:visible| decides whether an object is visible at all.
1295 \item |:stage| is identical to |:visible|, but when the object is not
1296 animated, it will be hidden by default.
1297 \end{itemize}
1298
1299
1300 \subsubsection{Animating Color, Opacity, and Visibility}
1301 \label{section-animation-painting}
1302
1303 You can animate the color of the target object of an animation using the
1304 attributes |fill|, |draw|, and |text|. When the target of a color animation is
1305 a scope, you animate the color ``used in this scope'' for filling or stroking.
1306 However, when an object inside the scope has its color set explicitly, this
1307 color overrules the color of the scope.
1308
1309 \begin{tikzanimateattribute}{fill, draw}
1310 \begin{codeexample}[
1311 preamble={\usetikzlibrary{animations}},
1312 animation list={0.5,1,1.5,2},
1313 ]
1314 \tikz :fill = {0s = "red", 2s = "blue", begin on = click}
1315 [text = white, fill = orange ] {
1316 \node [fill] at (0mm,0) {A};
1317 \node [fill] at (5mm,0) {B};
1318 \node [fill = green!50!black ] at (1cm,0) {C};
1319 }
1320 \end{codeexample}
1321 \end{tikzanimateattribute}
1322
1323 \begin{tikzanimateattribute}{text}
1324 The |text| attribute only applies to nodes and you need to directly animate
1325 the |text| attribute of each node individually.
1326 %
1327 \begin{codeexample}[
1328 preamble={\usetikzlibrary{animations}},
1329 animation list={0.5,1,1.5,2},
1330 ]
1331 \tikz [my anim/.style={ animate = {
1332 myself:text = {0s = "red", 2s = "blue", begin on = click}}},
1333 text = white, fill = orange ] {
1334 \node [fill, my anim] at (0,0) {A};
1335 \node [fill, my anim] at (1,0) {B};
1336 }
1337 \end{codeexample}
1338 %
1339 Unlike the |fill| and |draw| colors, you cannot animate the |text| color
1340 for scopes:
1341 %
1342 \begin{codeexample}[
1343 preamble={\usetikzlibrary{animations}},
1344 animation list={0.5,1,1.5,2},
1345 ]
1346 \tikz [animate = {myself:text = {0s = "red", 2s = "blue",
1347 begin on = click}},
1348 text = white, fill = orange ] {
1349 \node [fill] at (0,0) {A};
1350 \node [fill] at (1,0) {B};
1351 }
1352 \end{codeexample}
1353 %
1354 \end{tikzanimateattribute}
1355
1356 \begin{tikzanimateattribute}{color}
1357 The |color| attribute is not really an attribute. Rather, it is a shorthand
1358 for |{draw,fill,text}|. This means that |color| does not start a separate
1359 timeline, but continues the |draw| timeline, the |fill| timeline, and the
1360 |text| timeline.
1361 \end{tikzanimateattribute}
1362
1363 \begin{tikzanimateattribute}{opacity, fill opacity, stroke opacity}
1364 Similarly to the color, you can also set the opacity used for filling and
1365 for drawing using the attributes |fill opacity| and |draw opacity|, which
1366 are exactly the same as the usual \tikzname\ keys of the same names.
1367 %
1368 \begin{codeexample}[
1369 preamble={\usetikzlibrary{animations}},
1370 animation list={0.5,1,1.5,2},
1371 ]
1372 \tikz \node :fill opacity = { 0s="1", 2s="0", begin on=click }
1373 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1374 \end{codeexample}
1375 %
1376 Unlike colors, where there is no joint attribute for filling and stroking,
1377 there is a single |opacity| attribute in addition to the above two
1378 attributes. If supported by the driver, it treats the graphic object to
1379 which it is applied as a transparency group. In essence, ``this attribute
1380 does what you want'' at least in most situations.
1381 %
1382 \begin{codeexample}[
1383 preamble={\usetikzlibrary{animations}},
1384 animation list={0.5,1,1.5,2},
1385 ]
1386 \tikz \node :opacity = { 0s="1", 2s="0", begin on=click }
1387 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1388 \end{codeexample}
1389 %
1390 \end{tikzanimateattribute}
1391
1392 \begin{tikzanimateattribute}{visible, stage}
1393 The difference between the |visible| attribute and an opacity of |0| is
1394 that an invisible object cannot be clicked and does not need to be
1395 rendered. The (only) two possible values for this attribute are |false| and
1396 |true|.
1397 %
1398 \begin{codeexample}[
1399 preamble={\usetikzlibrary{animations}},
1400 animation list={1,2,3,4},
1401 ]
1402 \tikz :visible = {begin on=click, 0s="false", 2s="false"}
1403 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
1404 \end{codeexample}
1405
1406 This |stage| attribute is the same as the |visible| attribute, only
1407 |base="false"| is set by default. This means that the object is \emph{only}
1408 visible when you explicitly during the time the entries are set to |true|.
1409 The idea behind the name ``stage'' is that the object is normally ``off
1410 stage'' and when you explicitly set the ``stage attribute'' to |true| the
1411 object ``enters'' the stage and ``leaves'' once more when it is no longer
1412 ``on stage''.
1413 %
1414 \begin{codeexample}[
1415 preamble={\usetikzlibrary{animations}},
1416 animation list={-1,0,1,2,3},
1417 animation bb={(1.3,-0.7) rectangle (2.7,0.7)},
1418 ]
1419 \tikz [animate = {example:stage = {
1420 begin on = {click, of next=node},
1421 0s="true", 2s="true" }}] {
1422 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
1423 \node at (2,0) (example) [fill = blue!20, circle] {Effect};
1424 }
1425 \end{codeexample}
1426 \end{tikzanimateattribute}
1427
1428
1429 \subsubsection{Animating Paths and their Rendering}
1430 \label{section-animation-paths}
1431
1432 The attributes of the appearance of a path that you can animate include the
1433 line width and the dash pattern, the path itself, as well as the arrow tips
1434 attached to the paths. Animating the line width and the dash pattern is easy
1435 since the animation attributes simply have that same names as the properties
1436 that they animate and the syntax for setting is also the same:
1437
1438 \begin{tikzanimateattribute}{line width}
1439 \begin{codeexample}[
1440 preamble={\usetikzlibrary{animations}},
1441 animation list={0.5,1,1.5,2},
1442 ]
1443 \tikz \node :line width = { 0s="1pt", 2s="5mm", begin on=click}
1444 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1445 \end{codeexample}
1446 %
1447 Note that you must specify number (or expressions that evaluate to numbers)
1448 as values, you cannot say |thin| or |thick| (these are styles, internally,
1449 and you also cannot say |line width=thick|).
1450 \end{tikzanimateattribute}
1451
1452 \begin{tikzanimateattribute}{dash, dash phase, dash phase}
1453 The values for an animation of the dashing are specifications (see the
1454 |dash| key for details) consisting of a sequence of |on| and |off| numbers.
1455 In each value of the animation the length of these sequences \emph{must} be
1456 identical. The interpolation of the values is done for each position of the
1457 sequences individually, and also on the phase.
1458 %
1459 \begin{codeexample}[
1460 preamble={\usetikzlibrary{animations}},
1461 animation list={0.5,1,1.5,2},
1462 ]
1463 \tikz \node :dash = { 0s="on 10pt off 1pt phase 0pt",
1464 2s="on 1pt off 10pt phase 0pt", begin on=click}
1465 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1466 \end{codeexample}
1467 %
1468 \begin{codeexample}[
1469 preamble={\usetikzlibrary{animations}},
1470 animation list={0.5,1,1.5,2},
1471 ]
1472 \tikz \node :dash = { 0s="on 1cm off 1pt phase 0pt",
1473 2s="on 1cm off 1pt phase 1cm", begin on=click}
1474 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1475 \end{codeexample}
1476
1477 This |dash pattern| key allows you to animate the dash phase only. However,
1478 due to the way dashing is handled by certain drivers, the dash pattern is
1479 also set, namely to the current dash pattern that is in force when the
1480 animation is created.
1481 %
1482 \begin{codeexample}[
1483 preamble={\usetikzlibrary{animations}},
1484 animation list={0.5,1,1.5,2},
1485 ]
1486 \tikz \node :dash phase = { 0s="0pt", 2s="1cm", begin on=click}
1487 [fill = blue!20, draw = blue, ultra thick, circle, dashed] {Click me!};
1488 \end{codeexample}
1489 %
1490 \end{tikzanimateattribute}
1491
1492 The above attributes ``only'' influence how the path is rendered. You can,
1493 however, also animate the path itself:
1494
1495 \begin{tikzanimateattribute}{path}
1496 When you animate a path, the values are, of course, paths themselves:
1497 %
1498 \begin{codeexample}[
1499 preamble={\usetikzlibrary{animations}},
1500 animation list={0.5,1,1.5,2},
1501 ]
1502 \tikz \node :path = {
1503 0s = "{(0,-1) .. controls (0,0) and (0,0) .. (0,1) -- (1,1)}",
1504 2s = "{(0,-1) .. controls (-1,0) and (-1,0) .. (-1,1) -- (.5,-1)}",
1505 begin on=click }
1506 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1507 \end{codeexample}
1508 %
1509 There a number of things to keep in mind when you animate a path:
1510 %
1511 \begin{itemize}
1512 \item The path ``values'' are parsed and executed in an especially
1513 protected scope to ensure that they have only little side effects,
1514 but you should not do ``fancy things'' on these paths.
1515 \item As for the dash pattern, you must ensure that all paths in the
1516 timeline have the same structure (same sequence of path
1517 construction commands); only the coordinates may differ. In
1518 particular, you cannot say that the path at |1s| is a rectangle
1519 using |rectangle| and at |2s| is a circle using |circle|. Instead,
1520 you would have to ensure that at both times the path consists of
1521 appropriate Bézier curves (which is cumbersome as the following
1522 example shows, where we used the fact that a circle consists of
1523 four Bézier curves):
1524 %
1525 \begin{codeexample}[
1526 preamble={\usetikzlibrary{animations}},
1527 animation list={0.5,1,1.5,2},
1528 ]
1529 \tikz \node :path = {
1530 0s = "{(0,0) circle [radius=1cm]}",
1531 2s = "{(0,0)
1532 (1,0) .. controls +(0,0) and +(0,0) .. (0,1)
1533 .. controls +(0,0) and +(0,0) .. (-1,0)
1534 .. controls +(0,0) and +(0,0) .. (0,-1)
1535 .. controls +(0,0) and +(0,0) .. (1,0)
1536 -- cycle (0,0)}",
1537 begin on=click}
1538 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1539 \end{codeexample}
1540 %
1541 \item You must specify arrow tips for an animated path in a special
1542 way, namely using the |arrows| key for \emph{animations}, not the
1543 normal |arrows| key (see below).
1544 \end{itemize}
1545 \end{tikzanimateattribute}
1546
1547 \begin{key}{/tikz/animate/arrows=\meta{arrow spec}}
1548 This key only has an effect on |:path| animations. It causes the arrow tips
1549 specified in \meta{arrow spec} to be added to the path during the animation
1550 (the syntax is the same as for the normal |arrows| key). If you have
1551 several different animations for a paths, these may contain different arrow
1552 tips, but each animation must stick to one kind of arrow tips.
1553
1554 What happens internally when this key is used is the following: The
1555 specified arrow tips are rendered internally as so-called \emph{markers,}
1556 which are small graphics that can be placed at the beginning and ends of
1557 paths and which ``rotate along'' as a path changes. Note that these markers
1558 are used \emph{only} in the context of animated paths, the arrow tips of
1559 normal, ``static'' paths are drawn without the use of markers. Normally,
1560 there is no visual difference between an arrow tip drawn using markers or
1561 those drawn for static paths, but in rare cases there may be differences.
1562 You should only add arrows to open path consisting of a single segment with
1563 sufficiently long first and last segments (so that \tikzname\ can shorten
1564 these segments correctly when necessary).
1565
1566 As pointed out earlier, the only way to add arrow tips to a path that is
1567 animated is using this key, you can \emph{not} say something like
1568 %
1569 \begin{codeexample}[code only]
1570 \draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}" }
1571 [->] (0,0) -- (1,0);
1572 \end{codeexample}
1573 %
1574 This will raise an error since you try to animate a path (|:path = ...|)
1575 that has normal arrow tips attached (|[->]|).
1576
1577 Instead, you must specify the arrow tips inside the animation command:
1578 %
1579 \begin{codeexample}[code only]
1580 \draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}", arrows = -> }
1581 (0,0) -- (1,0);
1582 \end{codeexample}
1583
1584 However, the above code now has a big shortcoming: While the animation is
1585 \emph{not} running, \emph{no} arrow tip is shown (the |arrows| key only
1586 applies to the animation.
1587
1588 The trick is to use the |base| key. It allows you to install a path as the
1589 ``base'' path that is used when no animation is running and the arrows
1590 specified for the animation will also be used for the base. All told, the
1591 ``correct'' way to specify the animation is the following (note that no
1592 static path is specified, any specified path would be overruled by the
1593 |base| path anyway):
1594 %
1595 \begin{codeexample}[code only]
1596 \draw :path = { 1s = "{(0,0) -- (1,0)}" base, 2s = "{(0,1) -- (1,0)}", arrows = -> };
1597 \end{codeexample}
1598
1599 Here is an example:
1600 %
1601 \begin{codeexample}[
1602 preamble={\usetikzlibrary{animations}},
1603 animation list={0.5,1,1.5,2},
1604 animation bb={(-0.1,-0.1) rectangle (1.1,1.1)},
1605 ]
1606 \tikz [very thick] {
1607 \node (node) at (-2,0)
1608 [fill = blue!20, draw = blue, very thick, circle] {Click me!};
1609 \draw :path = {
1610 0s = "{(0,0) to[out=90, in=180] (.5,1) to[out=0, in=90] (.5,.5)}" base,
1611 2s = "{(1,0) to[out=180, in=180] (.25,.5) to[out=0, in=180] (1,.5)}",
1612 arrows = <.<->, begin on = {click, of=node} }; }
1613 \end{codeexample}
1614 %
1615 \end{key}
1616
1617 \begin{key}{/tikz/animate/shorten < = \meta{dimension}}
1618 \end{key}
1619
1620 \begin{key}{/tikz/animate/shorten > = \meta{dimension}}
1621 For animated paths, just as the key |arrows| has to be passed to the
1622 animation (to |:path|) instead of to the static path, the keys |shorten >|
1623 and |shorten <| also have to be passed to the |:path| key.
1624 \end{key}
1625
1626
1627 \subsubsection{Animating Transformations: Relative Transformations}
1628
1629 In order to animate the canvas transformation matrix, you do not animate an
1630 attribute called ``|:transform|''. Rather, there are several attributes that
1631 all manipulate the canvas transformation matrix in different ways. These keys,
1632 taken in appropriate combination, allow you to achieve any particular canvas
1633 transformation matrix. All keys that animate the transformation matrix always
1634 accumulate.
1635
1636 Let us start with the ``standard'' attributes that are also available as keys
1637 in \tikzname:
1638
1639 \begin{tikzanimateattribute}{scale, xscale, yscale}
1640 \begin{codeexample}[
1641 preamble={\usetikzlibrary{animations}},
1642 animation list={0.5,1,1.5,2},
1643 ]
1644 \tikz \node :scale = { 0s="1", 2s="0.2", begin on=click}
1645 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1646 \end{codeexample}
1647 \end{tikzanimateattribute}
1648
1649 \begin{tikzanimateattribute}{rotate}
1650 The |rotate| key adds an animation of the rotation:
1651 %
1652 \begin{codeexample}[
1653 preamble={\usetikzlibrary{animations}},
1654 animation list={0.5,1,1.5,2},
1655 ]
1656 \tikz \node :rotate = { 0s="45", 2s="90", begin on=click}
1657 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1658 \end{codeexample}
1659 %
1660 Note that there is no |rotate around| attribute, but you can use the
1661 |origin| key to change the origin of the rotation.
1662 \end{tikzanimateattribute}
1663
1664 \begin{tikzanimateattribute}{xskew, yskew, xslant, yslant}
1665 The keys add an animation of the skew (given in degrees) or slant (given as
1666 in the |xslant| and |yslant| key):
1667 %
1668 \begin{codeexample}[
1669 preamble={\usetikzlibrary{animations}},
1670 animation list={0.5,1,1.5,2},
1671 ]
1672 \tikz \node :xskew = { 0s="0", 2s="45", begin on=click}
1673 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1674 \end{codeexample}
1675 %
1676 \begin{codeexample}[
1677 preamble={\usetikzlibrary{animations}},
1678 animation list={0.5,1,1.5,2},
1679 ]
1680 \tikz \node :xslant = { 0s="-1", 2s="1", begin on=click}
1681 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1682 \end{codeexample}
1683 %
1684 \end{tikzanimateattribute}
1685
1686 \begin{tikzanimateattribute}{xshift, yshift}
1687 \begin{codeexample}[
1688 preamble={\usetikzlibrary{animations}},
1689 animation list={0.5,1,1.5,2},
1690 ]
1691 \tikz \node :shift = { 0s="{(0,0)}", 2s="{(5mm,-5mm)}",
1692 begin on=click}
1693 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1694 \end{codeexample}
1695
1696 \begin{codeexample}[
1697 preamble={\usetikzlibrary{animations}},
1698 animation list={0.5,1,1.5,2},
1699 ]
1700 \tikz \node :xshift = { 0s="0pt", 2s="5mm", begin on=click}
1701 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1702 \end{codeexample}
1703 %
1704 \end{tikzanimateattribute}
1705
1706 \begin{tikzanimateattribute}{shift}
1707 This |:shift| attribute can be animated in two ways. First, you can simply
1708 specify a sequence of coordinates in the same way as you would use the
1709 |shift| key in \tikzname:
1710 %
1711 \begin{codeexample}[
1712 preamble={\usetikzlibrary{animations}},
1713 animation list={0.5,1,1.5,2},
1714 ]
1715 \tikz \node :shift = { 0s = "{(0,0)}", 2s = "{(5mm,-5mm)}",
1716 begin on = click }
1717 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
1718 \end{codeexample}
1719
1720 However, you can also specify the sequence of positions along which the
1721 shift should occur in a different way, namely by \emph{specifying a path
1722 along which the object should be moved.} This is often not only more
1723 natural to do, but also allows you to specify movements along curves.
1724
1725 \begin{key}{/tikz/animate/options/along=\marg{path}\meta{|sloped| or
1726 |upright|}\opt{| in|\meta{time}}%
1727 }
1728 Use this key with a |:shift| (or a |:position|) to make \tikzname\
1729 shift the object by the coordinates along the \meta{path}. When this
1730 key is used, the values may no longer be coordinates, but must be
1731 fractions of the distance along the path. A value of |"0"| refers to
1732 the beginning of the path and |"1"| refers to the end:
1733 %
1734 \begin{codeexample}[
1735 preamble={\usetikzlibrary{animations}},
1736 animation list={0.5,1,1.5,2},
1737 ]
1738 \tikz {
1739 \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
1740 \draw (1,.5) circle [radius=1mm];
1741 \node :shift = {
1742 along = {(0,0) circle[radius=5mm]} upright,
1743 0s="0", 2s=".25", begin on=click }
1744 at (1,.5) [fill = blue, opacity=.5, circle] {Click};
1745 }
1746 \end{codeexample}
1747 \end{key}
1748
1749 Following the \meta{path}, which must be put in braces, you must either
1750 specify |upright| or |sloped|. In the first case, the to-be-animated object
1751 is moved along the path normally (and stays ``upright''), whereas when you
1752 use |sloped|, the object will be continuously rotated so that it always
1753 points along the path.
1754 %
1755 \begin{codeexample}[
1756 preamble={\usetikzlibrary{animations}},
1757 animation list={0.5,1,1.5,2},
1758 ]
1759 \tikz {
1760 \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
1761 \draw (1,.5) circle [radius=1mm];
1762 \node :shift = {
1763 along = {(0,0) circle[radius=5mm]} sloped,
1764 0s="0", 2s=".25", begin on=click }
1765 at (1,.5) [fill = blue, opacity=.5, circle] {Click};
1766 }
1767 \end{codeexample}
1768
1769 In most motion animations that use |along|, you will set the value for |0s|
1770 to |"0"| and the value for some specific \meta{time} to |"1"|. Because of
1771 this, you can add |in| \meta{time} after the path, to achieve exactly this
1772 effect.
1773 \end{tikzanimateattribute}
1774
1775 For the above attributes, it is not immediately clear which coordinate system
1776 should be used for the animation. That is, when you move an object 1cm ``to the
1777 right'', where is ``the right''? By default, movements and transformations like
1778 |:shift| or |:scale| are relative to the \emph{animation coordinate system,}
1779 which defaults to the local coordinate system of the to-be-animated object.
1780 Consider the following example:
1781 %
1782 \begin{codeexample}[
1783 preamble={\usetikzlibrary{animations}},
1784 animation list={0.5,1,1.5,2},
1785 ]
1786 \tikz {
1787 \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
1788 \node :rotate = { 0s="0", 2s="45", begin on=click}
1789 at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
1790 }
1791 \end{codeexample}
1792 %
1793 Note how the node rotates around its center even though this center is at
1794 position |(1,1)| in the picture's coordinate system. This is because |at (1,1)|
1795 actually only does a shift of the coordinate system and the node is then drawn
1796 at the origin of this shifted coordinate system. Since this shifted coordinate
1797 system becomes the animation coordinate system, the rotation ``around the
1798 origin'' is actually a rotation around the origin of the animation coordinate
1799 system, which is at |(1,1)| in the picture's coordinate system.
1800
1801 Let us, by comparison, do a rotation of a scope surrounding the node where the
1802 origin is not (yet) shifted:
1803 %
1804 \begin{codeexample}[
1805 preamble={\usetikzlibrary{animations}},
1806 animation list={0.5,1,1.5,2},
1807 ]
1808 \tikz {
1809 \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
1810 \scoped :rotate = { 0s="0", 2s="45", begin on={click, of next=n} }
1811 \node (n) at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
1812 }
1813 \end{codeexample}
1814 %
1815 Now the rotation is really around the origin of the picture.
1816
1817 Most of the time the animation coordinate system will be setup in the way ``you
1818 expect'', but you can modify it using the following keys:
1819
1820 \begin{key}{/tikz/animate/options/origin=\meta{coordinate}}
1821 Shifts the animation coordinate system by \meta{coordinate}. This has the
1822 effect that the ``origin'' for scalings and rotations gets shifted by this
1823 amount. In the following example, the point around which the rotation is
1824 done is the right border at |(2,1)| since the origin of the animation is at
1825 |(1,1)| relative to the picture's origin and the |origin| key shifts it one
1826 centimeter to the right.
1827 %
1828 \begin{codeexample}[
1829 preamble={\usetikzlibrary{animations}},
1830 animation list={0.5,1,1.5,2},
1831 ]
1832 \tikz {
1833 \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
1834 \node :rotate = { 0s="0", 2s="45", begin on=click,
1835 origin = {(1,0)}}
1836 at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
1837 }
1838 \end{codeexample}
1839 %
1840 \end{key}
1841
1842 \begin{key}{/tikz/animate/options/transform=\meta{transformation keys}}
1843 While the |origin| key does only a shift, the |transform| key allows you to
1844 add an arbitrary transformation to the animation coordinate system using
1845 keys like |shift|, |rotate| or even |reset cm| and |cm|. In particular,
1846 |origin=|\meta{c} has the same effect as |transform| |=|
1847 |{shift=|\meta{c}|}|. Note that the transformation only influences the
1848 animation, not the object itself.
1849
1850 As an example, when you say |transform={scale=2}|, an |:xshift| with a
1851 value of |"1cm"| will actually shift the object by 2cm. Similarly, after
1852 you say |transform={rotate=90,scale=2}|, the same |:xshift| of |"1cm"| will
1853 actually shift the object by 2cm upwards.
1854
1855 Note that, internally, \tikzname\ has to invert the transformation matrix
1856 resulting from the \meta{transformation keys} (plus the original animation
1857 transformation matrix), which can by numerically instable when you use
1858 ill-conditioned transformations.
1859 %
1860 \begin{codeexample}[
1861 preamble={\usetikzlibrary{animations}},
1862 animation list={0.5,1,1.5,2},
1863 ]
1864 \tikz {
1865 \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
1866 \node :xshift = { 0s="0cm", 2s="5mm", begin on=click,
1867 transform = {rotate=-90} }
1868 at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
1869 }
1870 \end{codeexample}
1871 %
1872 \begin{codeexample}[
1873 preamble={\usetikzlibrary{animations}},
1874 animation list={0.5,1,1.5,2},
1875 ]
1876 \tikz {
1877 \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
1878 \node :xshift = { 0s="0cm", 2s="5mm", begin on=click,
1879 transform = {rotate=-45, scale=2} }
1880 at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
1881 }
1882 \end{codeexample}
1883 %
1884 \end{key}
1885
1886
1887 \subsubsection{Animating Transformations: Positioning}
1888
1889 The attributes for specifying transformations and, in particular, the |:shift|
1890 attribute are always expressed in the local animation coordinate system. This
1891 makes it easy to ``shift around a node a little bit'', but makes it hard to
1892 move a node ``from one position to another'' since coordinates need to be
1893 expressed relative to the node's coordinate system, which leads to all sorts of
1894 problems: Suppose you wish to have a node move from $(1,1)$ to $(2,1)$ and then
1895 to $(2,0)$. Now, if the node has already been placed at $(1,1)$ in the usual
1896 manner using |at|, then from the ``node's point of view'' you need to move the
1897 node to $(0,0)$, $(1,0)$, and $(1,-1)$. To make matters worse, when you use
1898 named coordinates as in
1899 %
1900 \begin{codeexample}[code only]
1901 \coordinate(A) at (1,1);
1902 \coordinate(B) at (2,1);
1903 \coordinate(C) at (2,0);
1904 \end{codeexample}
1905 %
1906 and then say that the movement should be from |(A)| to |(B)| to |(C)|, what
1907 should you expect? On the one hand, |(A)| and |(1,1)| should normally be
1908 interchangeable; on the other hand, |(A)| is a specific point in the plane, no
1909 matter from which coordinate system we look at it. It turns out that \tikzname\
1910 will stick to the second interpretation and actually turn |(A)| into |(0,0)|
1911 when it is parsed in the local coordinate system of a node starting at |(A)| --
1912 while |(1,1)| will stay the same.
1913
1914 Because of all these confusing effects, there is another attribute |:position|,
1915 which is similar to a |:shift|, but the coordinates are not interpreted in the
1916 local coordinate system of the node, but in the coordinate system that is in
1917 force when the |animate| key is used. For a node, this is \emph{prior} to the
1918 setup of the node's coordinate system and, thus, usually the picture's
1919 coordinate system.
1920
1921 \begin{tikzanimateattribute}{position}
1922 Compare the two animations, one with |:position|, one with |:shift|.
1923 %
1924 \begin{codeexample}[
1925 preamble={\usetikzlibrary{animations}},
1926 animation list={0.5,1,1.5,2},
1927 ]
1928 \tikz {
1929 \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
1930 \draw (1,.5) circle [radius=1mm] (1.5,0) circle [radius=1mm];
1931 \node :position = { 0s="{(1,.5)}", 2s="{(1.5,0)}", begin on=click }
1932 at (1,.5) [fill = blue, opacity=.5, circle] {Click};
1933 }
1934 \end{codeexample}
1935 %
1936 Compare this to a shift:
1937 %
1938 \begin{codeexample}[
1939 preamble={\usetikzlibrary{animations}},
1940 animation list={0.5,1,1.5,2},
1941 ]
1942 \tikz {
1943 \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
1944 \draw (1,.5) circle [radius=1mm] (1.5,0) circle [radius=1mm];
1945 \node :shift = { 0s="{(1,.5)}", 2s="{(1.5,0)}", begin on=click }
1946 at (1,.5) [fill = blue, opacity=.5, circle] {Click};
1947 }
1948 \end{codeexample}
1949 %
1950 You can use the |along| key with |:position| in the same way as with
1951 |:shift|, which is especially useful for specifying that a node ``travels''
1952 between positions of the canvas:
1953 %
1954 \begin{codeexample}[
1955 preamble={\usetikzlibrary{animations}},
1956 animation list={0.5,1,1.5,2},
1957 ]
1958 \tikz {
1959 \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
1960 \draw (1,1) circle [radius=1mm] (1.5,0) circle [radius=1mm];
1961 \node :position = {
1962 along = {(1,1) to[bend left] (1.5,0)} sloped in 2s,
1963 begin on = click }
1964 at (1,1) [fill = blue, opacity=.5, circle] {Click};
1965 }
1966 \end{codeexample}
1967 %
1968 \end{tikzanimateattribute}
1969
1970
1971 \subsubsection{Animating Transformations: Views}
1972 \label{section-animation-views}
1973
1974 The final method of changing the transformation matrix is to animate a
1975 \emph{view}.
1976
1977 \begin{tikzanimateattribute}{view}
1978 A view is a canvas transformation that shifts and scales the canvas in such
1979 a way that a certain rectangle ``matches'' another rectangle: The idea is
1980 that you ``look through'' a ``window'' (the view) and ``see'' a certain
1981 area of the canvas. View animation do not allow you to do anything that
1982 cannot also be done using the |shift| and |scale| keys in combination, but
1983 it often much more natural to animate which area of a graphic you wish to
1984 see than to compute and animate a scaling and shift explicitly.
1985
1986 In order to use a view, you first need to create a view, which is done
1987 using the |meet| or |slice| keys from the |views| library, see
1988 Section~\ref{section-library-views}. You can then animate the view using
1989 the |view| attribute. The values passed to the |entry| key follow the same
1990 syntax as the views in the |views| library (though you only animate the
1991 to-be-viewed rectangle).
1992 %
1993 \begin{codeexample}[
1994 preamble={\usetikzlibrary{animations,views}},
1995 animation list={0.5,1,1.5,2},
1996 animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
1997 ]
1998 \tikz [very thick] {
1999 \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
2000
2001 \draw [green!50!black] (1.2,-0.8) rectangle (2.7,0.8);
2002 \begin{scope}[view = {(0,0) (2,2) at (1.2,-0.8) (2.7,0.8)},
2003 animate = {myself:view = {
2004 begin on = {click, of=node},
2005 0s = "{(0,0) (2,2)}",
2006 2s = "{(1,1) (1.5,1.5)}" }}]
2007 \draw [red] (10mm,10mm) rectangle (15mm,15mm);
2008 \node at (10mm,10mm) [circle, fill=red, text=white, font=\tiny] {red};
2009 \end{scope}
2010 }
2011 \end{codeexample}
2012 %
2013 \end{tikzanimateattribute}
2014
2015
2016 \subsection{Controlling the Timeline}
2017 \label{section-anim-timeline}
2018
2019 We can already specify timelines by giving a sequence of times in
2020 non-decreasing order along with corresponding values. In this section we have a
2021 look at further options that allow us to extend or control the timeline.
2022
2023
2024 \subsubsection{Before and After the Timeline: Value Filling}
2025
2026 When you specify the timeline, you specify it for a certain interval
2027 $[t_1,t_2]$. By default, outside this interval the animation has no effect on
2028 the to-be-animated attribute. The following keys allows you to change this:
2029
2030 \begin{key}{/tikz/animate/base=\meta{options}}
2031 A ``base'' value is a value that is used for the attribute whenever the
2032 timeline is \emph{not} active:
2033 %
2034 \begin{codeexample}[
2035 preamble={\usetikzlibrary{animations}},
2036 animation list = {0.5,1,1.5,2,2.5},
2037 ]
2038 \tikz \node [fill = green, text = white] :fill =
2039 { 1s = "red", 2s = "blue", base = "orange", begin on = click }
2040 {Click me};
2041 \end{codeexample}
2042
2043 Syntactically, the |base| key works much like special time syntax: It sets
2044 up a local |sync| scope and executes the \meta{options} in it and creates
2045 an |entry|. However, instead of setting the |time| attribute to a time, it
2046 sets it to a special value that tells \tikzname\ that when the entry is
2047 created, the current \meta{value} should be used as the |base| value.
2048
2049 This means that you can write |base = "orange"| as in the above example to
2050 set the base. However, you can also use the |base| key in other ways; most
2051 noticeably, you can use it \emph{after} some value:
2052 %
2053 \begin{codeexample}[
2054 preamble={\usetikzlibrary{animations}},
2055 animation list = {0.5,1,1.5,2,2.5},
2056 ]
2057 \tikz \node [fill = green, text = white] :fill =
2058 { 1s = {"red" = base}, 2s = "blue", begin on = click }
2059 {Click me};
2060 \end{codeexample}
2061
2062 Instead of using |base| as a key, you can also add |base| directly after
2063 the quotes of a value. This is particularly useful for setting up a base
2064 value that is also used in a timeline:
2065 %
2066 \begin{codeexample}[
2067 preamble={\usetikzlibrary{animations}},
2068 animation list = {0.5,1,1.5,2,2.5},
2069 ]
2070 \tikz \node [fill = green, text = white] :fill =
2071 { 1s = "red" base, 2s = "blue", begin on = click }
2072 {Click me};
2073 \end{codeexample}
2074 %
2075 \end{key}
2076
2077 \begin{key}{/tikz/animate/options/forever}
2078 This key causes the timeline to continue ``forever'' after the last time
2079 with the last value. You can also think of this as having the animation
2080 ``freeze'' at the end.
2081 %
2082 \begin{codeexample}[
2083 preamble={\usetikzlibrary{animations}},
2084 animation list = {0.5,1,1.5,2,2.5},
2085 ]
2086 \tikz \node :fill = { 1s="red", 2s="blue", forever, begin on=click}
2087 [fill = green!50!black, text = white] {Click me};
2088 \end{codeexample}
2089 %
2090 \begin{codeexample}[
2091 preamble={\usetikzlibrary{animations}},
2092 animation list = {0.5,1,1.5,2,2.5},
2093 ]
2094 \tikz \node [fill = green!50!black, text = white]
2095 :fill = { 1s = "red", 2s = "blue", begin on = click }
2096 {Click me};
2097 \end{codeexample}
2098 %
2099 \end{key}
2100
2101 \begin{key}{/tikz/animate/options/freeze}
2102 An alias for |forever|.
2103 \end{key}
2104
2105
2106 \subsubsection{Beginning and Ending Timelines}
2107 \label{section-anim-begin-end}
2108
2109 The \meta{time} used with the first use of the |entry| key in a timeline is the
2110 start time and the \meta{time} in the last |entry| key is the stop time.
2111 However, this leaves open then question of when the whole timeline is to be
2112 started: The moment the document is opened? When the page is displayed? When
2113 the user scrolls to the to-be-animated object? When some other object is
2114 clicked? The key |begin|, and also the key |end|, allow you to specify answers
2115 to these questions.
2116
2117 \begin{key}{/tikz/animate/options/begin=\meta{time}}
2118 This key specifies when the ``moment |0s|'' should be relative to the
2119 moment when the current graphic is first displayed. You can use this key
2120 multiple times, in this case the timeline is restarted for each of the
2121 times specified (if it is already running, it will be reset). If no |begin|
2122 key is given at all, the effect is the same as if |begin=0s| had been
2123 specified.
2124
2125 It is permissible to set \meta{time} to a negative value.
2126
2127 Note that this key has no effect for snapshots.
2128 \end{key}
2129
2130 \begin{key}{/tikz/animate/options/end=\meta{time}}
2131 This key will truncate the timeline so that it ends \meta{time} after the
2132 display of the graphic, provided the timeline begins before the specified
2133 end time. For instance, if you specify a timeline starting at 2\,s and
2134 ending at 5\,s and you set |begin| to 1\,s and |end| to 4\,s, the timeline
2135 will run, relative to the moment when the graphic is displayed from 3\,s to
2136 4\,s.
2137 %
2138 \begin{codeexample}[preamble={\usetikzlibrary{animations}}]
2139 \tikz \node [fill = green!50!black, text = white]
2140 :rotate = { 1s = "0", 5s = "90", begin = 2s, end = 4s }
2141 {Click me};
2142 \end{codeexample}
2143 %
2144 \end{key}
2145
2146 Instead of specifying the beginning of the timeline relative to the moment to
2147 to-be-animated graphic is displayed, you can also set the ``moment |0s|'' to
2148 the moment a specific \emph{event} happens using the following key:
2149
2150 \begin{key}{/tikz/animate/options/begin on=\meta{options}}
2151 The \meta{options} will be executed with the path |/pgf/animation/events|
2152 and will cause a new beginning to be added to the list of possible
2153 beginnings for the timeline (so the uses of this key accumulate). Each
2154 ``beginning'' is just another possible ``moment |0s|'' for the timeline.
2155 For instance, when the \meta{options} are set to |click|, then each time
2156 the graph is clicked a moment |0s| starts for the timeline.
2157
2158 Most events are ``caused'' or ``happen to'' some object. For instance, the
2159 |click| event happens when you click on a certain object. In order to
2160 specify this object, use the following two keys inside the \meta{options}:
2161 |of| and |of next|. If neither of these keys are given, the to-be-animated
2162 object is used.
2163
2164 \begin{key}{/pgf/animation/events/of=\meta{id}\opt{|.|\meta{type}}}
2165 This specifies a graphic object id in the same way as the |whom| key,
2166 also with an optional \meta{type}. This is the object that ``causes''
2167 the event to happen.
2168
2169 Unlike the |whom| key, which always refers to a not-yet-existing
2170 object, this key always refers to an already existing object, namely to
2171 the most recent use of the \meta{id}. In the following example, the
2172 referenced object is the node with the label |2| since it is the most
2173 recently referenced node with \meta{id} |X|.
2174 %
2175 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{animations}}]
2176 \tikz [very thick] {
2177 \node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1};
2178 \node (X) at (1,0.4) [fill = orange!20, draw = orange, circle] {2};
2179 \node (node) :rotate = {0s="0", 2s="90", begin on = {click, of = X}}
2180 [fill = red!20, draw = red, rectangle] {Anim};
2181 \node (X) at (1,-0.4) [fill = blue!20, draw = blue, circle] {3};
2182 \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; }
2183 \end{codeexample}
2184 \end{key}
2185
2186 \begin{key}{/pgf/animation/events/of next=\meta{id}\opt{|.|\meta{type}}}
2187 This key works like the |of| key, only it refers to a future (actually,
2188 the next) object with the given \meta{id}, not to a previous one. This,
2189 in the next example, the referenced node is the one with label |3|.
2190 %
2191 \begin{codeexample}[width=3cm,preamble={\usetikzlibrary{animations}}]
2192 \tikz [very thick] {
2193 \node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1};
2194 \node (X) at (1,0.4) [fill = blue!20, draw = blue, circle] {2};
2195 \node (node) :rotate = {
2196 0s="0", 2s="90", begin on = {click, of next = X}}
2197 [fill = red!20, draw = red, rectangle] {Anim};
2198 \node (X) at (1,-0.4) [fill = orange!20, draw = orange, circle] {3};
2199 \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; }
2200 \end{codeexample}
2201 \end{key}
2202
2203 The following key allows you to specify the event that should cause the
2204 animation to start:
2205 %
2206 \begin{key}{/pgf/animation/events/event=\meta{event name}}
2207 Specifies the name of the event whose occurrence should start the
2208 timeline. Which events are supported depends on the device on which the
2209 animation is displayed, the output format (\textsc{svg} or some other
2210 format), and the setup of scripts, but here is a list of events
2211 supported by ``plain \textsc{svg}'': |click|, |focusin|, |focusout|,
2212 |mousedown|, |mouseup|, |mouseover|, |mousemove|, |mouseout|, |begin|,
2213 |end|. However, the following keys make using these events simpler:
2214 %
2215 \begin{key}{/pgf/animate/events/click}
2216 This is a shorthand for |event=click|. This event gets triggered
2217 when the user clicks on the triggering object with a mouse (or
2218 something equivalent).
2219 %
2220 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
2221 \tikz \node :rotate = { 0s="0", 2s="90", begin on = {click}}
2222 [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2223 \end{codeexample}
2224 \end{key}
2225 %
2226 \begin{key}{/pgf/animation/events/mouse down}
2227 Shorthand for |event=mousedown|. The event gets triggered when the
2228 user presses a mouse button down on the object.
2229 %
2230 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
2231 \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse down}}
2232 [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2233 \end{codeexample}
2234 \end{key}
2235 %
2236 \begin{key}{/pgf/animation/events/mouse up}
2237 Shorthand for |event=mouseup| and gets triggered, of course, when a
2238 pressed button is released on the object.
2239 %
2240 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
2241 \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse up} }
2242 [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2243 \end{codeexample}
2244 \end{key}
2245 %
2246 \begin{key}{/pgf/animation/events/mouse over}
2247 Shorthand for |event=mouseover|. The event gets triggered the
2248 moment the mouse cursor moves over the object.
2249 %
2250 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
2251 \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse over} }
2252 [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2253 \end{codeexample}
2254 \end{key}
2255 %
2256 \begin{key}{/pgf/animation/events/mouse move}
2257 Shorthand for |event=mousemove|. The event gets triggered lots of
2258 times, namely each time the mouse moves while being ``over'' the
2259 object.
2260 %
2261 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
2262 \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse move} }
2263 [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2264 \end{codeexample}
2265 \end{key}
2266 %
2267 \begin{key}{/pgf/animation/events/mouse out}
2268 Shorthand for |event=mouseout|. The opposite of |mouse over|:
2269 triggered when the mouse leaves the object.
2270 %
2271 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
2272 \tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse out} }
2273 [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2274 \end{codeexample}
2275 \end{key}
2276 %
2277 \begin{key}{/pgf/animation/events/begin}
2278 Shorthand for |event=begin|. The ``begin'' refers to the beginning
2279 of another animation, namely the one referenced by |of| or
2280 |of whom|. This means that the current animation will begin when
2281 some other animation begins.
2282 %
2283 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
2284 \tikz \node [animate = {
2285 myself:rotate = { 0s="0", 2s="90", begin on = {begin, of next=anim}},
2286 myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim}
2287 },
2288 fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2289 \end{codeexample}
2290 \end{key}
2291 %
2292 \begin{key}{/pgf/animation/events/end}
2293 Shorthand for |event=end|. Again, the ``end'' refers to the end of
2294 another animation, namely the one referenced by |of| or |of whom|.
2295 This means that the current animation will \emph{begin} when some
2296 other animation \emph{ends}.
2297 %
2298 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
2299 \tikz \node [animate = {
2300 myself:rotate = { 0s="0", 2s="90", begin on = {end, of next=anim}},
2301 myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim }
2302 },
2303 fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2304 \end{codeexample}
2305 \end{key}
2306 %
2307 \begin{key}{/pgf/animation/events/focus in}
2308 This is a shorthand for |event=focusin|. This event gets triggered
2309 when the graphic object gets the focus (this usually makes sense
2310 only for text input fields).
2311 \end{key}
2312 %
2313 \begin{key}{/pgf/animation/events/focus out}
2314 This is a shorthand for |event=focusout|.
2315 \end{key}
2316 \end{key}
2317
2318 In addition to the events specified using the generic |event| key, there
2319 are two further events that take a parameter:
2320 %
2321 \begin{key}{/pgf/animation/events/repeat=\meta{number}}
2322 The event is triggered when a repeating animation has been repeated
2323 \meta{number} times.
2324 %
2325 \begin{codeexample}[
2326 preamble={\usetikzlibrary{animations}},
2327 animation list={
2328 0.333/\frac{1}{3},0.666/\frac{2}{3},1,
2329 1.333/1\frac{1}{3},1.666/1\frac{2}{3},2,
2330 2.333/2\frac{1}{3},2.666/2\frac{2}{3},3,
2331 3.333/2\frac{1}{3},3.666/2\frac{2}{3},4%
2332 },
2333 ]
2334 \tikz
2335 \node [animate = { myself: = {
2336 :rotate = { 0s="0", 2s="90", begin on = {repeat = 2, of next = anim },
2337 begin snapshot = 2 },
2338 :xshift = { 0s="0mm", 2s="5mm", begin on=click, name=anim, repeats=4 }}},
2339 fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2340 \end{codeexample}
2341 \end{key}
2342
2343 \begin{key}{/pgf/animation/events/key=\meta{key}}
2344 The event is triggered when the keyboard key \meta{key} has been
2345 pressed. For security reasons, a viewer may suppress this.
2346 \end{key}
2347
2348 Having specified the event, you can also specify a delay relative to this
2349 event:
2350
2351 \begin{key}{/pgf/animation/events/delay=\meta{time}}
2352 Specifies that the timeline should not start with the event, but,
2353 rather, be delayed by \meta{time}.
2354 \end{key}
2355 \end{key}
2356
2357 When you use |begin on| to start an animation when a certain event is
2358 triggered, it is not clear what should happen when the event is triggered
2359 \emph{again}. Should this be ignored completely? Should it only be ignored
2360 while the animation is running? The following key allows you to specify when
2361 should happen:
2362
2363 \begin{key}{/tikz/animate/options/restart=\meta{choice} (default true)}
2364 You can set \meta{choice} to one of the following:
2365 %
2366 \begin{itemize}
2367 \item |true| means that the animation will restart each time the event
2368 is triggered. If the animation is already running, it will be reset
2369 to its beginning.
2370 \item |false| means that once the animation has started once, it will
2371 never be restarted.
2372 %
2373 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
2374 \tikz \node :rotate = { 0s="0", 2s="90",
2375 restart = false, begin on = {click}}
2376 [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2377 \end{codeexample}
2378 %
2379 \item |never| means the same as |false|.
2380 \item |when not active| means that the animation will restart when the
2381 event is triggered, but \emph{not} while the animation is running.
2382 %
2383 \begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
2384 \tikz \node :rotate = { 0s="0", 2s="90",
2385 restart = when not active, begin on = {click}}
2386 [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
2387 \end{codeexample}
2388 \end{itemize}
2389 \end{key}
2390
2391 Just like |begin on| specifies when a timeline begins relative to some event,
2392 the |end on| allows you to stop is early when some event happens:
2393
2394 \begin{key}{/tikz/animate/options/end on=\meta{options}}
2395 Works exactly like |begin on|, one possible end of the timeline is
2396 specified using the \meta{options}.
2397 \end{key}
2398
2399
2400 \subsubsection{Repeating Timelines and Accumulation}
2401
2402 \begin{key}{/tikz/animate/options/repeats=\meta{specification}}
2403 Use this key to specify that the timeline animation should repeat at the
2404 end. The \meta{specification} must consist of two parts, each of which may
2405 be empty. The first part is one of the following:
2406 %
2407 \begin{itemize}
2408 \item Empty, in which case the timeline repeats forever.
2409 %
2410 \begin{codeexample}[
2411 preamble={\usetikzlibrary{animations}},
2412 animation list={1,2,3,4,5},
2413 ]
2414 \tikz \node :rotate = { 0s = "0", 2s = "90",
2415 repeats, begin on = click }
2416 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
2417 \end{codeexample}
2418 %
2419 \item A \meta{number} (like |2| or |3.25|), in which case the timeline
2420 repeats \meta{number} times.
2421 %
2422 \begin{codeexample}[
2423 preamble={\usetikzlibrary{animations}},
2424 animation list={1,2,3,4,5},
2425 ]
2426 \tikz \node :rotate = { 0s = "0", 2s = "90",
2427 repeats = 1.75, begin on = click }
2428 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
2429 \end{codeexample}
2430 %
2431 \item The text ``|for| \meta{time}'' (like |for 2s| or |for 300ms|), in
2432 which case the timeline repeats however often necessary so that it
2433 stops exactly after \meta{time}.
2434 %
2435 \begin{codeexample}[
2436 preamble={\usetikzlibrary{animations}},
2437 animation list={1,2,3,4,5},
2438 ]
2439 \tikz \node :rotate = { 0s = "0", 2s = "90",
2440 repeats = for 3.5s, begin on = click }
2441 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
2442 \end{codeexample}
2443 \end{itemize}
2444 %
2445 The second part of the specification must be one of the following:
2446 %
2447 \begin{itemize}
2448 \item Empty, in which case each time the timeline is restarted, the
2449 attribute's value undergoes the same series of values it did
2450 previously.
2451 \item The text |accumulating|. This has the effect that each time the
2452 timeline is restarted, the last values specified by the timeline is
2453 \emph{added} to the value from the previous iteration(s). A typical
2454 example is an animation that shifts a scope by, say, 1\,cm over a
2455 time of 1\,s. Now, if you repeat this five times, normally the
2456 scope will shift 1\,cm for 1\,s then ``jump back'', shift again,
2457 jump back, and so on for five times. In contrast, when the repeats
2458 are accumulating, the scope will move by 5\,cm over 5\,s in total.
2459 %
2460 \begin{codeexample}[
2461 preamble={\usetikzlibrary{animations}},
2462 animation list={1,2,3,4,5},
2463 ]
2464 \tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click,
2465 repeats = accumulating }
2466 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
2467 \end{codeexample}
2468 %
2469 \begin{codeexample}[
2470 preamble={\usetikzlibrary{animations}},
2471 animation list={1,2,3,4,5},
2472 ]
2473 \tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click,
2474 repeats = for 4s accumulating }
2475 [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
2476 \end{codeexample}
2477 \end{itemize}
2478 \end{key}
2479
2480 \begin{key}{/tikz/animate/options/repeat=\meta{specification}}
2481 An alias for |repeats|.
2482 \end{key}
2483
2484
2485 \subsubsection{Smoothing and Jumping Timelines}
2486 \label{section-anim-smooth}
2487
2488 Your specification of the timeline will consist of a sequence of times along
2489 with values that the attribute should have at these ``key times''. Between
2490 these key times, the attribute's value needs to be interpolated.
2491
2492 Suppose that an animation is supposed to interpolate a attribute's value
2493 between the two values |50| and |100| over a time of 10\,s. The simplest way of
2494 doing so is to do a linear interpolation, where the value as, say, 1\,s is 55,
2495 at 2\,s it is 60, and so on. Unfortunately, the linear interpolation does not
2496 ``look'' nice in many cases since the acceleration of a linear interpolation is
2497 zero during the animation, but infinite at the beginning and at the end; which
2498 looks ``jerky''.
2499
2500 To avoid this, you can specify that the time--attribute curve should not be a
2501 straight line, but rather a curve. You specify this curve using a spline. The
2502 most logical ``coordinate rectangle'' used for this spline in our example would
2503 be |(0s,50)| and |(10s,100)| and we would like to specify something like
2504 %
2505 \begin{codeexample}[code only]
2506 (0s,50) .. controls (5s,50) and (9s,100) .. (10s,100)
2507 \end{codeexample}
2508 %
2509 This would result in a time--attribute curve where the attribute at |50|
2510 changes slowly at 0\,s and also arrives slowly at |100| at 10\,s, but speeds up
2511 between these values.
2512
2513 We call the first control point |(5s,50)| the ``exit control'' and call
2514 |(9s,100)| the ``entry control'': The first control dictates how quickly or
2515 slowly a time point is left, the second dictates how quickly or slowly we enter
2516 the next one.
2517
2518 The control points are, however, not specified in the coordinate system
2519 indicated above. Rather, the rectangle |(0s,50)| to |(10s, 100)| gets
2520 normalized to |(0,0)| to |(1,1)|. The control point |(5s,50)| would thus become
2521 |(0.5,0)| and |(9s,100)| becomes |(0.9,1)|.
2522
2523 \begin{key}{/tikz/animate/options/exit control=\marg{time fraction}\marg{value fraction}}
2524 Specifies an exit control using two values as above. The spline from above
2525 would be specified as follows:
2526 %
2527 \begin{codeexample}[code only]
2528 exit control={0.5}{0},
2529 entry control={0.9}{1},
2530 0s = "50",
2531 10s = "100"
2532 \end{codeexample}
2533
2534 Note that the curve specified using exit and entry controls must be
2535 ``well-behaved'' in the sense that exactly one value must be specified for
2536 each point in time in the time interval.
2537
2538 In the next three example, we first specify a ``smooth'' exit from the
2539 start position, then a smooth arrival at the end position, and, finally
2540 both.
2541 %
2542 \begin{codeexample}[
2543 preamble={\usetikzlibrary{animations}},
2544 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}},
2545 ]
2546 \tikz {
2547 \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
2548 \node :yshift = { begin on = click,
2549 0s = { exit control = {1}{0}, "0cm" },
2550 1s = "-5mm",
2551 2s = "-10mm" }
2552 [fill = blue!20, draw = blue, very thick, circle] {Click me!};
2553 }
2554 \end{codeexample}
2555
2556 \begin{codeexample}[
2557 preamble={\usetikzlibrary{animations}},
2558 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}},
2559 ]
2560 \tikz {
2561 \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
2562 \node :yshift = { begin on = click,
2563 0s = "0cm",
2564 1s = "-5mm",
2565 2s = { entry control = {0}{1}, "-10mm" } }
2566 [fill = blue!20, draw = blue, very thick, circle] {Click me!};
2567 }
2568 \end{codeexample}
2569
2570 \begin{codeexample}[
2571 preamble={\usetikzlibrary{animations}},
2572 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}},
2573 ]
2574 \tikz {
2575 \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
2576 \node :yshift = { begin on = click,
2577 0s = { exit control = {1}{0}, "0cm" },
2578 1s = "-5mm",
2579 2s = { entry control = {0}{1}, "-10mm" } }
2580 [fill = blue!20, draw = blue, very thick, circle] {Click me!};
2581 }
2582 \end{codeexample}
2583 %
2584 \end{key}
2585
2586 \begin{key}{/tikz/animate/options/entry control=\marg{time fraction}\marg{value fraction}}
2587 Works like |exit control|.
2588 \end{key}
2589
2590 \begin{key}{/tikz/animate/options/ease in=\marg{fraction} (default 0.5)}
2591 A shorthand for |entry control={1-|\meta{fraction}|}{1}|.
2592 \end{key}
2593
2594 \begin{key}{/tikz/animate/options/ease out=\marg{fraction} (default 0.5)}
2595 A shorthand for |exit control={|\meta{fraction}|}{1}|.
2596 \end{key}
2597
2598 \begin{key}{/tikz/animate/options/ease=\marg{fraction} (default 0.5)}
2599 A shorthand for |ease in=|\meta{fraction}|, ease out=|\meta{fraction}.
2600
2601 Note that since for the first time the entry control is ignored and,
2602 similarly, for the last time the exit control is ignored, using the |ease|
2603 key with an animation having only two times is particularly easy, since we
2604 only need to set |ease| once:
2605 %
2606 \begin{codeexample}[
2607 preamble={\usetikzlibrary{animations}},
2608 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}},
2609 ]
2610 \tikz {
2611 \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
2612 \node :yshift = { begin on = click, ease, 0s = "0cm", 2s = "-10mm" }
2613 [fill = blue!20, draw = blue, very thick, circle] {Click me!};
2614 }
2615 \end{codeexample}
2616 %
2617 \end{key}
2618
2619 The opposite of having a smooth curve between two values, is to have a ``jump''
2620 from one value to the next. There are two keys for this:
2621
2622 \begin{key}{/tikz/animate/options/stay}
2623 Specifies that inside the time interval the value ``stays put'' at the
2624 first value till the end of the interval, where it will jump to the second
2625 value. This is similar to an exit control where the curve is ``infinitely
2626 flat''.
2627 %
2628 \begin{codeexample}[
2629 preamble={\usetikzlibrary{animations}},
2630 animation list={0.5,1,1.5,2,2.5},
2631 ]
2632 \tikz {
2633 \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
2634 \node :yshift = { begin on = click,
2635 0s = "0cm",
2636 1s = {stay, "-5mm"},
2637 2s = "-10mm" }
2638 [fill = blue!20, draw = blue, very thick, circle] {Click me!};
2639 }
2640 \end{codeexample}
2641 %
2642 \end{key}
2643
2644 \begin{key}{/tikz/animate/options/jump}
2645 Works like the |stay| key, but will cause the value to ``jump to'' the new
2646 value right at the beginning of the time interval. It is similar to an
2647 entry control specifying a ``flat'' curve.
2648 %
2649 \begin{codeexample}[
2650 preamble={\usetikzlibrary{animations}},
2651 animation list={0.5,1,1.5,2,2.5},
2652 ]
2653 \tikz {
2654 \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
2655 \node :yshift = { begin on = click,
2656 0s = "0cm",
2657 1s = {jump, "-5mm"},
2658 2s = "-10mm" }
2659 [fill = blue!20, draw = blue, very thick, circle] {Click me!};
2660 }
2661 \end{codeexample}
2662 %
2663 \end{key}
2664
2665
2666 \subsection{Snapshots}
2667 \label{section-anim-snap}
2668
2669 Snapshots are a way of taking a ``photographic snapshot'' of an animation at a
2670 certain time and then insert these into \textsc{pdf} files (or, for that
2671 matter, Postscript files or files in any other format, including \textsc{svg}):
2672 You specify a time like |2s| and then \tikzname\ will compute what the
2673 animation ``would look like after 2s'' and insert the necessary graphics
2674 command for rendering the graphic objects in the correct way. Since this
2675 computation is done by \tikzname\ and since only ``normal'' graphics command
2676 are inserted into the output, snapshots work with all output formats.
2677
2678 Apart from providing a fallback for \textsc{pdf}, snapshots are very useful by
2679 themselves: They make it easy to ``show'' how an animation unfolds on paper.
2680 For this, you simply typeset the same picture with the same animation several
2681 times (using a simple |\foreach| loop), but each time you set a different
2682 snapshot time. This will result in a sequence of pictures that depict the
2683 animation at different points in time and which can then be inserted alongside
2684 each other into the printed document. This approach has been used with the
2685 examples of animations in this manual.
2686 %
2687 \begin{codeexample}[preamble={\usetikzlibrary{animations}}]
2688 \foreach \t in {0.5, 1, 1.5, 2}
2689 \tikz [make snapshot of = \t]
2690 \fill :fill = {0s="black", 2s="red"} (0,0) circle [radius = 5mm];
2691 \end{codeexample}
2692
2693 Creating snapshots is done using the following key:
2694
2695 \begin{key}{/tikz/make snapshot of=\meta{time}}
2696 When this key is used in a \TeX\ scope, animation commands given in the
2697 scope do not add animation code to the output. Instead, \tikzname\ computes
2698 the values the attributes of the animation would have at the specified
2699 \meta{time} and inserts the necessary system layer command to set the
2700 attribute to the computed values (some care has been taken to make this
2701 computation match the computations done by viewer applications as best as
2702 possible).
2703 %
2704 \begin{codeexample}[preamble={\usetikzlibrary{animations}}]
2705 \tikz [make snapshot of = 1s] {
2706 \fill :fill = { 0s = "black", 2s = "white" } (0,0) rectangle ++(1,1);
2707 \fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1);
2708 }
2709 \end{codeexample}
2710
2711 The moment \meta{time} is best thought of as \meta{time} seconds after the
2712 ``moment zero'' where all timelines start by default. Now, ``real''
2713 animation may start at different time through user interaction, which
2714 clearly makes no sense for snapshots. Nevertheless, you will sometimes wish
2715 to have more control over when a timeline starts for the purposes of taking
2716 snapshots. You can use the following key for this:
2717
2718 \begin{key}{/tikz/animate/options/begin snapshot=\meta{start time}}
2719 Use this key on a timeline to specify that, only for purposes of taking
2720 snapshots, the timeline starts at \meta{start time} rather than at
2721 ``moment zero''. (Think of this as saying that the animation starts
2722 when a virtual user clicks on the animation and this click occurs
2723 \meta{start time} seconds after the general ``moment zero'', causing
2724 the animation to ``lag behind'' by this amount of time.)
2725 Computationally, for the timeline the \meta{start time} is subtracted
2726 from the snapshot's \meta{time} when the value needs to be determined:
2727 %
2728 \begin{codeexample}[preamble={\usetikzlibrary{animations}}]
2729 \tikz [make snapshot of = 1s] {
2730 \fill :fill = { 0s = "black", 2s = "white",
2731 begin snapshot = 1s } (0,0) rectangle ++(1,1);
2732 \fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1);
2733 }
2734 \end{codeexample}
2735 \end{key}
2736
2737 The computations of the values the animation ``would have'' are done
2738 entirely by \tikzname, which has the big advantage is that no support from
2739 the viewer application or the output format is needed -- snapshots work
2740 with all output formats, not just with \textsc{svg}. However, computations
2741 done by \tikzname\ are not always very precise and can be slow because of
2742 \TeX's limitations. In addition, there are some further limitations when it
2743 comes to \tikzname's computation of snapshot values:
2744 %
2745 \begin{itemize}
2746 \item As mentioned above, except for |begin snapshot|, other commands
2747 for specifying the beginning or end of a timeline based on user
2748 interaction make no sense for timelines: The keys |begin|,
2749 |begin on|, |end|, and |end on| are silently ignored.
2750 \item The value |current value| for a value is forbidden since this
2751 value is almost impossible to compute by \tikzname.
2752 \item Accumulating repeats of a motion are (currently) not supported,
2753 but should not rely on this.
2754 \end{itemize}
2755
2756 When \meta{time} is empty, ``snapshot taking'' is switched off and
2757 animation commands are inserted once more.
2758 \end{key}
2759
2760 \begin{key}{/tikz/make snapshot after=\meta{time}}
2761 Works exactly like |make snapshot of|, only the \meta{time} is interpreted
2762 as $\meta{time} + \epsilon$. This only makes a difference at the end of a
2763 timeline and when there are two or more values specified for the same time:
2764 When there are several values specified for time~$t$, a normal snapshot for
2765 time~$t$ uses the first value given for the attribute. In contrast, this
2766 command would use the last one given. Similarly, when an animation timeline
2767 ends at time $t$, a normal snapshot of time $t$ would use the last value of
2768 the timeline, while this key would not apply the animation at all (it has
2769 already ended at time $t + \epsilon$).
2770 %
2771 \begin{codeexample}[preamble={\usetikzlibrary{animations}}]
2772 \tikz [make snapshot of = 2s]
2773 \fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1);
2774 \tikz [make snapshot after = 2s]
2775 \fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1);
2776 \end{codeexample}
2777 %
2778 \end{key}
2779
2780 \begin{key}{/tikz/make snapshot if necessary=\meta{time} (default 0s)}
2781 This key makes a snapshot of \meta{time} only when the output format does
2782 not provide support for animations; if the output format supports
2783 animations (like \textsc{svg}), then the command has no effect and
2784 animations are created normally.
2785
2786 This manual is typeset with the following being set once are for all in
2787 preamble:
2788 %
2789 \begin{codeexample}[code only]
2790 \tikzset{make snapshot if necessary}
2791 \end{codeexample}
2792
2793 Because of this setting, in the \textsc{pdf} version of this document, all
2794 animations are shown at the value they would have at moment~$0s$. In
2795 contrast, in the \textsc{svg} version, the animations are created normally.
2796
2797 In both versions, the smaller pictures showing how the animation proceeds
2798 over time are created using |make snapshot of| for the indicated times.
2799 \end{key}
2800
2801
2802 %%% Local Variables:
2803 %%% mode: latex
2804 %%% TeX-master: "pgfmanual"
2805 %%% End: