| 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: |