diff options
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-library-chains.tex')
-rw-r--r-- | graphics/pgf/base/doc/pgfmanual-en-library-chains.tex | 499 |
1 files changed, 499 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-library-chains.tex b/graphics/pgf/base/doc/pgfmanual-en-library-chains.tex new file mode 100644 index 0000000000..e601610e7f --- /dev/null +++ b/graphics/pgf/base/doc/pgfmanual-en-library-chains.tex @@ -0,0 +1,499 @@ +% 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{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 a 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 +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 it 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}[preamble={\usetikzlibrary{chains}}] +\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}[preamble={\usetikzlibrary{chains,scopes}}] +\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}[preamble={\usetikzlibrary{chains}}] +\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 being constructed. For + this, just give this option somewhere inside the scope of the chain. + % +\begin{codeexample}[preamble={\usetikzlibrary{chains}}] +\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}[preamble={\usetikzlibrary{chains,scopes}}] +\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. + + The 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|-direction 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}[preamble={\usetikzlibrary{chains}}] +\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 on a chain, including the + first one. + \end{stylekey} + \end{enumerate} + + Recall that the standard placement 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}[preamble={\usetikzlibrary{chains}}] +\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}[preamble={\usetikzlibrary{chains}}] +\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}[preamble={\usetikzlibrary{chains}}] +\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}[preamble={\usetikzlibrary{chains}}] +\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}; + + \begin{scope}[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{scope} +\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}[preamble={\usetikzlibrary{chains,matrix,scopes,shapes.geometric}}] +\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)| ! \\ + }; + + % (the `scopes' library needs to be loaded to make the following work) + { [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 it 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}[preamble={\usetikzlibrary{chains}}] +\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}[preamble={\usetikzlibrary{chains,scopes}}] +\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}[preamble={\usetikzlibrary{chains,scopes}}] +\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} |