From 6bc1f5497cfb2f56d65c80a4c36ea3bad6dc046c Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Fri, 29 Oct 2010 00:31:31 +0000
Subject: pgf 2.10 (28oct10)

git-svn-id: svn://tug.org/texlive/trunk@20236 c570f23f-e606-0410-a88d-b1316a301751
---
 .../pgf/text-en/pgfmanual-en-library-spy.tex       | 451 +++++++++++++++++++++
 1 file changed, 451 insertions(+)
 create mode 100644 Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex

(limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex')

diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex
new file mode 100644
index 00000000000..dc6f163929f
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex
@@ -0,0 +1,451 @@
+% Copyright 2006 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{Spy Library: Magnifying Parts of Pictures}
+\label{section-library-spy}
+
+\begin{tikzlibrary}{spy}
+  The package defines options for creating pictures in which some part
+  of the picture is repeated in another area in a magnified way (as if
+  you were looking through a spyglass, hence the name).
+\end{tikzlibrary}
+
+
+\subsection{Magnifying a Part of a Picture}
+
+The idea behind the |spy| library is to make is easy to create high-density
+pictures in which some important parts are repeated somewhere, but
+magnified as if you were looking through a spyglass:
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+  [spy using outlines={circle, magnification=4, size=2cm, connect spies}]
+
+  \draw [help lines] (0,0) grid (3,2);
+
+  \draw [decoration=Koch curve type 1]
+    decorate { decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}};
+
+  \spy [red] on (1.6,0.3)
+             in node [left] at (3.5,-1.25);
+
+  \spy [blue, size=1cm] on (1,1)
+              in node [right] at (0,-1.25);
+\end{tikzpicture}
+\end{codeexample}
+
+\begin{codeexample}[]
+\begin{tikzpicture}[spy using overlays={size=12mm}]
+  \draw [decoration=Koch snowflake]
+    decorate { decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}};
+
+  \spy [green,magnification=3] on (0.6,0.1) in node at (-0.3,-1);
+  \spy [blue,magnification=5]  on (1,0.5)   in node at (1,-1);
+  \spy [red,magnification=10]  on (1.6,0.1) in node at (2.3,-1);
+\end{tikzpicture}
+\end{codeexample}
+
+
+Note that this magnification uses what is called a \emph{canvas
+  transformation} in this manual: Everything is magnified, including
+line width and text.
+
+In order for ``spying'' to work, the picture obviously has to be drawn
+several times: Once at its normal size and then again for each
+``magnifying glass.'' Several keys and commands work in concert to
+make this possible:
+\begin{itemize}
+\item You need to make \tikzname\ aware of the fact that a picture (or
+  just a scope) is to be magnified. This is done by adding the special
+  key |spy scope| to a |{scope}| or |{tikzpicture}| (which is also
+  just a scope). Some special keys like |spy using outlines|
+  implicitly set the |spy scope|.
+
+\item Inside this scope you may then use the command |\spy|, which is
+  only available inside such scopes (so there is no danger of your
+  inadvertently using this command outside such a scope). This command
+  has a special syntax and will (at some point) create two nodes: One
+  node that shows the magnified picture (called the \emph{spy-in
+    node}) and another node showing which part of the original picture
+  is magnified (called the \emph{spy-on} node). The spy-in node is,
+  indeed, a normal node, so it can have any shape or border that you
+  like and you can apply all of \tikzname's advanced features to
+  it. The only difference compared to a normal node is that instead of
+  some ``text'' it contains a magnified version of the picture,
+  clipped to the size of the node.
+
+  The |\spy| command does not create the nodes immediately. Rather,
+  the creation of these nodes is postponed till the end of the
+  |spy scope| in which the |\spy| command is used. This is necessary
+  since in order to repeat the whole scope inside the node containing
+  the magnified version, the whole picture needs to be available when
+  this node is created.
+\end{itemize}
+
+A basic question any library for ``magnifying things'' has to address
+is how you specify which part of the picture is to be
+magnified (the spy-on node) and where this magnified part is to be
+shown (the spy-in node). There are two possible ways:
+\begin{enumerate}
+\item You specify the size and position of the spy-on node. Then the
+  size of the spy-in node is determined by the size of the spy-on node
+  and the magnification factor -- you can still decide where the
+  spy-in node should be placed, but not its size.
+\item Alternatively, you specify the size and position of the spy-in
+  node. Then, similarly to the first case, the size of the spy-on node
+  is determined implicitly and you can only decide where the
+  spy-on node should be placed, but not its size.
+\end{enumerate}
+
+The |spy| library uses the second method: You specify the size and
+position of the spy-in nodes, the sizes of the spy-on nodes are then
+computed automatically.
+
+
+
+\subsection{Spy Scopes}
+
+\begin{key}{/tikz/spy scope=\meta{options} (default \normalfont empty)}
+  This option may be used with a |{scope}| or any environment that
+  creates such a scope internally (like |{tikzpicture}|). It has the
+  following effects:
+  \begin{itemize}
+  \item It resets a number of graphic state parameters, including the
+    color, line style, and other. This is necessary for technical
+    reasons.
+  \item It tells \tikzname\ that the content of the scope should be saved
+    internally in a special box.
+  \item It defines the command |\spy| so that it can be used inside
+    the scope.
+  \item At the end of the scope, the nodes belonging to the |\spy|
+    commands used inside the scope are created.
+  \item The \meta{options} are saved in an internal style. Each time
+    |\spy| is used, these \meta{options} will be used.
+  \item Three keys are defined that provide useful shortcuts:
+    \begin{key}{/tikz/size=\meta{dimension}}
+      Inside a |spy scope|, |size| this is a shortcut for |minimum size|.
+    \end{key}
+    \begin{key}{/tikz/height=\meta{dimension}}
+      Inside a |spy scope|, |height| this is a shortcut for |minimum height|.
+    \end{key}
+    \begin{key}{/tikz/width=\meta{dimension}}
+      Inside a |spy scope|, |width| this is a shortcut for |minimum width|.
+    \end{key}
+  \end{itemize}
+  It is permissible to nest |spy scopes|. In this case, all |\spy|
+  commands inside the inner |spy scope| only have an effect on
+  material inside the scope, whereas |\spy| commands outside the inner
+  |spy scope| but inside the outer |spy scope| allow you to ``spy on
+  the spy.''
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+  [spy using outlines={rectangle, red, magnification=5,
+                       size=1.5cm, connect spies}]
+
+  \begin{scope}
+    [spy using outlines={circle, blue,
+                         magnification=3, size=1.5cm, connect spies}]
+    \draw [help lines] (0,0) grid (3,2);
+
+    \draw [decoration=Koch curve type 1]
+      decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
+
+    \spy on (1.6,0.3) in node (zoom) [left] at (3.5,-1.25);
+  \end{scope}
+
+  \spy on (zoom.north west) in node [right] at (0,-1.25);
+\end{tikzpicture}
+\end{codeexample}
+
+\end{key}
+
+
+
+\subsection{The Spy Command}
+
+\begin{command}{\spy \opt{\oarg{options}} |on| \meta{coordinate}
+    |in node| \meta{node options}|;|}
+  This command can only be used inside a |spy scope|. Let us start with the syntax:
+  \begin{itemize}
+  \item The |\spy| command is not a special case of |\path|. Rather,
+    it has a small parser of its own.
+  \item Following the optional \meta{options}, you must write |on|,
+    followed by a coordinate. This coordinate will be the center of
+    the area that is to be magnified.
+  \item Following the \meta{coordinate}, you must write |in node|
+    followed by some \meta{node options}. The syntax for these options is the same
+    as for a normal |node| path command, such as |[left]| or
+    |(foo) [red] at (bar)|. \emph{However},  \meta{node options} are
+    \emph{not} followed by a curly brace. Rather, the \meta{node
+      options} must directly be followed by a semicolon.
+  \end{itemize}
+  The effect of this command is the following: The \meta{options},
+  \meta{coordinate}, and \meta{node options} are stored internally
+  till the end of the current
+  |spy scope|. This means that, in particular, you can reference any node
+  inside the |spy scope|, even if it is not yet defined when the
+  |\spy| command is given. At the end of the current |spy scope|, two
+  nodes are created, called the \emph{spy-in node} and the
+  \emph{spy-on node}.
+  \begin{itemize}
+  \item The \emph{spy-in node} is the node that contains a magnified
+    part of the picture (the node \emph{in} which we see on what we
+    spy). This node is, indeed, a normal \tikzname\
+    node, so you can use all standard options to style this node. In
+    particular, you can specify a shape or a border color or a drop
+    shadow or whatever. The only thing that is special about this node
+    is that instead of containing some normal text, its ``text'' is
+    the magnified picture.
+
+    To be precise, the picture of the |spy scope| is scaled by a
+    certain factor, specified by the |lens| or |magnification| options
+    discussed below, and the shifted in such a way that the
+    \meta{coordinate} lies at the center of the spy-on node.
+  \item The \emph{spy-on node} is a node that is centered on the
+    \meta{coordinate} and whose size reflects exactly the area shown
+    inside the spy-in node (the node containing \emph{on} what we
+    spy).
+  \end{itemize}
+
+  Let us now go over what happens in detail when the two nodes are
+  created:
+  \begin{enumerate}
+  \item A scope is started. Two sets of options are used with this
+    scope: First, the options passed to the enclosing |spy scope| and
+    then the \meta{options} (which will, thus, overrule the options of
+    the |spy scope|).
+  \item Then, the spy-on node is created. However, we will first
+    discuss the spy-in node.
+  \item The spy-in node is created after the spy-on node (and, hence,
+    will cover the spy-on node in case they overlap). When this node is
+    created, the \meta{node options} are used in addition to the
+    effect caused by the \meta{options} and the options of the
+    |{spy scope}|. Additionally, the following style is used:
+    \begin{stylekey}{/tikz/every spy in node}
+      This style is used with every spy in node.
+    \end{stylekey}
+    The position of the node (the |at| option) is set to the
+    \meta{coordinate} by default, so that it will cover the
+    to-be-magnified area. You can change this by providing the |at|
+    option yourself:
+\begin{codeexample}[]
+\begin{tikzpicture}
+  [spy using outlines={circle, magnification=3, size=1cm}]
+
+  \draw [decoration=Koch curve type 1]
+    decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
+
+  \spy [red]  on (1.6,0.3) in node;
+  \spy [blue] on (1,1)     in node at (1,-1);
+\end{tikzpicture}
+\end{codeexample}
+    No ``text'' can be specified for the node. Rather, the ``text''
+    shown inside this node is the picture of the current |spy scope|,
+    but canvas-transformed according to the following key:
+    \begin{key}{/tikz/lens=\meta{options}}
+      The \meta{options} should contain transformation commands like
+      |scale| or |rotate|. These transformations are applied to the
+      picture when it is shown inside the spy-on node.
+    \end{key}
+    Since the most common transformation is undoubtedly a simple
+    scaling, there is a special style for this:
+    \begin{key}{/tikz/magnification=\meta{number}}
+      This has the same effect as saying
+      |lens={scale=|\meta{number}|}|.
+    \end{key}
+    Now, usually the size of a node is determined in such a way that
+    it ``fits'' around the text of the node. For a spy-on node this is
+    not a good approach since the ``text'' of this node would contain
+    ``the whole picture.'' Because of this, \tikzname\ acts
+    as if the ``text'' of the node has zero size. You must then use
+    keys like |minimum size| to cause the node to have a certain
+    size. Note that the key |size| is an abbreviation for
+    |minimum size| inside a spy scope.
+
+    You can name the spy on node in the usual ways. Additionally, the
+    node is (also) always named |tikzspyinnode|. Following the spy
+    scope, you can use this node like any other node:
+\begin{codeexample}[]
+\begin{tikzpicture}
+  \begin{scope}
+    [spy using outlines={circle, magnification=3, size=2cm, connect spies}]
+
+    \draw [decoration=Koch curve type 1]
+      decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
+
+    \spy [red] on (1.6,0.3) in node (a) [left] at (3.5,-1.25);
+
+    \spy [blue, size=1cm] on (1,1) in node (b) [right] at (0,-1.25);
+  \end{scope}
+  \draw [ultra thick, green!50!black] (b) -- (a.north west);
+\end{tikzpicture}
+\end{codeexample}
+
+  \item Once both nodes have been created, the current value of the
+    following key is used to connect them:
+    \begin{key}{/tikz/spy connection path=\meta{code} (initially
+        \normalfont empty)}
+      The \meta{code} is executed after the spy-on and spy-in nodes
+      have just been created. Inside this \meta{code}, the two nodes
+      can be accessed as |tikzspyinnode| and  |tikzspyonnode|.
+      For example, the key |connect spies| sets this command to
+\begin{codeexample}[code only]
+\draw[thin] (tikzspyonnode) -- (tikzspyinnode);
+\end{codeexample}
+    \end{key}
+  \end{enumerate}
+  Returning to the creation of the spy-in node: This node is centered on
+  \meta{coordinate} (more precisely, its anchor is set to |center| and
+  the |at| option is set to \meta{coordinate}). Its size and shape are
+  initially determined in the same way as the size and shape of the
+  spy-on node (unless, of course, you explicitly provide a different
+  shape for, say, the spy-on node locally, which is not really a good
+  idea). Then, additionally, the \emph{inverted} transformation done
+  by the |lens| option is applied, resulting in a node whose size and
+  shape exactly corresponds to the area in the picture that is shown
+  in the spy-on node.
+\begin{codeexample}[]
+\begin{tikzpicture}
+  [spy using outlines={lens={scale=3,rotate=20}, size=2cm, connect spies}]
+
+  \draw [decoration=Koch curve type 1]
+    decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
+
+  \spy [red] on (1.6,0.3) in node at (2.5,-1.25);
+\end{tikzpicture}
+\end{codeexample}
+
+  Like for the spy-in node, a style can be used to format the spy-on
+  node:
+  \begin{stylekey}{/tikz/every spy on node}
+    This style is used with every spy on node.
+  \end{stylekey}
+  The spy-on node is named |tikzspyonnode| (but, as always, this node
+  is only available after the spy scope). If you have multiple
+  spy-on nodes and you would like to access all of them, you need to
+  use the |name| key inside the |every spy on node| style.
+
+  The |inner sep| and |outer sep| of both spy-in and spy-on nodes are
+  set to |0pt|.
+\end{command}
+
+
+
+\subsection{Predefined Spy Styles}
+
+There are some predefined styles that make using the |spy| library
+easier. The following two styles can be used instead of |spy scope|,
+they pass their \meta{options} directly to |spy scope|. They
+additionally setup the graphic styles to be used for the spy-in nodes
+and the spy-on nodes in some special way.
+
+\begin{key}{/tikz/spy using outlines=\meta{options} (default
+    \normalfont empty)}
+  This key creates a |spy scope| in which the spy-in node is drawn,
+  but not filled, using a thick line; and the spy-on node is drawn,
+  but not filled, using a very thin line.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+  [spy using outlines={circle, magnification=3, size=1cm, connect spies}]
+
+  \draw [decoration=Koch curve type 1]
+    decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
+
+  \spy [red] on (1.6,0.3) in node at (3,1);
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+\begin{key}{/tikz/spy using overlays=\meta{options} (default
+    \normalfont empty)}
+  This key creates a |spy scope| in which both the spy-in and spy-on
+  nodes are filled, but with the fill opacity set to 20\%.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+  [spy using overlays={circle, magnification=3, size=1cm, connect spies}]
+
+  \draw [decoration=Koch curve type 1]
+    decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
+
+  \spy [green] on (1.6,0.3) in node at (3,1);
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+The following style is useful for connecting the spy-in and the spy-on
+nodes:
+
+\begin{key}{/tikz/connect spies}
+  Causes the spy-in and the spy-on nodes to be connected by a thin
+  line.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+  [spy using overlays={circle, magnification=3, size=1cm}]
+
+  \draw [decoration=Koch curve type 2]
+    decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
+
+  \spy [green] on (1.6,0.1) in node at (3,1);
+  \spy [red,connect spies] on (0.5,0.4) in node at (1,1.5);
+\end{tikzpicture}
+\end{codeexample}
+\end{key}
+
+
+\subsection{Examples}
+
+Usually, the spy-in node and the spy-on node should have the same
+shape. However, you might also wish to use the |circle| shape for the
+spy-on node and the |magnifying glass| shape for the spy-in node:
+
+\begin{codeexample}[]
+\tikzset{spy using mag glass/.style={
+    spy scope={
+      every spy on node/.style={
+        circle,
+        fill, fill opacity=0.2, text opacity=1},
+      every spy in node/.style={
+        magnifying glass, circular drop shadow,
+        fill=white, draw, ultra thick, cap=round},
+      #1
+    }}}
+\begin{tikzpicture}[spy using mag glass={magnification=3, size=1cm}]
+  \draw [decoration=Koch curve type 2]
+    decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
+
+  \spy [green!50!black] on (1.6,0.1) in node at (2.5,-0.5);
+\end{tikzpicture}
+\end{codeexample}
+
+With the magnifying glass, you can also put it ``on top'' of the
+picture itself:
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+  [spy scope={magnification=4, size=1cm},
+   every spy in node/.style={
+     magnifying glass, circular drop shadow,
+     fill=white, draw, ultra thick, cap=round}]
+
+  \draw [decoration=Koch curve type 2]
+    decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
+
+  \spy on (1.6,0.1) in node;
+\end{tikzpicture}
+\end{codeexample}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "pgfmanual-pdftex-version"
+%%% End:
-- 
cgit v1.2.3

