diff options
author | Karl Berry <karl@freefriends.org> | 2008-02-23 00:49:54 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2008-02-23 00:49:54 +0000 |
commit | 4fc1af1461e934c39f8f5e10d5d8788681d82223 (patch) | |
tree | 7716e8a3e8787a3d11c5ce728d21b808f786ce7d /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-chains.tex | |
parent | 6f5a4edf390b6e05291d7a4b816782b14122a205 (diff) |
tikz/pgf 2.0 first attempt (22feb08)
git-svn-id: svn://tug.org/texlive/trunk@6741 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-chains.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-chains.tex | 493 |
1 files changed, 493 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-chains.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-chains.tex new file mode 100644 index 00000000000..6354593d91d --- /dev/null +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-library-chains.tex @@ -0,0 +1,493 @@ +% Copyright 2008 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{Chains} + +\label{section-chains} + +\begin{tikzlibrary}{chains} + This library defines options for creating chains. +\end{tikzlibrary} + + +\subsection{Overview} + +\emph{Chains} are sequences of nodes that are -- typically -- arranged +in an o row or a column and that are -- typically -- connected by +edges. More generally, they can be used to position nodes of a +branching network in a systematic manner. For the positioning of nodes +in rows and columns you can also use matrices, see +Section~\ref{section-matrices}, but chains can also be used +to describe the connections between nodes that have already been +connected using, say, matrices. Thus, it often makes sense to use +matrices for the positioning of elements and chains to describe the +connections. + + + +\subsection{Starting and Continuing a Chain} + +Typically, you construct one chain at a time, but it is +permissible to have construct multiple chains simultaneously. In this +case, the chains must be named differently and you must specify for +each node which chain it belongs to. + +The first step toward creating a chain is to use the |start chain| +option. + +\begin{key}{/tikz/start chain=\opt{\meta{chain name}}\opt{\meta{direction}}} + This key should, but need not, be given as an option to a scope + enclosing all nodes of the chain. Typically, this will be a |scope| + or the whole |tikzpicture|, but it might just be a path on which all + nodes of the chain are found. + If no \meta{chain name} is given, the default value |chain| will be + used instead. + + The key starts a chain named \meta{chain name} and makes it + \emph{active}, which means that is currently being constructed. The + |start chain| can be issued only once to activate a chain, inside a + scope in which a chain is active you cannot use this option once + more (for the same chain name). The chain stops being active at the + end of the scope in which the |start chain| command was given. + + Although chains are only locally active (that is, active inside the + scope the |start chain| command was issued), the information + concerning the chains is stored globally and it is possible + to \emph{continue} a chain after a scope has ended. For this, the + |continue chain| option can be used, which allows you to reactivate + an existing chain in another scope. + + The \meta{direction} is used to determine the placement rule for + nodes on the chain. If it is omitted, the current value of the + following key is used: + \begin{key}{/tikz/chain default direction=\meta{direction} + (initially going right)} + This \meta{direction} is used in a |chain| option, if no other + \meta{direction} is specified. + \end{key} + + The \meta{direction} can have two different forms: + \declare{|going |\meta{options}} or + \declare{|placed |\meta{options}}. The effect of these rules will be + explained in the description of the |on chain| option. Right now, + just remember that the \meta{direction} you provide with the |chain| + option applies to the whole chain. + + Other than this, this key has no further effect. In particular, to + place nodes on the chain, you must use the |on chain| option, + described next. +\begin{codeexample}[] +\begin{tikzpicture}[start chain] + % The chain is called just "chain" + \node [on chain] {A}; + \node [on chain] {B}; + \node [on chain] {C}; +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + % Same as above, using the scope shorthand + { [start chain] + \node [on chain] {A}; + \node [on chain] {B}; + \node [on chain] {C}; + } +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture}[start chain=1 going right, + start chain=2 going below, + node distance=5mm, + every node/.style=draw] + \node [on chain=1] {A}; + \node [on chain=1] {B}; + \node [on chain=1] {C}; + + \node [on chain=2] at (0.5,-.5) {0}; + \node [on chain=2] {1}; + \node [on chain=2] {2}; + + \node [on chain=1] {D}; +\end{tikzpicture} +\end{codeexample} +\end{key} + +\begin{key}{/tikz/continue chain=\opt{\meta{chain name}}\opt{\meta{direction}}} + This option allows you to (re)activate an existing chain and to + possibly change the default direction. If the |chain name| is + missing, the name of the innermost activated chain is used. If no + chain is activated, |chain| is used. + + Let us have a look at the two different applications of this + option. The first is to change the direction of a chain as it is + begin constructed. For this, just give this option somewhere inside + the scope of the chain. +\begin{codeexample}[] +\begin{tikzpicture}[start chain=going right,node distance=5mm] + \node [draw,on chain] {Hello}; + \node [draw,on chain] {World}; + \node [draw,continue chain=going below,on chain] {,}; + \node [draw,on chain] {this}; + \node [draw,on chain] {is}; +\end{tikzpicture} +\end{codeexample} + + The second application is to reactivate a chain after it ``has + already been closed down.'' + +\begin{codeexample}[] +\begin{tikzpicture}[node distance=5mm, + every node/.style=draw] + { [start chain=1] + \node [on chain] {A}; + \node [on chain] {B}; + \node [on chain] {C}; + } + + { [start chain=2 going below] + \node [on chain=2] at (0.5,-.5) {0}; + \node [on chain=2] {1}; + \node [on chain=2] {2}; + } + + { [continue chain=1] + \node [on chain] {D}; + } +\end{tikzpicture} +\end{codeexample} +\end{key} + + +\subsection{Nodes on a Chain} + +\begin{key}{/tikz/on chain=\opt{\meta{chain name}}\opt{\meta{direction}}} + This key should be given as an option to a node. When the option is + used, the \meta{chain name} must be the name of a chain that has + been started using the |start chain| option. If \meta{chain name} is + the empty string, the current value of the innermost activated chain + is used. If this option is used several times for a node, only the + last invocation ``wins.'' (To place a node on several chains, use + the |\chainin| command repeatedly.) + + The \meta{direction} part is optional. If present it sets the + direction used for this node, otherwise the \meta{direction} + that was given to the original |start chain| option is used (or of + the last |continue chain| option, which allows you to change this + default). + + The effects of this option are the following: + \begin{enumerate} + \item An internal counter (there is one, local, counter + for each chain) is increased. This counter reflects the current + number of the node in the chain, where the first node is node 1, + the second is node 2, and so on. + + This value of this internal counter is globally stored in the + macro \declare{|\tikzchaincount|}. + \item If the node does not yet have a name, (having been given using + the |name| option or the name-syntax), the name of the node is set to + \meta{chain name}|-|\meta{value of the internal chain + counter}. For instance, if the chain is called |nums|, the first + node would be named |nums-1|, the second |nums-2|, and so on. For + the default chain name |chain|, the first node is named |chain-1|, + the second |chain-2|, and so on. + \item Independently of whether the name has been provided + automatically or via the |name| option, the name of the node is + globally stored in the macro \declare{|\tikzchaincurrent|}. + \item Except for the first node, the macro + \declare{|\tikzchainprevious|} is now globally set to the name of + the node of the previous node on the chain. For the first node of + the chain, this macro is globally set to the empty string. + \item Except possibly for the first node of the chain, the placement + rule is now executed. The placement rule is just a \tikzname\ option + that is applied automatically to each node on the chain. Depending + on the form of the \meta{direction} parameter (either the locally + given one or the one given to the |start chain| option), different + things happen. + + First, it makes a difference whether the \meta{direction} starts + with |going| or with |placed|. The difference is that in the first + case, the placement rule is not applied to the first node of the + chain, while in the second case the placement rule is applied also + to this first node. The idea is that a |going|-direciton indicates + that we are ``going somewhere relative to the previous node'' + whereas a |placed| indicates that we are ``placing nodes according + to their number.'' + + Independently of which form is used, the \meta{text} inside + \meta{direction} that follows |going| or |placed| (separated by a + compulsory space) can have two different effects: + \begin{enumerate} + \item If it contains an equal sign, then this \meta{text} is used + as the placement rule, that is, it is simply executed. + \item If it does not contain an equal sign, then + \meta{text}|=of \tikzchainprevious| is used as the placement + rule. + \end{enumerate} + + Note that in the first case, inside the \meta{text} you have + access to |\tikzchainprevious| and |\tikzchaincount| for doing + your positioning calculations. +\begin{codeexample}[] +\begin{tikzpicture}[start chain=circle placed {at=(\tikzchaincount*30:1.5)}] + \foreach \i in {1,...,10} + \node [on chain] {\i}; + + \draw (circle-1) -- (circle-10); +\end{tikzpicture} +\end{codeexample} + \item + The following style is executed: + \begin{stylekey}{/tikz/every on chain} + This key is executed for every node of a chain, including the + first one. + \end{stylekey} + \end{enumerate} + + Recall that the standard replacement rule has a form like + |right=of (\tikzchainprevious)|. This means that each + new node is placed to the right of the previous one, spaced by the + current value of |node distance|. +\begin{codeexample}[] +\begin{tikzpicture}[start chain,node distance=5mm] + \node [draw,on chain] {}; + \node [draw,on chain] {Hallo}; + \node [draw,on chain] {Welt}; +\end{tikzpicture} +\end{codeexample} + + The optional \meta{direction} allows us to temporarily change the + direction in the middle of a chain: +\begin{codeexample}[] +\begin{tikzpicture}[start chain,node distance=5mm] + \node [draw,on chain] {Hello}; + \node [draw,on chain] {World}; + \node [draw,on chain=going below] {,}; + \node [draw,on chain] {this}; + \node [draw,on chain] {is}; +\end{tikzpicture} +\end{codeexample} + + You can also use more complicated computations in the \meta{direction}: +\begin{codeexample}[] +\begin{tikzpicture}[start chain=going {at=(\tikzchainprevious),shift=(30:1)}] + \draw [help lines] (0,0) grid (3,2); + \node [draw,on chain] {1}; + \node [draw,on chain] {Hello}; + \node [draw,on chain] {World}; + \node [draw,on chain] {.}; +\end{tikzpicture} +\end{codeexample} +\end{key} + +For each chain, two special ``pseudo nodes'' are created. + +\begin{predefinednode}{\meta{chain name}-begin} + This node is the same as the first node on the chain. It is only + defined after a first node has been defined. +\end{predefinednode} + +\begin{predefinednode}{\meta{chain name}-end} + This node is the same as the (currently) last node on the chain. As + the chain is extended, this node changes. +\end{predefinednode} + +The |on chain| option can also be used, in conjunction with +|late options|, to add an already existing node to a chain. The +following command, which is only defined inside scopes where a +|start chain| option is present, simplifies this process. + +\begin{command}{\chainin |(|\meta{existing name}|)| \opt{\oarg{options}}} + This command makes it easy to add a node to chain that has already + been constructed. This node may even be part of a another chain. + + When you say |\chainin (some node);|, the node |some node| must + already exist. It will then be made part of the current chain. This + does not mean that the node can be changed (it is already + constructed, after all), but the |join| option can be used to join + |some node| to the previous last node on the chain and subsequent + nodes will be placed relative to |some node|. + + It is permissible to give the |on chain| option inside the + \meta{options} in order to specify on which chain the node should be + put. + + This command is just a shortcut for +\begin{quote} +|\path (|\meta{existing name}|) [late options={on chain,every chain in,|\meta{options}|}]| +\end{quote} + In particular, it is possible to continue to path after a |\chainin| + command, though that does not seem very useful. + +\begin{codeexample}[] +\begin{tikzpicture}[node distance=5mm, + every node/.style=draw,every join/.style=->] + \draw [help lines] (0,0) grid (3,2); + + \node[red] (existing) at (0,2) {existing}; + + { [start chain] + \node [draw,on chain,join] {Hello}; + \node [draw,on chain,join] {World}; + \chainin (existing) [join]; + \node [draw,on chain,join] {this}; + \node [draw,on chain,join] {is}; + } +\end{tikzpicture} +\end{codeexample} + + Here is an example where nodes are positioned using a matrix and + then connected using a chain +{\catcode`\|=12 +\begin{codeexample}[] +\begin{tikzpicture}[every node/.style=draw] + \matrix [matrix of nodes,column sep=5mm,row sep=5mm] + { + |(a)| World & |(b) [circle]| peace \\ + |(c)| be & |(d) [isosceles triangle]| would \\ + |(e) [ellipse]| great & |(f)| ! \\ + }; + + { [start chain,every on chain/.style={join=by ->}] + \chainin (a); + \chainin (b); + \chainin (d); + \chainin (c); + \chainin (e); + \chainin (f); + } +\end{tikzpicture} +\end{codeexample} +} +\end{command} + + + +\subsection{Joining Nodes on a Chain} + +\begin{key}{/tikz/join=\opt{|with |\meta{with} }\opt{|by |\meta{options}}} + When this key is given to any node on a chain (except possibly for + the first node), an |edge| command is added after the node. The + |with| part specifies which node should be used for the start point + of the edge; if the |with| part is omitted, the |\tikzchainprevious| + is used. This |edge| command gets the \meta{options} as parameter + and the current node as its target. If there is no + previous node and no |with| is given, no |edge| command gets + executed. + \begin{stylekey}{/tikz/every join} + This style is executed each time this command is used. + \end{stylekey} + + Note that is makes sense to call this option several times for a + node, in order to connect it to several nodes. This is especially + useful for joining in branches, see the next section. +\begin{codeexample}[] +\begin{tikzpicture}[start chain,node distance=5mm, + every join/.style={->,red}] + \node [draw,on chain,join] {}; + \node [draw,on chain,join] {Hallo}; + \node [draw,on chain,join] {Welt}; + \node [draw,on chain=going below, + join,join=with chain-1 by {blue,<-}] {foo}; +\end{tikzpicture} +\end{codeexample} +\end{key} + + +\subsection{Branches} + +A \emph{branch} is a chain that (typically only temporarily) extends +an existing chain. The idea is the following: Suppose we are +constructing a chain and at some node |x| there is a fork. In this +case, one (or even more) branches starts at this fork. For each branch +a chain is created, but the first node on this chain should +be~|x|. For this, it is useful to use |\chainin| on the node |x| to +make it part of the different branch chains and to name the branch +chains in some way that reflects the name of the main chain. + +The |start branch| option provides a shorthand for doing exactly what +was just described. + +\begin{key}{/tikz/start branch=\meta{branch name}\opt{\meta{direction}}} + This key is used in the same manner as the |start chain| command, + however, the effect is slightly different: + \begin{itemize} + \item This option may only be used if some chain is already active + and there is a (last) node on this chain. Let us call this node + the \meta{fork node}. + \item The chain is not just called \meta{branch name}, but + \meta{current chain}|/|\meta{branch name}. For instance, if the + \meta{fork node} is part of the chain called |trunk| and the + \meta{branch name} is set to |left|, the complete chain name of + the branch is |trunk/left|. The \meta{branch name} must be given, + there is no default value. + \item The \meta{fork node} is automatically ``chained into'' the + branch chain as its first node. Thus, for the first node on the + branch that you provide, the |join| option will cause it to be + connected to the fork node. + \end{itemize} +\begin{codeexample}[] +\begin{tikzpicture}[every on chain/.style=join,every join/.style=->, + node distance=2mm and 1cm] + { [start chain=trunk] + \node [on chain] {A}; + \node [on chain] {B}; + + { [start branch=numbers going below] + \node [on chain] {1}; + \node [on chain] {2}; + \node [on chain] {3}; + } + { [start branch=greek going above] + \node [on chain] {$\alpha$}; + \node [on chain] {$\beta$}; + \node [on chain] {$\gamma$}; + } + + \node [on chain,join=with trunk/numbers-end,join=with trunk/greek-end] {C}; + { [start branch=symbols going below] + \node [on chain] {$\star$}; + \node [on chain] {$\circ$}; + \node [on chain] {$\int$}; + } + } +\end{tikzpicture} +\end{codeexample} +\end{key} + +\begin{key}{/tikz/continue branch=\meta{branch name}\opt{\meta{direction}}} + This option works like the |continue chain| option, only + \meta{current chain}|/|\meta{branch name} is used as the chain name, + rather than just \meta{branch name}. +\begin{codeexample}[] +\begin{tikzpicture}[every on chain/.style=join,every join/.style=->, + node distance=2mm and 1cm] + { [start chain=trunk] + \node [on chain] {A}; + \node [on chain] {B}; + { [start branch=numbers going below] } % just a declaration, + { [start branch=greek going above] } % we will come back later + \node [on chain] {C}; + + % Now come the branches... + { [continue branch=numbers] + \node [on chain] {1}; + \node [on chain] {2}; + } + { [continue branch=greek] + \node [on chain] {$\alpha$}; + \node [on chain] {$\beta$}; + } + } +\end{tikzpicture} +\end{codeexample} +\end{key} |