summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-library-chains.tex
blob: e601610e7fde768aacc3472a203a56fce6b8911f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
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}