| 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: |