Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-library-chains.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Chains}
12 \label{section-chains}
13
14 \begin{tikzlibrary}{chains}
15 This library defines options for creating chains.
16 \end{tikzlibrary}
17
18
19 \subsection{Overview}
20
21 \emph{Chains} are sequences of nodes that are -- typically -- arranged in a row
22 or a column and that are -- typically -- connected by edges. More generally,
23 they can be used to position nodes of a branching network in a systematic
24 manner. For the positioning of nodes in rows and columns you can also use
25 matrices, see Section~\ref{section-matrices}, but chains can also be used to
26 describe the connections between nodes that have already been connected using,
27 say, matrices. Thus, it often makes sense to use matrices for the positioning
28 of elements and chains to describe the connections.
29
30
31 \subsection{Starting and Continuing a Chain}
32
33 Typically, you construct one chain at a time, but it is permissible to
34 construct multiple chains simultaneously. In this case, the chains must be
35 named differently and you must specify for each node which chain it belongs to.
36
37 The first step toward creating a chain is to use the |start chain| option.
38
39 \begin{key}{/tikz/start chain=\opt{\meta{chain name}}\opt{\meta{direction}}}
40 This key should, but need not, be given as an option to a scope enclosing
41 all nodes of the chain. Typically, this will be a |scope| or the whole
42 |tikzpicture|, but it might just be a path on which all nodes of the chain
43 are found. If no \meta{chain name} is given, the default value |chain| will
44 be used instead.
45
46 The key starts a chain named \meta{chain name} and makes it \emph{active},
47 which means that it is currently being constructed. The |start chain| can
48 be issued only once to activate a chain, inside a scope in which a chain is
49 active you cannot use this option once more (for the same chain name). The
50 chain stops being active at the end of the scope in which the |start chain|
51 command was given.
52
53 Although chains are only locally active (that is, active inside the scope
54 the |start chain| command was issued), the information concerning the
55 chains is stored globally and it is possible to \emph{continue} a chain
56 after a scope has ended. For this, the |continue chain| option can be used,
57 which allows you to reactivate an existing chain in another scope.
58
59 The \meta{direction} is used to determine the placement rule for nodes on
60 the chain. If it is omitted, the current value of the following key is
61 used:
62 %
63 \begin{key}{/tikz/chain default direction=\meta{direction} (initially going right)}
64 This \meta{direction} is used in a |chain| option, if no other
65 \meta{direction} is specified.
66 \end{key}
67
68 The \meta{direction} can have two different forms:
69 \declare{|going |\meta{options}} or \declare{|placed |\meta{options}}. The
70 effect of these rules will be explained in the description of the
71 |on chain| option. Right now, just remember that the \meta{direction} you
72 provide with the |chain| option applies to the whole chain.
73
74 Other than this, this key has no further effect. In particular, to place
75 nodes on the chain, you must use the |on chain| option, described next.
76 %
77 \begin{codeexample}[preamble={\usetikzlibrary{chains}}]
78 \begin{tikzpicture}[start chain]
79 % The chain is called just "chain"
80 \node [on chain] {A};
81 \node [on chain] {B};
82 \node [on chain] {C};
83 \end{tikzpicture}
84 \end{codeexample}
85
86 \begin{codeexample}[preamble={\usetikzlibrary{chains,scopes}}]
87 \begin{tikzpicture}
88 % Same as above, using the scope shorthand
89 { [start chain]
90 \node [on chain] {A};
91 \node [on chain] {B};
92 \node [on chain] {C};
93 }
94 \end{tikzpicture}
95 \end{codeexample}
96
97 \begin{codeexample}[preamble={\usetikzlibrary{chains}}]
98 \begin{tikzpicture}[start chain=1 going right,
99 start chain=2 going below,
100 node distance=5mm,
101 every node/.style=draw]
102 \node [on chain=1] {A};
103 \node [on chain=1] {B};
104 \node [on chain=1] {C};
105
106 \node [on chain=2] at (0.5,-.5) {0};
107 \node [on chain=2] {1};
108 \node [on chain=2] {2};
109
110 \node [on chain=1] {D};
111 \end{tikzpicture}
112 \end{codeexample}
113 %
114 \end{key}
115
116 \begin{key}{/tikz/continue chain=\opt{\meta{chain name}}\opt{\meta{direction}}}
117 This option allows you to (re)activate an existing chain and to possibly
118 change the default direction. If the |chain name| is missing, the name of
119 the innermost activated chain is used. If no chain is activated, |chain| is
120 used.
121
122 Let us have a look at the two different applications of this option. The
123 first is to change the direction of a chain as it is being constructed. For
124 this, just give this option somewhere inside the scope of the chain.
125 %
126 \begin{codeexample}[preamble={\usetikzlibrary{chains}}]
127 \begin{tikzpicture}[start chain=going right,node distance=5mm]
128 \node [draw,on chain] {Hello};
129 \node [draw,on chain] {World};
130 \node [draw,continue chain=going below,on chain] {,};
131 \node [draw,on chain] {this};
132 \node [draw,on chain] {is};
133 \end{tikzpicture}
134 \end{codeexample}
135
136 The second application is to reactivate a chain after it ``has already been
137 closed down''.
138 %
139 \begin{codeexample}[preamble={\usetikzlibrary{chains,scopes}}]
140 \begin{tikzpicture}[node distance=5mm,
141 every node/.style=draw]
142 { [start chain=1]
143 \node [on chain] {A};
144 \node [on chain] {B};
145 \node [on chain] {C};
146 }
147
148 { [start chain=2 going below]
149 \node [on chain=2] at (0.5,-.5) {0};
150 \node [on chain=2] {1};
151 \node [on chain=2] {2};
152 }
153
154 { [continue chain=1]
155 \node [on chain] {D};
156 }
157 \end{tikzpicture}
158 \end{codeexample}
159 %
160 \end{key}
161
162
163 \subsection{Nodes on a Chain}
164
165 \begin{key}{/tikz/on chain=\opt{\meta{chain name}}\opt{\meta{direction}}}
166 This key should be given as an option to a node. When the option is used,
167 the \meta{chain name} must be the name of a chain that has been started
168 using the |start chain| option. If \meta{chain name} is the empty string,
169 the current value of the innermost activated chain is used. If this option
170 is used several times for a node, only the last invocation ``wins''. (To
171 place a node on several chains, use the |\chainin| command repeatedly.)
172
173 The \meta{direction} part is optional. If present, it sets the direction
174 used for this node, otherwise the \meta{direction} that was given to the
175 original |start chain| option is used (or of the last |continue chain|
176 option, which allows you to change this default).
177
178 The effects of this option are the following:
179 %
180 \begin{enumerate}
181 \item An internal counter (there is one local counter for each chain)
182 is increased. This counter reflects the current number of the node
183 in the chain, where the first node is node 1, the second is node 2,
184 and so on.
185
186 The value of this internal counter is globally stored in the macro
187 \declare{|\tikzchaincount|}.
188 \item If the node does not yet have a name, (having been given using
189 the |name| option or the name-syntax), the name of the node is set
190 to \meta{chain name}|-|\meta{value of the internal chain counter}.
191 For instance, if the chain is called |nums|, the first node would
192 be named |nums-1|, the second |nums-2|, and so on. For the default
193 chain name |chain|, the first node is named |chain-1|, the second
194 |chain-2|, and so on.
195 \item Independently of whether the name has been provided automatically
196 or via the |name| option, the name of the node is globally stored
197 in the macro \declare{|\tikzchaincurrent|}.
198 \item Except for the first node, the macro
199 \declare{|\tikzchainprevious|} is now globally set to the name of
200 the node of the previous node on the chain. For the first node of
201 the chain, this macro is globally set to the empty string.
202 \item Except possibly for the first node of the chain, the placement
203 rule is now executed. The placement rule is just a \tikzname\
204 option that is applied automatically to each node on the chain.
205 Depending on the form of the \meta{direction} parameter (either the
206 locally given one or the one given to the |start chain| option),
207 different things happen.
208
209 First, it makes a difference whether the \meta{direction} starts
210 with |going| or with |placed|. The difference is that in the first
211 case, the placement rule is not applied to the first node of the
212 chain, while in the second case the placement rule is applied also
213 to this first node. The idea is that a |going|-direction indicates
214 that we are ``going somewhere relative to the previous node''
215 whereas a |placed| indicates that we are ``placing nodes according
216 to their number''.
217
218 Independently of which form is used, the \meta{text} inside
219 \meta{direction} that follows |going| or |placed| (separated by a
220 compulsory space) can have two different effects:
221 %
222 \begin{enumerate}
223 \item If it contains an equal sign, then this \meta{text} is
224 used as the placement rule, that is, it is simply executed.
225 \item If it does not contain an equal sign, then
226 \meta{text}|=of \tikzchainprevious| is used as the
227 placement rule.
228 \end{enumerate}
229
230 Note that in the first case, inside the \meta{text} you have access
231 to |\tikzchainprevious| and |\tikzchaincount| for doing your
232 positioning calculations.
233 %
234 \begin{codeexample}[preamble={\usetikzlibrary{chains}}]
235 \begin{tikzpicture}[start chain=circle placed {at=(\tikzchaincount*30:1.5)}]
236 \foreach \i in {1,...,10}
237 \node [on chain] {\i};
238
239 \draw (circle-1) -- (circle-10);
240 \end{tikzpicture}
241 \end{codeexample}
242 \item The following style is executed:
243 %
244 \begin{stylekey}{/tikz/every on chain}
245 This key is executed for every node on a chain, including the
246 first one.
247 \end{stylekey}
248 \end{enumerate}
249
250 Recall that the standard placement rule has a form like
251 |right=of (\tikzchainprevious)|. This means that each new node is placed to
252 the right of the previous one, spaced by the current value of
253 |node distance|.
254 %
255 \begin{codeexample}[preamble={\usetikzlibrary{chains}}]
256 \begin{tikzpicture}[start chain,node distance=5mm]
257 \node [draw,on chain] {};
258 \node [draw,on chain] {Hallo};
259 \node [draw,on chain] {Welt};
260 \end{tikzpicture}
261 \end{codeexample}
262
263 The optional \meta{direction} allows us to temporarily change the direction
264 in the middle of a chain:
265 %
266 \begin{codeexample}[preamble={\usetikzlibrary{chains}}]
267 \begin{tikzpicture}[start chain,node distance=5mm]
268 \node [draw,on chain] {Hello};
269 \node [draw,on chain] {World};
270 \node [draw,on chain=going below] {,};
271 \node [draw,on chain] {this};
272 \node [draw,on chain] {is};
273 \end{tikzpicture}
274 \end{codeexample}
275
276 You can also use more complicated computations in the \meta{direction}:
277 %
278 \begin{codeexample}[preamble={\usetikzlibrary{chains}}]
279 \begin{tikzpicture}[start chain=going {at=(\tikzchainprevious),shift=(30:1)}]
280 \draw [help lines] (0,0) grid (3,2);
281 \node [draw,on chain] {1};
282 \node [draw,on chain] {Hello};
283 \node [draw,on chain] {World};
284 \node [draw,on chain] {.};
285 \end{tikzpicture}
286 \end{codeexample}
287 %
288 \end{key}
289
290 For each chain, two special ``pseudo nodes'' are created.
291
292 \begin{predefinednode}{\meta{chain name}-begin}
293 This node is the same as the first node on the chain. It is only defined
294 after a first node has been defined.
295 \end{predefinednode}
296
297 \begin{predefinednode}{\meta{chain name}-end}
298 This node is the same as the (currently) last node on the chain. As the
299 chain is extended, this node changes.
300 \end{predefinednode}
301
302 The |on chain| option can also be used, in conjunction with |late options|, to
303 add an already existing node to a chain. The following command, which is only
304 defined inside scopes where a |start chain| option is present, simplifies this
305 process.
306
307 \begin{command}{\chainin |(|\meta{existing name}|)| \opt{\oarg{options}}}
308 This command makes it easy to add a node to chain that has already been
309 constructed. This node may even be part of a another chain.
310
311 When you say |\chainin (some node);|, the node |some node| must already
312 exist. It will then be made part of the current chain. This does not mean
313 that the node can be changed (it is already constructed, after all), but
314 the |join| option can be used to join |some node| to the previous last node
315 on the chain and subsequent nodes will be placed relative to |some node|.
316
317 It is permissible to give the |on chain| option inside the \meta{options}
318 in order to specify on which chain the node should be put.
319
320 This command is just a shortcut for
321 %
322 \begin{quote}
323 |\path (|\meta{existing name}|) [late options={on chain,every chain in,|\meta{options}|}]|
324 \end{quote}
325 %
326 In particular, it is possible to continue to path after a |\chainin|
327 command, though that does not seem very useful.
328 %
329 \begin{codeexample}[preamble={\usetikzlibrary{chains}}]
330 \begin{tikzpicture}[node distance=5mm,
331 every node/.style=draw,every join/.style=->]
332 \draw [help lines] (0,0) grid (3,2);
333
334 \node[red] (existing) at (0,2) {existing};
335
336 \begin{scope}[start chain]
337 \node [draw,on chain,join] {Hello};
338 \node [draw,on chain,join] {World};
339 \chainin (existing) [join];
340 \node [draw,on chain,join] {this};
341 \node [draw,on chain,join] {is};
342 \end{scope}
343 \end{tikzpicture}
344 \end{codeexample}
345
346 Here is an example where nodes are positioned using a matrix and then
347 connected using a chain
348 %
349 {\catcode`\|=12
350 \begin{codeexample}[preamble={\usetikzlibrary{chains,matrix,scopes,shapes.geometric}}]
351 \begin{tikzpicture}[every node/.style=draw]
352 \matrix [matrix of nodes,column sep=5mm,row sep=5mm]
353 {
354 |(a)| World & |(b) [circle]| peace \\
355 |(c)| be & |(d) [isosceles triangle]| would \\
356 |(e) [ellipse]| great & |(f)| ! \\
357 };
358
359 % (the `scopes' library needs to be loaded to make the following work)
360 { [start chain,every on chain/.style={join=by ->}]
361 \chainin (a);
362 \chainin (b);
363 \chainin (d);
364 \chainin (c);
365 \chainin (e);
366 \chainin (f);
367 }
368 \end{tikzpicture}
369 \end{codeexample}
370 }
371 %
372 \end{command}
373
374
375 \subsection{Joining Nodes on a Chain}
376
377 \begin{key}{/tikz/join=\opt{|with |\meta{with} }\opt{|by |\meta{options}}}
378 When this key is given to any node on a chain (except possibly for the
379 first node), an |edge| command is added after the node. The |with| part
380 specifies which node should be used for the start point of the edge; if the
381 |with| part is omitted, the |\tikzchainprevious| is used. This |edge|
382 command gets the \meta{options} as parameter and the current node as its
383 target. If there is no previous node and no |with| is given, no |edge|
384 command gets executed.
385 %
386 \begin{stylekey}{/tikz/every join}
387 This style is executed each time this command is used.
388 \end{stylekey}
389
390 Note that it makes sense to call this option several times for a node, in
391 order to connect it to several nodes. This is especially useful for joining
392 in branches, see the next section.
393 %
394 \begin{codeexample}[preamble={\usetikzlibrary{chains}}]
395 \begin{tikzpicture}[start chain,node distance=5mm,
396 every join/.style={->,red}]
397 \node [draw,on chain,join] {};
398 \node [draw,on chain,join] {Hallo};
399 \node [draw,on chain,join] {Welt};
400 \node [draw,on chain=going below,
401 join,join=with chain-1 by {blue,<-}] {foo};
402 \end{tikzpicture}
403 \end{codeexample}
404 %
405 \end{key}
406
407
408 \subsection{Branches}
409
410 A \emph{branch} is a chain that (typically only temporarily) extends an
411 existing chain. The idea is the following: Suppose we are constructing a chain
412 and at some node |x| there is a fork. In this case, one (or even more) branches
413 starts at this fork. For each branch a chain is created, but the first node on
414 this chain should be~|x|. For this, it is useful to use |\chainin| on the node
415 |x| to make it part of the different branch chains and to name the branch
416 chains in some way that reflects the name of the main chain.
417
418 The |start branch| option provides a shorthand for doing exactly what was just
419 described.
420
421 \begin{key}{/tikz/start branch=\meta{branch name}\opt{\meta{direction}}}
422 This key is used in the same manner as the |start chain| command, however,
423 the effect is slightly different:
424 %
425 \begin{itemize}
426 \item This option may only be used if some chain is already active and
427 there is a (last) node on this chain. Let us call this node the
428 \meta{fork node}.
429 \item The chain is not just called \meta{branch name}, but
430 \meta{current chain}|/|\meta{branch name}. For instance, if the
431 \meta{fork node} is part of the chain called |trunk| and the
432 \meta{branch name} is set to |left|, the complete chain name of the
433 branch is |trunk/left|. The \meta{branch name} must be given, there
434 is no default value.
435 \item The \meta{fork node} is automatically ``chained into'' the branch
436 chain as its first node. Thus, for the first node on the branch
437 that you provide, the |join| option will cause it to be connected
438 to the fork node.
439 \end{itemize}
440 %
441 \begin{codeexample}[preamble={\usetikzlibrary{chains,scopes}}]
442 \begin{tikzpicture}[every on chain/.style=join,every join/.style=->,
443 node distance=2mm and 1cm]
444 { [start chain=trunk]
445 \node [on chain] {A};
446 \node [on chain] {B};
447
448 { [start branch=numbers going below]
449 \node [on chain] {1};
450 \node [on chain] {2};
451 \node [on chain] {3};
452 }
453 { [start branch=greek going above]
454 \node [on chain] {$\alpha$};
455 \node [on chain] {$\beta$};
456 \node [on chain] {$\gamma$};
457 }
458
459 \node [on chain,join=with trunk/numbers-end,join=with trunk/greek-end] {C};
460 { [start branch=symbols going below]
461 \node [on chain] {$\star$};
462 \node [on chain] {$\circ$};
463 \node [on chain] {$\int$};
464 }
465 }
466 \end{tikzpicture}
467 \end{codeexample}
468 %
469 \end{key}
470
471 \begin{key}{/tikz/continue branch=\meta{branch name}\opt{\meta{direction}}}
472 This option works like the |continue chain| option, only \meta{current
473 chain}|/|\meta{branch name} is used as the chain name, rather than just
474 \meta{branch name}.
475 %
476 \begin{codeexample}[preamble={\usetikzlibrary{chains,scopes}}]
477 \begin{tikzpicture}[every on chain/.style=join,every join/.style=->,
478 node distance=2mm and 1cm]
479 { [start chain=trunk]
480 \node [on chain] {A};
481 \node [on chain] {B};
482 { [start branch=numbers going below] } % just a declaration,
483 { [start branch=greek going above] } % we will come back later
484 \node [on chain] {C};
485
486 % Now come the branches...
487 { [continue branch=numbers]
488 \node [on chain] {1};
489 \node [on chain] {2};
490 }
491 { [continue branch=greek]
492 \node [on chain] {$\alpha$};
493 \node [on chain] {$\beta$};
494 }
495 }
496 \end{tikzpicture}
497 \end{codeexample}
498 %
499 \end{key}