summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-library-views.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-views.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-library-views.tex127
1 files changed, 127 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-library-views.tex b/graphics/pgf/base/doc/pgfmanual-en-library-views.tex
new file mode 100644
index 0000000000..a080042808
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-library-views.tex
@@ -0,0 +1,127 @@
+% 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{Views Library}
+\label{section-library-views}
+
+\begin{tikzlibrary}{views}
+ This library is used for creating \emph{views}, which are transformations
+ of a part of a picture so that this part ``fits'' into a ``viewbox''.
+ Mostly, views are useful in conjunction with animations.
+\end{tikzlibrary}
+
+A \emph{view} is essentially a ``window'' through which you see a graphic. To
+establish a view, you specify a rectangle -- which is the window -- and another
+rectangle surrounding the to-be-viewed graphic. The graphic will then be
+rescaled and shifted in such a way that the to-be-viewed rectangle matches the
+view's rectangle as well as possible. Note that establishing a view causes a
+\emph{canvas} transformation to be installed, not a coordinate transformation.
+
+View boxes are only seldom needed in normal graphics; you may prefer to use
+coordinate transformations or the |spy| library. Their main application is with
+animations since you can \emph{animate} the to-be-viewed rectangle. This makes
+it easy to create animations in which you zoom in, zoom out, and pan a graphic.
+
+\begin{key}{/tikz/meet=\meta{to-be-viewed corner}
+ \opt{|rectangle|} \meta{to-be-viewed corner} \opt{|at|
+ \meta{window corner} |rectangle| \meta{window corner}}%
+}
+ Use this key with a scope to establish a view for the scope. In the
+ argument to the |meet| key, both |rectangle| texts are optional. Also,
+ everything following |at| is optional; when it is missing, the \meta{window
+ corner}s are assumed to be the same as the \meta{to-be-viewed corner}s. The
+ latter are two corners of a rectangle that should be transformed in such a
+ way that it fits inside the rectangle described by the two window corners.
+
+ More precisely, at the beginning of the scope a canvas transformation is
+ installed that scales and translates the canvas is such a way that
+ %
+ \begin{enumerate}
+ \item the center of the to-be-viewed rectangle lies at the center of
+ the window rectangle and
+ \item the to-be-viewed rectangle has maximum size that it still fits
+ inside the window rectangle.
+ \end{enumerate}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{views}}]
+\tikz {
+ \draw [red, very thick] (0,0) rectangle (20mm,20mm);
+ \begin{scope}[meet = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}]
+ \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
+ \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi};
+ \end{scope} }
+\end{codeexample}
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{views}}]
+\tikz {
+ \draw [red, very thick] (0,0) rectangle (20mm,20mm);
+ \begin{scope}[slice = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}]
+ \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
+ \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi};
+ \end{scope} }
+\end{codeexample}
+
+ As mentioned earlier, the main use of views is in conjunction with
+ animations. In order to animate a view, you specify the scope containing
+ the |meet| command as the target object and then animate its |:view|
+ attribute:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{animations,views}}]
+\tikz [animate = {
+ my scope:view = {
+ begin on = { click, of next = here },
+ 0s = "{(0.5,0.5) (2.5,1.5)}",
+ 2s = "{(0.5,0) (1.5,2)}", forever
+ }}] {
+ \draw [red, fill=red!20, very thick, name=here]
+ (0,0) rectangle (20mm,20mm);
+ \begin{scope}[name = my scope,
+ meet = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}]
+ \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
+ \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi};
+ \end{scope} }
+\end{codeexample}
+ %
+ You can, of course, also specify the animation using the |animate myself:|
+ key when you specify the animation inside the scope:
+ %
+\begin{codeexample}[preamble={\usetikzlibrary{animations,views}}]
+\tikz [animate = {
+ my scope:view = {
+ }}] {
+ \draw [red, fill=red!20, very thick, name=here]
+ (0,0) rectangle (20mm,20mm);
+ \begin{scope}[animate = { myself: = { :view = {
+ begin on = { click, of = here },
+ 0s = "{(0.5,0.5) (2.5,1.5)}",
+ 2s = "{(0.5,0) (1.5,2)}", forever }}},
+ slice = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}]
+ \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
+ \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi};
+ \end{scope} }
+\end{codeexample}
+ %
+\end{key}
+
+\begin{key}{/tikz/view}
+ This is an alias for |/tikz/meet|.
+\end{key}
+
+\begin{key}{/tikz/slice=\meta{to-be-viewed corner}
+ \opt{|rectangle|} \meta{to-be-viewed corner} \opt{|at|
+ \meta{window corner} |rectangle| \meta{window corner}}%
+}
+ This key works exactly like |meet|, only the second rule is changed:
+ %
+ \begin{enumerate}
+ \item[$2'$.] the to-be-viewed rectangle has minimal size that it
+ encompasses all of the window rectangle.
+ \end{enumerate}
+\end{key}