diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-spy.tex | 498 |
1 files changed, 255 insertions, 243 deletions
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 index 3f4aad69293..b20b312e0e8 100644 --- 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 @@ -12,18 +12,18 @@ \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). + 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: - +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}] @@ -52,99 +52,100 @@ magnified as if you were looking through a spyglass: \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. -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: +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 you - 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. + \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 you + 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: +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. + \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. - +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 others. 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|, this is a shortcut for |minimum size|. - \end{key} - \begin{key}{/tikz/height=\meta{dimension}} - Inside a |spy scope|, this is a shortcut for |minimum height|. - \end{key} - \begin{key}{/tikz/width=\meta{dimension}} - Inside a |spy scope|, 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.'' - + 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 others. 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|, this is a shortcut for |minimum size|. + \end{key} + % + \begin{key}{/tikz/height=\meta{dimension}} + Inside a |spy scope|, this is a shortcut for |minimum height|. + \end{key} + % + \begin{key}{/tikz/width=\meta{dimension}} + Inside a |spy scope|, 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, @@ -164,78 +165,81 @@ computed automatically. \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} - \texttt{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 is 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{command}{\spy \opt{\oarg{options}} |on| \meta{coordinate} \texttt{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 is 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}] @@ -247,32 +251,38 @@ computed automatically. \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: + % + 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} @@ -288,30 +298,32 @@ computed automatically. \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 + % + \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. + \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}] @@ -323,36 +335,35 @@ computed automatically. \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|. + 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 set up 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. - +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 set up 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}] @@ -363,13 +374,13 @@ and the spy-on nodes in some special way. \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{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}] @@ -380,15 +391,14 @@ and the spy-on nodes in some special way. \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: +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. - + 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}] @@ -400,15 +410,16 @@ nodes: \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: - +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={ @@ -428,9 +439,9 @@ spy-on node and the |magnifying glass| shape for the spy-in node: \end{tikzpicture} \end{codeexample} -With the magnifying glass, you can also put it ``on top'' of the -picture itself: - +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}, @@ -445,6 +456,7 @@ picture itself: \end{tikzpicture} \end{codeexample} + %%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual-pdftex-version" |