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