Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-trees.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{Making Trees Grow}
12 \label{section-trees}
13
14 \subsection{Introduction to the Child Operation}
15
16 \emph{Trees} are a common way of visualizing hierarchical structures. A simple
17 tree looks like this:
18 %
19 \begin{codeexample}[]
20 \begin{tikzpicture}
21 \node {root}
22 child {node {left}}
23 child {node {right}
24 child {node {child}}
25 child {node {child}}
26 };
27 \end{tikzpicture}
28 \end{codeexample}
29
30 Admittedly, in reality trees are more likely to grow \emph{upward} and not
31 downward as above. You can tell whether the author of a paper is a
32 mathematician or a computer scientist by looking at the direction their trees
33 grow. A computer scientist's trees will grow downward while a mathematician's
34 tree will grow upward. Naturally, the \emph{correct} way is the mathematician's
35 way, which can be specified as follows:
36 %
37 \begin{codeexample}[]
38 \begin{tikzpicture}
39 \node {root} [grow'=up]
40 child {node {left}}
41 child {node {right}
42 child {node {child}}
43 child {node {child}}
44 };
45 \end{tikzpicture}
46 \end{codeexample}
47
48 In \tikzname, there are two ways of specifying trees: Using either the |graph|
49 path operation, which is covered in Section~\ref{section-library-graphs}, or
50 using the |child| path operation, which is covered in the present section. Both
51 methods have their advantages.
52
53 In \tikzname, trees are specified by adding \emph{children} to a node on a path
54 using the |child| operation:
55
56 \begin{pathoperation}{child}{\opt{\oarg{options}}%
57 \opt{|foreach|\meta{variables}|in|\marg{values}}\opt{\marg{child path}}}
58 This operation should directly follow a completed |node| operation or
59 another |child| operation, although it is permissible that the first
60 |child| operation is preceded by options (we will come to that).
61
62 When a |node| operation like |node {X}| is followed by |child|, \tikzname\
63 starts counting the number of child nodes that follow the original
64 |node {X}|. For this, it scans the input and stores away each |child| and
65 its arguments until it reaches a path operation that is not a |child|. Note
66 that this will fix the character codes of all text inside the child
67 arguments, which means, in essence, that you cannot use verbatim text
68 inside the nodes inside a |child|. Sorry.
69
70 Once the children have been collected and counted, \tikzname\ starts
71 generating the child nodes. For each child of a parent node \tikzname\
72 computes an appropriate position where the child is placed. For each child,
73 the coordinate system is transformed so that the origin is at this
74 position. Then the \meta{child path} is drawn. Typically, the child path
75 just consists of a |node| specification, which results in a node being
76 drawn at the child's position. Finally, an edge is drawn from the first
77 node in the \meta{child path} to the parent node.
78
79 The optional |foreach| part (note that there is no backslash before
80 |foreach|) allows you to specify multiple children in a single |child|
81 command. The idea is the following: A |\foreach| statement is (internally)
82 used to iterate over the list of \meta{values}. For each value in this
83 list, a new |child| is added to the node. The syntax for \meta{variables}
84 and for \meta{values} is the same as for the |\foreach| statement, see
85 Section~\ref{section-foreach}. For example, when you say
86 %
87 \begin{codeexample}[code only]
88 node {root} child [red] foreach \name in {1,2} {node {\name}}
89 \end{codeexample}
90 %
91 the effect will be the same as if you had said
92 %
93 \begin{codeexample}[code only]
94 node {root} child[red] {node {1}} child[red] {node {2}}
95 \end{codeexample}
96 %
97 When you write
98 %
99 \begin{codeexample}[code only]
100 node {root} child[\pos] foreach \name/\pos in {1/left,2/right} {node[\pos] {\name}}
101 \end{codeexample}
102 %
103 the effect will be the same as for
104 %
105 \begin{codeexample}[code only]
106 node {root} child[left] {node[left] {1}} child[right] {node[right] {2}}
107 \end{codeexample}
108
109 You can nest things as in the following example:
110 %
111 \begin{codeexample}[]
112 \begin{tikzpicture}
113 [level distance=4mm,level/.style={sibling distance=8mm/#1}]
114 \coordinate
115 child foreach \x in {0,1}
116 {child foreach \y in {0,1}
117 {child foreach \z in {0,1}}};
118 \end{tikzpicture}
119 \end{codeexample}
120
121 The details and options for this operation are described in the rest of
122 this present section.
123 \end{pathoperation}
124
125
126 \subsection{Child Paths and Child Nodes}
127
128 For each |child| of a root node, its \meta{child path} is inserted at a
129 specific location in the picture (the placement rules are discussed in
130 Section~\ref{section-tree-placement}). The first node in the \meta{child path},
131 if it exists, is special and called the \emph{child node}. If there is no first
132 node in the \meta{child path}, that is, if the \meta{child path} is missing
133 (including the curly braces) or if it does not start with |node| or with
134 |coordinate|, then an empty child node of shape |coordinate| is automatically
135 added.
136
137 Consider the example |\node {x} child {node {y}} child;|. For the first child,
138 the \meta{child path} has the child node |node {y}|. For the second child, no
139 child node is specified and, thus, it is just |coordinate|.
140
141 As for any normal node, you can give the child node a name, shift it around, or
142 use options to influence how it is rendered.
143 %
144 \begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
145 \begin{tikzpicture}[sibling distance=15mm]
146 \node[rectangle,draw] {root}
147 child {node[circle,draw,yshift=-5mm] (left node) {left}}
148 child {node[ellipse,draw] (right node) {right}};
149 \draw[dashed,->] (left node) -- (right node);
150 \end{tikzpicture}
151 \end{codeexample}
152
153 In many cases, the \meta{child path} will just consist of a specification of a
154 child node and, possibly, children of this child node. However, the node
155 specification may be followed by arbitrary other material that will be added to
156 the picture, transformed to the child's coordinate system. For your
157 convenience, a move-to |(0,0)| operation is inserted automatically at the
158 beginning of the path. Here is an example:
159 %
160 \begin{codeexample}[]
161 \begin{tikzpicture}
162 \node {root}
163 child {[fill] circle (2pt)}
164 child {[fill] circle (2pt)};
165 \end{tikzpicture}
166 \end{codeexample}
167
168 At the end of the \meta{child path} you may add a special path operation called
169 |edge from parent|. If this operation is not given by yourself somewhere on the
170 path, it will be automatically added at the end. This option causes a
171 connecting edge from the parent node to the child node to be added to the path.
172 By giving options to this operation you can influence how the edge is rendered.
173 Also, nodes following the |edge from parent| operation will be placed on this
174 edge, see Section~\ref{section-edge-from-parent} for details.
175
176 To sum up:
177 %
178 \begin{enumerate}
179 \item The child path starts with a node specification. If it is not there,
180 it is added automatically.
181 \item The child path ends with a |edge from parent| operation, possibly
182 followed by nodes to be put on this edge. If the operation is not given
183 at the end, it is added automatically.
184 \end{enumerate}
185
186
187 \subsection{Naming Child Nodes}
188
189 Child nodes can be named like any other node using either the |name| option or
190 the special syntax in which the name of the node is placed in round parentheses
191 between the |node| operation and the node's text.
192
193 If you do not assign a name to a child node, \tikzname\ will automatically
194 assign a name as follows: Assume that the name of the parent node is, say,
195 |parent|. (If you did not assign a name to the parent, \tikzname\ will do so
196 itself, but that name will not be user-accessible.) The first child of |parent|
197 will be named |parent-1|, the second child is named |parent-2|, and so on.
198
199 This naming convention works recursively. If the second child |parent-2| has
200 children, then the first of these children will be called |parent-2-1| and the
201 second |parent-2-2| and so on.
202
203 If you assign a name to a child node yourself, no name is generated
204 automatically (the node does not have two names). However, ``counting
205 continues'', which means that the third child of |parent| is called |parent-3|
206 independently of whether you have assigned names to the first and/or second
207 child of |parent|.
208
209 Here is an example:
210 %
211 \begin{codeexample}[]
212 \begin{tikzpicture}[sibling distance=15mm]
213 \node (root) {root}
214 child
215 child {
216 child {coordinate (special)}
217 child
218 };
219 \node at (root-1) {root-1};
220 \node at (root-2) {root-2};
221 \node at (special) {special};
222 \node at (root-2-2) {root-2-2};
223 \end{tikzpicture}
224 \end{codeexample}
225
226
227 \subsection{Specifying Options for Trees and Children}
228 \label{section-tree-options}
229
230 Each |child| may have its own \meta{options}, which apply to ``the whole
231 child'', including all of its grandchildren. Here is an example:
232 %
233 \begin{codeexample}[]
234 \begin{tikzpicture}
235 [thick,level 1/.style={sibling distance=15mm},
236 level 2/.style={sibling distance=10mm}]
237 \coordinate
238 child[red] {child child}
239 child[green] {child child[blue]};
240 \end{tikzpicture}
241 \end{codeexample}
242
243 The options of the root node have no effect on the children since the options
244 of a node are always ``local'' to that node. Because of this, the edges in the
245 following tree are black, not red.
246 %
247 \begin{codeexample}[]
248 \begin{tikzpicture}[thick]
249 \node [red] {root}
250 child
251 child;
252 \end{tikzpicture}
253 \end{codeexample}
254 %
255 This raises the problem of how to set options for \emph{all} children.
256 Naturally, you could always set options for the whole path as in
257 |\path [red] node {root} child child;| but this is bothersome in some
258 situations. Instead, it is easier to give the options \emph{before the first
259 child} as follows:
260 %
261 \begin{codeexample}[]
262 \begin{tikzpicture}[thick]
263 \node [red] {root}
264 [green] % option applies to all children
265 child
266 child;
267 \end{tikzpicture}
268 \end{codeexample}
269
270 Here is the set of rules:
271 %
272 \begin{enumerate}
273 \item Options for the whole tree are given before the root node.
274 \item Options for the root node are given directly to the |node| operation
275 of the root.
276 \item Options for all children can be given between the root node and the
277 first child.
278 \item Options applying to a specific child path are given as options to the
279 |child| operation.
280 \item Options applying to the node of a child, but not to the whole child
281 path, are given as options to the |node| command inside the \meta{child
282 path}.
283 \end{enumerate}
284 %
285 \begin{codeexample}[code only]
286 \begin{tikzpicture}
287 \scoped
288 [...] % Options apply to the whole tree
289 \node[...] {root} % Options apply to the root node only
290 [...] % Options apply to all children
291 child[...] % Options apply to this child and all its children
292 {
293 node[...] {} % Options apply to the child node only
294 ...
295 }
296 child[...] % Options apply to this child and all its children
297 ;
298 \end{tikzpicture}
299 \end{codeexample}
300
301 There are additional styles that influence how children are rendered:
302 %
303 \begin{stylekey}{/tikz/every child (initially \normalfont empty)}
304 This style is used at the beginning of each child, as if you had given the
305 style's contents as options to the |child| operation.
306 \end{stylekey}
307
308 \begin{stylekey}{/tikz/every child node (initially \normalfont empty)}
309 This style is used at the beginning of each child node in addition to the
310 |every node| style.
311 \end{stylekey}
312
313 \begin{stylekey}{/tikz/level=\meta{number} (initially \normalfont empty)}
314 This style is executed at the beginning of each set of children, where
315 \meta{number} is the current level in the current tree. For example, when
316 you say |\node {x} child child;|, then |level=1| is used before the first
317 |child|. The style or code of this key will be passed \meta{number} as its
318 first parameter. If this first |child| has children itself, then |level=2|
319 would be used for them.
320 %
321 \begin{codeexample}[]
322 \begin{tikzpicture}[level/.style={sibling distance=20mm/#1}]
323 \node {root}
324 child { child child }
325 child { child child child };
326 \end{tikzpicture}
327 \end{codeexample}
328 %
329 \end{stylekey}
330
331 \begin{stylekey}{/tikz/level \meta{number} (initially \normalfont empty)}
332 This style is used in addition to the |level| style. So, when you say
333 |\node {x} child child;|, then the following key list is executed:
334 |level=1,level 1|.
335 %
336 \begin{codeexample}[]
337 \begin{tikzpicture}
338 [level 1/.style={sibling distance=20mm},
339 level 2/.style={sibling distance=5mm}]
340 \node {root}
341 child { child child }
342 child { child child child };
343 \end{tikzpicture}
344 \end{codeexample}
345 %
346 \end{stylekey}
347
348
349 \subsection{Placing Child Nodes}
350 \label{section-tree-placement}
351
352 \subsubsection{Basic Idea}
353
354 Perhaps the most difficult part in drawing a tree is the correct layout of the
355 children. Typically, the children have different sizes and it is not easy to
356 arrange them in such a manner that not too much space is wasted, the children
357 do not overlap, and they are either evenly spaced or their centers are evenly
358 distributed. Calculating good positions is especially difficult since a good
359 position for the first child may depend on the size of the last child.
360
361 In basic \tikzname, when you do not make use of the graph drawing facilities
362 explained in Part~\ref{part-gd}, a comparatively simple approach is taken to
363 placing the children. In order to compute a child's position, all that is taken
364 into account is the number of the current child in the list of children and the
365 number of children in this list. Thus, if a node has five children, then there
366 is a fixed position for the first child, a position for the second child, and
367 so on. These positions \emph{do not depend on the size of the children} and,
368 hence, children can easily overlap. However, since you can use options to shift
369 individual children a bit, this is not as great a problem as it may seem.
370
371 Although the placement of the children only depends on their number in the list
372 of children and the total number of children, everything else about the
373 placement is highly configurable. You can change the distance between children
374 (appropriately called the |sibling distance|) and the distance between levels
375 of the tree. These distances may change from level to level. The direction in
376 which the tree grows can be changed globally and for parts of the tree. You can
377 even specify your own ``growth function'' to arrange children on a circle or
378 along special lines or curves.
379
380
381 \subsubsection{Default Growth Function}
382
383 The default growth function works as follows: Assume that we are given a node
384 and five children. These children will be placed on a line with their centers
385 (or, more generally, with their anchors) spaced apart by the current
386 |sibling distance|. The line is orthogonal to the current \emph{direction of
387 growth}, which is set with the |grow| and |grow'| option (the latter option
388 reverses the ordering of the children). The distance from the line to the
389 parent node is given by the |level distance|.
390 %
391 {\catcode`\|=12
392 \begin{codeexample}[]
393 \begin{tikzpicture}[sibling distance=15mm, level distance=15mm]
394 \path [help lines]
395 node (root) {root}
396 [grow=-10]
397 child {node {1}}
398 child {node {2}}
399 child {node {3}}
400 child {node {4}};
401
402 \draw[|<->|,thick] (root-1.center)
403 -- node[above,sloped] {sibling distance} (root-2.center);
404
405 \draw[|<->|,thick] (root.center)
406 -- node[above,sloped] {level distance} +(-10:\tikzleveldistance);
407 \end{tikzpicture}
408 \end{codeexample}
409 }
410
411 \begin{key}{/tikz/level distance=\meta{distance} (initially 15mm)}
412 This key determines the distance between different levels of the tree, more
413 precisely, between the parent and the line on which its children are
414 arranged. When given to a single child, this will set the distance for this
415 child only.
416 %
417 \begin{codeexample}[]
418 \begin{tikzpicture}
419 \node {root}
420 [level distance=20mm]
421 child
422 child {
423 [level distance=5mm]
424 child
425 child
426 child
427 }
428 child[level distance=10mm];
429 \end{tikzpicture}
430 \end{codeexample}
431
432 \begin{codeexample}[]
433 \begin{tikzpicture}
434 [level 1/.style={level distance=10mm},
435 level 2/.style={level distance=5mm}]
436 \node {root}
437 child
438 child {
439 child
440 child[level distance=10mm]
441 child
442 }
443 child;
444 \end{tikzpicture}
445 \end{codeexample}
446 %
447 \end{key}
448
449 \begin{key}{/tikz/sibling distance=\meta{distance} (initially 15mm)}
450 This key specifies the distance between the anchors of the children of a
451 parent node.
452 %
453 \begin{codeexample}[]
454 \begin{tikzpicture}
455 [level distance=4mm,
456 level 1/.style={sibling distance=8mm},
457 level 2/.style={sibling distance=4mm},
458 level 3/.style={sibling distance=2mm}]
459 \coordinate
460 child {
461 child {child child}
462 child {child child}
463 }
464 child {
465 child {child child}
466 child {child child}
467 };
468 \end{tikzpicture}
469 \end{codeexample}
470
471 \begin{codeexample}[]
472 \begin{tikzpicture}
473 [level distance=10mm,
474 every node/.style={fill=red!60,circle,inner sep=1pt},
475 level 1/.style={sibling distance=20mm,nodes={fill=red!45}},
476 level 2/.style={sibling distance=10mm,nodes={fill=red!30}},
477 level 3/.style={sibling distance=5mm,nodes={fill=red!25}}]
478 \node {31}
479 child {node {30}
480 child {node {20}
481 child {node {5}}
482 child {node {4}}
483 }
484 child {node {10}
485 child {node {9}}
486 child {node {1}}
487 }
488 }
489 child {node {20}
490 child {node {19}
491 child {node {1}}
492 child[missing]
493 }
494 child {node {18}}
495 };
496 \end{tikzpicture}
497 \end{codeexample}
498 %
499 \end{key}
500
501 \begin{key}{/tikz/grow=\meta{direction}}
502 This key is used to define the \meta{direction} in which the tree will
503 grow. The \meta{direction} can either be an angle in degrees or one of the
504 following special text strings: |down|, |up|, |left|, |right|, |north|,
505 |south|, |east|, |west|, |north east|, |north west|, |south east|, and
506 |south west|. All of these have ``their obvious meaning'', so, say,
507 |south west| is the same as the angle $-135^\circ$.
508
509 As a side effect, this option installs the default growth function.
510
511 In addition to setting the direction, this option also has a seemingly
512 strange effect: It sets the sibling distance for the current level to
513 |0pt|, but leaves the sibling distance for later levels unchanged.
514
515 This somewhat strange behavior has a highly desirable effect: If you give
516 this option before the list of children of a node starts, the ``current
517 level'' is still the parent level. Each child will be on a later level and,
518 hence, the sibling distance will be as specified originally. This will
519 cause the children to be neatly aligned in a line orthogonal to the given
520 \meta{direction}. However, if you give this option locally to a single
521 child, then ``current level'' will be the same as the child's level. The
522 zero sibling distance will then cause the child to be placed exactly at a
523 point at distance |level distance| in the direction \meta{direction}.
524 However, the children of the child will be placed ``normally'' on a line
525 orthogonal to the \meta{direction}.
526
527 These placement effects are best demonstrated by some examples:
528 %
529 \begin{codeexample}[]
530 \tikz \node {root} [grow=right] child child;
531 \end{codeexample}
532
533 \begin{codeexample}[]
534 \tikz \node {root} [grow=south west] child child;
535 \end{codeexample}
536
537 \begin{codeexample}[]
538 \begin{tikzpicture}[level distance=10mm,sibling distance=5mm]
539 \node {root}
540 [grow=down]
541 child
542 child
543 child[grow=right] {
544 child child child
545 };
546 \end{tikzpicture}
547 \end{codeexample}
548
549 \begin{codeexample}[]
550 \begin{tikzpicture}[level distance=2em]
551 \node {C}
552 child[grow=up] {node {H}}
553 child[grow=left] {node {H}}
554 child[grow=down] {node {H}}
555 child[grow=right] {node {C}
556 child[grow=up] {node {H}}
557 child[grow=right] {node {H}}
558 child[grow=down] {node {H}}
559 edge from parent[double]
560 coordinate (wrong)
561 };
562 \draw[<-,red] ([yshift=-2mm]wrong) -- +(0,-1)
563 node[below]{This is wrong!};
564 \end{tikzpicture}
565 \end{codeexample}
566
567 \begin{codeexample}[]
568 \begin{tikzpicture}
569 \node[rectangle,draw] (a) at (0,0) {start node};
570 \node[rectangle,draw] (b) at (2,1) {end};
571
572 \draw (a) -- (b)
573 node[coordinate,midway] {}
574 child[grow=100,<-] {node[above] {the middle is here}};
575 \end{tikzpicture}
576 \end{codeexample}
577 %
578 \end{key}
579
580 \begin{key}{/tikz/grow'=\meta{direction}}
581 This key has the same effect as |grow|, only the children are arranged in
582 the opposite order.
583 \end{key}
584
585
586 \subsubsection{Missing Children}
587
588 Sometimes one or more of the children of a node are ``missing''. Such a missing
589 child will count as a child with respect to the total number of children and
590 also with respect to the current child count, but it will not be rendered.
591
592 \begin{key}{/tikz/missing=\meta{true or false} (default true)}
593 If this option is given to a child, the current child counter is increased,
594 but the child is otherwise ignored. In particular, the normal contents of
595 the child is completely ignored.
596 %
597 \begin{codeexample}[]
598 \begin{tikzpicture}[level distance=10mm,sibling distance=5mm]
599 \node {root} [grow=down]
600 child { node {1} }
601 child { node {2} }
602 child { node {3} }
603 child[missing] { node {4} }
604 child { node {5} }
605 child { node {6} };
606 \end{tikzpicture}
607 \end{codeexample}
608 %
609 \end{key}
610
611
612 \subsubsection{Custom Growth Functions}
613
614 \begin{key}{/tikz/growth parent anchor=\meta{anchor} (initially center)}
615 This key allows you to specify which anchor of the parent node is to be
616 used for computing the children's position. For example, when there is only
617 one child and the |level distance| is |2cm|, then the child node will be
618 placed two centimeters below the \meta{anchor} of the parent node. ``Being
619 placed'' means that the child node's anchor (which is the anchor specified
620 using the |anchor=| option in the |node| command of the child) is two
621 centimeters below the parent node's \meta{anchor}.
622
623 In the following example, the two red lines both have length |1cm|.
624 %
625 \begin{codeexample}[]
626 \begin{tikzpicture}[level distance=1cm]
627 \node [rectangle,draw] (a) at (0,0) {root}
628 [growth parent anchor=south] child;
629
630 \node [rectangle,draw] (b) at (2,0) {root}
631 [growth parent anchor=north east] child;
632
633 \draw [red,thick,dashed] (a.south) -- (a-1);
634 \draw [red,thick,dashed] (b.north east) -- (b-1);
635 \end{tikzpicture}
636 \end{codeexample}
637
638 In the next example, the top and bottom nodes are aligned at the top and
639 the bottom, respectively.
640 %
641 \begin{codeexample}[]
642 \begin{tikzpicture}
643 [level distance=2cm,growth parent anchor=north,
644 every node/.style={anchor=north,rectangle,draw}
645 every child node/.style={anchor=south}]
646
647 \node at (0,0) {root} child {node {small}};
648
649 \node at (2,0) {big root} child {node {\large big}};
650 \end{tikzpicture}
651 \end{codeexample}
652 %
653 \end{key}
654
655 \begin{key}{/tikz/growth function=\meta{macro name} (initially \normalfont an internal function)}
656 This rather low-level option allows you to set a new growth function. The
657 \meta{macro name} must be the name of a macro without parameters. This
658 macro will be called for each child of a node. The initial function is an
659 internal function that corresponds to downward growth.
660
661 The effect of executing the macro should be the following: It should
662 transform the coordinate system in such a way that the origin becomes the
663 place where the current child should be anchored. When the macro is called,
664 the current coordinate system will be set up such that the anchor of the
665 parent node is in the origin. Thus, in each call, the \meta{macro name}
666 must essentially do a shift to the child's origin. When the macro is
667 called, the \TeX\ counter |\tikznumberofchildren| will be set to the total
668 number of children of the parent node and the counter
669 |\tikznumberofcurrentchild| will be set to the number of the current child.
670
671 The macro may, in addition to shifting the coordinate system, also
672 transform the coordinate system further. For example, it could be rotated
673 or scaled.
674
675 Additional growth functions are defined in the library, see
676 Section~\ref{section-tree-library}.
677 \end{key}
678
679
680 \subsection{Edges From the Parent Node}
681 \label{section-edge-from-parent}
682
683 Every child node is connected to its parent node via a special kind of edge
684 called the |edge from parent|. This edge is added to the \meta{child path} when
685 the following path operation is encountered:
686
687 \begin{pathoperation}{edge from parent}{\opt{\oarg{options}}}
688 This path operation can only be used inside \meta{child paths} and should
689 be given at the end, possibly followed by \meta{node specifications} like
690 |node {a}|. If a \meta{child path} does not contain this operation, it will
691 be added at the end of the \meta{child path} automatically.
692
693 By default, this operation does the following:
694 %
695 \begin{enumerate}
696 \item The following style is executed:
697 %
698 \begin{stylekey}{/tikz/edge from parent (initially draw)}
699 This style is inserted right before the |edge from parent path|
700 and before the \meta{options} are inserted.
701 %
702 \begin{codeexample}[]
703 \begin{tikzpicture}
704 [edge from parent/.style={draw,red,thick}]
705 \node {root}
706 child {node {left} edge from parent[dashed]}
707 child {node {right}
708 child {node {child}}
709 child {node {child} edge from parent[draw=none]}
710 };
711 \end{tikzpicture}
712 \end{codeexample}
713 \end{stylekey}
714 \item Next, the \meta{options} are executed.
715 \item Next, the text stored in the following key is inserted:
716 %
717 \begin{key}{/tikz/edge from parent path=\meta{path} (initially \normalfont code shown below)}
718 This option allows you to set the |edge from parent path| to a
719 new path. Initially, this path is the following:
720 %
721 \begin{codeexample}[code only]
722 (\tikzparentnode\tikzparentanchor) -- (\tikzchildnode\tikzchildanchor)
723 \end{codeexample}
724 %
725 The |\tikzparentnode| is a macro that will expand to the name
726 of the parent node. This works even when you have not assigned
727 a name to the parent node, in this case an internal name is
728 automatically generated. The |\tikzchildnode| is a macro that
729 expands to the name of the child node. The two |...anchor|
730 macros are empty by default. So, what is essentially inserted
731 is just the path segment
732 |(\tikzparentnode) -- (\tikzchildnode)|; which is exactly an
733 edge from the parent to the child.
734
735 You can modify this edge from parent path to achieve all sorts
736 of effects. For example, we could replace the straight line by
737 a curve as follows:
738 %
739 \begin{codeexample}[]
740 \begin{tikzpicture}[level distance=15mm, sibling distance=15mm,
741 edge from parent path=
742 {(\tikzparentnode.south) .. controls +(0,-1) and +(0,1)
743 .. (\tikzchildnode.north)}]
744 \node {root}
745 child {node {left}}
746 child {node {right}
747 child {node {child}}
748 child {node {child}}
749 };
750 \end{tikzpicture}
751 \end{codeexample}
752
753 Further useful |edge from parent path|s are defined in the tree
754 library, see Section~\ref{section-tree-library}.
755
756 The nodes in a \meta{node specification} following the
757 |edge from parent| path command get executed as if the |pos|
758 option had been added to all these nodes, see also
759 Section~\ref{section-pos-option}.
760
761 As an example, consider the following code:
762 %
763 \begin{codeexample}[code only]
764 \node (root) {} child {node (child) {} edge to parent node {label}};
765 \end{codeexample}
766 %
767 The |edge to parent| operation and the following |node|
768 operation will, together, have the same effect as if we had
769 said:
770 %
771 \begin{codeexample}[code only]
772 (root) -- (child) node [pos=0.5] {label}
773 \end{codeexample}
774
775 Here is a more complicated example:
776 %
777 \begin{codeexample}[]
778 \begin{tikzpicture}
779 \node {root}
780 child {
781 node {left}
782 edge from parent
783 node[left] {a}
784 node[right] {b}
785 }
786 child {
787 node {right}
788 child {
789 node {child}
790 edge from parent
791 node[left] {c}
792 }
793 child {node {child}}
794 edge from parent
795 node[near end] {x}
796 };
797 \end{tikzpicture}
798 \end{codeexample}
799
800 As said before, the anchors in the default
801 |edge from parent path| are empty. However, you can set them
802 using the following keys:
803 %
804 \begin{key}{/tikz/child anchor=\meta{anchor} (initially border)}
805 Specifies the anchor where the edge from parent meets the
806 child node by setting the macro |\tikzchildanchor| to
807 |.|\meta{anchor}.
808
809 If you specify |border| as the \meta{anchor}, then the
810 macro |\tikzchildanchor| is set to the empty string. The
811 effect of this is that the edge from the parent will meet
812 the child on the border at an automatically calculated
813 position.
814 %
815 \begin{codeexample}[]
816 \begin{tikzpicture}
817 \node {root}
818 [child anchor=north]
819 child {node {left} edge from parent[dashed]}
820 child {node {right}
821 child {node {child}}
822 child {node {child} edge from parent[draw=none]}
823 };
824 \end{tikzpicture}
825 \end{codeexample}
826 \end{key}
827
828 \begin{key}{/tikz/parent anchor=\meta{anchor} (initially border)}
829 This option works the same way as the |child anchor|, only
830 for the parent.
831 \end{key}
832 \end{key}
833 \end{enumerate}
834
835 All of the above describes the standard functioning of the
836 |edge from parent| command. You may, however, sometimes need even more
837 fine-grained control (the graph drawing engine needs it, for instance). In
838 such cases the following key gives you complete control:
839 %
840 \begin{key}{/tikz/edge from parent macro=\meta{macro}}
841 The \meta{macro} gets expanded each time the |edge from parent| path
842 operation is used. This \meta{macro} must take two parameters and must
843 expand to some text that is subsequently parsed by the parser. The
844 first parameter will be the set of \meta{options} that where passed to
845 the |edge from parent| command, the second parameter will be the
846 \meta{node specifications} that following the command.
847
848 The standard behavior of drawing a straight line from the parent node
849 to the child node could be achieved by setting the \meta{macro} to the
850 following:
851 %
852 \begin{codeexample}[code only]
853 \def\mymacro#1#2{
854 [style=edge from parent, #1]
855 (\tikzparentnode\tikzparentanchor) -- #2 (\tikzchildnode\tikzchildanchor)
856 }
857 \end{codeexample}
858 %
859 Note that |#2| is placed between |--| and the node to ensure that nodes
860 are put ``on top'' of the line.
861 \end{key}
862 \end{pathoperation}
863
864
865 %%% Local Variables:
866 %%% mode: latex
867 %%% TeX-master: "pgfmanual-pdftex-version"
868 %%% End: