diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex | 747 |
1 files changed, 375 insertions, 372 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex index cdf2cf45456..91d2030c385 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex @@ -7,15 +7,15 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. -\section{Making Trees Grow} +\section{Making Trees Grow} \label{section-trees} - \subsection{Introduction to the Child Operation} -\emph{Trees} are a common way of visualizing hierarchical -structures. A simple tree looks like this: +\emph{Trees} are a common way of visualizing hierarchical structures. A simple +tree looks like this: +% \begin{codeexample}[] \begin{tikzpicture} \node {root} @@ -27,13 +27,13 @@ structures. A simple tree looks like this: \end{tikzpicture} \end{codeexample} -Admittedly, in reality trees are more likely to grow \emph{upward} and -not downward as above. You can tell whether the author of a paper is a -mathematician or a computer scientist by looking at the direction -their trees grow. A computer scientist's trees will grow downward -while a mathematician's tree will grow upward. Naturally, the -\emph{correct} way is the mathematician's way, which can be specified as -follows: +Admittedly, in reality trees are more likely to grow \emph{upward} and not +downward as above. You can tell whether the author of a paper is a +mathematician or a computer scientist by looking at the direction their trees +grow. A computer scientist's trees will grow downward while a mathematician's +tree will grow upward. Naturally, the \emph{correct} way is the mathematician's +way, which can be specified as follows: +% \begin{codeexample}[] \begin{tikzpicture} \node {root} [grow'=up] @@ -45,65 +45,69 @@ follows: \end{tikzpicture} \end{codeexample} -In \tikzname, there are two ways of specifying trees: Using either the -|graph| path operation, which is covered in -Section~\ref{section-library-graphs}, or using the |child| path -operation, which is covered in the present section. Both methods have -their advantages. +In \tikzname, there are two ways of specifying trees: Using either the |graph| +path operation, which is covered in Section~\ref{section-library-graphs}, or +using the |child| path operation, which is covered in the present section. Both +methods have their advantages. -In \tikzname, trees are specified by adding \emph{children} to a -node on a path using the |child| operation: +In \tikzname, trees are specified by adding \emph{children} to a node on a path +using the |child| operation: \begin{pathoperation}{child}{\opt{\oarg{options}}% - \opt{|foreach|\meta{variables}|in|\marg{values}}\opt{\marg{child path}}} - This operation should directly follow a completed |node| operation - or another |child| operation, although it is permissible that the - first |child| operation is preceded by options (we will come to - that). - - When a |node| operation like |node {X}| is followed by |child|, - \tikzname\ starts counting the number of child nodes that follow the - original |node {X}|. For this, it scans the input and stores away each - |child| and its arguments until it reaches a path operation that is - not a |child|. Note that this will fix the character codes of all - text inside the child arguments, which means, in essence, that you - cannot use verbatim text inside the nodes inside a |child|. Sorry. - - Once the children have been collected and counted, \tikzname\ starts - generating the child nodes. For each child of a parent node - \tikzname\ computes an appropriate position where the child is - placed. For each child, the coordinate system is transformed so that - the origin is at this position. Then the \meta{child path} is - drawn. Typically, the child path just consists of a |node| - specification, which results in a node being drawn at the child's - position. Finally, an edge is drawn from the first node in the - \meta{child path} to the parent node. - - The optional |foreach| part (note that there is no backslash before - |foreach|) allows you to specify multiple children in a single - |child| command. The idea is the following: A |\foreach| statement - is (internally) used to iterate over the list of \meta{values}. For - each value in this list, a new |child| is added to the node. The - syntax for \meta{variables} and for \meta{values} is the same as for - the |\foreach| statement, see Section~\ref{section-foreach}. For - example, when you say + \opt{|foreach|\meta{variables}|in|\marg{values}}\opt{\marg{child path}}} + This operation should directly follow a completed |node| operation or + another |child| operation, although it is permissible that the first + |child| operation is preceded by options (we will come to that). + + When a |node| operation like |node {X}| is followed by |child|, \tikzname\ + starts counting the number of child nodes that follow the original + |node {X}|. For this, it scans the input and stores away each |child| and + its arguments until it reaches a path operation that is not a |child|. Note + that this will fix the character codes of all text inside the child + arguments, which means, in essence, that you cannot use verbatim text + inside the nodes inside a |child|. Sorry. + + Once the children have been collected and counted, \tikzname\ starts + generating the child nodes. For each child of a parent node \tikzname\ + computes an appropriate position where the child is placed. For each child, + the coordinate system is transformed so that the origin is at this + position. Then the \meta{child path} is drawn. Typically, the child path + just consists of a |node| specification, which results in a node being + drawn at the child's position. Finally, an edge is drawn from the first + node in the \meta{child path} to the parent node. + + The optional |foreach| part (note that there is no backslash before + |foreach|) allows you to specify multiple children in a single |child| + command. The idea is the following: A |\foreach| statement is (internally) + used to iterate over the list of \meta{values}. For each value in this + list, a new |child| is added to the node. The syntax for \meta{variables} + and for \meta{values} is the same as for the |\foreach| statement, see + Section~\ref{section-foreach}. For example, when you say + % \begin{codeexample}[code only] node {root} child [red] foreach \name in {1,2} {node {\name}} \end{codeexample} - the effect will be the same as if you had said + % + the effect will be the same as if you had said + % \begin{codeexample}[code only] node {root} child[red] {node {1}} child[red] {node {2}} \end{codeexample} - When you write + % + When you write + % \begin{codeexample}[code only] node {root} child[\pos] foreach \name/\pos in {1/left,2/right} {node[\pos] {\name}} \end{codeexample} - the effect will be the same as for + % + the effect will be the same as for + % \begin{codeexample}[code only] node {root} child[left] {node[left] {1}} child[right] {node[right] {2}} \end{codeexample} - You can nest things as in the following example: + You can nest things as in the following example: + % \begin{codeexample}[] \begin{tikzpicture} [level distance=4mm,level/.style={sibling distance=8mm/#1}] @@ -114,30 +118,29 @@ node {root} child[left] {node[left] {1}} child[right] {node[right] {2}} \end{tikzpicture} \end{codeexample} - The details and options for this operation are described in the rest - of this present section. + The details and options for this operation are described in the rest of + this present section. \end{pathoperation} - \subsection{Child Paths and Child Nodes} -For each |child| of a root node, its \meta{child path} is inserted at -a specific location in the picture (the placement rules are discussed -in Section~\ref{section-tree-placement}). The first node in the -\meta{child path}, if it exists, is special and called the \emph{child - node}. If there is no first node in the \meta{child path}, that is, -if the \meta{child path} is missing (including the curly braces) or if -it does not start with |node| or with |coordinate|, then an empty -child node of shape |coordinate| is automatically added. - -Consider the example |\node {x} child {node {y}} child;|. For the -first child, the \meta{child path} has the child node |node {y}|. For -the second child, no child node is specified and, thus, it is just -|coordinate|. - -As for any normal node, you can give the child node a name, shift it -around, or use options to influence how it is rendered. +For each |child| of a root node, its \meta{child path} is inserted at a +specific location in the picture (the placement rules are discussed in +Section~\ref{section-tree-placement}). The first node in the \meta{child path}, +if it exists, is special and called the \emph{child node}. If there is no first +node in the \meta{child path}, that is, if the \meta{child path} is missing +(including the curly braces) or if it does not start with |node| or with +|coordinate|, then an empty child node of shape |coordinate| is automatically +added. + +Consider the example |\node {x} child {node {y}} child;|. For the first child, +the \meta{child path} has the child node |node {y}|. For the second child, no +child node is specified and, thus, it is just |coordinate|. + +As for any normal node, you can give the child node a name, shift it around, or +use options to influence how it is rendered. +% \begin{codeexample}[] \begin{tikzpicture}[sibling distance=15mm] \node[rectangle,draw] {root} @@ -147,14 +150,13 @@ around, or use options to influence how it is rendered. \end{tikzpicture} \end{codeexample} -In many cases, the \meta{child path} will just consist of a -specification of a child node and, possibly, children of this child -node. However, the node specification may be followed by arbitrary -other material that will be added to the picture, transformed to the -child's coordinate system. For your convenience, a move-to |(0,0)| -operation is inserted automatically at the beginning of the path. Here -is an example: - +In many cases, the \meta{child path} will just consist of a specification of a +child node and, possibly, children of this child node. However, the node +specification may be followed by arbitrary other material that will be added to +the picture, transformed to the child's coordinate system. For your +convenience, a move-to |(0,0)| operation is inserted automatically at the +beginning of the path. Here is an example: +% \begin{codeexample}[] \begin{tikzpicture} \node {root} @@ -163,56 +165,49 @@ is an example: \end{tikzpicture} \end{codeexample} - -At the end of the \meta{child path} you may add a special path -operation called |edge from parent|. If this operation is not given by -yourself somewhere on the path, it will be automatically added at the -end. This option causes a connecting edge from the parent node to the -child node to be added to the path. By giving options to this -operation you can influence how the edge is rendered. Also, nodes -following the |edge from parent| operation will be placed on this +At the end of the \meta{child path} you may add a special path operation called +|edge from parent|. If this operation is not given by yourself somewhere on the +path, it will be automatically added at the end. This option causes a +connecting edge from the parent node to the child node to be added to the path. +By giving options to this operation you can influence how the edge is rendered. +Also, nodes following the |edge from parent| operation will be placed on this edge, see Section~\ref{section-edge-from-parent} for details. To sum up: +% \begin{enumerate} -\item - The child path starts with a node specification. If it is not there, - it is added automatically. -\item - The child path ends with a |edge from parent| operation, possibly - followed by nodes to be put on this edge. If the operation is not - given at the end, it is added automatically. + \item The child path starts with a node specification. If it is not there, + it is added automatically. + \item The child path ends with a |edge from parent| operation, possibly + followed by nodes to be put on this edge. If the operation is not given + at the end, it is added automatically. \end{enumerate} - \subsection{Naming Child Nodes} -Child nodes can be named like any other node using either the |name| -option or the special syntax in which the name of the node is placed -in round parentheses between the |node| operation and the node's -text. +Child nodes can be named like any other node using either the |name| option or +the special syntax in which the name of the node is placed in round parentheses +between the |node| operation and the node's text. -If you do not assign a name to a child node, \tikzname\ will -automatically assign a name as follows: Assume that the name of the -parent node is, say, |parent|. (If you did not assign a -name to the parent, \tikzname\ will do so itself, but that name will -not be user-accessible.) The first child -of |parent| will be named |parent-1|, the second child is named -|parent-2|, and so on. +If you do not assign a name to a child node, \tikzname\ will automatically +assign a name as follows: Assume that the name of the parent node is, say, +|parent|. (If you did not assign a name to the parent, \tikzname\ will do so +itself, but that name will not be user-accessible.) The first child of |parent| +will be named |parent-1|, the second child is named |parent-2|, and so on. -This naming convention works recursively. If the second child -|parent-2| has children, then the first of these children will be -called |parent-2-1| and the second |parent-2-2| and so on. +This naming convention works recursively. If the second child |parent-2| has +children, then the first of these children will be called |parent-2-1| and the +second |parent-2-2| and so on. If you assign a name to a child node yourself, no name is generated automatically (the node does not have two names). However, ``counting -continues,'' which means that the third child of |parent| is called -|parent-3| independently of whether you have assigned names to the -first and/or second child of |parent|. +continues'', which means that the third child of |parent| is called |parent-3| +independently of whether you have assigned names to the first and/or second +child of |parent|. Here is an example: - +% \begin{codeexample}[] \begin{tikzpicture}[sibling distance=15mm] \node (root) {root} @@ -228,13 +223,13 @@ Here is an example: \end{tikzpicture} \end{codeexample} + \subsection{Specifying Options for Trees and Children} \label{section-tree-options} -Each |child| may have its own \meta{options}, which apply to ``the -whole child,'' including all of its grandchildren. Here is an -example: - +Each |child| may have its own \meta{options}, which apply to ``the whole +child'', including all of its grandchildren. Here is an example: +% \begin{codeexample}[] \begin{tikzpicture} [thick,level 1/.style={sibling distance=15mm}, @@ -245,10 +240,10 @@ example: \end{tikzpicture} \end{codeexample} -The options of the root node have no effect on the children since -the options of a node are always ``local'' to that node. Because of -this, the edges in the following tree are black, not red. - +The options of the root node have no effect on the children since the options +of a node are always ``local'' to that node. Because of this, the edges in the +following tree are black, not red. +% \begin{codeexample}[] \begin{tikzpicture}[thick] \node [red] {root} @@ -256,11 +251,13 @@ this, the edges in the following tree are black, not red. child; \end{tikzpicture} \end{codeexample} - This raises the problem of how to set options for \emph{all} - children. Naturally, you could always set options for the whole path - as in |\path [red] node {root} child child;| but this is bothersome - in some situations. Instead, it is easier to give the options - \emph{before the first child} as follows: +% +This raises the problem of how to set options for \emph{all} children. +Naturally, you could always set options for the whole path as in +|\path [red] node {root} child child;| but this is bothersome in some +situations. Instead, it is easier to give the options \emph{before the first +child} as follows: +% \begin{codeexample}[] \begin{tikzpicture}[thick] \node [red] {root} @@ -271,24 +268,20 @@ this, the edges in the following tree are black, not red. \end{codeexample} Here is the set of rules: +% \begin{enumerate} -\item - Options for the whole tree are given before the root node. -\item - Options for the root node are given directly to the |node| operation - of the root. -\item - Options for all children can be given between the root node and the - first child. -\item - Options applying to a specific child path are given as options to - the |child| operation. -\item - Options applying to the node of a child, but not to the whole child - path, are given as options to the |node| command inside the - \meta{child path}. + \item Options for the whole tree are given before the root node. + \item Options for the root node are given directly to the |node| operation + of the root. + \item Options for all children can be given between the root node and the + first child. + \item Options applying to a specific child path are given as options to the + |child| operation. + \item Options applying to the node of a child, but not to the whole child + path, are given as options to the |node| command inside the \meta{child + path}. \end{enumerate} - +% \begin{codeexample}[code only] \begin{tikzpicture} \scoped @@ -306,24 +299,25 @@ Here is the set of rules: \end{codeexample} There are additional styles that influence how children are rendered: +% \begin{stylekey}{/tikz/every child (initially \normalfont empty)} - This style is used at the beginning of each child, as if you had - given the style's contents as options to the |child| operation. + This style is used at the beginning of each child, as if you had given the + style's contents as options to the |child| operation. \end{stylekey} \begin{stylekey}{/tikz/every child node (initially \normalfont empty)} - This style is used at the beginning of each child node in addition - to the |every node| style. + This style is used at the beginning of each child node in addition to the + |every node| style. \end{stylekey} \begin{stylekey}{/tikz/level=\meta{number} (initially \normalfont empty)} - This style is executed at the beginning of each set of children, where - \meta{number} is the current level in the current tree. For example, - when you say |\node {x} child child;|, then |level=1| is - used before the first |child|. The style or code of this key will be - passed \meta{number} as its first parameter. If this first |child| - has children itself, then |level=2| would be used for them. - + This style is executed at the beginning of each set of children, where + \meta{number} is the current level in the current tree. For example, when + you say |\node {x} child child;|, then |level=1| is used before the first + |child|. The style or code of this key will be passed \meta{number} as its + first parameter. If this first |child| has children itself, then |level=2| + would be used for them. + % \begin{codeexample}[] \begin{tikzpicture}[level/.style={sibling distance=20mm/#1}] \node {root} @@ -331,13 +325,14 @@ There are additional styles that influence how children are rendered: child { child child child }; \end{tikzpicture} \end{codeexample} + % \end{stylekey} \begin{stylekey}{/tikz/level \meta{number} (initially \normalfont empty)} - This style is used in addition to the |level| style. So, when you - say |\node {x} child child;|, then the following key list is - executed: |level=1,level 1|. - + This style is used in addition to the |level| style. So, when you say + |\node {x} child child;|, then the following key list is executed: + |level=1,level 1|. + % \begin{codeexample}[] \begin{tikzpicture} [level 1/.style={sibling distance=20mm}, @@ -347,57 +342,52 @@ There are additional styles that influence how children are rendered: child { child child child }; \end{tikzpicture} \end{codeexample} + % \end{stylekey} - \subsection{Placing Child Nodes} - \label{section-tree-placement} \subsubsection{Basic Idea} -Perhaps the most difficult part in drawing a tree is the correct -layout of the children. Typically, the children have different sizes -and it is not easy to arrange them in such a manner that not too much -space is wasted, the children do not overlap, and they are either -evenly spaced or their centers are evenly distributed. Calculating -good positions is especially difficult since a good position for the -first child may depend on the size of the last child. - -In basic \tikzname, when you do not make use of the graph drawing -facilities explained in Part~\ref{part-gd}, a comparatively simple -approach is taken to placing the -children. In order to compute a child's position, all that is taken -into account is the number of the current child in the list of -children and the number of children in this list. Thus, if a node has -five children, then there is a fixed position for the first child, a -position for the second child, and so on. These positions \emph{do not - depend on the size of the children} and, hence, children can easily -overlap. However, since you can use options to shift individual -children a bit, this is not as great a problem as it may seem. - -Although the placement of the children only depends on their number in -the list of children and the total number of children, everything else -about the placement is highly configurable. You can change the -distance between children (appropriately called the -|sibling distance|) and the distance between levels of the tree. These -distances may change from level to level. The direction in which the -tree grows can be changed globally and for parts of the tree. You can -even specify your own ``growth function'' to arrange children on a -circle or along special lines or curves. +Perhaps the most difficult part in drawing a tree is the correct layout of the +children. Typically, the children have different sizes and it is not easy to +arrange them in such a manner that not too much space is wasted, the children +do not overlap, and they are either evenly spaced or their centers are evenly +distributed. Calculating good positions is especially difficult since a good +position for the first child may depend on the size of the last child. + +In basic \tikzname, when you do not make use of the graph drawing facilities +explained in Part~\ref{part-gd}, a comparatively simple approach is taken to +placing the children. In order to compute a child's position, all that is taken +into account is the number of the current child in the list of children and the +number of children in this list. Thus, if a node has five children, then there +is a fixed position for the first child, a position for the second child, and +so on. These positions \emph{do not depend on the size of the children} and, +hence, children can easily overlap. However, since you can use options to shift +individual children a bit, this is not as great a problem as it may seem. + +Although the placement of the children only depends on their number in the list +of children and the total number of children, everything else about the +placement is highly configurable. You can change the distance between children +(appropriately called the |sibling distance|) and the distance between levels +of the tree. These distances may change from level to level. The direction in +which the tree grows can be changed globally and for parts of the tree. You can +even specify your own ``growth function'' to arrange children on a circle or +along special lines or curves. -\subsubsection{Default Growth Function} -The default growth function works as follows: Assume that we are given -a node and five children. These children will be placed on a line with -their centers (or, more generally, with their anchors) spaced apart by -the current |sibling distance|. The line is -orthogonal to the current \emph{direction of growth}, which is set -with the |grow| and |grow'| option (the latter option reverses the -ordering of the children). The distance from the line to the parent node -is given by the |level distance|. +\subsubsection{Default Growth Function} +The default growth function works as follows: Assume that we are given a node +and five children. These children will be placed on a line with their centers +(or, more generally, with their anchors) spaced apart by the current +|sibling distance|. The line is orthogonal to the current \emph{direction of +growth}, which is set with the |grow| and |grow'| option (the latter option +reverses the ordering of the children). The distance from the line to the +parent node is given by the |level distance|. +% {\catcode`\|=12 \begin{codeexample}[] \begin{tikzpicture}[sibling distance=15mm, level distance=15mm] @@ -419,11 +409,11 @@ is given by the |level distance|. } \begin{key}{/tikz/level distance=\meta{distance} (initially 15mm)} - This key determines the distance between different levels of the - tree, more precisely, between the parent and the line - on which its children are arranged. When given to a single child, - this will set the distance for this child only. - + This key determines the distance between different levels of the tree, more + precisely, between the parent and the line on which its children are + arranged. When given to a single child, this will set the distance for this + child only. + % \begin{codeexample}[] \begin{tikzpicture} \node {root} @@ -453,12 +443,13 @@ is given by the |level distance|. child; \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/sibling distance=\meta{distance} (initially 15mm)} - This key specifies the distance between the anchors of the - children of a parent node. - + This key specifies the distance between the anchors of the children of a + parent node. + % \begin{codeexample}[] \begin{tikzpicture} [level distance=4mm, @@ -504,39 +495,37 @@ is given by the |level distance|. }; \end{tikzpicture} \end{codeexample} + % \end{key} - \begin{key}{/tikz/grow=\meta{direction}} - This key is used to define the \meta{direction} in which the tree - will grow. The \meta{direction} can either be an angle in degrees or - one of the following special text strings: |down|, |up|, |left|, - |right|, |north|, |south|, |east|, |west|, |north east|, - |north west|, |south east|, and |south west|. All of these have - ``their obvious meaning,'' so, say, |south west| is the same as the - angle $-135^\circ$. - - As a side effect, this option installs the default growth function. - - In addition to setting the direction, this option also has a - seemingly strange effect: It sets the sibling distance for the - current level to |0pt|, but leaves the sibling distance for later - levels unchanged. - - This somewhat strange behaviour has a highly desirable effect: If - you give this option before the list of children of a node starts, - the ``current level'' is still the parent level. Each child will be - on a later level and, hence, the sibling distance will be as - specified originally. This will cause the children to be neatly - aligned in a line orthogonal to the given \meta{direction}. However, - if you give this option locally to a single child, then ``current - level'' will be the same as the child's level. The zero sibling - distance will then cause the child to be placed exactly at a point - at distance |level distance| in the direction - \meta{direction}. However, the children of the child will be placed - ``normally'' on a line orthogonal to the \meta{direction}. - - These placement effects are best demonstrated by some examples: + This key is used to define the \meta{direction} in which the tree will + grow. The \meta{direction} can either be an angle in degrees or one of the + following special text strings: |down|, |up|, |left|, |right|, |north|, + |south|, |east|, |west|, |north east|, |north west|, |south east|, and + |south west|. All of these have ``their obvious meaning'', so, say, + |south west| is the same as the angle $-135^\circ$. + + As a side effect, this option installs the default growth function. + + In addition to setting the direction, this option also has a seemingly + strange effect: It sets the sibling distance for the current level to + |0pt|, but leaves the sibling distance for later levels unchanged. + + This somewhat strange behaviour has a highly desirable effect: If you give + this option before the list of children of a node starts, the ``current + level'' is still the parent level. Each child will be on a later level and, + hence, the sibling distance will be as specified originally. This will + cause the children to be neatly aligned in a line orthogonal to the given + \meta{direction}. However, if you give this option locally to a single + child, then ``current level'' will be the same as the child's level. The + zero sibling distance will then cause the child to be placed exactly at a + point at distance |level distance| in the direction \meta{direction}. + However, the children of the child will be placed ``normally'' on a line + orthogonal to the \meta{direction}. + + These placement effects are best demonstrated by some examples: + % \begin{codeexample}[] \tikz \node {root} [grow=right] child child; \end{codeexample} @@ -585,26 +574,26 @@ is given by the |level distance|. child[grow=100,<-] {node[above] {the middle is here}}; \end{tikzpicture} \end{codeexample} + % \end{key} \begin{key}{/tikz/grow'=\meta{direction}} - This key has the same effect as |grow|, only the children are - arranged in the opposite order. + This key has the same effect as |grow|, only the children are arranged in + the opposite order. \end{key} \subsubsection{Missing Children} -Sometimes one or more of the children of a node are ``missing.'' Such -a missing child will count as a child with respect to the total number -of children and also with respect to the current child count, but it -will not be rendered. +Sometimes one or more of the children of a node are ``missing''. Such a missing +child will count as a child with respect to the total number of children and +also with respect to the current child count, but it will not be rendered. \begin{key}{/tikz/missing=\meta{true or false} (default true)} - If this option is given to a child, the current child counter is - increased, but the child is otherwise ignored. In particular, the - normal contents of the child is completely ignored. - + If this option is given to a child, the current child counter is increased, + but the child is otherwise ignored. In particular, the normal contents of + the child is completely ignored. + % \begin{codeexample}[] \begin{tikzpicture}[level distance=10mm,sibling distance=5mm] \node {root} [grow=down] @@ -616,22 +605,23 @@ will not be rendered. child { node {6} }; \end{tikzpicture} \end{codeexample} + % \end{key} \subsubsection{Custom Growth Functions} \begin{key}{/tikz/growth parent anchor=\meta{anchor} (initially center)} - This key allows you to specify which anchor of the parent node is - to be used for computing the children's position. For example, when - there is only one child and the |level distance| is |2cm|, then the - child node will be placed two centimeters below the \meta{anchor} of - the parent node. ``Being placed'' means that the child node's - anchor (which is the anchor specified using the |anchor=| option in - the |node| command of the child) is two centimeters below the parent - node's \meta{anchor}. - - In the following example, the two red lines both have length |1cm|. + This key allows you to specify which anchor of the parent node is to be + used for computing the children's position. For example, when there is only + one child and the |level distance| is |2cm|, then the child node will be + placed two centimeters below the \meta{anchor} of the parent node. ``Being + placed'' means that the child node's anchor (which is the anchor specified + using the |anchor=| option in the |node| command of the child) is two + centimeters below the parent node's \meta{anchor}. + + In the following example, the two red lines both have length |1cm|. + % \begin{codeexample}[] \begin{tikzpicture}[level distance=1cm] \node [rectangle,draw] (a) at (0,0) {root} @@ -645,8 +635,9 @@ will not be rendered. \end{tikzpicture} \end{codeexample} - In the next example, the top and bottom nodes are aligned at the top - and the bottom, respectively. + In the next example, the top and bottom nodes are aligned at the top and + the bottom, respectively. + % \begin{codeexample}[] \begin{tikzpicture} [level distance=2cm,growth parent anchor=north, @@ -658,58 +649,56 @@ will not be rendered. \node at (2,0) {big root} child {node {\large big}}; \end{tikzpicture} \end{codeexample} + % \end{key} -\begin{key}{/tikz/growth function=\meta{macro name} (initially - \normalfont an internal function)} - This rather low-level option allows you to set a new growth - function. The \meta{macro name} must be the name of a macro without - parameters. This macro will be called for each child of a node. The - initial function is an internal function that corresponds to - downward growth. - - The effect of executing the macro should be the following: It should - transform the coordinate system in such a way that the origin - becomes the place where the current child should be anchored. When - the macro is called, the current coordinate system will be set up - such that the anchor of the parent node is in the origin. Thus, in - each call, the \meta{macro name} must essentially do a shift to the - child's origin. When the macro is called, the \TeX\ counter - |\tikznumberofchildren| will be set to the total number of children - of the parent node and the counter |\tikznumberofcurrentchild| will - be set to the number of the current child. - - The macro may, in addition to shifting the coordinate system, also - transform the coordinate system further. For example, it could be - rotated or scaled. - - Additional growth functions are defined in the library, see - Section~\ref{section-tree-library}. +\begin{key}{/tikz/growth function=\meta{macro name} (initially \normalfont an internal function)} + This rather low-level option allows you to set a new growth function. The + \meta{macro name} must be the name of a macro without parameters. This + macro will be called for each child of a node. The initial function is an + internal function that corresponds to downward growth. + + The effect of executing the macro should be the following: It should + transform the coordinate system in such a way that the origin becomes the + place where the current child should be anchored. When the macro is called, + the current coordinate system will be set up such that the anchor of the + parent node is in the origin. Thus, in each call, the \meta{macro name} + must essentially do a shift to the child's origin. When the macro is + called, the \TeX\ counter |\tikznumberofchildren| will be set to the total + number of children of the parent node and the counter + |\tikznumberofcurrentchild| will be set to the number of the current child. + + The macro may, in addition to shifting the coordinate system, also + transform the coordinate system further. For example, it could be rotated + or scaled. + + Additional growth functions are defined in the library, see + Section~\ref{section-tree-library}. \end{key} - \subsection{Edges From the Parent Node} - \label{section-edge-from-parent} -Every child node is connected to its parent node via a special kind of -edge called the |edge from parent|. This edge is added to the -\meta{child path} when the following path operation is encountered: +Every child node is connected to its parent node via a special kind of edge +called the |edge from parent|. This edge is added to the \meta{child path} when +the following path operation is encountered: \begin{pathoperation}{edge from parent}{\opt{\oarg{options}}} - This path operation can only be used inside \meta{child paths} and - should be given at the end, possibly followed by \meta{node - specifications} like |node {a}|. If a \meta{child path} does not - contain this operation, it will be added at the end of the - \meta{child path} automatically. - - By default, this operation does the following: - \begin{enumerate} - \item The following style is executed: - \begin{stylekey}{/tikz/edge from parent (initially draw)} - This style is inserted right before the |edge from parent path| and - before the \meta{options} are inserted. + This path operation can only be used inside \meta{child paths} and should + be given at the end, possibly followed by \meta{node specifications} like + |node {a}|. If a \meta{child path} does not contain this operation, it will + be added at the end of the \meta{child path} automatically. + + By default, this operation does the following: + % + \begin{enumerate} + \item The following style is executed: + % + \begin{stylekey}{/tikz/edge from parent (initially draw)} + This style is inserted right before the |edge from parent path| + and before the \meta{options} are inserted. + % \begin{codeexample}[] \begin{tikzpicture} [edge from parent/.style={draw,red,thick}] @@ -721,28 +710,32 @@ edge called the |edge from parent|. This edge is added to the }; \end{tikzpicture} \end{codeexample} - \end{stylekey} - \item Next, the \meta{options} are executed. - \item Next, the text stored in the following key is inserted: - \begin{key}{/tikz/edge from parent path=\meta{path} (initially - \normalfont code shown below)} - This option allows you to set the |edge from parent path| to a new - path. Initially, this path is the following: + \end{stylekey} + \item Next, the \meta{options} are executed. + \item Next, the text stored in the following key is inserted: + % + \begin{key}{/tikz/edge from parent path=\meta{path} (initially \normalfont code shown below)} + This option allows you to set the |edge from parent path| to a + new path. Initially, this path is the following: + % \begin{codeexample}[code only] (\tikzparentnode\tikzparentanchor) -- (\tikzchildnode\tikzchildanchor) \end{codeexample} - The |\tikzparentnode| is a macro that will expand to the name of - the parent node. This works even when you have not assigned a name - to the parent node, in this case an internal name is automatically - generated. The |\tikzchildnode| is a macro that expands to the - name of the child node. The two |...anchor| macros are empty by - default. So, what is essentially inserted is just the path segment - |(\tikzparentnode) -- (\tikzchildnode)|; which is exactly an edge - from the parent to the child. - - You can modify this edge from parent path to achieve all sorts of - effects. For example, we could replace the straight line by a - curve as follows: + % + The |\tikzparentnode| is a macro that will expand to the name + of the parent node. This works even when you have not assigned + a name to the parent node, in this case an internal name is + automatically generated. The |\tikzchildnode| is a macro that + expands to the name of the child node. The two |...anchor| + macros are empty by default. So, what is essentially inserted + is just the path segment + |(\tikzparentnode) -- (\tikzchildnode)|; which is exactly an + edge from the parent to the child. + + You can modify this edge from parent path to achieve all sorts + of effects. For example, we could replace the straight line by + a curve as follows: + % \begin{codeexample}[] \begin{tikzpicture}[level distance=15mm, sibling distance=15mm, edge from parent path= @@ -757,24 +750,30 @@ edge called the |edge from parent|. This edge is added to the \end{tikzpicture} \end{codeexample} - Further useful |edge from parent path|s are defined in the tree - library, see Section~\ref{section-tree-library}. - - The nodes in a \meta{node specification} following the - |edge from parent| path command get executed as if the |pos| option - had been added to all these nodes, see also Section~\ref{section-pos-option}. + Further useful |edge from parent path|s are defined in the tree + library, see Section~\ref{section-tree-library}. + + The nodes in a \meta{node specification} following the + |edge from parent| path command get executed as if the |pos| + option had been added to all these nodes, see also + Section~\ref{section-pos-option}. - As an example, consider the following code: + As an example, consider the following code: + % \begin{codeexample}[code only] \node (root) {} child {node (child) {} edge to parent node {label}}; \end{codeexample} - The |edge to parent| operation and the following |node| operation - will, together, have the same effect as if we had said: + % + The |edge to parent| operation and the following |node| + operation will, together, have the same effect as if we had + said: + % \begin{codeexample}[code only] (root) -- (child) node [pos=0.5] {label} \end{codeexample} - Here is a more complicated example: + Here is a more complicated example: + % \begin{codeexample}[] \begin{tikzpicture} \node {root} @@ -797,18 +796,22 @@ edge called the |edge from parent|. This edge is added to the }; \end{tikzpicture} \end{codeexample} - - As said before, the anchors in the default |edge from parent path| - are empty. However, you can set them using the following keys: - \begin{key}{/tikz/child anchor=\meta{anchor} (initially border)} - Specifies the anchor where the edge from parent meets the child - node by setting the macro |\tikzchildanchor| to - |.|\meta{anchor}. - - If you specify |border| as the \meta{anchor}, then the macro - |\tikzchildanchor| is set to the empty string. The effect of - this is that the edge from the parent will meet the child on the - border at an automatically calculated position. + + As said before, the anchors in the default + |edge from parent path| are empty. However, you can set them + using the following keys: + % + \begin{key}{/tikz/child anchor=\meta{anchor} (initially border)} + Specifies the anchor where the edge from parent meets the + child node by setting the macro |\tikzchildanchor| to + |.|\meta{anchor}. + + If you specify |border| as the \meta{anchor}, then the + macro |\tikzchildanchor| is set to the empty string. The + effect of this is that the edge from the parent will meet + the child on the border at an automatically calculated + position. + % \begin{codeexample}[] \begin{tikzpicture} \node {root} @@ -820,45 +823,45 @@ edge called the |edge from parent|. This edge is added to the }; \end{tikzpicture} \end{codeexample} - \end{key} - - \begin{key}{/tikz/parent anchor=\meta{anchor} (initially border)} - This option works the same way as the |child anchor|, only for - the parent. - \end{key} - \end{key} - \end{enumerate} - - All of the above describes the standard functioning of the - |edge from parent| command. You may, however, sometimes need even - more fine-grained control (the graph drawing engine needs it, for - instance). In such cases the following key gives you complete - control: - \begin{key}{/tikz/edge from parent macro=\meta{macro}} - The \meta{macro} gets expanded each time the |edge from parent| - path operation is used. This \meta{macro} must take two parameters - and must expand to some text that is subsequently parsed by the - parser. The first parameter will be the set of \meta{options} that - where passed to the |edge from parent| command, the second - parameter will be the \meta{node specifications} that following - the command. - - The standard behaviour of drawing a straight line from the parent - node to the child node could be achieved by setting the - \meta{macro} to the following: + \end{key} + + \begin{key}{/tikz/parent anchor=\meta{anchor} (initially border)} + This option works the same way as the |child anchor|, only + for the parent. + \end{key} + \end{key} + \end{enumerate} + + All of the above describes the standard functioning of the + |edge from parent| command. You may, however, sometimes need even more + fine-grained control (the graph drawing engine needs it, for instance). In + such cases the following key gives you complete control: + % + \begin{key}{/tikz/edge from parent macro=\meta{macro}} + The \meta{macro} gets expanded each time the |edge from parent| path + operation is used. This \meta{macro} must take two parameters and must + expand to some text that is subsequently parsed by the parser. The + first parameter will be the set of \meta{options} that where passed to + the |edge from parent| command, the second parameter will be the + \meta{node specifications} that following the command. + + The standard behaviour of drawing a straight line from the parent node + to the child node could be achieved by setting the \meta{macro} to the + following: + % \begin{codeexample}[code only] \def\mymacro#1#2{ [style=edge from parent, #1] (\tikzparentnode\tikzparentanchor) -- #2 (\tikzchildnode\tikzchildanchor) } \end{codeexample} - Note that |#2| is placed between |--| and the node to ensure that - nodes are put ``on top'' of the line. - \end{key} + % + Note that |#2| is placed between |--| and the node to ensure that nodes + are put ``on top'' of the line. + \end{key} \end{pathoperation} - %%% Local Variables: %%% mode: latex %%% TeX-master: "pgfmanual-pdftex-version" |