summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-trees.tex
diff options
context:
space:
mode:
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.tex747
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"