summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-tikz-animations.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-tikz-animations.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-tikz-animations.tex2805
1 files changed, 2805 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-tikz-animations.tex b/graphics/pgf/base/doc/pgfmanual-en-tikz-animations.tex
new file mode 100644
index 0000000000..cda41ef690
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-tikz-animations.tex
@@ -0,0 +1,2805 @@
+% Copyright 2019 by Till Tantau
+%
+% This file may be distributed and/or modified
+%
+% 1. under the LaTeX Project Public License and/or
+% 2. under the GNU Free Documentation License.
+%
+% See the file doc/generic/pgf/licenses/LICENSE for more details.
+
+
+\section{Animations}
+\label{section-tikz-animations}
+
+\begin{tikzlibrary}{animations}
+ This library must be loaded in order to use animations with \tikzname.
+\end{tikzlibrary}
+
+
+\subsection{Introduction}
+
+An \emph{animation} changes the appearance of some part of a graphic over time.
+The archetypical animation is, of course, a \emph{movement} of some part of a
+picture, but a change of, say, the opacity of a path is also an animation.
+\tikzname\ allows you to specify such animations using special keys and
+notations.
+%
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ width=8cm,
+ animation list={0.7,1.4,2.1,2.8},
+ animation scale=.25,
+]
+\begin{tikzpicture}[
+ animate/orbit/.style 2 args = {
+ myself:shift = {
+ along = {
+ (0,0) circle [radius=#1]
+ } sloped in #2s/10,
+ repeats }} ]
+
+ \node :color = {0s = "orange",
+ 2s = "red",
+ 4s = "orange",
+ repeats}
+ {Sun};
+
+ \begin{scope}[animate={orbit={2.5cm}{365}}]
+ \node {Earth};
+ \node [animate={orbit={1cm}{28}}] {Moon};
+ \end{scope}
+
+ \useasboundingbox (-3.8,-3.8) (3.8,3.8);
+\end{tikzpicture}
+\end{codeexample}
+
+Adding an animation to a \tikzname\ picture is done as follows:
+%
+\begin{enumerate}
+ \item \emph{Before} or \emph{in the options of} the to-be-animated object
+ you specify the object together with an \emph{attribute} that you wish
+ to animate. Attributes are things like the fill color or the line width
+ or the position of the object.
+ \item You specify \emph{when} this attribute should have \emph{which}
+ values using a so-called \emph{timeline}. This is just a curve that
+ specifies for each point in time which value the attribute should have.
+ \item You can additionally use further options to configure the animation,
+ for instance you can specify that the animation should repeat or that
+ it should only start when a certain object is clicked.
+\end{enumerate}
+
+As a simple example, let us move a circle within thirty seconds by three
+centimeters to the left:
+%
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \draw :xshift = {0s = "0cm", 30s = "-3cm", repeats} (0,0) circle (5mm);
+\end{codeexample}
+
+As can be seen, a special syntax is used in several places: Entries with a
+colon such as |:xshift| specify an attribute, values are specified in quotation
+marks. This syntax will be explained in more detail later on.
+
+
+\subsubsection{Animations Change Attributes}
+
+Before we plunge into the details of how animations are specified, it is
+important to understand what \tikzname\ actually does when creating an
+animation: It does \emph{not} (as all other animation packages do) precompute a
+sequence of pictures that are later somehow displayed in rapid succession.
+Neither does it insert an external video into the document. Rather, a
+\tikzname\ animation is just an ``annotation'' in the output that a certain
+attribute of a certain object should change over time in some specific way when
+the object is displayed. It is the job of the document viewer application to
+actually compute and display the animation. The big advantage of this approach
+is that animations neither increase the output file sizes noticeably nor do
+they really slow down \TeX: The hard and complicated calculations are done by
+the viewer application. The disadvantage is, of course, that a document viewer
+application must understand the annotations and actually compute and display
+the animations. The \textsc{svg} format is a format for which this is possible,
+the popular \textsc{pdf} format is not. For the \textsc{svg} format, there are
+actually different possible ways of ``formulating'' the animations (using
+\textsc{smil} or \textsc{css} or JavaScript) and they have different advantages
+and disadvantages.
+
+To make a long story short: \tikzname\ animations currently work only with
+\textsc{svg} output (and use the \textsc{smil} ``flavor'' of describing
+animations). In future, it may well happen that other ``flavor'' of describing
+animations will be added, but it is very unlikely that \textsc{pdf} will ever
+support animations in a useful way.
+
+It is, however, possible to create ``snapshots'' of an animation and insert
+these into \textsc{pdf} files (or any other kind of file including \textsc{svg}
+files), see Section~\ref{section-anim-snap} for details. Snapshots are also
+useful for creating ``printed versions'' of animations and all of the small
+sequences of pictures in the manual that are used for showing what an animation
+key does have been creating using snapshots.
+
+
+\subsubsection{Limitations of the Animation System}
+
+There are a certain limitations of the animation system that you should keep in
+mind when considering how and when to use it:
+%
+\begin{enumerate}
+ \item As pointed out earlier, animations require a specific output format
+ (currently only \textsc{svg} is supported).
+ \item It is extremely difficult to animate ``lines between moving nodes''
+ correctly. Consider code like |\draw(a)--(b);| where |a| and |b| are
+ nodes. Now, when you animate the position of~|(a)|, the line connecting
+ |(a)| and |(b)| will, unfortunately, not ``move along'' automatically
+ (but it is easy to move the whole group of |(a)|, |(b)|, and the
+ connecting line as whole). You must ``cheat'' and introduce some
+ ``virtual'' nodes, which leads to rather complex and bloated code.
+ \item Animations are taken into consideration for bounding box computations,
+ but only for shifts, not for rotations, scaling, or skewing and also
+ possibly not when multiple shifts are active at the same time for the
+ same object.
+\end{enumerate}
+
+
+\subsubsection{Concepts: (Graphic) Objects}
+
+During an animation an attribute of a certain ``object'' changes over time. The
+term ``object'' is deliberately a bit vague since there are numerous different
+``things'' whose attributes can change. In detail, the following objects have
+attributes that can be animated:
+%
+\begin{enumerate}
+ \item Nodes, which are created by the |\node| command (and, also,
+ internally by commands such as |\graph|). For nodes, different parts of
+ the node can be animated separately; for instance, you can animate the
+ color of the background path, but also the color of the text, and also
+ the color of the foreground path (though most nodes do not have a
+ foreground path) and also the color of different text parts (though
+ only few nodes have multiple text parts).
+ \item Graphic scopes, which are created by numerous command, including the
+ |{scope}| environment, the |\scopes| command, but also |\tikz| itself
+ creates a graphic scope and so does each node and even each path.
+ \item View boxes, which can only be created using the |views| library.
+ \item Paths, which you create using the |\path| command or commands like
+ |\draw| that call |\path| internally. However, the (usually background)
+ path of a node can also be animated. Note that ``animating the path''
+ really means that the path itself should change over time; in essence,
+ you can ``warp'' a path over time.
+\end{enumerate}
+
+In all of these cases, you must either specify the animation inside the
+object's options using |animate| or use the |name| key to name the object and,
+then, refer to it in an |animate|. For nodes you can, of course, use the
+|(|\meta{node name}|)| syntax to name the node. Recall that you must
+\emph{always} specify the animation \emph{before} the object is created; it is
+not possible to animate an already created object.
+
+There is a special syntax for choosing the object of an animation, see
+Section~\ref{section-anim-syntax-obj}, but you can also use the |object| key to
+choose them directly, see Section~\ref{section-anim-def-obj}.
+
+
+\subsubsection{Concepts: Attributes}
+
+In addition to the to-be-animated object, you must also choose an
+\emph{attribute} that you wish to animate. Attributes are things like the color
+of an object, the position, but also things like the line width. The syntax for
+choosing attributes and the list of attributes will be explained in detail
+later on.
+
+Most attributes correspond directly to attributes that are directly supported
+by the backend driver (\textsc{svg}), but this is not always the case. For
+instance, for a node, \tikzname\ differentiates between the fill color, the
+draw (stroke) color, and the text color, while \textsc{svg} treats the text
+color are a special case of the fill color. \tikzname\ will do some internal
+mappings to ensure that you can animate the ``\tikzname\ attributes'' even when
+they are not directly supported.
+
+The same syntax that is used for specifying object is also used to specify
+attributes, see Section~\ref{section-anim-syntax-obj}, but you could also set
+them directly using the |attribute| key see
+Section~\ref{section-anim-def-attr}.
+
+
+\subsubsection{Concepts: Timelines}
+
+Once an object and an attribute have been chosen, a \emph{timeline} needs to be
+established. This is, essentially, a curve that specifies for each ``moment in
+time'' which value the attribute should have.
+
+A timeline has a \emph{start} and an \emph{end}, but the start need not be the
+``moment zero'' (we will come to that) and may even be negative, while the end
+may be at infinity. You specify the timeline by specifying for certain points
+in time what the value is at that moment; for all other moments the value is
+then interpolated. For instance, if you specify that the attribute |:xshift|
+(the ``horizontal position'' of the object) is 0\,mm at time 5\,s and 10\,mm at
+time 10\,s, then at 7.5\,s it will be 5\,mm and at 9\,s it will be 8\,mm
+(assuming a linear interpolation). The resulting optical effect will be that
+the object \emph{smoothly moves} by one centimeter to the right over a period
+of five seconds, starting five seconds after ``moment zero''.
+
+Now, what is the ``moment zero'', the ``beginning of an animation''? If nothing
+else is specified, an animation starts immediately when the graphic is shown
+and this is the moment zero relative to which the timeline is measured.
+However, it is also possible to change this. In particular, you can specify
+that the moment zero is when a particular \emph{event} occurs such as the user
+clicking on another object or another animation ending or starting.
+
+The interpolation of values is not always a straightforward affair. Firstly,
+for certain kinds of values is not clear how an interpolation should be
+computed. How does one interpolate between two paths? Between the colors red
+and green? Between the values |"true"| and |"false"|? In these cases, one must
+define carefully what the interpolation should be. Secondly, you may wish to
+use a non-linear interpolation, which is useful for ``easing'' motions: The
+visual effect of the movement specified above is that the object sits still
+from moment $0$ for five seconds, then there is an ``infinite acceleration''
+causing the object to suddenly move at the speed of 2\,mm per second, then
+there is no acceleration at all for five seconds, causing the object to move
+for one centimeter, followed by an ``infinite negative acceleration'' that
+makes the object come to a full stop. As a viewer you experience these infinite
+accelerations as ``unrealistic'', spoiling the effect of watching a (virtual)
+physical process. Non-linear interpolations allow you to avoid this effect.
+
+Just as for specifying objects and attributes, there is also a special syntax
+for specifying times and values.
+
+
+\subsection{Creating an Animation}
+
+\subsubsection{The Animate Key}
+
+In order to animate a picture, you create timelines for all objects and
+attributes that change during the animation. The key |animate| is used for
+creating these timelines.
+
+\begin{key}{/tikz/animate=\meta{animation specification}}
+ You must place all specifications of animations inside uses of |animate|.
+ You can, and usually should, place the specification of all timelines of a
+ single picture inside a single use of this key since it will reset the time
+ and the fork time (explained in Section~\ref{section-anim-def-times}). You
+ can, however, use this key several times, in principle. Note that if you
+ animate the same attribute of the same object in two different uses of
+ |animate|, two separate timelines will result (and complicated rules are
+ used to determine which one ``wins'' in case they specify conflicting
+ values for the attribute at different times).
+
+ The key can be used at all places where a \tikzname\ key is used; typically
+ you will use it with a |{scope}| environment, inside the options of a node,
+ or directly with the |\tikz| command:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list = {0.5,1,1.5,2},
+]
+\tikz \node [fill, text = white, animate = {
+ myself:fill = {0s = "red", 2s = "blue", begin on = click }}] {Click me};
+\end{codeexample}
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list = {0.5,1,1.5,2},
+]
+\tikz [animate = {a node:fill = {0s = "red", 2s = "blue",
+ begin on = click}}]
+ \node (a node) [fill, text = white] {Click me};
+\end{codeexample}
+
+ The details of what, exactly, happens in the \meta{animation specification}
+ will be described in the rest of this section. However, basically, an
+ \meta{animation specification} is just a sequence of normal \tikzname\
+ key--value pairs that get executed with the path prefix |/tikz/animate| and
+ with some special syntax handlers installed. In particular, you can define
+ styles for this key path and use them. For instance, we can define a
+ |shake| animation like this:
+ %
+\begin{codeexample}[width=4cm,preamble={\usetikzlibrary{animations}}]
+\tikzset{
+ animate/shake/.style = {myself:xshift = { begin on=click,
+ 0s = "0mm", 50ms = "#1", 150ms = "-#1", 250ms = "#1", 300ms = "0mm" }}}
+\tikz \node [fill = blue!20, draw=blue, very thick, circle,
+ animate = {shake = 1mm}] {Shake};
+\tikz \node [fill = blue!20, draw=blue, very thick, circle,
+ animate = {shake = 2mm}] {SHAKE};
+\end{codeexample}
+
+ Note that, as stressed earlier, you can only use the |animate| key to
+ specify animations for objects that do not yet exist. The node and object
+ names mentioned in a specification always refer to ``upcoming'' objects;
+ already existing objects of the same name are not influenced.
+
+ You can use the |name| key inside |animate| to ``name'' the animation. Once
+ named, you can later reference the animation in other animations; for
+ instance, you can say that another animation should start when the present
+ animation has ended.
+\end{key}
+
+
+\subsubsection{Timeline Entries}
+
+The ``job'' of the options passed to the |animate| key is to specify the
+timelines of the animation of (a part of) a picture. For each object and each
+attribute there may or may not be a timeline and, if present, the timeline
+consist of sequences of pairs of times and values. Thus, the most basic entity
+of an animation specification is a tuple consisting of five parts, which are
+selected by five different keys:
+%
+\begin{itemize}
+ \item |object| for selecting the object,
+ \item |attribute| for selecting the attribute,
+ \item |id| for selecting the timeline id (explained in
+ Section~\ref{section-anim-def-id}),
+ \item |time| for selecting a time, and
+ \item |value| for selecting a value.
+\end{itemize}
+%
+When all of these parts have been set up (using the above keys, which will be
+explained in more detail in a moment), you can use the following key to create
+an entry:
+
+\begin{key}{/tikz/animate/entry}
+ Each time this key is used in the options of |animate|, \tikzname\ checks
+ whether the five keys |object|, |attribute|, |id|, |time|, and |value| are
+ set. If one of them is not set, nothing happens. (The |id| key is set to
+ the value |default| by default, all other keys must be set explicitly.)
+
+ If all of these keys are set, a \emph{time--value} pair is created and
+ added to the timeline of attribute of the object. Additionally, all options
+ starting with |/tikz/animate/options/|, which also influence the timeline
+ like |begin on|, are also added to the timeline of the object--attribute
+ pair.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz [animate = {
+ object = node, attribute = fill, time = 0s, value = red, entry,
+ object = node, attribute = fill, time = 2s, value = blue, entry,
+ object = node, attribute = fill, begin on = click, entry}]
+ \node (node) [fill, text=white] { Click me };
+\end{codeexample}
+ %
+ In the above example, it would not have been necessary the specify the
+ object and the attribute in each line, they retain their values unless they
+ are overwritten. Thus, we could also have written:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz [animate = {
+ object = node, attribute = fill, time = 0s, value = red, entry,
+ time = 2s, value = blue, entry,
+ begin on = click, entry}]
+ \node (node) [fill, text=white] { Click me };
+\end{codeexample}
+ %
+ Note, however, that in both examples we actually add the time--value pair
+ $(2\mathrm{s}, \mathrm{blue})$ twice since the |time| and |value| keys also
+ retain their settings and, thus, for the third |entry| they have the same
+ values as before and a new pair is added. While this superfluous pair is
+ not a problem in the example (it has no visual effect), we will see later
+ on how such pairs can be avoided by using the |scope| key.
+
+ A sequence of calls of |entry| can freely switch between objects and
+ attributes (that is, between timelines), but the times for any given
+ timeline must be given in non-decreasing order:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz [animate = {
+ object = node, attribute = fill, time = 0s, value = red, entry,
+ object = node2, attribute = draw, entry,
+ object = node, attribute = fill, time = 2s, value = blue, entry,
+ object = node2, attribute = draw, entry,
+ object = node, attribute = fill, begin on = click, entry,
+ object = node2, attribute = draw, begin on = click, entry}] {
+ \node (node) [fill, text=white] { Node 1 };
+ \node (node2) [draw, ultra thick] at (0,-1) { Node 2 };
+}
+\end{codeexample}
+ %
+ In the above example, we could not have exchanged the first two lines of
+ the |animate| options with the third and fourth line since the values for
+ time |0s| must come before the values for time |2s|.
+\end{key}
+
+In the following, we have a closer look at the five keys the influence the
+|entry| key and then have a look at ways of grouping keys more easily.
+
+
+\subsubsection{Specifying Objects}
+\label{section-anim-def-obj}
+
+You use the |object| key to select the object(s) to which the next use of
+|entry| applies. There is also a special syntax for this, which is explained in
+Section~\ref{section-anim-syntax-obj}.
+
+\begin{key}{/tikz/animate/object=\meta{list of objects}}
+ The \meta{list of objects} is a comma-separated list of strings of the form
+ \meta{object}\opt{|.|\meta{type}}. All of the objects in the list are
+ selected as to-be-animate object for the next use of the |entry| key. The
+ objects referred to by \meta{object} will be the \emph{next} objects with
+ the |name| key set to \meta{object}. You can apply the |name| key to nodes
+ (where you can also use the special parentheses-syntax and put the name in
+ parentheses, it has the same effect), but also to scopes and paths. (The
+ |name path| key is not the same as |name|; it is an older key from the
+ intersections package and not related.)
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue",
+ begin on = click }}] {
+ \node (a) [fill, text = white, minimum width=1.5cm] at (0,1cm) {a};
+ \node (b) [fill, text = white, minimum width=1.5cm] at (0,5mm) {b};
+ \node (c) [fill, text = white, minimum width=1.5cm] at (0,0mm) {c}; }
+\end{codeexample}
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue",
+ begin on = click },
+ object = c, :fill = {0s = "green", 2s = "blue",
+ begin on = click } }] {
+ \scoped [name = a, yshift=1cm] \fill (0,0) rectangle (1.5cm,2mm);
+ \scoped [name = b, yshift=5mm] \fill (0,0) rectangle (1.5cm,2mm);
+ \scoped [name = c, yshift=0mm] \fill (0,0) rectangle (1.5cm,2mm); }
+\end{codeexample}
+
+ If the \meta{object} name is never used later in the file, no animation is
+ created.
+
+ The \meta{object} may also be the special text |myself|. In this case, the
+ referenced object is the scope or object to which the |animate| key is
+ given. If an object is named |myself| (as in |\node (myself) ...|), you
+ cannot reference this node using the |object| key, |myself| \emph{always}
+ refers to the object where the |animate| key is given (of course, you can
+ animate the node named |myself| by placing the |animate| key inside the
+ options of this node; you only cannot ``remotely'' add an animation to it).
+
+ The \meta{object} may be followed by a dot and a \emph{type}. This is needed
+ in rare cases where you want to animate only a special ``part'' of an
+ object that is not accessible in other ways. Normally, \tikzname\ takes
+ care of choosing these types automatically, you only need to set these ``if
+ you know what you are doing''.
+\end{key}
+
+
+\subsubsection{Specifying Attributes}
+\label{section-anim-def-attr}
+
+\begin{key}{/tikz/animate/attribute=\meta{list of attributes}}
+ The list of attributes must be a comma-separated list of attribute names.
+ The timelines specified later will apply to all of these attributes (and to
+ all objects previously selected using |object|). Possible attributes
+ include colors, positions, line width, but even the paths themselves. The
+ exact list of possible attributes is documented in
+ Section~\ref{section-anim-attrs}.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz [animate = {attribute = fill, n: = { 0s = "red", 2s = "blue",
+ begin on = click } }]
+ \node (n) [fill, text = white] {The node};
+\end{codeexample}
+\end{key}
+
+
+\subsubsection{Specifying IDs}
+\label{section-anim-def-id}
+
+\begin{key}{/tikz/animate/id=\meta{id} (initially default)}
+ Timelines are use to defined how the values of an attribute of an object
+ change over time. In many cases, you will have at most one timeline for
+ each object--attribute pair, but, sometimes, you may wish to have more than
+ one timeline for the same object and the same attribute. For instance, you
+ might have a timeline that specifies a changing |shift| of a node in some
+ direction and, at the same time, another timeline that specifies an
+ additional |shift| in some other direction(s). The problem is that there is
+ only one |shift| attribute and it would be difficult to compute the joint
+ effect of the two timelines.
+
+ For this purpose, timelines are actually identified not only by the
+ object--attribute pair but, in reality, by the triple consisting of the
+ object, the attribute, and the value of this key. We can now specify two
+ separate timelines:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz [animate = {
+ id = 1, n:shift = { 0s = "{(0,0)}", 2s = "{(0,5mm)}", begin on = click },
+ id = 2, n:shift = { 0s = "{(0,0)}", 2s = "{(5mm,0)}", begin on = click }
+}]
+ \node (n) [fill = blue!20, draw=blue, very thick] {The node};
+\end{codeexample}
+
+ The default value of |id| is |default|.
+\end{key}
+
+Because of the possibility of creating multiple timelines for the same
+attribute, it may happen that there is more than one timeline active that is
+``trying to modify'' a given attribute. In this case, the following rules are
+used to determine, which timeline ``wins'':
+%
+\begin{enumerate}
+ \item If no animation is active at the current time (all animation either
+ have not yet started or they have already ended), then the |base| value
+ given in the animation encountered last in the code is used. (If there
+ are no base values, the attribute is taken from the surrounding scope
+ and the animations have ``no effect''.)
+ \item If there are several active animations, the one that has started last
+ is used and its value is used.
+ \item If there are several active animations that have started at the same
+ time, the one that comes last in the code is used.
+\end{enumerate}
+
+Note that these rules do not apply to transformations of the canvas since these
+are always additive (or, phrased differently, they are always all active and
+the effects accumulate).
+
+
+\subsubsection{Specifying Times}
+\label{section-anim-def-times}
+
+\begin{key}{/tikz/animate/time=\meta{time}\opt{|later|}}
+ Sets the time for the next time--value pair in a call of |entry| to
+ \meta{time} plus the current fork time. The text |later| is optional. Both
+ ``fork times'' and the optional |later| will be explained in a moment.
+
+ \medskip\textbf{Time Parsing.}
+ The \meta{time} is parsed using the command |\pgfparsetime|, which is
+ essentially the same as the usual math parser of \tikzname, and the result
+ is interpreted as a time in seconds. Thus, a \meta{time} of |2+3| means ``5
+ seconds'' and a \meta{time} of |2*(2.1)| means ``4.2 seconds''. (You could
+ even specify silly times like |1in|, which results in the time ``72.27
+ seconds''. Please do not do that.) The ``essentially'' refers to the fact
+ that some extras are installed when the time parser is running:
+ %
+ \begin{itemize}
+ \item The postfix operator |s| is added, which has no effect. Thus,
+ when you write |5s| you get the same results as |5|, which is
+ exactly 5 seconds as desired.
+ \item The postfix operator |ms| is added, which divides a number by
+ 1000, so |2ms| equals 0.002s.
+ \item The postfix operator |min| is added, which multiplies a number by
+ 60.
+ \item The postfix operator |h| is added, which multiplies a number by
+ 3600.
+ \item The infix operator |:| is redefined, so that it multiplies its
+ first argument by 60 and adds the second. This implies that |1:20|
+ equals 80s and |01:00:00| equals 3600s.
+ \item The parsing of octal numbers is switched off to allow things like
+ |01:08| for 68s.
+ \end{itemize}
+
+ Note that you cannot use the colon syntax for times in things like
+ |01:20 = "0"| would (falsely) be interpreted as: ``For the object named |01|
+ and its attribute named |20|, do something.'' You can, however, use |01:20|
+ in arguments to the |time| key, meaning that you would have to write
+ instead: |time = 1:20, "0"|, possibly surround by a |scope|.
+
+ \medskip\textbf{Relative Times.}
+ You can suffix a |time| key with ``|later|''. In this case, the \meta{time}
+ is interpreted as an offset to the time in the previous use of the time
+ key:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :fill = { begin on = click,
+ 0s = "white",
+ 500ms later = "red",
+ 500ms later = "green", % same as 1s = "-5mm"
+ 500ms later = "blue"} % same as 1.5s = "-2.5mm"
+ [fill=blue!20, draw=blue, very thick, circle] {Click me};
+\end{codeexample}
+
+ In reality, the offset is not taken to just any previous use of the |time|
+ key, but to the most recent use of this key or of the |resume| key in the
+ current local \TeX\ scope. Here is an example:
+ %
+\begin{codeexample}[code only]
+time = 2s,
+time = 1s later, % same as time = 3s
+time = 500ms later, % same as time = 3.5s
+time = 4s,
+time = 1s later, % same as time = 5s
+scope = { % opens a local scope
+ time = 1s later, % same as time = 6s
+ time = 10s
+ time = 1s later % same as time = 11s
+}, % closes the scope, most recent time is 5s once more
+time = 2s later % same as time = 7s
+\end{codeexample}
+
+ \medskip\textbf{Fork Times.}
+ The time meant by the value \meta{time} passed to the |time| key is not
+ used directly. Rather, \tikzname\ adds the current \emph{fork time} to it,
+ which is |0s| by default. You can change the fork time using the following
+ key:
+ %
+ \begin{key}{/tikz/animate/fork=\meta{t} (default 0s later)}
+ Sets the fork time for the local scope to \meta{t} and sets the current
+ time to |0s|. In this scope, when you use ``absolute'' times like |0s|
+ or |2s|, you actually refer to later times that have started as
+ \meta{t}.
+
+ One application of forks is in the definition of keys that add a
+ certain part to a longer animation. Consider for instance the
+ definition of a |highlight| key:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={1.05,1.1,1.15,1.2,2.05,2.1,2.15,2.2},
+]
+\tikz [animate/highlight/.style = {
+ scope = { fork = #1,
+ :fill = { 0s = "black", 0.1s = "white", 0.2s = "black"} }
+ }]
+ \node [animate = { myself: = {
+ :fill = { 0s = "black", begin on = click },
+ highlight = 1s, highlight = 2s } },
+ fill = blue, text=white, very thick, circle] { Click me };
+\end{codeexample}
+ %
+ In the above example, we could also have written |0.1s later| instead
+ of |0.2s| and, indeed, the whole style could have been defined using
+ only times with |later|, eliminating the need for the |fork| key.
+ However, using forks you can specify absolute times for things
+ happening in a conceptual ``subprocess'' and also relative times. The
+ name |fork| for the key is also borrowed from operating system theory,
+ where a ``fork'' is the spawning of an independent process.
+ \end{key}
+
+ \medskip\textbf{Remembering and Resuming Times.}
+ When you have a complicated animation with a long timeline, you will
+ sometimes wish to start some animation when some other animation has
+ reached a certain moment; but this moment is only reached through heavy use
+ of |later| times and/or forks. In such situations, the following keys are
+ useful:
+ %
+ \begin{key}{/tikz/animate/remember=\meta{macroname}}
+ This key stores the current time (the time of the last use of the
+ |time| key) globally in the macro \meta{macroname}. This time will
+ include the offset of the fork time:
+ %
+\begin{codeexample}[code only]
+time = 2s,
+fork = 2s later, % fork time is now 4s
+time = 1s, % local time is 1s, absolute time is 5s (1s + fork time)
+time = 1s later, % local time is 2s, absolute time is 6s (2s + fork time)
+remember = \mytime % \mytime is now 6s
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/tikz/animate/resume=\meta{absolute time}}
+ The \meta{absolute time} is evaluated using |\pgfparsetime| and, then,
+ the current time is set to the resulting time minus the fork time. When
+ the \meta{absolute time} is a macro previously set using |remember|,
+ the net effect of this is that we return to the exact ``moment'' in the
+ global time line when |remember| was used.
+ %
+\begin{codeexample}[code only]
+fork = 4s,
+time = 1s,
+remember = \mytime % \mytime is now 5s
+fork = 2s, % fork time is now 2s, local time is 0s
+resume = \mytime % fork time is still 2s, local time is 3s
+\end{codeexample}
+ %
+ Using resume you can easily implement a ``join'' operation for forked
+ times. You simply remember the times at the ends of the forks and then
+ resume the maximum time of these remembered times:
+ %
+\begin{codeexample}[code only]
+scope = {
+ fork,
+ time = 1s later,
+ ...
+ remember = \forka
+},
+scope = {
+ fork,
+ time = 5s later,
+ ...
+ remember = \forkb
+},
+scope = {
+ fork,
+ time = 2s later,
+ ...
+ remember = \forkc
+},
+resume = {max(\forka,\forkb,\forkc)} % "join" the three forks
+\end{codeexample}
+ \end{key}
+\end{key}
+
+
+\subsubsection{Values}
+\label{section-anim-def-values}
+
+\begin{key}{/tikz/animate/value=\meta{value}}
+ This key sets the value of the next time--value pair created by |entry| to
+ \meta{value}. The syntax of the \meta{value} is not fixed, it depends on
+ the type of the attribute. For instance, for an attribute like |opacity|
+ the \meta{value} must be an expression that can be evaluated to a number
+ between 0 and 1; for the attribute |color| the \meta{value} must, instead,
+ be a color; and so on. Take care that when a value contains a comma, you
+ must surround it by braces as in |"{(1,1)}"|.
+
+ The allowed texts for the \meta{value} is always the same as the one you
+ would pass to the \tikzname\ option of the same name. For instance, since
+ the \tikzname\ option |shift| expects a coordinate, you use coordinates as
+ \meta{value} with the usual \tikzname\ syntax (including all sorts of
+ extensions, the animation system calls the standard \tikzname\ parsing
+ routines). The same is true of dimensions, scalar values, colors, and so
+ on.
+
+ In addition to the values normally use for setting the attribute, you can
+ also (sometimes) use the special text |current value| as \meta{value}. This
+ means that the value of the point in the timeline should be whatever the
+ value the attribute has at the beginning of the timeline. For instance,
+ when you write
+ %
+\begin{codeexample}[code only]
+animate = { obj:color = { 0s = "current value", 2s = "white" } }
+\end{codeexample}
+ %
+ the color of |obj| will change from whatever color it currently has to
+ white in two seconds. This is especially useful when several animations are
+ triggered by user events and the current color of |obj| cannot be
+ determined beforehand.
+
+ There are several limitations on the use of the text |current value|, which
+ had to be imposed partly because of the limited support of this feature in
+ \textsc{svg}:
+ %
+ \begin{itemize}
+ \item You can use |current value| only with the first time in a
+ timeline.
+ \item You can only have two times in a timeline that starts with
+ |current value|.
+ \item You cannot use |current value| for timelines of which you wish to
+ take a snapshot.
+ \end{itemize}
+\end{key}
+
+
+\subsubsection{Scopes}
+\label{section-anim-scopes}
+
+When you specify multiple timelines at the same time, it is often useful and
+sometimes even necessary to have keys be set only locally. The following key
+makes this easy:
+
+\begin{key}{/tikz/animate/scope=\meta{options}}
+ Executed the \meta{options} inside a \TeX\ scope. In particular, all
+ settings made inside the scope have no effect after the end of the |scope|.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node [animate = { myself: = { begin on = click,
+ scope = { attribute = fill, repeats = 3, 0s = "red", 2s = "red!50" },
+ scope = { attribute = draw, 0s = "red", 2s = "red!50" }
+ }},
+ fill=blue!20, draw=blue, very thick, circle] {Click me};
+\end{codeexample}
+
+ Without the use of the |scope| key, the |repeats| key would also affect the
+ draw attribute.
+\end{key}
+
+While the |scope| key is useful for structuring timeline code, it also keeps
+the current time local to the scope, that is, if you use something like
+|1s later| after the scope, this will refer to one second after the last use of
+|time| \emph{before} the scope. The times set inside the |scope| do not matter.
+While this is desirable effect for forks, you may also sometimes wish to
+synchronize the local time after the scope with the last time reached in the
+scope. The following key makes this easy:
+
+\begin{key}{/tikz/animate/sync=\meta{options}}
+ A shorthand for |scope={| \meta{options} |, remember=\temp},resume=\temp|
+ where |\temp| is actually an internal name. The effect is that after a
+ |sync| the local time just continues as if the scope where not present --
+ but regarding everything else the effects are local to the |sync| scope.
+\end{key}
+
+
+\subsection{Syntactic Simplifications}
+\label{section-anim-syntax-animate}
+
+In the previous subsection we saw how timelines can be created by specifying
+the individual entries of the timelines sequentially. However, most of the time
+you will wish to use a simpler syntax that makes it easier to specify
+animations. This syntax is only available inside the |animate| key (it is
+switched on at the beginning) and consists of three ``parts'': The colon
+syntax, the time syntax, and the quote syntax.
+
+
+\subsubsection{The Colon Syntax I: Specifying Objects and Attributes}
+\label{section-anim-syntax-obj}
+
+Inside the \meta{animation specification} passed to the |animate| key, you can
+specify an object and an attribute of this object using the following syntax,
+whose use is detected by the presence of a colon inside a key:
+%
+\begin{quote}
+ \normalfont
+ \opt{\meta{object name(s)}}|:|\opt{\meta{attribute(s)}}
+ |={|\meta{options}|}|
+
+ or
+
+ \opt{\meta{object
+ name(s)}}|:|\opt{\meta{attribute(s)}}|_|\opt{\meta{id}}
+ |={|\meta{options}|}|
+\end{quote}
+%
+In the place to the left of an equal sign, where you would normally use a key,
+you can instead place an object name and an attribute separated by a colon.
+Additionally, the attribute may be followed by an underscore and an \meta{id},
+which identifies the timeline (see Section~\ref{section-anim-def-id}).
+
+Each of these values may be missing, in which case it is not changed from its
+previous value.
+
+The effect of the above code is the same as:
+%
+\begin{quote}
+ \normalfont
+ |sync = { object = |\meta{objects}|, attribute = |\meta{attribute}|, id = |\meta{id}|, |\meta{options}|, entry }|
+\end{quote}
+%
+although when the object, the attribute, or the id is left empty in the colon
+syntax, the corresponding setting will be missing in the above call of |sync|.
+Note that because of the |sync| the last time used inside the \meta{options}
+will be available afterwards as the last time. Also note that an |entry| is
+added at the end, so any settings of keys like |begin| or |repeats| inside the
+\meta{options} will get added to the timeline.
+
+Let us now have a look at some examples. First, we set the \meta{object name}
+to |mynode| and |othernode| and the \meta{attribute} to |opacity| and to
+|color|:
+%
+\begin{codeexample}[code only]
+animate = {
+ mynode:opacity = { 0s = "1", 5s = "0" },
+ mynode:color = { 0s = "red", 5s = "blue" },
+ othernode:opacity = { 0s = "1", 5s = "0" },
+}
+\end{codeexample}
+
+Next, we do the same, but ``in two steps'': First, we set the object to
+|mynode|, but leave the attribute open and, then, set the attribute, but leave
+the object:
+%
+\begin{codeexample}[code only]
+animate = {
+ mynode: = {
+ :opacity = { 0s = "1", 5s = "0" },
+ :color = { 0s = "red", 5s = "blue" }
+ },
+ othernode:opacity = { 0s = "1", 5s = "0" },
+}
+\end{codeexample}
+%
+Note how both in |mynode:| and in |:opacity| and |:color| you must provide the
+colon. Its presence signals that an object--attribute pair is being specified;
+only now either the object or the attribute is missing.
+
+We can also do it the other way round:
+%
+\begin{codeexample}[code only]
+animate = {
+ :opacity = {
+ mynode: = { 0s = "1", 5s = "0" },
+ othernode: = { 0s = "1", 5s = "0" }
+ },
+ mynode:color = { 0s = "red", 5s = "blue" }
+}
+\end{codeexample}
+%
+Finally, if several objects should get the exact same values, we can also group
+them:
+%
+\begin{codeexample}[code only]
+animate = {
+ {mynode,othernode}:opacity = { 0s = "1", 5s = "0" },
+ mynode:color = { 0s = "red", 5s = "blue" }
+}
+\end{codeexample}
+
+As mentioned earlier, all references to objects will be interpreted to future
+objects, never to objects already created. Furthermore, also as mentioned
+earlier, \tikzname\ allows you to specify |myself| as \meta{object}, which is
+interpreted as the scope or node where the |animate| is given (you cannot
+animate a node or scope named |myself|, this special name always refers to the
+current node). In order to have all attributes refer to the current object, you
+write:
+%
+\begin{codeexample}[code only]
+\begin{scope} [animate = {
+ myself: = { % Animate the attribute of the scope
+ :opacity = { ... },
+ :xshift = { ... }
+ }
+ }]
+ ...
+\end{scope}
+\end{codeexample}
+
+The list of permissible attributes is given in
+Section~\ref{section-anim-attrs}.
+
+
+\subsubsection{The Colon Syntax II: Animating Myself}
+
+A frequent use of the |animate| key is for animating attributes of the current
+object |myself|. In these cases, it is a bit length to write
+%
+\begin{codeexample}[code only]
+[animate = { myself: = { :some attribute = {...} } } ]
+\end{codeexample}
+%
+\noindent in the options of a node or a scope. For this reason, \tikzname\
+allows you to use a special syntax with nodes and scopes:
+%
+\begin{enumerate}
+ \item In a \meta{node specification}, which is everything following a
+ |node| command up to the content of the node (which is surrounded by
+ curly braces), you can write
+ %
+ \begin{quote}
+ |:some attribute = {|\meta{options}|}|
+ \end{quote}
+ %
+ and this will have the same effect as if you had written
+ %
+ \begin{quote}
+ |[animate = { myself: = { :some attribute = {|\meta{options}|}}}]|
+ \end{quote}
+ %
+ Note that you can use this syntax repeatedly, but each use creates a
+ new use of the |animate| key, resulting in a new timeline. In order to
+ create complex timelines for several objects, use the |animate| key.
+ \item For the commands |\tikz|, |\scoped| and the environments
+ |{tikzpicture}| and |{scope}|, when they are followed immediately by
+ %
+ \begin{quote}
+ |:some attribute = {|\meta{options}|}|
+ \end{quote}
+ %
+ then
+ %
+ \begin{quote}
+ |animate = { myself: = { :some attribute = {|\meta{options}|}}}|
+ \end{quote}
+ %
+ is added to the options of the command or scope. Again, you can use the
+ syntax repeatedly. Note that when an opening square bracket is
+ encountered, this special parsing stops.
+\end{enumerate}
+
+Let us have a look at some examples. First, we use the syntax to set the fill
+opacity of a node:
+%
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node
+ :fill opacity = { 0s="1", 2s="0", begin on=click }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Here!};
+\end{codeexample}
+%
+Next, we additionally rotate the node:
+%
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node
+ :fill opacity = { 0s="1", 2s="0", begin on=click }
+ :rotate = { 0s="0", 2s="90", begin on=click }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Here!};
+\end{codeexample}
+%
+Note that there is no comma between consecutive uses of the colon syntax in
+this case. We could have exchanged the order of the options and the uses of the
+colon syntax:
+%
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node
+ :fill opacity = { 0s="1", 2s="0", begin on=click }
+ [fill = blue!20, draw = blue, ultra thick, circle]
+ :rotate = { 0s="0", 2s="90", begin on=click } {Here!};
+\end{codeexample}
+
+We can also use the special syntax with the |\tikz| command itself:
+%
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz :fill opacity = { 0s="1", 2s="0", begin on=click }
+ :rotate = { 0s="0", 2s="90", begin on=click }
+ [ultra thick]
+ \node [fill = blue!20, draw = blue, circle] {Here!};
+\end{codeexample}
+
+Note that we could \emph{not} have moved the |[ultra thick]| options before
+|:rotate| since the options in square brackets end the special parsing.
+
+
+\subsubsection{The Time Syntax: Specifying Times}
+
+For each object--attribute pair you must specify the \emph{timeline} of the
+attribute. This is a curve that specifies for each ``moment in time'' which
+value the attribute should have. In the simplest case, you specify such a
+time--value pair as follows:
+%
+\begin{quote}
+ \normalfont
+ \meta{time} |="|\meta{value}|"|
+\end{quote}
+
+When you specify time--value pairs, you must specify the times in chronological
+order (so earlier times come first), but you may specify the same time several
+times (this is useful in situations where you have a ``jump'' from one value to
+another at a certain moment in time: you first specify the value ``from which
+the attribute jumps'' and then you specify the value ``to which the attribute
+jumps'' for the same moment).
+
+The above syntax is just a special case of a more general situation. Let us
+start with the times. The general syntax for specifying times is as follows:
+%
+\begin{quote}
+ \normalfont
+ \meta{time} \opt{|=| \meta{options}}
+\end{quote}
+
+Here, \meta{time} is a text that ``looks like a time'', which means that:
+%
+\begin{enumerate}
+ \item It is not a key and does not contain a colon and does not start with
+ a quotation mark.
+ \item It starts with a digit, a plus or minus sing, a dot, or a
+ parenthesis.
+\end{enumerate}
+
+If these two things are the case, the above code is transformed to the
+following call:
+%
+\begin{quote}
+ \normalfont
+ |sync = {time = |\meta{time}|, |\meta{options}|, entry}|
+\end{quote}
+
+
+\subsubsection{The Quote Syntax: Specifying Values}
+
+We saw already in several examples that values are put in quotation marks
+(similar to the way this is done in \textsc{xml}). This quote syntax is as
+follows:
+%
+\begin{quote}
+ \normalfont
+ |"|\meta{value}|"| \opt{|base|} \opt{|=| \meta{options}}
+\end{quote}
+
+This syntax is triggered whenever a key starts with a quotation mark%
+\footnote{Of catcode 12 for those knowledgeable of such things.} (and note that
+when the \meta{value} contains a comma, you have to surround it by curly braces
+\emph{inside} the quotation marks as in |"{(1,1)}"|). Then, the following code
+is executed:
+%
+\begin{quote}
+ \normalfont
+ |sync = {value = |\meta{value}|, |\meta{options}|, entry}|
+\end{quote}
+
+This means that when you write |1s = "red"|, what actually happens is that
+\tikzname\ executes the following:
+%
+\begin{codeexample}[code only]
+sync = { time = 1s, sync = { value = red, entry }, entry }
+\end{codeexample}
+%
+Note that the second entry has no effect since no value is specified and the
+|entry| key only ``takes action'' when both a time and a value have been
+specified. Thus, only the innermost |entry| does, indeed, create a time--value
+pair as desired.
+
+In addition to the above, if you have added |base| after the closing quote, the
+following gets executed before the above |sync|:
+%
+\begin{quote}
+ \normalfont
+ |base = {value = |\meta{value}|}|
+\end{quote}
+
+This makes it easy to specify base values for timelines.
+
+Interestingly, instead of |1s="red"| you can also write |"red"=1s|. Let us now
+have a look at situations where this can be useful.
+
+
+\subsubsection{Timesheets}
+
+Using the |sync| key or using the three different syntactic constructs
+introduced earlier (the color syntax, the time syntax, the value syntax), you
+can organize the specification of an animation in different ways. Basically,
+the two most useful ways are the following:
+%
+\begin{enumerate}
+ \item You first select an object and an attribute for which you wish to
+ establish a timeline and then provide the time--value pairs in a
+ sequence:
+ %
+\begin{codeexample}[code only]
+animate = {
+ obj:color = {
+ 0s = "red",
+ 2s = "blue",
+ 1s later = "green",
+ 1s later = "green!50!black",
+ 10s = "black"
+ }
+}
+\end{codeexample}
+ %
+ When you specify timelines for several attributes of the same object,
+ you can group these together:
+ %
+\begin{codeexample}[code only]
+animate = {
+ obj: = {
+ :color = { 0s = "red", 2s = "green" },
+ :opacity = { 0s = "1", 2s = "0" }
+ }
+}
+\end{codeexample}
+ %
+ In this way of specifying animations the ``object comes first''.
+ \item Alternatively, you can also group the animation by time and, for each
+ ``moment'' (known as \emph{keyframes}) you specify which values the
+ attributes of the object(s) have:
+ %
+\begin{codeexample}[code only]
+animate = {
+ 0s = {
+ obj:color = "red",
+ obj:opacity = "1"
+ },
+ 2s = {
+ obj:color = "green",
+ obj:opacity = "0"
+ }
+}
+\end{codeexample}
+ %
+ Naturally, in this case it would have been better to ``move the object
+ outside'':
+ %
+\begin{codeexample}[code only]
+animate = {
+ obj: = {
+ 0s = {
+ :color = "red",
+ :opacity = "1"
+ },
+ 2s = {
+ :color = "green",
+ :opacity = "0"
+ }
+ }
+}
+\end{codeexample}
+ %
+ When there are several objects involved, we can mix all of these
+ approaches:
+ %
+\begin{codeexample}[code only]
+animate = {
+ 0s = {
+ obj: = {
+ :color = "red",
+ :opacity = "1"
+ },
+ main node: = {
+ :color = "black"
+ }
+ },
+ 2s = {
+ obj: = {
+ :color = "green",
+ :opacity = "0"
+ },
+ main node: = {
+ :color = "white"
+ }
+ }
+}
+\end{codeexample}
+ %
+\end{enumerate}
+
+
+\subsection{The Attributes That Can Be Animated}
+\label{section-anim-attrs}
+
+The following \meta{attributes} are permissible (actually, the attribute names
+do not include a colon, but since they will almost always be used with the
+colon syntax, it makes it easier to identify them):
+%
+\begin{itemize}
+ \itemsep0pt
+ \item |:dash phase|
+ \item |:dash pattern|
+ \item |:dash|
+ \item |:draw opacity|
+ \item |:draw|
+ \item |:fill opacity|
+ \item |:fill|
+ \item |:line width|
+ \item |:opacity|
+ \item |:position|
+ \item |:path|
+ \item |:rotate|
+ \item |:scale|
+ \item |:stage|
+ \item |:text opacity|
+ \item |:text|
+ \item |:translate|
+ \item |:view|
+ \item |:visible|
+ \item |:xscale|
+ \item |:xshift|
+ \item |:xskew|
+ \item |:xslant|
+ \item |:yscale|
+ \item |:yshift|
+ \item |:yskew|
+ \item |:yslant|
+\end{itemize}
+
+These attributes are detailed in the following sections, but here is a quick
+overview of those that do not have a \tikzname\ key of the same name (and which
+thus do not just animate the attribute set using this key):
+%
+\begin{itemize}
+ \item |:shift| allows you to add an animated shifting of the canvas, just
+ like \tikzname's |shift| key. However, in conjunction with the |along|
+ key, you can also specify the shifting along a path rather than via a
+ timeline of coordinates.
+ \item |:position| works similar to |:shift|, only the coordinates are not
+ relative movements (no ``shifts''), but refer to ``absolute positions''
+ in the picture.
+ \item |:path| allows you to animate a path (it will morph). The ``values''
+ are now paths themselves.
+ \item |:view| allows you to animate the view box of a view.
+ \item |:visible| decides whether an object is visible at all.
+ \item |:stage| is identical to |:visible|, but when the object is not
+ animated, it will be hidden by default.
+\end{itemize}
+
+
+\subsubsection{Animating Color, Opacity, and Visibility}
+\label{section-animation-painting}
+
+You can animate the color of the target object of an animation using the
+attributes |fill|, |draw|, and |text|. When the target of a color animation is
+a scope, you animate the color ``used in this scope'' for filling or stroking.
+However, when an object inside the scope has its color set explicitly, this
+color overrules the color of the scope.
+
+\begin{tikzanimateattribute}{fill, draw}
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz :fill = {0s = "red", 2s = "blue", begin on = click}
+ [text = white, fill = orange ] {
+ \node [fill] at (0mm,0) {A};
+ \node [fill] at (5mm,0) {B};
+ \node [fill = green!50!black ] at (1cm,0) {C};
+}
+\end{codeexample}
+\end{tikzanimateattribute}
+
+\begin{tikzanimateattribute}{text}
+ The |text| attribute only applies to nodes and you need to directly animate
+ the |text| attribute of each node individually.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz [my anim/.style={ animate = {
+ myself:text = {0s = "red", 2s = "blue", begin on = click}}},
+ text = white, fill = orange ] {
+ \node [fill, my anim] at (0,0) {A};
+ \node [fill, my anim] at (1,0) {B};
+}
+\end{codeexample}
+ %
+ Unlike the |fill| and |draw| colors, you cannot animate the |text| color
+ for scopes:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz [animate = {myself:text = {0s = "red", 2s = "blue",
+ begin on = click}},
+ text = white, fill = orange ] {
+ \node [fill] at (0,0) {A};
+ \node [fill] at (1,0) {B};
+}
+\end{codeexample}
+ %
+\end{tikzanimateattribute}
+
+\begin{tikzanimateattribute}{color}
+ The |color| attribute is not really an attribute. Rather, it is a shorthand
+ for |{draw,fill,text}|. This means that |color| does not start a separate
+ timeline, but continues the |draw| timeline, the |fill| timeline, and the
+ |text| timeline.
+\end{tikzanimateattribute}
+
+\begin{tikzanimateattribute}{opacity, fill opacity, stroke opacity}
+ Similarly to the color, you can also set the opacity used for filling and
+ for drawing using the attributes |fill opacity| and |draw opacity|, which
+ are exactly the same as the usual \tikzname\ keys of the same names.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :fill opacity = { 0s="1", 2s="0", begin on=click }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+ Unlike colors, where there is no joint attribute for filling and stroking,
+ there is a single |opacity| attribute in addition to the above two
+ attributes. If supported by the driver, it treats the graphic object to
+ which it is applied as a transparency group. In essence, ``this attribute
+ does what you want'' at least in most situations.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :opacity = { 0s="1", 2s="0", begin on=click }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+\end{tikzanimateattribute}
+
+\begin{tikzanimateattribute}{visible, stage}
+ The difference between the |visible| attribute and an opacity of |0| is
+ that an invisible object cannot be clicked and does not need to be
+ rendered. The (only) two possible values for this attribute are |false| and
+ |true|.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={1,2,3,4},
+]
+\tikz :visible = {begin on=click, 0s="false", 2s="false"}
+ \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
+\end{codeexample}
+
+ This |stage| attribute is the same as the |visible| attribute, only
+ |base="false"| is set by default. This means that the object is \emph{only}
+ visible when you explicitly during the time the entries are set to |true|.
+ The idea behind the name ``stage'' is that the object is normally ``off
+ stage'' and when you explicitly set the ``stage attribute'' to |true| the
+ object ``enters'' the stage and ``leaves'' once more when it is no longer
+ ``on stage''.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={-1,0,1,2,3},
+ animation bb={(1.3,-0.7) rectangle (2.7,0.7)},
+]
+\tikz [animate = {example:stage = {
+ begin on = {click, of next=node},
+ 0s="true", 2s="true" }}] {
+ \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
+ \node at (2,0) (example) [fill = blue!20, circle] {Effect};
+}
+\end{codeexample}
+\end{tikzanimateattribute}
+
+
+\subsubsection{Animating Paths and their Rendering}
+\label{section-animation-paths}
+
+The attributes of the appearance of a path that you can animate include the
+line width and the dash pattern, the path itself, as well as the arrow tips
+attached to the paths. Animating the line width and the dash pattern is easy
+since the animation attributes simply have that same names as the properties
+that they animate and the syntax for setting is also the same:
+
+\begin{tikzanimateattribute}{line width}
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :line width = { 0s="1pt", 2s="5mm", begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+ Note that you must specify number (or expressions that evaluate to numbers)
+ as values, you cannot say |thin| or |thick| (these are styles, internally,
+ and you also cannot say |line width=thick|).
+\end{tikzanimateattribute}
+
+\begin{tikzanimateattribute}{dash, dash phase, dash phase}
+ The values for an animation of the dashing are specifications (see the
+ |dash| key for details) consisting of a sequence of |on| and |off| numbers.
+ In each value of the animation the length of these sequences \emph{must} be
+ identical. The interpolation of the values is done for each position of the
+ sequences individually, and also on the phase.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :dash = { 0s="on 10pt off 1pt phase 0pt",
+ 2s="on 1pt off 10pt phase 0pt", begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :dash = { 0s="on 1cm off 1pt phase 0pt",
+ 2s="on 1cm off 1pt phase 1cm", begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+
+ This |dash pattern| key allows you to animate the dash phase only. However,
+ due to the way dashing is handled by certain drivers, the dash pattern is
+ also set, namely to the current dash pattern that is in force when the
+ animation is created.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :dash phase = { 0s="0pt", 2s="1cm", begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle, dashed] {Click me!};
+\end{codeexample}
+ %
+\end{tikzanimateattribute}
+
+The above attributes ``only'' influence how the path is rendered. You can,
+however, also animate the path itself:
+
+\begin{tikzanimateattribute}{path}
+ When you animate a path, the values are, of course, paths themselves:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :path = {
+ 0s = "{(0,-1) .. controls (0,0) and (0,0) .. (0,1) -- (1,1)}",
+ 2s = "{(0,-1) .. controls (-1,0) and (-1,0) .. (-1,1) -- (.5,-1)}",
+ begin on=click }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+ There a number of things to keep in mind when you animate a path:
+ %
+ \begin{itemize}
+ \item The path ``values'' are parsed and executed in an especially
+ protected scope to ensure that they have only little side effects,
+ but you should not do ``fancy things'' on these paths.
+ \item As for the dash pattern, you must ensure that all paths in the
+ timeline have the same structure (same sequence of path
+ construction commands); only the coordinates may differ. In
+ particular, you cannot say that the path at |1s| is a rectangle
+ using |rectangle| and at |2s| is a circle using |circle|. Instead,
+ you would have to ensure that at both times the path consists of
+ appropriate Bézier curves (which is cumbersome as the following
+ example shows, where we used the fact that a circle consists of
+ four Bézier curves):
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :path = {
+ 0s = "{(0,0) circle [radius=1cm]}",
+ 2s = "{(0,0)
+ (1,0) .. controls +(0,0) and +(0,0) .. (0,1)
+ .. controls +(0,0) and +(0,0) .. (-1,0)
+ .. controls +(0,0) and +(0,0) .. (0,-1)
+ .. controls +(0,0) and +(0,0) .. (1,0)
+ -- cycle (0,0)}",
+ begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+ \item You must specify arrow tips for an animated path in a special
+ way, namely using the |arrows| key for \emph{animations}, not the
+ normal |arrows| key (see below).
+ \end{itemize}
+\end{tikzanimateattribute}
+
+\begin{key}{/tikz/animate/arrows=\meta{arrow spec}}
+ This key only has an effect on |:path| animations. It causes the arrow tips
+ specified in \meta{arrow spec} to be added to the path during the animation
+ (the syntax is the same as for the normal |arrows| key). If you have
+ several different animations for a paths, these may contain different arrow
+ tips, but each animation must stick to one kind of arrow tips.
+
+ What happens internally when this key is used is the following: The
+ specified arrow tips are rendered internally as so-called \emph{markers,}
+ which are small graphics that can be placed at the beginning and ends of
+ paths and which ``rotate along'' as a path changes. Note that these markers
+ are used \emph{only} in the context of animated paths, the arrow tips of
+ normal, ``static'' paths are drawn without the use of markers. Normally,
+ there is no visual difference between an arrow tip drawn using markers or
+ those drawn for static paths, but in rare cases there may be differences.
+ You should only add arrows to open path consisting of a single segment with
+ sufficiently long first and last segments (so that \tikzname\ can shorten
+ these segments correctly when necessary).
+
+ As pointed out earlier, the only way to add arrow tips to a path that is
+ animated is using this key, you can \emph{not} say something like
+ %
+\begin{codeexample}[code only]
+\draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}" }
+ [->] (0,0) -- (1,0);
+\end{codeexample}
+ %
+ This will raise an error since you try to animate a path (|:path = ...|)
+ that has normal arrow tips attached (|[->]|).
+
+ Instead, you must specify the arrow tips inside the animation command:
+ %
+\begin{codeexample}[code only]
+\draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}", arrows = -> }
+ (0,0) -- (1,0);
+\end{codeexample}
+
+ However, the above code now has a big shortcoming: While the animation is
+ \emph{not} running, \emph{no} arrow tip is shown (the |arrows| key only
+ applies to the animation.
+
+ The trick is to use the |base| key. It allows you to install a path as the
+ ``base'' path that is used when no animation is running and the arrows
+ specified for the animation will also be used for the base. All told, the
+ ``correct'' way to specify the animation is the following (note that no
+ static path is specified, any specified path would be overruled by the
+ |base| path anyway):
+ %
+\begin{codeexample}[code only]
+\draw :path = { 1s = "{(0,0) -- (1,0)}" base, 2s = "{(0,1) -- (1,0)}", arrows = -> };
+\end{codeexample}
+
+ Here is an example:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+ animation bb={(-0.1,-0.1) rectangle (1.1,1.1)},
+]
+\tikz [very thick] {
+ \node (node) at (-2,0)
+ [fill = blue!20, draw = blue, very thick, circle] {Click me!};
+ \draw :path = {
+ 0s = "{(0,0) to[out=90, in=180] (.5,1) to[out=0, in=90] (.5,.5)}" base,
+ 2s = "{(1,0) to[out=180, in=180] (.25,.5) to[out=0, in=180] (1,.5)}",
+ arrows = <.<->, begin on = {click, of=node} }; }
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/animate/shorten < = \meta{dimension}}
+\end{key}
+
+\begin{key}{/tikz/animate/shorten > = \meta{dimension}}
+ For animated paths, just as the key |arrows| has to be passed to the
+ animation (to |:path|) instead of to the static path, the keys |shorten >|
+ and |shorten <| also have to be passed to the |:path| key.
+\end{key}
+
+
+\subsubsection{Animating Transformations: Relative Transformations}
+
+In order to animate the canvas transformation matrix, you do not animate an
+attribute called ``|:transform|''. Rather, there are several attributes that
+all manipulate the canvas transformation matrix in different ways. These keys,
+taken in appropriate combination, allow you to achieve any particular canvas
+transformation matrix. All keys that animate the transformation matrix always
+accumulate.
+
+Let us start with the ``standard'' attributes that are also available as keys
+in \tikzname:
+
+\begin{tikzanimateattribute}{scale, xscale, yscale}
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :scale = { 0s="1", 2s="0.2", begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+\end{tikzanimateattribute}
+
+\begin{tikzanimateattribute}{rotate}
+ The |rotate| key adds an animation of the rotation:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :rotate = { 0s="45", 2s="90", begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+ Note that there is no |rotate around| attribute, but you can use the
+ |origin| key to change the origin of the rotation.
+\end{tikzanimateattribute}
+
+\begin{tikzanimateattribute}{xskew, yskew, xslant, yslant}
+ The keys add an animation of the skew (given in degrees) or slant (given as
+ in the |xslant| and |yslant| key):
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :xskew = { 0s="0", 2s="45", begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :xslant = { 0s="-1", 2s="1", begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+\end{tikzanimateattribute}
+
+\begin{tikzanimateattribute}{xshift, yshift}
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :shift = { 0s="{(0,0)}", 2s="{(5mm,-5mm)}",
+ begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :xshift = { 0s="0pt", 2s="5mm", begin on=click}
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+\end{tikzanimateattribute}
+
+\begin{tikzanimateattribute}{shift}
+ This |:shift| attribute can be animated in two ways. First, you can simply
+ specify a sequence of coordinates in the same way as you would use the
+ |shift| key in \tikzname:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz \node :shift = { 0s = "{(0,0)}", 2s = "{(5mm,-5mm)}",
+ begin on = click }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+
+ However, you can also specify the sequence of positions along which the
+ shift should occur in a different way, namely by \emph{specifying a path
+ along which the object should be moved.} This is often not only more
+ natural to do, but also allows you to specify movements along curves.
+
+ \begin{key}{/tikz/animate/options/along=\marg{path}\meta{|sloped| or
+ |upright|}\opt{| in|\meta{time}}%
+ }
+ Use this key with a |:shift| (or a |:position|) to make \tikzname\
+ shift the object by the coordinates along the \meta{path}. When this
+ key is used, the values may no longer be coordinates, but must be
+ fractions of the distance along the path. A value of |"0"| refers to
+ the beginning of the path and |"1"| refers to the end:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz {
+ \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
+ \draw (1,.5) circle [radius=1mm];
+ \node :shift = {
+ along = {(0,0) circle[radius=5mm]} upright,
+ 0s="0", 2s=".25", begin on=click }
+ at (1,.5) [fill = blue, opacity=.5, circle] {Click};
+}
+\end{codeexample}
+ \end{key}
+
+ Following the \meta{path}, which must be put in braces, you must either
+ specify |upright| or |sloped|. In the first case, the to-be-animated object
+ is moved along the path normally (and stays ``upright''), whereas when you
+ use |sloped|, the object will be continuously rotated so that it always
+ points along the path.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz {
+ \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
+ \draw (1,.5) circle [radius=1mm];
+ \node :shift = {
+ along = {(0,0) circle[radius=5mm]} sloped,
+ 0s="0", 2s=".25", begin on=click }
+ at (1,.5) [fill = blue, opacity=.5, circle] {Click};
+}
+\end{codeexample}
+
+ In most motion animations that use |along|, you will set the value for |0s|
+ to |"0"| and the value for some specific \meta{time} to |"1"|. Because of
+ this, you can add |in| \meta{time} after the path, to achieve exactly this
+ effect.
+\end{tikzanimateattribute}
+
+For the above attributes, it is not immediately clear which coordinate system
+should be used for the animation. That is, when you move an object 1cm ``to the
+right'', where is ``the right''? By default, movements and transformations like
+|:shift| or |:scale| are relative to the \emph{animation coordinate system,}
+which defaults to the local coordinate system of the to-be-animated object.
+Consider the following example:
+%
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz {
+ \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
+ \node :rotate = { 0s="0", 2s="45", begin on=click}
+ at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
+}
+\end{codeexample}
+%
+Note how the node rotates around its center even though this center is at
+position |(1,1)| in the picture's coordinate system. This is because |at (1,1)|
+actually only does a shift of the coordinate system and the node is then drawn
+at the origin of this shifted coordinate system. Since this shifted coordinate
+system becomes the animation coordinate system, the rotation ``around the
+origin'' is actually a rotation around the origin of the animation coordinate
+system, which is at |(1,1)| in the picture's coordinate system.
+
+Let us, by comparison, do a rotation of a scope surrounding the node where the
+origin is not (yet) shifted:
+%
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz {
+ \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
+ \scoped :rotate = { 0s="0", 2s="45", begin on={click, of next=n} }
+ \node (n) at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
+}
+\end{codeexample}
+%
+Now the rotation is really around the origin of the picture.
+
+Most of the time the animation coordinate system will be setup in the way ``you
+expect'', but you can modify it using the following keys:
+
+\begin{key}{/tikz/animate/options/origin=\meta{coordinate}}
+ Shifts the animation coordinate system by \meta{coordinate}. This has the
+ effect that the ``origin'' for scalings and rotations gets shifted by this
+ amount. In the following example, the point around which the rotation is
+ done is the right border at |(2,1)| since the origin of the animation is at
+ |(1,1)| relative to the picture's origin and the |origin| key shifts it one
+ centimeter to the right.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz {
+ \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
+ \node :rotate = { 0s="0", 2s="45", begin on=click,
+ origin = {(1,0)}}
+ at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
+}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/animate/options/transform=\meta{transformation keys}}
+ While the |origin| key does only a shift, the |transform| key allows you to
+ add an arbitrary transformation to the animation coordinate system using
+ keys like |shift|, |rotate| or even |reset cm| and |cm|. In particular,
+ |origin=|\meta{c} has the same effect as |transform| |=|
+ |{shift=|\meta{c}|}|. Note that the transformation only influences the
+ animation, not the object itself.
+
+ As an example, when you say |transform={scale=2}|, an |:xshift| with a
+ value of |"1cm"| will actually shift the object by 2cm. Similarly, after
+ you say |transform={rotate=90,scale=2}|, the same |:xshift| of |"1cm"| will
+ actually shift the object by 2cm upwards.
+
+ Note that, internally, \tikzname\ has to invert the transformation matrix
+ resulting from the \meta{transformation keys} (plus the original animation
+ transformation matrix), which can by numerically instable when you use
+ ill-conditioned transformations.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz {
+ \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
+ \node :xshift = { 0s="0cm", 2s="5mm", begin on=click,
+ transform = {rotate=-90} }
+ at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
+}
+\end{codeexample}
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz {
+ \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
+ \node :xshift = { 0s="0cm", 2s="5mm", begin on=click,
+ transform = {rotate=-45, scale=2} }
+ at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
+}
+\end{codeexample}
+ %
+\end{key}
+
+
+\subsubsection{Animating Transformations: Positioning}
+
+The attributes for specifying transformations and, in particular, the |:shift|
+attribute are always expressed in the local animation coordinate system. This
+makes it easy to ``shift around a node a little bit'', but makes it hard to
+move a node ``from one position to another'' since coordinates need to be
+expressed relative to the node's coordinate system, which leads to all sorts of
+problems: Suppose you wish to have a node move from $(1,1)$ to $(2,1)$ and then
+to $(2,0)$. Now, if the node has already been placed at $(1,1)$ in the usual
+manner using |at|, then from the ``node's point of view'' you need to move the
+node to $(0,0)$, $(1,0)$, and $(1,-1)$. To make matters worse, when you use
+named coordinates as in
+%
+\begin{codeexample}[code only]
+\coordinate(A) at (1,1);
+\coordinate(B) at (2,1);
+\coordinate(C) at (2,0);
+\end{codeexample}
+%
+and then say that the movement should be from |(A)| to |(B)| to |(C)|, what
+should you expect? On the one hand, |(A)| and |(1,1)| should normally be
+interchangeable; on the other hand, |(A)| is a specific point in the plane, no
+matter from which coordinate system we look at it. It turns out that \tikzname\
+will stick to the second interpretation and actually turn |(A)| into |(0,0)|
+when it is parsed in the local coordinate system of a node starting at |(A)| --
+while |(1,1)| will stay the same.
+
+Because of all these confusing effects, there is another attribute |:position|,
+which is similar to a |:shift|, but the coordinates are not interpreted in the
+local coordinate system of the node, but in the coordinate system that is in
+force when the |animate| key is used. For a node, this is \emph{prior} to the
+setup of the node's coordinate system and, thus, usually the picture's
+coordinate system.
+
+\begin{tikzanimateattribute}{position}
+ Compare the two animations, one with |:position|, one with |:shift|.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz {
+ \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
+ \draw (1,.5) circle [radius=1mm] (1.5,0) circle [radius=1mm];
+ \node :position = { 0s="{(1,.5)}", 2s="{(1.5,0)}", begin on=click }
+ at (1,.5) [fill = blue, opacity=.5, circle] {Click};
+}
+\end{codeexample}
+ %
+ Compare this to a shift:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz {
+ \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
+ \draw (1,.5) circle [radius=1mm] (1.5,0) circle [radius=1mm];
+ \node :shift = { 0s="{(1,.5)}", 2s="{(1.5,0)}", begin on=click }
+ at (1,.5) [fill = blue, opacity=.5, circle] {Click};
+}
+\end{codeexample}
+ %
+ You can use the |along| key with |:position| in the same way as with
+ |:shift|, which is especially useful for specifying that a node ``travels''
+ between positions of the canvas:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2},
+]
+\tikz {
+ \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
+ \draw (1,1) circle [radius=1mm] (1.5,0) circle [radius=1mm];
+ \node :position = {
+ along = {(1,1) to[bend left] (1.5,0)} sloped in 2s,
+ begin on = click }
+ at (1,1) [fill = blue, opacity=.5, circle] {Click};
+}
+\end{codeexample}
+ %
+\end{tikzanimateattribute}
+
+
+\subsubsection{Animating Transformations: Views}
+\label{section-animation-views}
+
+The final method of changing the transformation matrix is to animate a
+\emph{view}.
+
+\begin{tikzanimateattribute}{view}
+ A view is a canvas transformation that shifts and scales the canvas in such
+ a way that a certain rectangle ``matches'' another rectangle: The idea is
+ that you ``look through'' a ``window'' (the view) and ``see'' a certain
+ area of the canvas. View animation do not allow you to do anything that
+ cannot also be done using the |shift| and |scale| keys in combination, but
+ it often much more natural to animate which area of a graphic you wish to
+ see than to compute and animate a scaling and shift explicitly.
+
+ In order to use a view, you first need to create a view, which is done
+ using the |meet| or |slice| keys from the |views| library, see
+ Section~\ref{section-library-views}. You can then animate the view using
+ the |view| attribute. The values passed to the |entry| key follow the same
+ syntax as the views in the |views| library (though you only animate the
+ to-be-viewed rectangle).
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations,views}},
+ animation list={0.5,1,1.5,2},
+ animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
+]
+\tikz [very thick] {
+ \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
+
+ \draw [green!50!black] (1.2,-0.8) rectangle (2.7,0.8);
+ \begin{scope}[view = {(0,0) (2,2) at (1.2,-0.8) (2.7,0.8)},
+ animate = {myself:view = {
+ begin on = {click, of=node},
+ 0s = "{(0,0) (2,2)}",
+ 2s = "{(1,1) (1.5,1.5)}" }}]
+ \draw [red] (10mm,10mm) rectangle (15mm,15mm);
+ \node at (10mm,10mm) [circle, fill=red, text=white, font=\tiny] {red};
+ \end{scope}
+}
+\end{codeexample}
+ %
+\end{tikzanimateattribute}
+
+
+\subsection{Controlling the Timeline}
+\label{section-anim-timeline}
+
+We can already specify timelines by giving a sequence of times in
+non-decreasing order along with corresponding values. In this section we have a
+look at further options that allow us to extend or control the timeline.
+
+
+\subsubsection{Before and After the Timeline: Value Filling}
+
+When you specify the timeline, you specify it for a certain interval
+$[t_1,t_2]$. By default, outside this interval the animation has no effect on
+the to-be-animated attribute. The following keys allows you to change this:
+
+\begin{key}{/tikz/animate/base=\meta{options}}
+ A ``base'' value is a value that is used for the attribute whenever the
+ timeline is \emph{not} active:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list = {0.5,1,1.5,2,2.5},
+]
+\tikz \node [fill = green, text = white] :fill =
+ { 1s = "red", 2s = "blue", base = "orange", begin on = click }
+ {Click me};
+\end{codeexample}
+
+ Syntactically, the |base| key works much like special time syntax: It sets
+ up a local |sync| scope and executes the \meta{options} in it and creates
+ an |entry|. However, instead of setting the |time| attribute to a time, it
+ sets it to a special value that tells \tikzname\ that when the entry is
+ created, the current \meta{value} should be used as the |base| value.
+
+ This means that you can write |base = "orange"| as in the above example to
+ set the base. However, you can also use the |base| key in other ways; most
+ noticeably, you can use it \emph{after} some value:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list = {0.5,1,1.5,2,2.5},
+]
+\tikz \node [fill = green, text = white] :fill =
+ { 1s = {"red" = base}, 2s = "blue", begin on = click }
+ {Click me};
+\end{codeexample}
+
+ Instead of using |base| as a key, you can also add |base| directly after
+ the quotes of a value. This is particularly useful for setting up a base
+ value that is also used in a timeline:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list = {0.5,1,1.5,2,2.5},
+]
+\tikz \node [fill = green, text = white] :fill =
+ { 1s = "red" base, 2s = "blue", begin on = click }
+ {Click me};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/animate/options/forever}
+ This key causes the timeline to continue ``forever'' after the last time
+ with the last value. You can also think of this as having the animation
+ ``freeze'' at the end.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list = {0.5,1,1.5,2,2.5},
+]
+\tikz \node :fill = { 1s="red", 2s="blue", forever, begin on=click}
+ [fill = green!50!black, text = white] {Click me};
+\end{codeexample}
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list = {0.5,1,1.5,2,2.5},
+]
+\tikz \node [fill = green!50!black, text = white]
+ :fill = { 1s = "red", 2s = "blue", begin on = click }
+ {Click me};
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/animate/options/freeze}
+ An alias for |forever|.
+\end{key}
+
+
+\subsubsection{Beginning and Ending Timelines}
+\label{section-anim-begin-end}
+
+The \meta{time} used with the first use of the |entry| key in a timeline is the
+start time and the \meta{time} in the last |entry| key is the stop time.
+However, this leaves open then question of when the whole timeline is to be
+started: The moment the document is opened? When the page is displayed? When
+the user scrolls to the to-be-animated object? When some other object is
+clicked? The key |begin|, and also the key |end|, allow you to specify answers
+to these questions.
+
+\begin{key}{/tikz/animate/options/begin=\meta{time}}
+ This key specifies when the ``moment |0s|'' should be relative to the
+ moment when the current graphic is first displayed. You can use this key
+ multiple times, in this case the timeline is restarted for each of the
+ times specified (if it is already running, it will be reset). If no |begin|
+ key is given at all, the effect is the same as if |begin=0s| had been
+ specified.
+
+ It is permissible to set \meta{time} to a negative value.
+
+ Note that this key has no effect for snapshots.
+\end{key}
+
+\begin{key}{/tikz/animate/options/end=\meta{time}}
+ This key will truncate the timeline so that it ends \meta{time} after the
+ display of the graphic, provided the timeline begins before the specified
+ end time. For instance, if you specify a timeline starting at 2\,s and
+ ending at 5\,s and you set |begin| to 1\,s and |end| to 4\,s, the timeline
+ will run, relative to the moment when the graphic is displayed from 3\,s to
+ 4\,s.
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
+\tikz \node [fill = green!50!black, text = white]
+ :rotate = { 1s = "0", 5s = "90", begin = 2s, end = 4s }
+ {Click me};
+\end{codeexample}
+ %
+\end{key}
+
+Instead of specifying the beginning of the timeline relative to the moment to
+to-be-animated graphic is displayed, you can also set the ``moment |0s|'' to
+the moment a specific \emph{event} happens using the following key:
+
+\begin{key}{/tikz/animate/options/begin on=\meta{options}}
+ The \meta{options} will be executed with the path |/pgf/animation/events|
+ and will cause a new beginning to be added to the list of possible
+ beginnings for the timeline (so the uses of this key accumulate). Each
+ ``beginning'' is just another possible ``moment |0s|'' for the timeline.
+ For instance, when the \meta{options} are set to |click|, then each time
+ the graph is clicked a moment |0s| starts for the timeline.
+
+ Most events are ``caused'' or ``happen to'' some object. For instance, the
+ |click| event happens when you click on a certain object. In order to
+ specify this object, use the following two keys inside the \meta{options}:
+ |of| and |of next|. If neither of these keys are given, the to-be-animated
+ object is used.
+
+ \begin{key}{/pgf/animation/events/of=\meta{id}\opt{|.|\meta{type}}}
+ This specifies a graphic object id in the same way as the |whom| key,
+ also with an optional \meta{type}. This is the object that ``causes''
+ the event to happen.
+
+ Unlike the |whom| key, which always refers to a not-yet-existing
+ object, this key always refers to an already existing object, namely to
+ the most recent use of the \meta{id}. In the following example, the
+ referenced object is the node with the label |2| since it is the most
+ recently referenced node with \meta{id} |X|.
+ %
+\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{animations}}]
+\tikz [very thick] {
+ \node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1};
+ \node (X) at (1,0.4) [fill = orange!20, draw = orange, circle] {2};
+ \node (node) :rotate = {0s="0", 2s="90", begin on = {click, of = X}}
+ [fill = red!20, draw = red, rectangle] {Anim};
+ \node (X) at (1,-0.4) [fill = blue!20, draw = blue, circle] {3};
+ \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; }
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/animation/events/of next=\meta{id}\opt{|.|\meta{type}}}
+ This key works like the |of| key, only it refers to a future (actually,
+ the next) object with the given \meta{id}, not to a previous one. This,
+ in the next example, the referenced node is the one with label |3|.
+ %
+\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{animations}}]
+\tikz [very thick] {
+ \node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1};
+ \node (X) at (1,0.4) [fill = blue!20, draw = blue, circle] {2};
+ \node (node) :rotate = {
+ 0s="0", 2s="90", begin on = {click, of next = X}}
+ [fill = red!20, draw = red, rectangle] {Anim};
+ \node (X) at (1,-0.4) [fill = orange!20, draw = orange, circle] {3};
+ \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; }
+\end{codeexample}
+ \end{key}
+
+ The following key allows you to specify the event that should cause the
+ animation to start:
+ %
+ \begin{key}{/pgf/animation/events/event=\meta{event name}}
+ Specifies the name of the event whose occurrence should start the
+ timeline. Which events are supported depends on the device on which the
+ animation is displayed, the output format (\textsc{svg} or some other
+ format), and the setup of scripts, but here is a list of events
+ supported by ``plain \textsc{svg}'': |click|, |focusin|, |focusout|,
+ |mousedown|, |mouseup|, |mouseover|, |mousemove|, |mouseout|, |begin|,
+ |end|. However, the following keys make using these events simpler:
+ %
+ \begin{key}{/pgf/animate/events/click}
+ This is a shorthand for |event=click|. This event gets triggered
+ when the user clicks on the triggering object with a mouse (or
+ something equivalent).
+ %
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \node :rotate = { 0s="0", 2s="90", begin on = {click}}
+ [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/animation/events/mouse down}
+ Shorthand for |event=mousedown|. The event gets triggered when the
+ user presses a mouse button down on the object.
+ %
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse down}}
+ [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/animation/events/mouse up}
+ Shorthand for |event=mouseup| and gets triggered, of course, when a
+ pressed button is released on the object.
+ %
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse up} }
+ [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/animation/events/mouse over}
+ Shorthand for |event=mouseover|. The event gets triggered the
+ moment the mouse cursor moves over the object.
+ %
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse over} }
+ [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/animation/events/mouse move}
+ Shorthand for |event=mousemove|. The event gets triggered lots of
+ times, namely each time the mouse moves while being ``over'' the
+ object.
+ %
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse move} }
+ [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/animation/events/mouse out}
+ Shorthand for |event=mouseout|. The opposite of |mouse over|:
+ triggered when the mouse leaves the object.
+ %
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse out} }
+ [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/animation/events/begin}
+ Shorthand for |event=begin|. The ``begin'' refers to the beginning
+ of another animation, namely the one referenced by |of| or
+ |of whom|. This means that the current animation will begin when
+ some other animation begins.
+ %
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \node [animate = {
+ myself:rotate = { 0s="0", 2s="90", begin on = {begin, of next=anim}},
+ myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim}
+ },
+ fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/animation/events/end}
+ Shorthand for |event=end|. Again, the ``end'' refers to the end of
+ another animation, namely the one referenced by |of| or |of whom|.
+ This means that the current animation will \emph{begin} when some
+ other animation \emph{ends}.
+ %
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \node [animate = {
+ myself:rotate = { 0s="0", 2s="90", begin on = {end, of next=anim}},
+ myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim }
+ },
+ fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/pgf/animation/events/focus in}
+ This is a shorthand for |event=focusin|. This event gets triggered
+ when the graphic object gets the focus (this usually makes sense
+ only for text input fields).
+ \end{key}
+ %
+ \begin{key}{/pgf/animation/events/focus out}
+ This is a shorthand for |event=focusout|.
+ \end{key}
+ \end{key}
+
+ In addition to the events specified using the generic |event| key, there
+ are two further events that take a parameter:
+ %
+ \begin{key}{/pgf/animation/events/repeat=\meta{number}}
+ The event is triggered when a repeating animation has been repeated
+ \meta{number} times.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ 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},2,
+ 2.333/2\frac{1}{3},2.666/2\frac{2}{3},3,
+ 3.333/2\frac{1}{3},3.666/2\frac{2}{3},4%
+ },
+]
+\tikz
+ \node [animate = { myself: = {
+ :rotate = { 0s="0", 2s="90", begin on = {repeat = 2, of next = anim },
+ begin snapshot = 2 },
+ :xshift = { 0s="0mm", 2s="5mm", begin on=click, name=anim, repeats=4 }}},
+ fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/pgf/animation/events/key=\meta{key}}
+ The event is triggered when the keyboard key \meta{key} has been
+ pressed. For security reasons, a viewer may suppress this.
+ \end{key}
+
+ Having specified the event, you can also specify a delay relative to this
+ event:
+
+ \begin{key}{/pgf/animation/events/delay=\meta{time}}
+ Specifies that the timeline should not start with the event, but,
+ rather, be delayed by \meta{time}.
+ \end{key}
+\end{key}
+
+When you use |begin on| to start an animation when a certain event is
+triggered, it is not clear what should happen when the event is triggered
+\emph{again}. Should this be ignored completely? Should it only be ignored
+while the animation is running? The following key allows you to specify when
+should happen:
+
+\begin{key}{/tikz/animate/options/restart=\meta{choice} (default true)}
+ You can set \meta{choice} to one of the following:
+ %
+ \begin{itemize}
+ \item |true| means that the animation will restart each time the event
+ is triggered. If the animation is already running, it will be reset
+ to its beginning.
+ \item |false| means that once the animation has started once, it will
+ never be restarted.
+ %
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \node :rotate = { 0s="0", 2s="90",
+ restart = false, begin on = {click}}
+ [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ %
+ \item |never| means the same as |false|.
+ \item |when not active| means that the animation will restart when the
+ event is triggered, but \emph{not} while the animation is running.
+ %
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
+\tikz \node :rotate = { 0s="0", 2s="90",
+ restart = when not active, begin on = {click}}
+ [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
+\end{codeexample}
+ \end{itemize}
+\end{key}
+
+Just like |begin on| specifies when a timeline begins relative to some event,
+the |end on| allows you to stop is early when some event happens:
+
+\begin{key}{/tikz/animate/options/end on=\meta{options}}
+ Works exactly like |begin on|, one possible end of the timeline is
+ specified using the \meta{options}.
+\end{key}
+
+
+\subsubsection{Repeating Timelines and Accumulation}
+
+\begin{key}{/tikz/animate/options/repeats=\meta{specification}}
+ Use this key to specify that the timeline animation should repeat at the
+ end. The \meta{specification} must consist of two parts, each of which may
+ be empty. The first part is one of the following:
+ %
+ \begin{itemize}
+ \item Empty, in which case the timeline repeats forever.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={1,2,3,4,5},
+]
+\tikz \node :rotate = { 0s = "0", 2s = "90",
+ repeats, begin on = click }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+ \item A \meta{number} (like |2| or |3.25|), in which case the timeline
+ repeats \meta{number} times.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={1,2,3,4,5},
+]
+\tikz \node :rotate = { 0s = "0", 2s = "90",
+ repeats = 1.75, begin on = click }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+ \item The text ``|for| \meta{time}'' (like |for 2s| or |for 300ms|), in
+ which case the timeline repeats however often necessary so that it
+ stops exactly after \meta{time}.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={1,2,3,4,5},
+]
+\tikz \node :rotate = { 0s = "0", 2s = "90",
+ repeats = for 3.5s, begin on = click }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ \end{itemize}
+ %
+ The second part of the specification must be one of the following:
+ %
+ \begin{itemize}
+ \item Empty, in which case each time the timeline is restarted, the
+ attribute's value undergoes the same series of values it did
+ previously.
+ \item The text |accumulating|. This has the effect that each time the
+ timeline is restarted, the last values specified by the timeline is
+ \emph{added} to the value from the previous iteration(s). A typical
+ example is an animation that shifts a scope by, say, 1\,cm over a
+ time of 1\,s. Now, if you repeat this five times, normally the
+ scope will shift 1\,cm for 1\,s then ``jump back'', shift again,
+ jump back, and so on for five times. In contrast, when the repeats
+ are accumulating, the scope will move by 5\,cm over 5\,s in total.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={1,2,3,4,5},
+]
+\tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click,
+ repeats = accumulating }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={1,2,3,4,5},
+]
+\tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click,
+ repeats = for 4s accumulating }
+ [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
+\end{codeexample}
+ \end{itemize}
+\end{key}
+
+\begin{key}{/tikz/animate/options/repeat=\meta{specification}}
+ An alias for |repeats|.
+\end{key}
+
+
+\subsubsection{Smoothing and Jumping Timelines}
+\label{section-anim-smooth}
+
+Your specification of the timeline will consist of a sequence of times along
+with values that the attribute should have at these ``key times''. Between
+these key times, the attribute's value needs to be interpolated.
+
+Suppose that an animation is supposed to interpolate a attribute's value
+between the two values |50| and |100| over a time of 10\,s. The simplest way of
+doing so is to do a linear interpolation, where the value as, say, 1\,s is 55,
+at 2\,s it is 60, and so on. Unfortunately, the linear interpolation does not
+``look'' nice in many cases since the acceleration of a linear interpolation is
+zero during the animation, but infinite at the beginning and at the end; which
+looks ``jerky''.
+
+To avoid this, you can specify that the time--attribute curve should not be a
+straight line, but rather a curve. You specify this curve using a spline. The
+most logical ``coordinate rectangle'' used for this spline in our example would
+be |(0s,50)| and |(10s,100)| and we would like to specify something like
+%
+\begin{codeexample}[code only]
+ (0s,50) .. controls (5s,50) and (9s,100) .. (10s,100)
+\end{codeexample}
+%
+This would result in a time--attribute curve where the attribute at |50|
+changes slowly at 0\,s and also arrives slowly at |100| at 10\,s, but speeds up
+between these values.
+
+We call the first control point |(5s,50)| the ``exit control'' and call
+|(9s,100)| the ``entry control'': The first control dictates how quickly or
+slowly a time point is left, the second dictates how quickly or slowly we enter
+the next one.
+
+The control points are, however, not specified in the coordinate system
+indicated above. Rather, the rectangle |(0s,50)| to |(10s, 100)| gets
+normalized to |(0,0)| to |(1,1)|. The control point |(5s,50)| would thus become
+|(0.5,0)| and |(9s,100)| becomes |(0.9,1)|.
+
+\begin{key}{/tikz/animate/options/exit control=\marg{time fraction}\marg{value fraction}}
+ Specifies an exit control using two values as above. The spline from above
+ would be specified as follows:
+ %
+\begin{codeexample}[code only]
+exit control={0.5}{0},
+entry control={0.9}{1},
+0s = "50",
+10s = "100"
+\end{codeexample}
+
+ Note that the curve specified using exit and entry controls must be
+ ``well-behaved'' in the sense that exactly one value must be specified for
+ each point in time in the time interval.
+
+ In the next three example, we first specify a ``smooth'' exit from the
+ start position, then a smooth arrival at the end position, and, finally
+ both.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ 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}},
+]
+\tikz {
+ \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
+ \node :yshift = { begin on = click,
+ 0s = { exit control = {1}{0}, "0cm" },
+ 1s = "-5mm",
+ 2s = "-10mm" }
+ [fill = blue!20, draw = blue, very thick, circle] {Click me!};
+}
+\end{codeexample}
+
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ 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}},
+]
+\tikz {
+ \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
+ \node :yshift = { begin on = click,
+ 0s = "0cm",
+ 1s = "-5mm",
+ 2s = { entry control = {0}{1}, "-10mm" } }
+ [fill = blue!20, draw = blue, very thick, circle] {Click me!};
+}
+\end{codeexample}
+
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ 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}},
+]
+\tikz {
+ \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
+ \node :yshift = { begin on = click,
+ 0s = { exit control = {1}{0}, "0cm" },
+ 1s = "-5mm",
+ 2s = { entry control = {0}{1}, "-10mm" } }
+ [fill = blue!20, draw = blue, very thick, circle] {Click me!};
+}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/animate/options/entry control=\marg{time fraction}\marg{value fraction}}
+ Works like |exit control|.
+\end{key}
+
+\begin{key}{/tikz/animate/options/ease in=\marg{fraction} (default 0.5)}
+ A shorthand for |entry control={1-|\meta{fraction}|}{1}|.
+\end{key}
+
+\begin{key}{/tikz/animate/options/ease out=\marg{fraction} (default 0.5)}
+ A shorthand for |exit control={|\meta{fraction}|}{1}|.
+\end{key}
+
+\begin{key}{/tikz/animate/options/ease=\marg{fraction} (default 0.5)}
+ A shorthand for |ease in=|\meta{fraction}|, ease out=|\meta{fraction}.
+
+ Note that since for the first time the entry control is ignored and,
+ similarly, for the last time the exit control is ignored, using the |ease|
+ key with an animation having only two times is particularly easy, since we
+ only need to set |ease| once:
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ 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}},
+]
+\tikz {
+ \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
+ \node :yshift = { begin on = click, ease, 0s = "0cm", 2s = "-10mm" }
+ [fill = blue!20, draw = blue, very thick, circle] {Click me!};
+}
+\end{codeexample}
+ %
+\end{key}
+
+The opposite of having a smooth curve between two values, is to have a ``jump''
+from one value to the next. There are two keys for this:
+
+\begin{key}{/tikz/animate/options/stay}
+ Specifies that inside the time interval the value ``stays put'' at the
+ first value till the end of the interval, where it will jump to the second
+ value. This is similar to an exit control where the curve is ``infinitely
+ flat''.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2,2.5},
+]
+\tikz {
+ \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
+ \node :yshift = { begin on = click,
+ 0s = "0cm",
+ 1s = {stay, "-5mm"},
+ 2s = "-10mm" }
+ [fill = blue!20, draw = blue, very thick, circle] {Click me!};
+}
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/animate/options/jump}
+ Works like the |stay| key, but will cause the value to ``jump to'' the new
+ value right at the beginning of the time interval. It is similar to an
+ entry control specifying a ``flat'' curve.
+ %
+\begin{codeexample}[
+ preamble={\usetikzlibrary{animations}},
+ animation list={0.5,1,1.5,2,2.5},
+]
+\tikz {
+ \foreach \i in {0,0.125,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
+ \node :yshift = { begin on = click,
+ 0s = "0cm",
+ 1s = {jump, "-5mm"},
+ 2s = "-10mm" }
+ [fill = blue!20, draw = blue, very thick, circle] {Click me!};
+}
+\end{codeexample}
+ %
+\end{key}
+
+
+\subsection{Snapshots}
+\label{section-anim-snap}
+
+Snapshots are a way of taking a ``photographic snapshot'' of an animation at a
+certain time and then insert these into \textsc{pdf} files (or, for that
+matter, Postscript files or files in any other format, including \textsc{svg}):
+You specify a time like |2s| and then \tikzname\ will compute what the
+animation ``would look like after 2s'' and insert the necessary graphics
+command for rendering the graphic objects in the correct way. Since this
+computation is done by \tikzname\ and since only ``normal'' graphics command
+are inserted into the output, snapshots work with all output formats.
+
+Apart from providing a fallback for \textsc{pdf}, snapshots are very useful by
+themselves: They make it easy to ``show'' how an animation unfolds on paper.
+For this, you simply typeset the same picture with the same animation several
+times (using a simple |\foreach| loop), but each time you set a different
+snapshot time. This will result in a sequence of pictures that depict the
+animation at different points in time and which can then be inserted alongside
+each other into the printed document. This approach has been used with the
+examples of animations in this manual.
+%
+\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
+\foreach \t in {0.5, 1, 1.5, 2}
+ \tikz [make snapshot of = \t]
+ \fill :fill = {0s="black", 2s="red"} (0,0) circle [radius = 5mm];
+\end{codeexample}
+
+Creating snapshots is done using the following key:
+
+\begin{key}{/tikz/make snapshot of=\meta{time}}
+ When this key is used in a \TeX\ scope, animation commands given in the
+ scope do not add animation code to the output. Instead, \tikzname\ computes
+ the values the attributes of the animation would have at the specified
+ \meta{time} and inserts the necessary system layer command to set the
+ attribute to the computed values (some care has been taken to make this
+ computation match the computations done by viewer applications as best as
+ possible).
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
+\tikz [make snapshot of = 1s] {
+ \fill :fill = { 0s = "black", 2s = "white" } (0,0) rectangle ++(1,1);
+ \fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1);
+}
+\end{codeexample}
+
+ The moment \meta{time} is best thought of as \meta{time} seconds after the
+ ``moment zero'' where all timelines start by default. Now, ``real''
+ animation may start at different time through user interaction, which
+ clearly makes no sense for snapshots. Nevertheless, you will sometimes wish
+ to have more control over when a timeline starts for the purposes of taking
+ snapshots. You can use the following key for this:
+
+ \begin{key}{/tikz/animate/options/begin snapshot=\meta{start time}}
+ Use this key on a timeline to specify that, only for purposes of taking
+ snapshots, the timeline starts at \meta{start time} rather than at
+ ``moment zero''. (Think of this as saying that the animation starts
+ when a virtual user clicks on the animation and this click occurs
+ \meta{start time} seconds after the general ``moment zero'', causing
+ the animation to ``lag behind'' by this amount of time.)
+ Computationally, for the timeline the \meta{start time} is subtracted
+ from the snapshot's \meta{time} when the value needs to be determined:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
+\tikz [make snapshot of = 1s] {
+ \fill :fill = { 0s = "black", 2s = "white",
+ begin snapshot = 1s } (0,0) rectangle ++(1,1);
+ \fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1);
+}
+\end{codeexample}
+ \end{key}
+
+ The computations of the values the animation ``would have'' are done
+ entirely by \tikzname, which has the big advantage is that no support from
+ the viewer application or the output format is needed -- snapshots work
+ with all output formats, not just with \textsc{svg}. However, computations
+ done by \tikzname\ are not always very precise and can be slow because of
+ \TeX's limitations. In addition, there are some further limitations when it
+ comes to \tikzname's computation of snapshot values:
+ %
+ \begin{itemize}
+ \item As mentioned above, except for |begin snapshot|, other commands
+ for specifying the beginning or end of a timeline based on user
+ interaction make no sense for timelines: The keys |begin|,
+ |begin on|, |end|, and |end on| are silently ignored.
+ \item The value |current value| for a value is forbidden since this
+ value is almost impossible to compute by \tikzname.
+ \item Accumulating repeats of a motion are (currently) not supported,
+ but should not rely on this.
+ \end{itemize}
+
+ When \meta{time} is empty, ``snapshot taking'' is switched off and
+ animation commands are inserted once more.
+\end{key}
+
+\begin{key}{/tikz/make snapshot after=\meta{time}}
+ Works exactly like |make snapshot of|, only the \meta{time} is interpreted
+ as $\meta{time} + \epsilon$. This only makes a difference at the end of a
+ timeline and when there are two or more values specified for the same time:
+ When there are several values specified for time~$t$, a normal snapshot for
+ time~$t$ uses the first value given for the attribute. In contrast, this
+ command would use the last one given. Similarly, when an animation timeline
+ ends at time $t$, a normal snapshot of time $t$ would use the last value of
+ the timeline, while this key would not apply the animation at all (it has
+ already ended at time $t + \epsilon$).
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
+\tikz [make snapshot of = 2s]
+ \fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1);
+\tikz [make snapshot after = 2s]
+ \fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1);
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/make snapshot if necessary=\meta{time} (default 0s)}
+ This key makes a snapshot of \meta{time} only when the output format does
+ not provide support for animations; if the output format supports
+ animations (like \textsc{svg}), then the command has no effect and
+ animations are created normally.
+
+ This manual is typeset with the following being set once are for all in
+ preamble:
+ %
+\begin{codeexample}[code only]
+\tikzset{make snapshot if necessary}
+\end{codeexample}
+
+ Because of this setting, in the \textsc{pdf} version of this document, all
+ animations are shown at the value they would have at moment~$0s$. In
+ contrast, in the \textsc{svg} version, the animations are created normally.
+
+ In both versions, the smaller pictures showing how the animation proceeds
+ over time are created using |make snapshot of| for the indicated times.
+\end{key}
+
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual"
+%%% End: