summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex3946
1 files changed, 2051 insertions, 1895 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex
index e9643c75744..36c4469d10c 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-graphs.tex
@@ -8,26 +8,26 @@
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.
+
\section{Specifying Graphs}
\label{section-library-graphs}
-
\subsection{Overview}
-\tikzname\ offers a powerful path command for specifying how the nodes
-in a graph are connected by edges and arcs: The |graph| path
-command, which becomes available when you load the |graphs| library.
+\tikzname\ offers a powerful path command for specifying how the nodes in a
+graph are connected by edges and arcs: The |graph| path command, which becomes
+available when you load the |graphs| library.
\begin{tikzlibrary}{graphs}
- The package must be loaded to use the |graph| path command.
+ The package must be loaded to use the |graph| path command.
\end{tikzlibrary}
-In this section, by \emph{graph} we refer to a set of nodes together
-with some edges (sometimes also called arcs, in case they are
-directed) such as the following:
-
+In this section, by \emph{graph} we refer to a set of nodes together with some
+edges (sometimes also called arcs, in case they are directed) such as the
+following:
+%
\begin{codeexample}[]
-\tikz \graph { a -> {b, c} -> d };
+\tikz \graph { a -> {b, c} -> d };
\end{codeexample}
\begin{codeexample}[]
@@ -59,7 +59,7 @@ directed) such as the following:
\begin{codeexample}[width=6.6cm]
\tikz [>={To[sep]}, rotate=90, xscale=-1,
mark/.style={fill=black!50}, mark/.default=]
- \graph [trie, simple,
+ \graph [trie, simple,
nodes={circle,draw},
edges={nodes={
inner sep=1pt, anchor=mid,
@@ -80,29 +80,28 @@ directed) such as the following:
},
{ [edges=red] % highlight one path
root -> f -> a -> n
- }
+ }
};
\end{codeexample}
-The nodes of a graph are normal \tikzname\ nodes, the edges are
-normal lines drawn between nodes. There is nothing in the |graph|
-library that you cannot do using the normal |\node| and the |edge|
-commands. Rather, its purpose is to offer a concise and powerful way of
-\emph{specifying} which nodes are present
-and how they are connected. The |graph| library only offers simple
-methods for specifying \emph{where} the nodes should be shown, its
-main strength is in specifying which nodes and edges are present in
-principle. The problem of finding ``good positions on the canvas'' for
-the nodes of a graph is left to \emph{graph drawing algorithms}, which
-are covered in Part~\ref{part-gd} of this manual and which
-are not part of the |graphs| library; indeed, these algorithms can be
-used also with graphs specified using |node| and |edge|
-commands. \ifluatex
-As an example, consider the above drawing of a trie, which is drawn
-without using the graph drawing libraries. Its layout can be
-somewhat improved by loading the |layered| graph drawing library,
-saying |\tikz[layered layout,...|, and then using Lua\TeX, resulting
-in the following drawing of the same graph:
+The nodes of a graph are normal \tikzname\ nodes, the edges are normal lines
+drawn between nodes. There is nothing in the |graph| library that you cannot do
+using the normal |\node| and the |edge| commands. Rather, its purpose is to
+offer a concise and powerful way of \emph{specifying} which nodes are present
+and how they are connected. The |graph| library only offers simple methods for
+specifying \emph{where} the nodes should be shown, its main strength is in
+specifying which nodes and edges are present in principle. The problem of
+finding ``good positions on the canvas'' for the nodes of a graph is left to
+\emph{graph drawing algorithms}, which are covered in Part~\ref{part-gd} of
+this manual and which are not part of the |graphs| library; indeed, these
+algorithms can be used also with graphs specified using |node| and |edge|
+commands.
+%
+\ifluatex
+As an example, consider the above drawing of a trie, which is drawn without
+using the graph drawing libraries. Its layout can be somewhat improved by
+loading the |layered| graph drawing library, saying |\tikz[layered layout,...|,
+and then using Lua\TeX, resulting in the following drawing of the same graph:
\medskip
\tikz [layered layout, >={To[sep]}, rotate=90, xscale=-1,
@@ -127,104 +126,101 @@ in the following drawing of the same graph:
},
{ [edges=red] % highlight one path
root -> f -> a -> n
- }
+ }
};
\medskip
\fi
-The |graph| library uses a syntax that is quite different from the
-normal \tikzname\ syntax for specifying nodes. The reason for this is
-that for many medium-sized graphs it can become quite cumbersome to
-specify all the nodes using |\node| repeatedly and then using a great
-number of |edge| command; possibly with complicated |\foreach|
-statements. Instead, the syntax of the |graph| library is loosely
-inspired by the \textsc{dot} format, which is quite useful for
-specifying medium-sized graphs, with some extensions on top.
-
+The |graph| library uses a syntax that is quite different from the normal
+\tikzname\ syntax for specifying nodes. The reason for this is that for many
+medium-sized graphs it can become quite cumbersome to specify all the nodes
+using |\node| repeatedly and then using a great number of |edge| command;
+possibly with complicated |\foreach| statements. Instead, the syntax of the
+|graph| library is loosely inspired by the \textsc{dot} format, which is quite
+useful for specifying medium-sized graphs, with some extensions on top.
\subsection{Concepts}
-The present section aims at giving a quick overview of the main
-concepts behind the |graph| command. The exact syntax is explained in
-more detail in later sections.
+The present section aims at giving a quick overview of the main concepts behind
+the |graph| command. The exact syntax is explained in more detail in later
+sections.
\subsubsection{Concept: Node Chains}
-The basic way of specifying a graph is to write down a \emph{node
- chain} as in the following example:
-
+The basic way of specifying a graph is to write down a \emph{node chain} as in
+the following example:
+%
\begin{codeexample}[]
\tikz [every node/.style = draw]
- \graph { foo -> bar -> blub };
+ \graph { foo -> bar -> blub };
\end{codeexample}
-As can be seen, the text |foo -> bar -> my node| creates three nodes,
-one with the text |foo|, one with |bar| and one with the text
-|blub|. These nodes are connected by arrows, which are caused by
-the |->| between the node texts. Such a sequence of node texts and
-arrows between them is called a \emph{chain} in the following.
+As can be seen, the text |foo -> bar -> my node| creates three nodes, one with
+the text |foo|, one with |bar| and one with the text |blub|. These nodes are
+connected by arrows, which are caused by the |->| between the node texts. Such
+a sequence of node texts and arrows between them is called a \emph{chain} in
+the following.
Inside a graph there can be more than one chain:
-
+%
\begin{codeexample}[]
\tikz \graph {
a -> b -> c;
d -> e -> f;
g -> f;
-};
+};
\end{codeexample}
-Multiple chains are separated by a semicolon or a comma (both have
-exactly the same effect). As the example shows, when a node text is
-seen for the second time, instead of creating a new node, a connection
-is created to the already existing node.
-
-When a node like |f| is created, both the node name and the node text
-are identical by default. This is not always desirable and can be
-changed by using the |as| key or by providing another text after
-a slash:
+Multiple chains are separated by a semicolon or a comma (both have exactly the
+same effect). As the example shows, when a node text is seen for the second
+time, instead of creating a new node, a connection is created to the already
+existing node.
+When a node like |f| is created, both the node name and the node text are
+identical by default. This is not always desirable and can be changed by using
+the |as| key or by providing another text after a slash:
+%
\begin{codeexample}[]
\tikz \graph {
x1/$x_1$ -> x2 [as=$x_2$, red] -> x34/{$x_3,x_4$};
x1 -> [bend left] x34;
-};
+};
\end{codeexample}
-When you wish to use a node name that contains special symbols like
-commas or dashes, you must surround the node name by quotes. This
-allows you to use quite arbitrary text as a ``node name'':
+When you wish to use a node name that contains special symbols like commas or
+dashes, you must surround the node name by quotes. This allows you to use quite
+arbitrary text as a ``node name'':
+%
\begin{codeexample}[]
\tikz \graph {
"$x_1$" -> "$x_2$"[red] -> "$x_3,x_4$";
"$x_1$" ->[bend left] "$x_3,x_4$";
-};
+};
\end{codeexample}
\subsubsection{Concept: Chain Groups}
-Multiple chains that are separated by a semicolon or a comma and that
-are surrounded by curly braces form what will be called a \emph{chain
- group} or just a \emph{group}. A group in itself has no special
-effect. However, things get interesting when you write down a node or
-even a whole group and connect it to another group. In this case, the
-``exit points'' of the first node or group get connected to the
-``entry points'' of the second node or group:
-
+Multiple chains that are separated by a semicolon or a comma and that are
+surrounded by curly braces form what will be called a \emph{chain group} or
+just a \emph{group}. A group in itself has no special effect. However, things
+get interesting when you write down a node or even a whole group and connect it
+to another group. In this case, the ``exit points'' of the first node or group
+get connected to the ``entry points'' of the second node or group:
+%
\begin{codeexample}[]
\tikz \graph {
a -> {
b -> c,
d -> e
} -> f
-};
+};
\end{codeexample}
Chain groups make it easy to create tree structures:
-
+%
\begin{codeexample}[width=10cm]
\tikz
\graph [grow down,
@@ -242,10 +238,11 @@ Chain groups make it easy to create tree structures:
};
\end{codeexample}
-As can be seen, the placement is not particularly nice by default, use
-the algorithms from the graph drawing libraries to get a better
-layout. For instance, adding |tree layout| to the above code results in the
-following somewhat more pleasing rendering:
+As can be seen, the placement is not particularly nice by default, use the
+algorithms from the graph drawing libraries to get a better layout. For
+instance, adding |tree layout| to the above code results in the following
+somewhat more pleasing rendering:
+%
\ifluatex
\medskip
@@ -262,64 +259,62 @@ following somewhat more pleasing rendering:
}
};
\else
-(You need to use Lua\TeX\ to typeset this graphic.)
+ (You need to use Lua\TeX\ to typeset this graphic.)
\fi
-\subsubsection{Concept: Edge Labels and Styles}
-When connectors like |->| or |--| are used to connect nodes or whole
-chain groups, one or more edges will typically be created. These edges
-can be styles easily by providing options in square brackets directly
-after these connectors:
+\subsubsection{Concept: Edge Labels and Styles}
+When connectors like |->| or |--| are used to connect nodes or whole chain
+groups, one or more edges will typically be created. These edges can be styles
+easily by providing options in square brackets directly after these connectors:
+%
\begin{codeexample}[]
\tikz \graph {
a ->[red] b --[thick] {c, d};
};
\end{codeexample}
-Using the quotes syntax, see Section~\ref{section-label-quotes},
-you can even add labels to the edges easily by putting the labels in
-quotes:
-
+Using the quotes syntax, see Section~\ref{section-label-quotes}, you can even
+add labels to the edges easily by putting the labels in quotes:
+%
\begin{codeexample}[]
\tikz \graph {
a ->[red, "foo"] b --[thick, "bar"] {c, d};
};
\end{codeexample}
-For the first edge, the effect is as desired, however
-between |b| and the group |{c,d}| two edges are inserted and the
-options |thick| and the label option |"bar"| is applied to both of
-them. While this is the correct and consistent behaviour, we typically
-might wish to specify different labels for the edge going from |b| to
-|c| and the edge going from |b| to |d|. To achieve this effect, we can
-no longer specify the label as part of the options of |--|. Rather, we
-must pass the desired label to the nodes |c| and |d|, but we must
-somehow also indicate that these options actually ``belong'' to the
-edge ``leading to'' to nodes. This is achieved by preceding the
-options with a greater-than sign:
-
+For the first edge, the effect is as desired, however between |b| and the group
+|{c,d}| two edges are inserted and the options |thick| and the label option
+|"bar"| is applied to both of them. While this is the correct and consistent
+behaviour, we typically might wish to specify different labels for the edge
+going from |b| to |c| and the edge going from |b| to |d|. To achieve this
+effect, we can no longer specify the label as part of the options of |--|.
+Rather, we must pass the desired label to the nodes |c| and |d|, but we must
+somehow also indicate that these options actually ``belong'' to the edge
+``leading to'' to nodes. This is achieved by preceding the options with a
+greater-than sign:
+%
\begin{codeexample}[]
\tikz \graph {
a -> b -- {c [> "foo"], d [> "bar"']};
};
\end{codeexample}
-Symmetrically, preceding the options by |<| causes the options and
-labels to apply to the ``outgoing'' edges of the node:
-
+Symmetrically, preceding the options by |<| causes the options and labels to
+apply to the ``outgoing'' edges of the node:
+%
\begin{codeexample}[]
\tikz \graph {
a [< red] -> b -- {c [> blue], d [> "bar"']};
};
\end{codeexample}
-This syntax allows you to easily create trees with special edge
-labels as in the following example of a treap:
-
+This syntax allows you to easily create trees with special edge labels as in
+the following example of a treap:
+%
\begin{codeexample}[]
-\tikz
+\tikz
\graph [edge quotes={fill=white,inner sep=1pt},
grow down, branch right, nodes={circle,draw}] {
"" -> h [>"9"] -> {
@@ -333,37 +328,33 @@ labels as in the following example of a treap:
\end{codeexample}
-
\subsubsection{Concept: Node Sets}
-When you write down some node text inside a |graph| command, a new
-node is created by default unless this node has already been created
-inside the same |graph| command. In particular, if a node has
-already been declared outside of the current |graph| command, a new
-node of the same name gets created.
-
-This is not always the desired behaviour. Often, you may wish to make
-nodes part of a graph than have already been defined prior to the use
-of the |graph| command. For this, simply surround a node name by
-parentheses. This will cause a reference to be created to an already
-existing node:
+When you write down some node text inside a |graph| command, a new node is
+created by default unless this node has already been created inside the same
+|graph| command. In particular, if a node has already been declared outside of
+the current |graph| command, a new node of the same name gets created.
+This is not always the desired behaviour. Often, you may wish to make nodes
+part of a graph than have already been defined prior to the use of the |graph|
+command. For this, simply surround a node name by parentheses. This will cause
+a reference to be created to an already existing node:
+%
\begin{codeexample}[]
\tikz {
\node (a) at (0,0) {A};
\node (b) at (1,0) {B};
\node (c) at (2,0) {C};
-
+
\graph { (a) -> (b) -> (c) };
}
\end{codeexample}
-You can even go a step further: A whole collection of nodes can all be
-flagged to belong to a \emph{node set} by adding the option
-|set=|\meta{node set name}. Then, inside a |graph| command, you can
-collectively refer to these nodes by surrounding the node set name in
-parentheses:
-
+You can even go a step further: A whole collection of nodes can all be flagged
+to belong to a \emph{node set} by adding the option |set=|\meta{node set name}.
+Then, inside a |graph| command, you can collectively refer to these nodes by
+surrounding the node set name in parentheses:
+%
\begin{codeexample}[]
\tikz [new set=my nodes] {
\node [set=my nodes, circle, draw] at (1,1) {A};
@@ -378,13 +369,12 @@ parentheses:
\subsubsection{Concept: Graph Macros}
-Often, a graph will consist -- at least in parts -- of standard
-parts. For instance, a graph might contain a cycle of certain size or
-a path or a clique. To facilitate specifying such graphs, you can
-define a \emph{graph macro}. Once a graph macro has been defined, you
-can use the name of the graph to make a copy of the graph part of the
-graph currently being specified:
-
+Often, a graph will consist -- at least in parts -- of standard parts. For
+instance, a graph might contain a cycle of certain size or a path or a clique.
+To facilitate specifying such graphs, you can define a \emph{graph macro}. Once
+a graph macro has been defined, you can use the name of the graph to make a
+copy of the graph part of the graph currently being specified:
+%
\begin{codeexample}[]
\tikz \graph { subgraph K_n [n=6, clockwise] };
\end{codeexample}
@@ -393,173 +383,181 @@ graph currently being specified:
\tikz \graph { subgraph C_n [n=5, clockwise] -> mid };
\end{codeexample}
-The library |graphs.standard| defines a number of such graphs,
-including the complete clique $K_n$ on $n$ nodes, the complete
-bipartite graph $K_{n,m}$ with shores sized $n$ and $m$, the cycle
-$C_n$ on $n$ nodes, the path $P_n$ on $n$ nodes, and the independent
-set $I_n$ on $n$ nodes.
+The library |graphs.standard| defines a number of such graphs, including the
+complete clique $K_n$ on $n$ nodes, the complete bipartite graph $K_{n,m}$ with
+shores sized $n$ and $m$, the cycle $C_n$ on $n$ nodes, the path $P_n$ on $n$
+nodes, and the independent set $I_n$ on $n$ nodes.
\subsubsection{Concept: Graph Expressions and Color Classes}
-When a graph is being constructed using the |graph| command, it is
-constructed recursively by uniting smaller graphs to larger
-graphs. During this recursive union process the nodes
-of the graph get implicitly \emph{colored} (conceptually) and you can
-also explicitly assign colors to individual nodes and even change the
-colors as the graph is being specified. All nodes having the same
-color form what is called a \emph{color class}.
-
-The power of color class is that special \emph{connector operators}
-allow you to add edges between nodes having certain colors. For instance,
-saying |clique=red| at the beginning of a group will
-cause all nodes that have been flagged as being (conceptually) ``red''
-to be connected as a clique. Similarly, saying
-|complete bipartite={red}{green}| will cause edges to be added
-between all red and all green nodes. More advanced connectors, like
-the |butterfly| connector, allow you to add edges between color
-classes in a fancy manner.
-
+When a graph is being constructed using the |graph| command, it is constructed
+recursively by uniting smaller graphs to larger graphs. During this recursive
+union process the nodes of the graph get implicitly \emph{colored}
+(conceptually) and you can also explicitly assign colors to individual nodes
+and even change the colors as the graph is being specified. All nodes having
+the same color form what is called a \emph{color class}.
+
+The power of color class is that special \emph{connector operators} allow you
+to add edges between nodes having certain colors. For instance, saying
+|clique=red| at the beginning of a group will cause all nodes that have been
+flagged as being (conceptually) ``red'' to be connected as a clique. Similarly,
+saying |complete bipartite={red}{green}| will cause edges to be added between
+all red and all green nodes. More advanced connectors, like the |butterfly|
+connector, allow you to add edges between color classes in a fancy manner.
+%
\begin{codeexample}[]
\tikz [x=8mm, y=6mm, circle]
\graph [nodes={fill=blue!70}, empty nodes, n=8] {
subgraph I_n [name=A] --[butterfly={level=4}]
subgraph I_n [name=B] --[butterfly={level=2}]
subgraph I_n [name=C] --[butterfly]
- subgraph I_n [name=D] --
- subgraph I_n [name=E]
+ subgraph I_n [name=D] --
+ subgraph I_n [name=E]
};
\end{codeexample}
-
\subsection{Syntax of the Graph Path Command}
\subsubsection{The Graph Command}
-In order to construct a graph, you should use the |graph| path
-command, which can be used anywhere on a path at any place where
-you could also use a command like, say, |plot| or |--|.
+In order to construct a graph, you should use the |graph| path command, which
+can be used anywhere on a path at any place where you could also use a command
+like, say, |plot| or |--|.
\begin{command}{\graph}
- Inside a |{tikzpicture}| this is an abbreviation for |\path graph|.
+ Inside a |{tikzpicture}| this is an abbreviation for |\path graph|.
\end{command}
\begin{pathoperation}{graph}{\opt{\oarg{options}}\meta{group specification}}
- When this command is encountered on a path, the construction of the
- current path is suspended (similarly to an |edge| command or a
- |node| command). In a local scope, the \meta{options} are first
- executed with the key path |/tikz/graphs| using the following
- command:
- \begin{command}{\tikzgraphsset\marg{options}}
- Executes the \meta{options} with the path prefix |/tikz/graphs|.
- \end{command}
- Apart from the keys explained in the following, further permissible
- keys will be listed during the course of the rest of this section.
-
- \begin{stylekey}{/tikz/graphs/every graph}
- This style is executed at the beginning of every |graph| path
- command prior to the \meta{options}.
- \end{stylekey}
-
- Once the scope has been set up and once the \meta{options} have been
- executed, a parser starts to parse the \meta{group
- specification}. The exact syntax of such a group specification
- in explained in detail in
- Section~\ref{section-library-graphs-group-spec}. Basically, a group
- specification is a list of chain specifications, separated by commas
- or semicolons.
-
- Depending on the content of the \meta{group specification}, two
- things will happen:
- \begin{enumerate}
- \item A number of new nodes may be created. These will be inserted
- into the picture in the same order as if they had been created
- using multiple |node| path commands at the place where the |graph|
- path command was used. In other words, all nodes created in a
- |graph| path command will be painted on top of any nodes created
- earlier in the path and behind any nodes created later in the
- path. Like normal nodes, the newly created nodes always lie on top
- of the path that is currently being created (which is often
- empty, for instance when the |\graph| command is used).
- \item Edges between the nodes may be added. They are added in the
- same order as if the |edge| command had been used at the position
- where the |graph| command is being used.
- \end{enumerate}
-
- Let us now have a look at some common keys that may be used inside
- the \meta{options}:
- \begin{key}{/tikz/graphs/nodes=\meta{options}}
- This option causes the \meta{options} to be applied to each newly
- created node inside the \meta{group specification}.
- \begin{codeexample}[]
-\tikz \graph [nodes=red] { a -> b -> c };
- \end{codeexample}
- Multiple uses of this key accumulate.
- \end{key}
- \begin{key}{/tikz/graphs/edges=\meta{options}}
- This option causes the \meta{options} to be applied to each newly
- created edge inside the \meta{group specification}.
- \begin{codeexample}[]
-\tikz \graph [edges={red,thick}] { a -> b -> c };
- \end{codeexample}
- Again, multiple uses of this key accumulate.
- \end{key}
- \begin{key}{/tikz/graphs/edge=\meta{options}}
- This is an alias for |edges|.
- \end{key}
-
- \begin{key}{/tikz/graphs/edge node=\meta{node specification}}
- This key specifies that the \meta{node specification} should be
- added to each newly created edge as an implicitly placed node.
- \begin{codeexample}[]
-\tikz \graph [edge node={node [red, near end] {X}}] { a -> b -> c };
- \end{codeexample}
- Again, multiple uses of this key accumulate.
- \begin{codeexample}[]
+ When this command is encountered on a path, the construction of the current
+ path is suspended (similarly to an |edge| command or a |node| command). In
+ a local scope, the \meta{options} are first executed with the key path
+ |/tikz/graphs| using the following command:
+ %
+ \begin{command}{\tikzgraphsset\marg{options}}
+ Executes the \meta{options} with the path prefix |/tikz/graphs|.
+ \end{command}
+ %
+ Apart from the keys explained in the following, further permissible keys
+ will be listed during the course of the rest of this section.
+
+ \begin{stylekey}{/tikz/graphs/every graph}
+ This style is executed at the beginning of every |graph| path command
+ prior to the \meta{options}.
+ \end{stylekey}
+
+ Once the scope has been set up and once the \meta{options} have been
+ executed, a parser starts to parse the \meta{group specification}. The
+ exact syntax of such a group specification in explained in detail in
+ Section~\ref{section-library-graphs-group-spec}. Basically, a group
+ specification is a list of chain specifications, separated by commas or
+ semicolons.
+
+ Depending on the content of the \meta{group specification}, two things will
+ happen:
+ %
+ \begin{enumerate}
+ \item A number of new nodes may be created. These will be inserted into
+ the picture in the same order as if they had been created using
+ multiple |node| path commands at the place where the |graph| path
+ command was used. In other words, all nodes created in a |graph|
+ path command will be painted on top of any nodes created earlier in
+ the path and behind any nodes created later in the path. Like
+ normal nodes, the newly created nodes always lie on top of the path
+ that is currently being created (which is often empty, for instance
+ when the |\graph| command is used).
+ \item Edges between the nodes may be added. They are added in the same
+ order as if the |edge| command had been used at the position where
+ the |graph| command is being used.
+ \end{enumerate}
+
+ Let us now have a look at some common keys that may be used inside the
+ \meta{options}:
+ %
+ \begin{key}{/tikz/graphs/nodes=\meta{options}}
+ This option causes the \meta{options} to be applied to each newly
+ created node inside the \meta{group specification}.
+ %
+\begin{codeexample}[]
+\tikz \graph [nodes=red] { a -> b -> c };
+\end{codeexample}
+ %
+ Multiple uses of this key accumulate.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/edges=\meta{options}}
+ This option causes the \meta{options} to be applied to each newly
+ created edge inside the \meta{group specification}.
+ %
+\begin{codeexample}[]
+\tikz \graph [edges={red,thick}] { a -> b -> c };
+\end{codeexample}
+ %
+ Again, multiple uses of this key accumulate.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/edge=\meta{options}}
+ This is an alias for |edges|.
+ \end{key}
+
+ \begin{key}{/tikz/graphs/edge node=\meta{node specification}}
+ This key specifies that the \meta{node specification} should be added
+ to each newly created edge as an implicitly placed node.
+ %
+\begin{codeexample}[]
+\tikz \graph [edge node={node [red, near end] {X}}] { a -> b -> c };
+\end{codeexample}
+ %
+ Again, multiple uses of this key accumulate.
+ %
+\begin{codeexample}[]
\tikz \graph [edge node={node [near end] {X}},
- edge node={node [near start] {Y}}] { a -> b -> c };
- \end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/graphs/edge label=\meta{text}}
- This key is an abbreviation for
- |edge node=node[auto]{|\meta{text}|}|. The net effect is that the
- |text| is placed next to the newly created edges.
- \begin{codeexample}[]
-\tikz \graph [edge label=x] { a -> b -> {c,d} };
- \end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/graphs/edge label'=\meta{text}}
- This key is an abbreviation for
- |edge node=node[auto,swap]{|\meta{text}|}|.
- \begin{codeexample}[]
+ edge node={node [near start] {Y}}] { a -> b -> c };
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/tikz/graphs/edge label=\meta{text}}
+ This key is an abbreviation for |edge node=node[auto]{|\meta{text}|}|.
+ The net effect is that the |text| is placed next to the newly created
+ edges.
+ %
+\begin{codeexample}[]
+\tikz \graph [edge label=x] { a -> b -> {c,d} };
+\end{codeexample}
+ \end{key}
+
+ \begin{key}{/tikz/graphs/edge label'=\meta{text}}
+ This key is an abbreviation for |edge node=node[auto,swap]{|\meta{text}|}|.
+ %
+\begin{codeexample}[]
\tikz \graph [edge label=out, edge label'=in]
- { subgraph C_n [clockwise, n=5] };
- \end{codeexample}
- \end{key}
+ { subgraph C_n [clockwise, n=5] };
+\end{codeexample}
+ \end{key}
\end{pathoperation}
\subsubsection{Syntax of Group Specifications}
\label{section-library-graphs-group-spec}
-A \meta{group specification} inside a |graph| path command has the
-following syntax:
+A \meta{group specification} inside a |graph| path command has the following
+syntax:
+%
\begin{quote}
- |{|\opt{\oarg{options}}\meta{list of chain specifications}|}|
+ |{|\opt{\oarg{options}}\meta{list of chain specifications}|}|
\end{quote}
-The \meta{chain specifications} must contain chain specifications,
-whose syntax is detailed in the next section, separated by either
-commas or semicolons; you can freely mix them.
-It is permissible to use empty lines (which are mapped to |\par|
-commands internally) to structure the chains visually, they are simply
-ignored by the parser.
-
-In the following example, the group specification consists of three
-chain specifications, namely of |a -> b|, then |c| alone, and finally
-|d -> e -> f|:
+%
+The \meta{chain specifications} must contain chain specifications, whose syntax
+is detailed in the next section, separated by either commas or semicolons; you
+can freely mix them. It is permissible to use empty lines (which are mapped to
+|\par| commands internally) to structure the chains visually, they are simply
+ignored by the parser.
+
+In the following example, the group specification consists of three chain
+specifications, namely of |a -> b|, then |c| alone, and finally |d -> e -> f|:
+%
\begin{codeexample}[]
\tikz \graph {
a -> b,
@@ -568,13 +566,14 @@ chain specifications, namely of |a -> b|, then |c| alone, and finally
d -> e -> f
};
\end{codeexample}
+%
The above has the same effect as the more compact group specification
|{a->b,c,d->e->f}|.
-Commas are used to detect where chain specifications end. However, you
-will often wish to use a comma also inside the options of a single
-node like in the following example:
-
+Commas are used to detect where chain specifications end. However, you will
+often wish to use a comma also inside the options of a single node like in the
+following example:
+%
\begin{codeexample}[]
\tikz \graph {
a [red, draw] -> b [blue, draw],
@@ -582,20 +581,18 @@ node like in the following example:
};
\end{codeexample}
-Note that the above example works as expected: The first comma inside
-the option list of |a| is \emph{not} interpreted as the end of the
-chain specification ``|a [red|''. Rather, commas inside square
-brackets are ``protected'' against being interpreted as separators of
-group specifications.
-
-The \meta{options} that can be given at the beginning of a group
-specification are local to the group. They are executed with the path
-prefix |/tikz/graphs|. Note that for the outermost group specification
-of a graph it makes no difference whether the options are passed to
-the |graph| command or whether they are given at the beginning of this
-group. However, for groups nested inside other groups, it does make a
-difference:
+Note that the above example works as expected: The first comma inside the
+option list of |a| is \emph{not} interpreted as the end of the chain
+specification ``|a [red|''. Rather, commas inside square brackets are
+``protected'' against being interpreted as separators of group specifications.
+The \meta{options} that can be given at the beginning of a group specification
+are local to the group. They are executed with the path prefix |/tikz/graphs|.
+Note that for the outermost group specification of a graph it makes no
+difference whether the options are passed to the |graph| command or whether
+they are given at the beginning of this group. However, for groups nested
+inside other groups, it does make a difference:
+%
\begin{codeexample}[]
\tikz \graph {
a -> { [nodes=red] % the option is local to these nodes:
@@ -607,16 +604,15 @@ difference:
\medskip
\textbf{Using foreach.}
-There is special support for the |\foreach| statement inside groups:
-You may use the statement inside a group
-specification at any place where a \meta{chain specification} would
-normally go. In this case, the |\foreach| statement is executed and
-for each iteration the content of the statement's body is treated and
-parsed as a new chain specification.
-
+There is special support for the |\foreach| statement inside groups: You may
+use the statement inside a group specification at any place where a \meta{chain
+specification} would normally go. In this case, the |\foreach| statement is
+executed and for each iteration the content of the statement's body is treated
+and parsed as a new chain specification.
+%
\begin{codeexample}[]
\tikz \graph [math nodes, branch down=5mm] {
- a -> {
+ a -> {
\foreach \i in {1,2,3} {
a_\i -> { x_\i, y_\i }
},
@@ -627,34 +623,35 @@ parsed as a new chain specification.
\medskip
\textbf{Using macros.}
-In some cases you may wish to use macros and \TeX\ code to compute
-which nodes and edges are present in a group. You cannot use macros in
-the normal way inside a graph specification since the parser does not
-expand macros as it scans for the start and end of groups and node
-names. Rather, only after commas, semicolons, and hyphens have already
-been detected and only after all other parsing decisions have been
-made will macros be expanded. At this point, when a macro expands to,
-say |a,b|, this will not result in two nodes to be created since the
-parsing is already done. For these reasons, a special key is needed to
-make it possible to ``compute'' which nodes should be present in a
+In some cases you may wish to use macros and \TeX\ code to compute which nodes
+and edges are present in a group. You cannot use macros in the normal way
+inside a graph specification since the parser does not expand macros as it
+scans for the start and end of groups and node names. Rather, only after
+commas, semicolons, and hyphens have already been detected and only after all
+other parsing decisions have been made will macros be expanded. At this point,
+when a macro expands to, say |a,b|, this will not result in two nodes to be
+created since the parsing is already done. For these reasons, a special key is
+needed to make it possible to ``compute'' which nodes should be present in a
group.
\begin{key}{/tikz/graph/parse=\meta{text}}
- This key can only be used inside the \meta{options} of a \meta{group
- specification}. Its effect is that the \meta{text} is inserted at
- the beginning of the current group as if you had entered it there.
- Naturally, it makes little sense to just write down some static
- \meta{text} since you could just as well directly place it at the
- beginning of the group. The real power of this command stems from
- the fact that the keys mechanism allows you to say, for instance,
- |parse/.expand once| to insert the text stored in some macro into
- the group.
-\begin{codeexample}[]
-\def\mychain{ a -> b -> c; }
+ This key can only be used inside the \meta{options} of a \meta{group
+ specification}. Its effect is that the \meta{text} is inserted at the
+ beginning of the current group as if you had entered it there. Naturally,
+ it makes little sense to just write down some static \meta{text} since you
+ could just as well directly place it at the beginning of the group. The
+ real power of this command stems from the fact that the keys mechanism
+ allows you to say, for instance, |parse/.expand once| to insert the text
+ stored in some macro into the group.
+ %
+\begin{codeexample}[]
+\def\mychain{ a -> b -> c; }
\tikz \graph { [parse/.expand once=\mychain] d -> e };
\end{codeexample}
- In the following, more fancy example we use a loop to create a chain
- of dynamic length.
+ %
+ In the following, more fancy example we use a loop to create a chain of
+ dynamic length.
+ %
\begin{codeexample}[]
\def\mychain#1{
\def\mytext{1}
@@ -668,151 +665,167 @@ group.
}
\tikz \graph { [my chain=4] };
\end{codeexample}
- Multiple uses of this key accumulate, that is, all the \text{text}s
- given in the different uses is inserted in the order it is given.
+ %
+ Multiple uses of this key accumulate, that is, all the \text{text}s given
+ in the different uses is inserted in the order it is given.
\end{key}
\subsubsection{Syntax of Chain Specifications}
-A \meta{chain specification} has the following syntax: It consists of
-a sequence of \meta{node specifications}, where subsequent node
-specifications are separated by \meta{edge specifications}. Node
-specifications, which typically consist of some text, are discussed in
-the next section in more detail. They normally represent a single node
-that is either newly created or exists already, but they may also
-specify a whole set of nodes.
-
-An \meta{edge specification} specifies \emph{which} of the node(s) to
-the left of the edge specification should be connected to which
-node(s) to the right of it and it also specifies in which direction
-the connections go. In the following, we only discuss how the
-direction is chosen, the powerful mechanism behind choosing which
-nodes should be connect is detailed in
+A \meta{chain specification} has the following syntax: It consists of a
+sequence of \meta{node specifications}, where subsequent node specifications
+are separated by \meta{edge specifications}. Node specifications, which
+typically consist of some text, are discussed in the next section in more
+detail. They normally represent a single node that is either newly created or
+exists already, but they may also specify a whole set of nodes.
+
+An \meta{edge specification} specifies \emph{which} of the node(s) to the left
+of the edge specification should be connected to which node(s) to the right of
+it and it also specifies in which direction the connections go. In the
+following, we only discuss how the direction is chosen, the powerful mechanism
+behind choosing which nodes should be connect is detailed in
Section~\ref{section-library-graphs-color-classes}.
-The syntax of an edge specification is always one of the following
-five possibilities:
-
+The syntax of an edge specification is always one of the following five
+possibilities:
+%
\begin{quote}
- |->| \opt{\oarg{options}}\\
- |--| \opt{\oarg{options}}\\
- |<-| \opt{\oarg{options}}\\
- |<->| \opt{\oarg{options}}\\
- |-!-| \opt{\oarg{options}}
+ |->| \opt{\oarg{options}}\\
+ |--| \opt{\oarg{options}}\\
+ |<-| \opt{\oarg{options}}\\
+ |<->| \opt{\oarg{options}}\\
+ |-!-| \opt{\oarg{options}}
\end{quote}
The first four correspond to a directed edge, an undirected edge, a
-``backward'' directed edge, and a bidirected edge, respectively. The
-fifth edge specification means that there should be no edge (this
-specification can be used together with the |simple| option to remove
-edges that have previously been added, see
-Section~\ref{section-library-graphs-simple}).
+``backward'' directed edge, and a bidirected edge, respectively. The fifth edge
+specification means that there should be no edge (this specification can be
+used together with the |simple| option to remove edges that have previously
+been added, see Section~\ref{section-library-graphs-simple}).
Suppose the nodes \meta{left nodes} are to the left of the \meta{edge
- specification} and \meta{right nodes} are to the right and suppose
-we have written |->| between them. Then the following happens:
+specification} and \meta{right nodes} are to the right and suppose we have
+written |->| between them. Then the following happens:
+%
\begin{enumerate}
-\item The \meta{options} are executed (inside a local scope) with the
- path |/tikz/graphs|. These options may setup the connector algorithm
- (see below) and may also use keys like |edge| or |edge label| to
- specify how the edge should look like. As a convenience, whenever an
- unknown key is encountered for the path |/tikz/graphs|, the key is
- passed to the |edge| key. This means that you can directly use
- options like |thick| or |red| inside the \meta{options} and they
- will apply to the edge as expected.
-\item The chosen connector algorithm, see
- Section~\ref{section-library-graphs-color-classes}, is used to
- compute from which of the \meta{left nodes} an edge should lead to
- which of the \meta{right nodes}. Suppose that $(l_1,r_1)$, \dots,
- $(l_n,r_n)$ is the list of node pairs that result (so there should
- be an edge between $l_1$ and $r_1$ and another edge between $l_2$
- and $r_2$ and so on).
-\item For each pair $(l_i,r_i)$ an edge is created. This is done by
- calling the following key (for the edge specification |->|, other
- keys are executed for the other kinds of specifications):
- \begin{key}{/tikz/graphs/new ->=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
- This key will be called for a |->| edge specification with the
- following four parameters:
- \begin{enumerate}
- \item \meta{left node} is the name of the ``left'' node, that is,
- the name of $l_i$.
- \item \meta{right node} is the name of the right node.
- \item \meta{edge options} are the accumulated options from all
- calls of |/tikz/graph/edges| in groups that surround the edge
- specification.
- \item \meta{edge nodes} is text like |node {A} node {B}| that
- specifies some nodes that should be put as labels on the edge
- using \tikzname's implicit positioning mechanism.
- \end{enumerate}
- By default, the key executes the following code:
- \begin{quote}
- |\path [->,every new ->]|\\
- \hbox{}\quad|(|\meta{left node}|\tikzgraphleftanchor) edge [|%
- \meta{edge options}|]| \meta{edge nodes}||\\
- \hbox{}\quad|(|\meta{right node}|\tikzgraphrightanchor);|
- \end{quote}
- You are welcome to change the code underlying the key.
- \begin{stylekey}{/tikz/every new ->}
- This key gets executed by default for a |new ->|.
- \end{stylekey}
- \end{key}
- \begin{key}{/tikz/graphs/left anchor=\meta{anchor}}
- This anchor is used for the node that is to the left of an edge
- specification. Setting this anchor to the empty string means that
- no special anchor is used (which is the default). The
- \meta{anchor} is stored in the macro |\tikzgraphleftanchor| with a
- leading dot.
- \begin{codeexample}[]
+ \item The \meta{options} are executed (inside a local scope) with the path
+ |/tikz/graphs|. These options may setup the connector algorithm (see
+ below) and may also use keys like |edge| or |edge label| to specify how
+ the edge should look like. As a convenience, whenever an unknown key is
+ encountered for the path |/tikz/graphs|, the key is passed to the
+ |edge| key. This means that you can directly use options like |thick|
+ or |red| inside the \meta{options} and they will apply to the edge as
+ expected.
+ \item The chosen connector algorithm, see
+ Section~\ref{section-library-graphs-color-classes}, is used to compute
+ from which of the \meta{left nodes} an edge should lead to which of the
+ \meta{right nodes}. Suppose that $(l_1,r_1)$, \dots, $(l_n,r_n)$ is the
+ list of node pairs that result (so there should be an edge between
+ $l_1$ and $r_1$ and another edge between $l_2$ and $r_2$ and so on).
+ \item For each pair $(l_i,r_i)$ an edge is created. This is done by calling
+ the following key (for the edge specification |->|, other keys are
+ executed for the other kinds of specifications):
+ %
+ \begin{key}{/tikz/graphs/new ->=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
+ This key will be called for a |->| edge specification with the
+ following four parameters:
+ %
+ \begin{enumerate}
+ \item \meta{left node} is the name of the ``left'' node, that
+ is, the name of $l_i$.
+ \item \meta{right node} is the name of the right node.
+ \item \meta{edge options} are the accumulated options from all
+ calls of |/tikz/graph/edges| in groups that surround the
+ edge specification.
+ \item \meta{edge nodes} is text like |node {A} node {B}| that
+ specifies some nodes that should be put as labels on the
+ edge using \tikzname's implicit positioning mechanism.
+ \end{enumerate}
+ %
+ By default, the key executes the following code:
+ %
+ \begin{quote}
+ |\path [->,every new ->]|\\
+ \hbox{}\quad|(|\meta{left node}|\tikzgraphleftanchor) edge [|%
+ \meta{edge options}|]| \meta{edge nodes}||\\
+ \hbox{}\quad|(|\meta{right node}|\tikzgraphrightanchor);|
+ \end{quote}
+ %
+ You are welcome to change the code underlying the key.
+ %
+ \begin{stylekey}{/tikz/every new ->}
+ This key gets executed by default for a |new ->|.
+ \end{stylekey}
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/left anchor=\meta{anchor}}
+ This anchor is used for the node that is to the left of an edge
+ specification. Setting this anchor to the empty string means that
+ no special anchor is used (which is the default). The \meta{anchor}
+ is stored in the macro |\tikzgraphleftanchor| with a leading dot.
+ %
+\begin{codeexample}[]
\tikz \graph {
{a,b,c} -> [complete bipartite] {e,f,g}
};
- \end{codeexample}
- \begin{codeexample}[]
+\end{codeexample}
+ %
+\begin{codeexample}[]
\tikz \graph [left anchor=east, right anchor=west] {
{a,b,c} -- [complete bipartite] {e,f,g}
};
- \end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/right anchor=\meta{anchor}}
- Works like |left anchor|, only for |\tikzgraphrightanchor|.
- \end{key}
- For the other three kinds of edge specifications, the following keys
- will be called:
- \begin{key}{/tikz/graphs/new --=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
- This key is called for |--| with the same parameters as above. The
- only difference in the definition is that in the |\path| command
- the |->| gets replaced by |-|.
- \begin{stylekey}{/tikz/every new --}
- \end{stylekey}
- \end{key}
- \begin{key}{/tikz/graphs/new <->=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
- Called for |<->| with the same parameters as above. The |->| is
- replaced by |<-|
- \begin{stylekey}{/tikz/every new <->}
- \end{stylekey}
- \end{key}
- \begin{key}{/tikz/graphs/new <-=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
- Called for |<-| with the same parameters as above.%
- \footnote{You might
- wonder why this key is needed: It seems more logical at first
- sight to just call |new edge directed| with swapped first
- parameters. However, a positioning
- algorithm might wish to take the fact into account that an edge is
- ``backward'' rather than ``forward'' in order to
- improve the layout. Also, different arrow heads might be used.}
- \begin{stylekey}{/tikz/every new <-}
- \end{stylekey}
- \end{key}
- \begin{key}{/tikz/graphs/new -\protect\exclamationmarktext-=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
- Called for |-!-| with the same parameters as above. Does nothing
- by default.
- \end{key}
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/right anchor=\meta{anchor}}
+ Works like |left anchor|, only for |\tikzgraphrightanchor|.
+ \end{key}
+ %
+ For the other three kinds of edge specifications, the following keys
+ will be called:
+ %
+ \begin{key}{/tikz/graphs/new --=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
+ This key is called for |--| with the same parameters as above. The
+ only difference in the definition is that in the |\path| command
+ the |->| gets replaced by |-|.
+ %
+ \begin{stylekey}{/tikz/every new --}
+ \end{stylekey}
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/new <->=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
+ Called for |<->| with the same parameters as above. The |->| is
+ replaced by |<-|
+ %
+ \begin{stylekey}{/tikz/every new <->}
+ \end{stylekey}
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/new <-=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
+ Called for |<-| with the same parameters as above.%
+ \footnote{%
+ You might wonder why this key is needed: It seems more logical
+ at first sight to just call |new edge directed| with swapped
+ first parameters. However, a positioning algorithm might wish
+ to take the fact into account that an edge is ``backward''
+ rather than ``forward'' in order to improve the layout. Also,
+ different arrow heads might be used.
+ }
+ %
+ \begin{stylekey}{/tikz/every new <-}
+ \end{stylekey}
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/new -\protect\exclamationmarktext-=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
+ Called for |-!-| with the same parameters as above. Does nothing by
+ default.
+ \end{key}
\end{enumerate}
-Here is an example that shows the default rendering of the different
-edge specifications:
-
+Here is an example that shows the default rendering of the different edge
+specifications:
+%
\begin{codeexample}[]
\tikz \graph [branch down=5mm] {
a -> b;
@@ -820,66 +833,61 @@ edge specifications:
e <- f;
g <-> h;
i -!- j;
-};
+};
\end{codeexample}
-
\subsubsection{Syntax of Node Specifications}
-
\label{section-library-graphs-node-spec}
-Node specifications are the basic building blocks of a graph
-specification. There are three different possible kinds of node
-specifications, each of which has a different syntax:
-
+Node specifications are the basic building blocks of a graph specification.
+There are three different possible kinds of node specifications, each of which
+has a different syntax:
+%
\begin{description}
-\item[Direct Node Specification]
- \ \\
- \opt{|"|}\meta{node name}\opt{|"|}\opt{|/|\opt{|"|}\meta{text}\opt{|"|}} \opt{\oarg{options}}\\
- (note that the quotation marks are optional and only needed when the
- \meta{node name} contains special symbols)
-\item[Reference Node Specification]
- \ \\
- |(|\meta{node name or node set name}|)|
-\item[Group Node Specification]
- \ \\
- \meta{group specification}
+ \item[Direct Node Specification]
+ \ \\
+ \opt{|"|}\meta{node name}\opt{|"|}\opt{|/|\opt{|"|}\meta{text}\opt{|"|}} \opt{\oarg{options}}\\
+ (note that the quotation marks are optional and only needed when the
+ \meta{node name} contains special symbols)
+ \item[Reference Node Specification]
+ \ \\
+ |(|\meta{node name or node set name}|)|
+ \item[Group Node Specification]
+ \ \\
+ \meta{group specification}
\end{description}
-The rule for determining which of the possible kinds is meant is
-as follows: If the node specification starts with an opening
-parenthesis, a reference node specification is meant; if it starts
-with an opening curly brace, a group specification is meant; and in
-all other cases a direct node specification is meant.
+The rule for determining which of the possible kinds is meant is as follows: If
+the node specification starts with an opening parenthesis, a reference node
+specification is meant; if it starts with an opening curly brace, a group
+specification is meant; and in all other cases a direct node specification is
+meant.
\medskip
-\textbf{Direct Node Specifications.} If after reading the first symbol
-of a node specification is has been detected to be \emph{direct},
-\tikzname\ will collect all text up to the next edge
-specification and store it as the \meta{node name}; however, square
-brackets are used to indicate options and a slash ends the \meta{node
- name} and start a special \meta{text} that is used as a
-rendering text instead of the original \meta{node name}.
-
-Due to the way the parsing works and due to the restrictions on node
-names, most special characters are forbidding inside the \meta{node
- name}, including commas, semicolons, hyphens, braces, dots,
-parentheses, slashes, dashes, and more (but spaces, single
-underscores, and the hat character \emph{are} allowed). To use special
-characters in the name of a node, you can optionally surround the
-\meta{node name} and/or the \meta{text} by quotation marks. In this
-case, you can use all of the special symbols once more. The details
-of what happens, exactly, when the \meta{node name} is surrounded by
-quotation marks is explained later; surrounding the \meta{text} by
-quotation marks has essentially the same effect as surrounding it by
-curly braces.
-
-Once the node name has been determined, it is checked whether the same
-node name was already used inside the current graph. If this is the
-case, then we say that the already existing node is \emph{referenced};
-otherwise we say that the node is \emph{fresh}.
-
+\textbf{Direct Node Specifications.} If after reading the first symbol of a
+node specification is has been detected to be \emph{direct}, \tikzname\ will
+collect all text up to the next edge specification and store it as the
+\meta{node name}; however, square brackets are used to indicate options and a
+slash ends the \meta{node name} and start a special \meta{text} that is used as
+a rendering text instead of the original \meta{node name}.
+
+Due to the way the parsing works and due to the restrictions on node names,
+most special characters are forbidding inside the \meta{node name}, including
+commas, semicolons, hyphens, braces, dots, parentheses, slashes, dashes, and
+more (but spaces, single underscores, and the hat character \emph{are}
+allowed). To use special characters in the name of a node, you can optionally
+surround the \meta{node name} and/or the \meta{text} by quotation marks. In
+this case, you can use all of the special symbols once more. The details of
+what happens, exactly, when the \meta{node name} is surrounded by quotation
+marks is explained later; surrounding the \meta{text} by quotation marks has
+essentially the same effect as surrounding it by curly braces.
+
+Once the node name has been determined, it is checked whether the same node
+name was already used inside the current graph. If this is the case, then we
+say that the already existing node is \emph{referenced}; otherwise we say that
+the node is \emph{fresh}.
+%
\begin{codeexample}[]
\tikz \graph {
a -> b; % both are fresh
@@ -887,25 +895,26 @@ otherwise we say that the node is \emph{fresh}.
};
\end{codeexample}
-This behaviour of deciding whether a node is fresh or referenced can,
-however, be modified by using the following keys:
-\begin{key}{/tikz/graphs/use existing node=\opt{\meta{true or
- false}} (default true)}
- When this key is set to |true|, all nodes will be considered to the
- referenced, no node will be fresh. This option is useful if you have
- already created all the nodes of a graph prior to using the |graph|
- command and you now only wish to connect the nodes.
+This behaviour of deciding whether a node is fresh or referenced can, however,
+be modified by using the following keys:
+%
+\begin{key}{/tikz/graphs/use existing nodes=\opt{\meta{true or false}} (default true)}
+ When this key is set to |true|, all nodes will be considered to the
+ referenced, no node will be fresh. This option is useful if you have
+ already created all the nodes of a graph prior to using the |graph| command
+ and you now only wish to connect the nodes. It also implies that an error
+ is raised if you reference a node which has not been defined previously.
\end{key}
-\begin{key}{/tikz/graphs/fresh nodes=\opt{\meta{true or
- false}} (default true)}
- When this key is set to |true|, all nodes will be considered to be
- fresh. This option is useful when you create for instance a tree
- with many identical nodes.
- When a node name is encountered that was already used previously,
- a new name is chosen is follows: An apostrophe (|'|) is appended
- repeatedly until a node name is found that has not yet been
- used:
+\begin{key}{/tikz/graphs/fresh nodes=\opt{\meta{true or false}} (default true)}
+ When this key is set to |true|, all nodes will be considered to be fresh.
+ This option is useful when you create for instance a tree with many
+ identical nodes.
+
+ When a node name is encountered that was already used previously, a new
+ name is chosen is follows: An apostrophe (|'|) is appended repeatedly until
+ a node name is found that has not yet been used:
+ %
\begin{codeexample}[]
\tikz \graph [branch down=5mm] {
{ [fresh nodes]
@@ -914,20 +923,22 @@ however, be modified by using the following keys:
b -> {c, c},
b -> {c, c},
}
- },
+ },
b' -- b''
};
\end{codeexample}
+ %
\end{key}
\begin{key}{/tikz/graphs/number nodes=\opt{\meta{start number}} (default 1)}
- When this key is used in a scope, each encountered node name will
- get appended a new number, starting with \meta{start}. Typically,
- this ensures that all node names are different. Between the original
- node name and the appended number, the setting of the following will
- be inserted:
- \begin{key}{/tikz/graphs/number nodes sep=\meta{text} (initially \normalfont space)}
- \end{key}
+ When this key is used in a scope, each encountered node name will get
+ appended a new number, starting with \meta{start}. Typically, this ensures
+ that all node names are different. Between the original node name and the
+ appended number, the setting of the following will be inserted:
+ %
+ \begin{key}{/tikz/graphs/number nodes sep=\meta{text} (initially \normalfont space)}
+ \end{key}
+ %
\begin{codeexample}[]
\tikz \graph [branch down=5mm] {
{ [number nodes]
@@ -936,41 +947,43 @@ however, be modified by using the following keys:
b -> {c, c},
b -> {c, c},
}
- },
+ },
b 2 -- b 5
};
\end{codeexample}
+ %
\end{key}
-When a fresh node has been detected, a new node is created in the
-inside a protecting scope. For this, the current
-placement strategy is asked to compute a default position for the
-node, see Section~\ref{section-library-graphs-placement} for
-details. Then, the command
+When a fresh node has been detected, a new node is created in the inside a
+protecting scope. For this, the current placement strategy is asked to compute
+a default position for the node, see
+Section~\ref{section-library-graphs-placement} for details. Then, the command
+%
\begin{quote}
- |\node (|\meta{full node name}|) [|\meta{node options}|] {|\meta{text}|};|
+ |\node (|\meta{full node name}|) [|\meta{node options}|] {|\meta{text}|};|
\end{quote}
+%
is called. The different parameters are as follows:
+%
\begin{itemize}
-\item
- The \meta{full node name} is normally the \meta{node name} that has
- been determined as described before. However, there are two exceptions:
-
- First, if the \meta{node name} is empty (which happens when there
- is no \meta{node name} before the slash), then a fresh internal node
- name is created and used as
- \meta{full node name}. This name is guaranteed to be different from all
- node names used in this or any other graph. Thus, a direct node
- starting with a slash represents an anonymous fresh node.
-
- Second, you can use the following key to prefix the \meta{node name}
- inside the \meta{full node name}:
-
- \begin{key}{/tikz/graphs/name=\meta{text}}
- This key prepends the \meta{text}, followed by a separating symbol
- (a space by default), to all
- \meta{node name}s inside a \meta{full node name}. Repeated calls
- of this key accumulate, leading to ever-longer ``name paths'':
+ \item The \meta{full node name} is normally the \meta{node name} that has
+ been determined as described before. However, there are two exceptions:
+
+ First, if the \meta{node name} is empty (which happens when there is no
+ \meta{node name} before the slash), then a fresh internal node name is
+ created and used as \meta{full node name}. This name is guaranteed to
+ be different from all node names used in this or any other graph. Thus,
+ a direct node starting with a slash represents an anonymous fresh node.
+
+ Second, you can use the following key to prefix the \meta{node name}
+ inside the \meta{full node name}:
+
+ \begin{key}{/tikz/graphs/name=\meta{text}}
+ This key prepends the \meta{text}, followed by a separating symbol
+ (a space by default), to all \meta{node name}s inside a \meta{full
+ node name}. Repeated calls of this key accumulate, leading to
+ ever-longer ``name paths'':
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\graph {
@@ -980,20 +993,22 @@ is called. The different parameters are as follows:
\draw [red] (second 1) circle [radius=3mm];
\end{tikzpicture}
\end{codeexample}
- Note that, indeed, in the above example six nodes are created even
- though the first and second set of nodes have the same \meta{node
- name}. The reason is that the full names of the six nodes are
- all different. Also note that only the \meta{node name} is used as
- the node text, not the full name. This can be changed as described
- later on.
+ %
+ Note that, indeed, in the above example six nodes are created even
+ though the first and second set of nodes have the same \meta{node
+ name}. The reason is that the full names of the six nodes are all
+ different. Also note that only the \meta{node name} is used as the
+ node text, not the full name. This can be changed as described
+ later on.
- This key can be used repeatedly, leading to ever longer node names.
- \end{key}
+ This key can be used repeatedly, leading to ever longer node names.
+ \end{key}
- \begin{key}{/tikz/graphs/name separator=\meta{symbols} (initially \string\space)}
- Changes the symbol that is used to separate the \meta{text} from
- the \meta{node name}. The default is |\space|, resulting in a
- space.
+ \begin{key}{/tikz/graphs/name separator=\meta{symbols} (initially \string\space)}
+ Changes the symbol that is used to separate the \meta{text} from
+ the \meta{node name}. The default is |\space|, resulting in a
+ space.
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\graph [name separator=] { % no separator
@@ -1003,6 +1018,7 @@ is called. The different parameters are as follows:
\draw [red] (second1) circle [radius=3mm];
\end{tikzpicture}
\end{codeexample}
+ %
\begin{codeexample}[]
\begin{tikzpicture}
\graph [name separator=-] {
@@ -1012,110 +1028,127 @@ is called. The different parameters are as follows:
\draw [red] (second-1) circle [radius=3mm];
\end{tikzpicture}
\end{codeexample}
- \end{key}
-\item
- The \meta{node options} are
- \begin{enumerate}
- \item The options that have accumulated in calls to |nodes| from
- the surrounding scopes.
- \item The local \meta{options}.
- \end{enumerate}
- The options are executed with the path prefix |/tikz/graphs|, but
- any unknown key is executed with the prefix |/tikz|. This means, in
- essence, that some esoteric keys are more difficult to use inside
- the options and that any key with the prefix |/tikz/graphs| will
- take precedence over a key with the prefix |/tikz|.
-\item The \meta{text} that is passed to the |\node| command is
- computed as follows: First, you can use the following key to
- directly set the \meta{text}:
- \begin{key}{/tikz/graphs/as=\meta{text}}
- The \meta{text} is used as the text of the node. This allows you
- to provide a text for the node that differs arbitrarily from the
- name of the node.
- \begin{codeexample}[]
+ \end{key}
+ \item The \meta{node options} are
+ %
+ \begin{enumerate}
+ \item The options that have accumulated in calls to |nodes| from
+ the surrounding scopes.
+ \item The local \meta{options}.
+ \end{enumerate}
+ %
+ The options are executed with the path prefix |/tikz/graphs|, but any
+ unknown key is executed with the prefix |/tikz|. This means, in
+ essence, that some esoteric keys are more difficult to use inside the
+ options and that any key with the prefix |/tikz/graphs| will take
+ precedence over a key with the prefix |/tikz|.
+ \item The \meta{text} that is passed to the |\node| command is computed as
+ follows: First, you can use the following key to directly set the
+ \meta{text}:
+ %
+ \begin{key}{/tikz/graphs/as=\meta{text}}
+ The \meta{text} is used as the text of the node. This allows you to
+ provide a text for the node that differs arbitrarily from the name
+ of the node.
+ %
+\begin{codeexample}[]
\tikz \graph { a [as=$x$] -- b [as=$y_5$] -> c [red, as={a--b}] };
- \end{codeexample}
- This key always takes precedence over all of the mechanisms
- described below.
- \end{key}
- In case the |as| key is not used, a default text
- is chosen as follows: First, when a direct node specification
- contains a slash (or, for historical reasons, a double underscore),
- the text to the right of the slash (or double underscore) is stored
- in the macro |\tikzgraphnodetext|; if
- there is no slash, the \meta{node name} is stored in
- |\tikzgraphnodetext|, instead. Then, the current value of the
- following key is used as \meta{text}:
- \begin{key}{/tikz/graphs/typeset=\meta{code}}
- The macro or code stored in this key is used as the
- \meta{text} if the node. Inside the \meta{code}, the following
- macros are available:
- \begin{command}{\tikzgraphnodetext}
- This macro expands to the \meta{text} to the right of the double
- underscore or slash in a direct node specification or, if there
- is no slash, to the \meta{node name}.
- \end{command}
- \begin{command}{\tikzgraphnodename}
- This macro expands to the name of the current node with the
- path.
- \end{command}
- \begin{command}{\tikzgraphnodepath}
- This macro expands to the current path of the node. These
- paths result from the use of the |name| key as described above.
- \end{command}
- \begin{command}{\tikzgraphnodefullname}
- This macro contains the concatenation of the above two.
- \end{command}
- \end{key}
- By default, the typesetter is just set to |\tikzgraphnodetext|,
- which means that the default text of a node is its name. However,
- it may be useful to change this: For instance, you might wish that
- the text of all graph nodes is, say, surrounded by parentheses:
- \begin{codeexample}[]
+\end{codeexample}
+ %
+ This key always takes precedence over all of the mechanisms
+ described below.
+ \end{key}
+ %
+ In case the |as| key is not used, a default text is chosen as follows:
+ First, when a direct node specification contains a slash (or, for
+ historical reasons, a double underscore), the text to the right of the
+ slash (or double underscore) is stored in the macro
+ |\tikzgraphnodetext|; if there is no slash, the \meta{node name} is
+ stored in |\tikzgraphnodetext|, instead. Then, the current value of the
+ following key is used as \meta{text}:
+ %
+ \begin{key}{/tikz/graphs/typeset=\meta{code}}
+ The macro or code stored in this key is used as the \meta{text} if
+ the node. Inside the \meta{code}, the following macros are
+ available:
+ %
+ \begin{command}{\tikzgraphnodetext}
+ This macro expands to the \meta{text} to the right of the
+ double underscore or slash in a direct node specification or,
+ if there is no slash, to the \meta{node name}.
+ \end{command}
+ %
+ \begin{command}{\tikzgraphnodename}
+ This macro expands to the name of the current node without the
+ path.
+ \end{command}
+ %
+ \begin{command}{\tikzgraphnodepath}
+ This macro expands to the current path of the node. These paths
+ result from the use of the |name| key as described above.
+ \end{command}
+ %
+ \begin{command}{\tikzgraphnodefullname}
+ This macro contains the concatenation of the above two.
+ \end{command}
+ \end{key}
+ %
+ By default, the typesetter is just set to |\tikzgraphnodetext|, which
+ means that the default text of a node is its name. However, it may be
+ useful to change this: For instance, you might wish that the text of
+ all graph nodes is, say, surrounded by parentheses:
+ %
+\begin{codeexample}[]
\tikz \graph [typeset=(\tikzgraphnodetext)]
{ a -> b -> c };
- \end{codeexample}
- A more advanced macro might take apart the node text and render it
- differently:
- \begin{codeexample}[]
+\end{codeexample}
+ %
+ A more advanced macro might take apart the node text and render it
+ differently:
+ %
+\begin{codeexample}[]
\def\mytypesetter{\expandafter\myparser\tikzgraphnodetext\relax}
\def\myparser#1 #2 #3\relax{%
$#1_{#2,\dots,#3}$
}
\tikz \graph [typeset=\mytypesetter, grow down]
{ a 1 n -> b 2 m -> c 4 nm };
- \end{codeexample}
- The following styles install useful predefined typesetting macros:
- \begin{key}{/tikz/graphs/empty nodes}
- Just sets |typeset| to nothing, which causes all nodes to have an
- empty text (unless, of course, the |as| option is used):
- \begin{codeexample}[]
-\tikz \graph [empty nodes, nodes={circle, draw}] { a -> {b, c} };
- \end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/math nodes}
- Sets |typeset| to |$\tikzgraphnodetext$|, which causes all nodes
- names to be typeset in math mode:
- \begin{codeexample}[]
-\tikz \graph [math nodes, nodes={circle, draw}] { a_1 -> {b^2, c_3^n} };
- \end{codeexample}
- \end{key}
+\end{codeexample}
+ %
+ The following styles install useful predefined typesetting macros:
+ %
+ \begin{key}{/tikz/graphs/empty nodes}
+ Just sets |typeset| to nothing, which causes all nodes to have an
+ empty text (unless, of course, the |as| option is used):
+ %
+\begin{codeexample}[]
+\tikz \graph [empty nodes, nodes={circle, draw}] { a -> {b, c} };
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/math nodes}
+ Sets |typeset| to |$\tikzgraphnodetext$|, which causes all nodes
+ names to be typeset in math mode:
+ %
+\begin{codeexample}[]
+\tikz \graph [math nodes, nodes={circle, draw}] { a_1 -> {b^2, c_3^n} };
+\end{codeexample}
+ \end{key}
\end{itemize}
-If a node is referenced instead of fresh, then this node becomes the
-node that will be connected by the preceding or following edge
-specification to other
-nodes. The \meta{options} are executed even for a referenced node, but
-they cannot be used to change the appearance of the node (because the
-node exists already). Rather, the \meta{options} can only be used to
-change the logical coloring of the node, see
-Section~\ref{section-library-graphs-color-classes} for details.
+If a node is referenced instead of fresh, then this node becomes the node that
+will be connected by the preceding or following edge specification to other
+nodes. The \meta{options} are executed even for a referenced node, but they
+cannot be used to change the appearance of the node (because the node exists
+already). Rather, the \meta{options} can only be used to change the logical
+coloring of the node, see Section~\ref{section-library-graphs-color-classes}
+for details.
\medskip
-\textbf{Quoted Node Names.} When the \meta{node name} and/or the
-\meta{text} of a node is surrounded by quotation marks, you can use
-all sorts of special symbols as part of the text that are
-normally forbidden:
+\textbf{Quoted Node Names.} When the \meta{node name} and/or the \meta{text} of
+a node is surrounded by quotation marks, you can use all sorts of special
+symbols as part of the text that are normally forbidden:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\graph [grow right=2cm] {
@@ -1126,96 +1159,98 @@ normally forbidden:
\end{tikzpicture}
\end{codeexample}
-In detail, for the following happens when qutation marks are
-encountered at the beginning of a node name or its text:
+In detail, for the following happens when quotation marks are encountered at
+the beginning of a node name or its text:
+%
\begin{itemize}
-\item Everything following the quotation mark up to the next single
- quotation mark is collected into a macro \meta{collected}. All sorts
- of special characters, including commas, square brackets, dashes,
- and even backslashes are allowed here. Basically, the only
- restriction is that braces must be balanced.
-\item A double quotation mark (|""|) does not count as the ``next
- single quotation mark.'' Rather, it is replaced by a single
- quotation mark. For instance, |"He said, ""Hello world."""| would be
- stored inside \meta{collected} as |He said, "Hello world."|
- However, this rule applies only on the outer-most level of
- braces. Thus, in
+ \item Everything following the quotation mark up to the next single
+ quotation mark is collected into a macro \meta{collected}. All sorts of
+ special characters, including commas, square brackets, dashes, and even
+ backslashes are allowed here. Basically, the only restriction is that
+ braces must be balanced.
+ \item A double quotation mark (|""|) does not count as the ``next single
+ quotation mark''. Rather, it is replaced by a single quotation mark.
+ For instance, |"He said, ""Hello world."""| would be stored inside
+ \meta{collected} as |He said, "Hello world."| However, this rule
+ applies only on the outer-most level of braces. Thus, in
+ %
\begin{codeexample}[code only]
"He {said, ""Hello world.""}"
\end{codeexample}
- we would get |He {said, ""Hello world.""}| as \meta{collected}.
-\item ``The next single quotation mark'' refers to the next
- quotation mark on the current level of braces, so in
- |"hello {"} world"|, the next quotation mark would be the one
- following |world|.
+ %
+ we would get |He {said, ""Hello world.""}| as \meta{collected}.
+ \item ``The next single quotation mark'' refers to the next quotation mark
+ on the current level of braces, so in |"hello {"} world"|, the next
+ quotation mark would be the one following |world|.
\end{itemize}
-Now, once the \meta{collected} text has been gather, it is used as
-follows: When used as \meta{text} (what is actually displayed), it is
-just used ``as is''. When it is used as \meta{node name}, however, the
-following happens: Every ``special character'' in \meta{collected} is
-replaced by its Unicode name, surrounded by |@|-signs. For instance,
-if \meta{collected} is |Hello, world!|, the \meta{node name} is the
-somewhat longer text |Hello@COMMA@ world@EXCLAMATION MARK@|. Admittedly,
-referencing such a node from outside the graph is
-cumbersome, but when you use exactly the same \meta{collected} text
-once more, the same \meta{node name} will result. The
+Now, once the \meta{collected} text has been gather, it is used as follows:
+When used as \meta{text} (what is actually displayed), it is just used ``as
+is''. When it is used as \meta{node name}, however, the following happens:
+Every ``special character'' in \meta{collected} is replaced by its Unicode
+name, surrounded by |@|-signs. For instance, if \meta{collected} is
+|Hello, world!|, the \meta{node name} is the somewhat longer text
+|Hello@COMMA@ world@EXCLAMATION MARK@|. Admittedly, referencing such a node
+from outside the graph is cumbersome, but when you use exactly the same
+\meta{collected} text once more, the same \meta{node name} will result. The
following characters are considered ``special'':
+%
\begin{quote}
- \texttt{\char`\|}|$&^~_[](){}/.-,+*'`!":;<=>?@#%\{}|%$
+ \texttt{\char`\|}|$&^~_[](){}/.-,+*'`!":;<=>?@#%\{}|%$
\end{quote}
-These are exactly the Unicode character with a decimal code number
-between 33 and 126 that are neither digits nor letters.
-
+%
+These are exactly the Unicode character with a decimal code number between 33
+and 126 that are neither digits nor letters.
\medskip
-\textbf{Reference Node Specifications.} A reference node specification
-is a node specification that starts with an opening parenthesis. In
-this case, parentheses must surround a \meta{name} as in |(foo)|,
-where |foo| is the \meta{name}. The following will now happen:
-
+\textbf{Reference Node Specifications.} A reference node specification is a
+node specification that starts with an opening parenthesis. In this case,
+parentheses must surround a \meta{name} as in |(foo)|, where |foo| is the
+\meta{name}. The following will now happen:
+%
\begin{enumerate}
-\item It is tested whether \meta{name} is the name of a currently
- active \emph{node set}. This case will be discussed in a moment.
-\item Otherwise, the \meta{name} is interpreted and treated as a
- referenced node, but independently of whether the node has already
- been fresh in the current graph or not. In other words, the node
- must have been defined either already inside the graph (in which
- case the parenthesis are more or less superfluous) or it must have
- been defined outside the current picture.
-
- The way the referenced node is handled is the same way as for a
- direct node that is a referenced node.
-
- If the node does not already exist, an error message is printed.
+ \item It is tested whether \meta{name} is the name of a currently active
+ \emph{node set}. This case will be discussed in a moment.
+ \item Otherwise, the \meta{name} is interpreted and treated as a referenced
+ node, but independently of whether the node has already been fresh in
+ the current graph or not. In other words, the node must have been
+ defined either already inside the graph (in which case the parenthesis
+ are more or less superfluous) or it must have been defined outside the
+ current picture.
+
+ The way the referenced node is handled is the same way as for a direct
+ node that is a referenced node.
+
+ If the node does not already exist, an error message is printed.
\end{enumerate}
-Let us now have a look at node sets. Inside a |{tikzpicture}| you can
-locally define a \emph{node set} by using the following key:
+Let us now have a look at node sets. Inside a |{tikzpicture}| you can locally
+define a \emph{node set} by using the following key:
+%
\begin{key}{/tikz/new set=\meta{set name}}
- This will setup a node set named \meta{set name} within the current
- scope. Inside the scope, you can add nodes to the node set using the
- |set| key. If a node set of the same name already exists in the
- current scope, it will be reset and made empty for the current
- scope.
+ This will setup a node set named \meta{set name} within the current scope.
+ Inside the scope, you can add nodes to the node set using the |set| key. If
+ a node set of the same name already exists in the current scope, it will be
+ reset and made empty for the current scope.
- Note that this command has the path |/tikz| and is normally used
- \emph{outside} the |graph| command.
+ Note that this command has the path |/tikz| and is normally used
+ \emph{outside} the |graph| command.
\end{key}
+%
\begin{key}{/tikz/set=\meta{set name}}
- This key can be used as an option with a |node| command. The
- \meta{set name} must be the name of a node set that has previously
- been created inside some enclosing scope via the |new set| key. The
- effect is that the current node is added to the node set.
-\end{key}
-
-When you use a |graph| command inside a scope where some node set
-called \meta{set name} is defined, then inside this |graph| command
-you use |(|\meta{set name}|)| to reference \emph{all} of the nodes in
-the node set. The effect is the same as if instead of the reference to
-the set name you had created a group specification containing a list
-of references to all the nodes that are part of the node set.
-
+ This key can be used as an option with a |node| command. The \meta{set
+ name} must be the name of a node set that has previously been created
+ inside some enclosing scope via the |new set| key. The effect is that the
+ current node is added to the node set.
+\end{key}
+
+When you use a |graph| command inside a scope where some node set called
+\meta{set name} is defined, then inside this |graph| command you use
+|(|\meta{set name}|)| to reference \emph{all} of the nodes in the node set. The
+effect is the same as if instead of the reference to the set name you had
+created a group specification containing a list of references to all the nodes
+that are part of the node set.
+%
\begin{codeexample}[]
\begin{tikzpicture}[new set=red, new set=green, shorten >=2pt]
\foreach \i in {1,2,3} {
@@ -1230,18 +1265,17 @@ of references to all the nodes that are part of the node set.
\end{tikzpicture}
\end{codeexample}
-There is an interesting caveat with referencing node sets: Suppose
-that at the beginning of a graph you just say |(foo);| where |foo| is
-a set name. Unless you have specified special options, this will cause
-the following to happen: A group is created whose members are all the
-nodes of the node set |foo|. These nodes become referenced nodes, but
-otherwise nothing happens since, by default, the nodes of a group are
-not connected automatically. However, the referenced nodes have now
-been referenced inside the graph, you can thus subsequently access
-them as if they had been defined inside the graph. Here is an example
-showing how you can create nodes outside a |graph| command and then
-connect them inside as if they had been declared inside:
-
+There is an interesting caveat with referencing node sets: Suppose that at the
+beginning of a graph you just say |(foo);| where |foo| is a set name. Unless
+you have specified special options, this will cause the following to happen: A
+group is created whose members are all the nodes of the node set |foo|. These
+nodes become referenced nodes, but otherwise nothing happens since, by default,
+the nodes of a group are not connected automatically. However, the referenced
+nodes have now been referenced inside the graph, you can thus subsequently
+access them as if they had been defined inside the graph. Here is an example
+showing how you can create nodes outside a |graph| command and then connect
+them inside as if they had been declared inside:
+%
\begin{codeexample}[]
\begin{tikzpicture}[new set=import nodes]
\begin{scope}[nodes={set=import nodes}] % make all nodes part of this set
@@ -1258,50 +1292,48 @@ connect them inside as if they had been declared inside:
\end{tikzpicture}
\end{codeexample}
-
\medskip
-\textbf{Group Node Specifications.}
-At a place where a node specification should go, you can also instead
-provide a group specification. Since nodes specifications are part of
-chain specifications, which in turn are part of group specifications,
-this is a recursive definition.
-
+\textbf{Group Node Specifications.} At a place where a node specification
+should go, you can also instead provide a group specification. Since nodes
+specifications are part of chain specifications, which in turn are part of
+group specifications, this is a recursive definition.
+%
\begin{codeexample}[]
\tikz \graph { a -> {b,c,d} -> {e -> {f,g}, h} };
\end{codeexample}
-As can be seen in the above example, when two groups of nodes are
-connected via an edge specification, it is not immediately obvious
-which connecting edges are added. This is detailed in
-Section~\ref{section-library-graphs-color-classes}.
-
+As can be seen in the above example, when two groups of nodes are connected via
+an edge specification, it is not immediately obvious which connecting edges are
+added. This is detailed in Section~\ref{section-library-graphs-color-classes}.
\subsubsection{Specifying Tries}
-In computer science, a \emph{trie} is a special kind of tree, where
-for each node and each symbol of an alphabet, there is at most one
-child of the node labeled with this symbol.
+In computer science, a \emph{trie} is a special kind of tree, where for each
+node and each symbol of an alphabet, there is at most one child of the node
+labeled with this symbol.
-The |trie| key is useful for drawing tries, but it can also be used in
-other situations. What it does, essentially, is to prepend the node
-names of all nodes \emph{before} the current node of the current chain
-to the node's name. This will often make it easier or more natural to
-specify graphs in which several nodes have the same label.
+The |trie| key is useful for drawing tries, but it can also be used in other
+situations. What it does, essentially, is to prepend the node names of all
+nodes \emph{before} the current node of the current chain to the node's name.
+This will often make it easier or more natural to specify graphs in which
+several nodes have the same label.
\begin{key}{/tikz/graphs/trie=\opt{\meta{true or false}} (default true, initially false)}
- If this key is set to |true|, after a node has been created on a
- chain, the |name| key is executed with the node's \meta{node
- name}. Thus, all nodes later on this chain have the ``path'' of
- nodes leading to this node as their name. This means, in particular,
- that
- \begin{enumerate}
- \item two nodes of the same name but in different parts of a chain
- will be different,
- \item while if another chain starts with the same nodes, no new
- nodes get created.
- \end{enumerate}
- In total, this is exactly the behaviour you would expect of a trie:
+ If this key is set to |true|, after a node has been created on a chain, the
+ |name| key is executed with the node's \meta{node name}. Thus, all nodes
+ later on this chain have the ``path'' of nodes leading to this node as
+ their name. This means, in particular, that
+ %
+ \begin{enumerate}
+ \item two nodes of the same name but in different parts of a chain will
+ be different,
+ \item while if another chain starts with the same nodes, no new nodes
+ get created.
+ \end{enumerate}
+ %
+ In total, this is exactly the behaviour you would expect of a trie:
+ %
\begin{codeexample}[]
\tikz \graph [trie] {
a -> {
@@ -1311,12 +1343,13 @@ specify graphs in which several nodes have the same label.
}
};
\end{codeexample}
- You can even ``reiterate'' over a path in conjunction with the
- |simple| option. However, in this case, the default placement
- strategies will not work and you will need options like
- |layered layout| from the graph drawing libraries, which need
- Lua\TeX.
-\ifluatex
+ %
+ You can even ``reiterate'' over a path in conjunction with the |simple|
+ option. However, in this case, the default placement strategies will not
+ work and you will need options like |layered layout| from the graph drawing
+ libraries, which need Lua\TeX.
+ %
+\ifluatex
\begin{codeexample}[]
\tikz \graph [trie, simple, layered layout] {
a -> b -> a,
@@ -1324,8 +1357,10 @@ specify graphs in which several nodes have the same label.
a -> {d,a}
};
\end{codeexample}
- In the following example, we setup the |typeset| key so that it
- shows the complete names of the nodes:
+ %
+ In the following example, we setup the |typeset| key so that it shows the
+ complete names of the nodes:
+ %
\begin{codeexample}[]
\tikz \graph [trie, simple, layered layout,
typeset=\tikzgraphnodefullname] {
@@ -1335,8 +1370,10 @@ specify graphs in which several nodes have the same label.
};
\end{codeexample}
\fi
- You can also use the |trie| key locally and later reference nodes
- using their full name:
+ %
+ You can also use the |trie| key locally and later reference nodes using
+ their full name:
+ %
\begin{codeexample}[]
\tikz \graph {
{ [trie, simple]
@@ -1348,82 +1385,77 @@ specify graphs in which several nodes have the same label.
a b ->[red] a c a
};
\end{codeexample}
+ %
\end{key}
\subsection{Quick Graphs}
-
\label{section-library-graphs-quick}
-The graph syntax is powerful, but this power comes at a price: parsing
-the graph syntax, which is done by \TeX, can take some time. Normally,
-the parsing is fast enough that you will not notice it, but it can be
-bothersome when you have graphs with hundreds of nodes as happens
-frequently when nodes are generated algorithmically by some other
-program. Fortunately, when another program generated a graph
-specification, we typically do not need the full power of the graph
-syntax. Rather, a small subset of the graph syntax would suffice that
-allows to specify nodes and edges. For these reasons, the is a special
-``quick'' version of the graph syntax.
-
-Note, however, that using this syntax will usually at most halve the
-time needed to parse a graph. Thus, it really mostly makes sense in
-conjunction with large, algorithmically generated graphs.
+The graph syntax is powerful, but this power comes at a price: parsing the
+graph syntax, which is done by \TeX, can take some time. Normally, the parsing
+is fast enough that you will not notice it, but it can be bothersome when you
+have graphs with hundreds of nodes as happens frequently when nodes are
+generated algorithmically by some other program. Fortunately, when another
+program generated a graph specification, we typically do not need the full
+power of the graph syntax. Rather, a small subset of the graph syntax would
+suffice that allows to specify nodes and edges. For these reasons, the is a
+special ``quick'' version of the graph syntax.
+
+Note, however, that using this syntax will usually at most halve the time
+needed to parse a graph. Thus, it really mostly makes sense in conjunction with
+large, algorithmically generated graphs.
\begin{key}{/tikz/graphs/quick}
- When you provide this key with a graph, the syntax of graph
- specifications gets restricted. You are no longer allowed to use
- certain features of the graph syntax; but all features that are
- still allowed are also allowed in the same way when you do not
- provide the |quick| option. Thus, leaving out the |quick| option
- will never hurt.
-
- Since the syntax is so severely restricted, it is easier to explain
- which aspects of the graph syntax \emph{will} still work:
-
- \begin{enumerate}
- \item
- A quick graph consists of a sequence of either nodes, edges sequences, or
- groups. These are separated by commas or semicolons.
- \item
- Every node is of the form
-
- \begin{quote}
- |"|\meta{node name}|"|\opt{|/"|\meta{node text}|"[|\meta{options}|]|}
- \end{quote}
-
- The quotation marks are mandatory. The part |/"|\meta{node
- text}|"| may be missing, in which case the node name is used as
- the node text. The \meta{options} may also be missing. The
- \meta{node name} may not contain any ``funny'' characters (unlike
- in the normal graph command).
- \item
- Every chain is of the form
-
- \begin{quote}
- \meta{node spec} \meta{connector} \meta{node spec}
- \meta{connector} \dots \meta{connector} \meta{node spec}|;|
- \end{quote}
-
- Here, the \meta{node spec} are node specifications as described
- above, the \meta{connector} is one of the four connectors |->|,
- |<-|, |--|, and |<->| (the connector |-!-| is not allowed since
- the |simple| option is also not allowed). Each connector may be
- followed by options in square brackets. The semicolon may be
- replaced by a comma.
- \item
- Every group is of the form
-
- \begin{quote}
- |{ [|\meta{options}|]| \meta{chains and groups} |};|
- \end{quote}
- The \meta{options} are compulsory. The semicolon can, again, be
- replaced by a comma.
- \item
- The |number nodes| option will work as expected.
- \end{enumerate}
-
- Here is a typical way this syntax might be used:
+ When you provide this key with a graph, the syntax of graph specifications
+ gets restricted. You are no longer allowed to use certain features of the
+ graph syntax; but all features that are still allowed are also allowed in
+ the same way when you do not provide the |quick| option. Thus, leaving out
+ the |quick| option will never hurt.
+
+ Since the syntax is so severely restricted, it is easier to explain which
+ aspects of the graph syntax \emph{will} still work:
+ %
+ \begin{enumerate}
+ \item A quick graph consists of a sequence of either nodes, edges
+ sequences, or groups. These are separated by commas or semicolons.
+ \item Every node is of the form
+ %
+ \begin{quote}
+ |"|\meta{node name}|"|\opt{|/"|\meta{node text}|"[|\meta{options}|]|}
+ \end{quote}
+
+ The quotation marks are mandatory. The part |/"|\meta{node text}|"|
+ may be missing, in which case the node name is used as the node
+ text. The \meta{options} may also be missing. The \meta{node name}
+ may not contain any ``funny'' characters (unlike in the normal
+ graph command).
+ \item Every chain is of the form
+ %
+ \begin{quote}
+ \meta{node spec} \meta{connector} \meta{node spec}
+ \meta{connector} \dots \meta{connector} \meta{node spec}|;|
+ \end{quote}
+
+ Here, the \meta{node spec} are node specifications as described
+ above, the \meta{connector} is one of the four connectors |->|,
+ |<-|, |--|, and |<->| (the connector |-!-| is not allowed since the
+ |simple| option is also not allowed). Each connector may be
+ followed by options in square brackets. The semicolon may be
+ replaced by a comma.
+ \item Every group is of the form
+ %
+ \begin{quote}
+ |{ [|\meta{options}|]| \meta{chains and groups} |};|
+ \end{quote}
+ %
+ The \meta{options} are compulsory. The semicolon can, again, be
+ replaced by a comma.
+ \item The |number nodes| option will work as expected.
+ \end{enumerate}
+
+ Here is a typical way this syntax might be used:
+ %
\begin{codeexample}[]
\tikz \graph [quick] { "a" --["foo"] "b"[x=1] };
\end{codeexample}
@@ -1435,77 +1467,78 @@ conjunction with large, algorithmically generated graphs.
};
\end{codeexample}
- Let us now have a look at the most important things that will
- \emph{not} work when the |quick| option is used:
+ Let us now have a look at the most important things that will \emph{not}
+ work when the |quick| option is used:
- \begin{itemize}
- \item Connecting a node and a group as in |a->{b,c}|.
- \item Node names without quotation marks as in |a--b|.
- \item Everything described in subsequent subsections, which includes
- subgraphs (graph macros), graph sets, graph color classes,
- anonymous nodes, the |fresh nodes| option, sublayouts, simple
- graphs, edge annotations.
- \item Placement strategies -- you either have to define all node
- positions explicitly using |at=| or |x=| and |y=| or you must use
- a graph drawing algorithm like |layered layout|.
- \end{itemize}
+ \begin{itemize}
+ \item Connecting a node and a group as in |a->{b,c}|.
+ \item Node names without quotation marks as in |a--b|.
+ \item Everything described in subsequent subsections, which includes
+ subgraphs (graph macros), graph sets, graph color classes,
+ anonymous nodes, the |fresh nodes| option, sublayouts, simple
+ graphs, edge annotations.
+ \item Placement strategies -- you either have to define all node
+ positions explicitly using |at=| or |x=| and |y=| or you must use a
+ graph drawing algorithm like |layered layout|.
+ \end{itemize}
\end{key}
\subsection{Simple Versus Multi-Graphs}
-
\label{section-library-graphs-simple}
The |graph| library allows you to construct both simple graphs and
-multi-graphs. In a simple graph there can be at most one edge between
-any two vertices, while in a multi-graph there can be multiple edges
-(hence the name). The two keys |multi| and |simple| allow you to
-switch (even locally inside on of the graph's scopes) between which
-kind of graph is being constructed. By default, the |graph| command
-produces a multi-graph since these are faster to construct.
+multi-graphs. In a simple graph there can be at most one edge between any two
+vertices, while in a multi-graph there can be multiple edges (hence the name).
+The two keys |multi| and |simple| allow you to switch (even locally inside on
+of the graph's scopes) between which kind of graph is being constructed. By
+default, the |graph| command produces a multi-graph since these are faster to
+construct.
\begin{key}{/tikz/graphs/multi}
- When this edge is set for a whole graph (which is the default) or
- just for a group (which is useful if the whole graph is simple in
- general, but a part is a multi-graph), then when you specify an edge
- between two nodes several times, several such edges get created:
-
+ When this edge is set for a whole graph (which is the default) or just for
+ a group (which is useful if the whole graph is simple in general, but a
+ part is a multi-graph), then when you specify an edge between two nodes
+ several times, several such edges get created:
+ %
\begin{codeexample}[]
\tikz \graph [multi] { % "multi" is not really necessary here
a ->[bend left, red] b;
a ->[bend right, blue] b;
};
\end{codeexample}
- In case |multi| is used for a scope inside a larger scope where the
- |simple| option is specified, then inside the local |multi| scope
- edges are immediately created and they are completely ignored when
- it comes to deciding which kind of edges should be present in the
- surrounding simple graph. From the surrounding scope's point of view
- it is as if the local |multi| graph contained no edges at all.
+ %
+ In case |multi| is used for a scope inside a larger scope where the
+ |simple| option is specified, then inside the local |multi| scope edges are
+ immediately created and they are completely ignored when it comes to
+ deciding which kind of edges should be present in the surrounding simple
+ graph. From the surrounding scope's point of view it is as if the local
+ |multi| graph contained no edges at all.
- This means, in particular, that you can use the |multi| option with
- a single edge to ``enforce'' this edge to be present in a simple
- graph.
+ This means, in particular, that you can use the |multi| option with a
+ single edge to ``enforce'' this edge to be present in a simple graph.
\end{key}
\begin{key}{/tikz/graphs/simple}
- In contrast a multi-graph, in a simple graph, at most one edge gets
- created for every pair of vertices:
+ In contrast a multi-graph, in a simple graph, at most one edge gets created
+ for every pair of vertices:
+ %
\begin{codeexample}[]
\tikz \graph [simple]{
a ->[bend left, red] b;
a ->[bend right, blue] b;
};
\end{codeexample}
- As can be seen, the second edge ``wins'' over the first edge. The
- general rule is as follows: In a simple graph, whenever an edge
- between two vertices is specified multiple times, only the very last
- specification and its options will actually be executed.
-
- The real power of the |simple| option lies in the fact that you can
- first create a complicated graph and then later redirect and otherwise
- modify edges easily:
+ %
+ As can be seen, the second edge ``wins'' over the first edge. The general
+ rule is as follows: In a simple graph, whenever an edge between two
+ vertices is specified multiple times, only the very last specification and
+ its options will actually be executed.
+ The real power of the |simple| option lies in the fact that you can first
+ create a complicated graph and then later redirect and otherwise modify
+ edges easily:
+ %
\begin{codeexample}[]
\tikz \graph [simple, grow right=2cm] {
{a,b,c,d} ->[complete bipartite] {e,f,g,h};
@@ -1514,14 +1547,13 @@ produces a multi-graph since these are faster to construct.
};
\end{codeexample}
- One particularly interesting kind of edge specification for a simple
- graph is |-!-|. Recall that this is used to indicate that ``no
- edge'' should be added between certain nodes. In a multi-graph, this
- key usually has no effect (unless the key |new -!-| has been
- redefined) and is pretty superfluous. In a simple graph, however, it
- counts as an edge kind and you can thus use it to remove an edge
- that been added previously:
-
+ One particularly interesting kind of edge specification for a simple graph
+ is |-!-|. Recall that this is used to indicate that ``no edge'' should be
+ added between certain nodes. In a multi-graph, this key usually has no
+ effect (unless the key |new -!-| has been redefined) and is pretty
+ superfluous. In a simple graph, however, it counts as an edge kind and you
+ can thus use it to remove an edge that been added previously:
+ %
\begin{codeexample}[]
\tikz \graph [simple] {
subgraph K_n [n=8, clockwise];
@@ -1534,155 +1566,151 @@ produces a multi-graph since these are faster to construct.
};
\end{codeexample}
- Creating a graph such as the above in other fashions is pretty
- awkward.
+ Creating a graph such as the above in other fashions is pretty awkward.
- For every unordered pair $\{u,v\}$ of vertices at most one edge will
- be created in a simple graph. In particular, when you say |a -> b|
- and later also |a <- b|, then only the edge |a <- b| will be
- created. Similarly, when you say |a -> b| and later |b -> a|, then
- only the edge |b -> a| will be created.
+ For every unordered pair $\{u,v\}$ of vertices at most one edge will be
+ created in a simple graph. In particular, when you say |a -> b| and later
+ also |a <- b|, then only the edge |a <- b| will be created. Similarly, when
+ you say |a -> b| and later |b -> a|, then only the edge |b -> a| will be
+ created.
- The power of the |simple| command comes at a certain cost: As the
- graph is being constructed, a (sparse) array is created that keeps
- track for each edge of the last edge being specified. Then, at the
- end of the scope containing the |simple| command, for every pair of
- vertices the edge is created. This is implemented by two nested
- loops iterating over all possible pairs of vertices -- which may
- take quite a while in a graph of, say, 1000 vertices.
- Internally, the |simple| command is implemented as an operator that
- adds the edges when it is called, but
- this should be unimportant in normal situations.
+ The power of the |simple| command comes at a certain cost: As the graph is
+ being constructed, a (sparse) array is created that keeps track for each
+ edge of the last edge being specified. Then, at the end of the scope
+ containing the |simple| command, for every pair of vertices the edge is
+ created. This is implemented by two nested loops iterating over all
+ possible pairs of vertices -- which may take quite a while in a graph of,
+ say, 1000 vertices. Internally, the |simple| command is implemented as an
+ operator that adds the edges when it is called, but this should be
+ unimportant in normal situations.
\end{key}
-
-
\subsection{Graph Edges: Labeling and Styling}
-When the |graph| library creates an edge between two nodes in a graph,
-the appearance (called ``styling'' in \tikzname) can be specified in
-different ways. Sometimes you will simply wish to say ``the edges
-between these two groups of node should be red,'' but sometimes you
-may wish to say ``this particular edge going into this node should be
-red.'' In the following, different ways of specifying such styling
-requirements are discussed. Note that adding labels to edges is, from
-\tikzname's point of view, almost the same as styling edges, since
-they are also specified using options.
+When the |graph| library creates an edge between two nodes in a graph, the
+appearance (called ``styling'' in \tikzname) can be specified in different
+ways. Sometimes you will simply wish to say ``the edges between these two
+groups of node should be red'', but sometimes you may wish to say ``this
+particular edge going into this node should be red''. In the following,
+different ways of specifying such styling requirements are discussed. Note that
+adding labels to edges is, from \tikzname's point of view, almost the same as
+styling edges, since they are also specified using options.
\subsubsection{Options For All Edges Between Two Groups}
-When you write |... ->[options] ...| somewhere inside your graph
-specification, this typically cause one or more edges to be created
-between the nodes in the chain group before the |->| and the nodes in
-the chain group following it. The |options| are applied to all of
-them. In particular, if you use the |quotes| library and you write
-some text in quotes inside the |options|, this text will be added as a
-label to each edge:
-
+When you write |... ->[options] ...| somewhere inside your graph specification,
+this typically cause one or more edges to be created between the nodes in the
+chain group before the |->| and the nodes in the chain group following it. The
+|options| are applied to all of them. In particular, if you use the |quotes|
+library and you write some text in quotes inside the |options|, this text will
+be added as a label to each edge:
+%
\begin{codeexample}[]
-\tikz
+\tikz
\graph [edge quotes=near start] {
{ a, b } -> [red, "x", complete bipartite] { c, d };
};
\end{codeexample}
-As documented in the |quotes| library in more detail, you can easily
-modify the appearance of edge labels created using the quotes syntax
-by adding options after the closing quotes:
-
+As documented in the |quotes| library in more detail, you can easily modify the
+appearance of edge labels created using the quotes syntax by adding options
+after the closing quotes:
+%
\begin{codeexample}[]
\tikz \graph {
a ->["x"] b ->["y"'] c ->["z" red] d;
};
\end{codeexample}
-The following options make it easy to setup the styling of nodes
-created in this way:
-
+The following options make it easy to setup the styling of nodes created in
+this way:
+%
\begin{key}{/tikz/graphs/edge quotes=\opt{\meta{options}}}
- A shorthand for setting the style |every edge quotes| to \meta{options}.
+ A shorthand for setting the style |every edge quotes| to \meta{options}.
\begin{codeexample}[]
\tikz \graph [edge quotes={blue,auto}] {
a ->["x"] b ->["y"'] c ->["b" red] d;
};
\end{codeexample}
+%
\end{key}
\begin{key}{/tikz/graphs/edge quotes center}
- A shorthand for |edge quotes| to |anchor=center|.
+ A shorthand for |edge quotes| to |anchor=center|.
+ %
\begin{codeexample}[]
\tikz \graph [edge quotes center] {
a ->["x"] b ->["y"] c ->["z" red] d;
};
\end{codeexample}
+ %
\end{key}
\begin{key}{/tikz/graphs/edge quotes mid}
- A shorthand for |edge quotes| to |anchor=mid|.
+ A shorthand for |edge quotes| to |anchor=mid|.
+ %
\begin{codeexample}[]
\tikz \graph [edge quotes mid] {
a ->["x"] b ->["y"] c ->["z" red] d;
};
\end{codeexample}
+ %
\end{key}
-
\subsubsection{Changing Options For Certain Edges}
-
Consider the following tree-like graph:
-
+%
\begin{codeexample}[]
\tikz \graph { a -> {b,c} };
\end{codeexample}
-Suppose we wish to specify that the edge from |a| to |b| should be
-red, while the edge from |a| to |c| should be blue. The difficulty
-lies in the fact that \emph{both} edges are created by the single |->|
-operator and we can only add one of these option |red| or |blue| to
-the operator.
-
-There are several ways to solve this problem. First, we can simply
-split up the specification and specify the two edges separately:
+Suppose we wish to specify that the edge from |a| to |b| should be red, while
+the edge from |a| to |c| should be blue. The difficulty lies in the fact that
+\emph{both} edges are created by the single |->| operator and we can only add
+one of these option |red| or |blue| to the operator.
+There are several ways to solve this problem. First, we can simply split up the
+specification and specify the two edges separately:
+%
\begin{codeexample}[]
\tikz \graph {
a -> [red] b;
a -> [blue] c;
-};
+};
\end{codeexample}
-While this works quite well, we can no longer use the nice chain group
-syntax of the |graphs| library. For the rather simple graph |a->{b,c}|
-this is not a big problem, but if you specify a tree with, say, 30
-nodes it is really worthwhile being able to specify the tree ``in its
-natural form in the \TeX\ code'' rather than having to list all of the
-edges explicitly. Also, as can be seen in the above example, the
-node placement is changed, which is not always desirable.
-
-One can sidestep this problem using the |simple| option: This option
-allows you to first specify a graph and then, later on, replace edges
-by other edges and, thereby, provide new options:
-
+%
+While this works quite well, we can no longer use the nice chain group syntax
+of the |graphs| library. For the rather simple graph |a->{b,c}| this is not a
+big problem, but if you specify a tree with, say, 30 nodes it is really
+worthwhile being able to specify the tree ``in its natural form in the \TeX\
+code'' rather than having to list all of the edges explicitly. Also, as can be
+seen in the above example, the node placement is changed, which is not always
+desirable.
+
+One can sidestep this problem using the |simple| option: This option allows you
+to first specify a graph and then, later on, replace edges by other edges and,
+thereby, provide new options:
+%
\begin{codeexample}[]
\tikz \graph [simple] {
a -> {b,c};
a -> [red] b;
a -> [blue] c;
-};
+};
\end{codeexample}
-The first line is the original specification of the tree, while the
-following two lines replace some edges of the tree (in this case, all
-of them) by edges with special options. While this method is slower
-and in the above example creates even longer code, it is very useful
-if you wish to, say, highlight a path in a larger tree: First specify
-the tree normally and, then, ``respecify'' the path or paths with some
-other edge options in force. In the following example, we use this to
-highlight a whole subtree of a larger tree:
-
+The first line is the original specification of the tree, while the following
+two lines replace some edges of the tree (in this case, all of them) by edges
+with special options. While this method is slower and in the above example
+creates even longer code, it is very useful if you wish to, say, highlight a
+path in a larger tree: First specify the tree normally and, then, ``respecify''
+the path or paths with some other edge options in force. In the following
+example, we use this to highlight a whole subtree of a larger tree:
+ %
\begin{codeexample}[]
\tikz \graph [simple] {
% The larger tree, no special options in force
@@ -1690,37 +1718,36 @@ highlight a whole subtree of a larger tree:
b -> {c,d},
e -> {f,g},
h
- },
+ },
{ [edges=red] % Now highlight a part of the tree
a -> e -> {f,g}
}
-};
+};
\end{codeexample}
-
\subsubsection{Options For Incoming and Outgoing Edges}
-When you use the syntax |... ->[options] ...| to specify options, you
-specify options for the ``connections between two sets of nodes''. In
-many cases, however, it will be more natural to specify options ``for
-the edges lead to or coming from a certain node'' and you will want to
-specify these options ``at the node''. Returning to the example of the
-graph |a->{b,c}| where we want a red edge between |a| and |b| and a
-blue edge between |a| and |c|, this could also be phrased as follows:
-``Make the edge leading to |b| red and make the edge leading to |c|
-blue.''
-
-For this situation, the |graph| library offers a number of special
-keys, which are documented in the following. However, most of the time
-you will not use these keys directly, but, rather, use a special
-syntax explained in Section~\ref{section-syntax-outgoing-incoming}.
+When you use the syntax |... ->[options] ...| to specify options, you specify
+options for the ``connections between two sets of nodes''. In many cases,
+however, it will be more natural to specify options ``for the edges lead to or
+coming from a certain node'' and you will want to specify these options ``at
+the node''. Returning to the example of the graph |a->{b,c}| where we want a
+red edge between |a| and |b| and a blue edge between |a| and |c|, this could
+also be phrased as follows: ``Make the edge leading to |b| red and make the
+edge leading to |c| blue''.
+
+For this situation, the |graph| library offers a number of special keys, which
+are documented in the following. However, most of the time you will not use
+these keys directly, but, rather, use a special syntax explained in
+Section~\ref{section-syntax-outgoing-incoming}.
\begin{key}{/tikz/graphs/target edge style=\meta{options}}
- This key can (only) be used with a \emph{node} inside a graph
- specification. When used, the \meta{options} will be added to every
- edge that is created by a connector like |->| in which the node is a
- \emph{target}. Consider the following example:
+ This key can (only) be used with a \emph{node} inside a graph
+ specification. When used, the \meta{options} will be added to every edge
+ that is created by a connector like |->| in which the node is a
+ \emph{target}. Consider the following example:
+ %
\begin{codeexample}[]
\tikz \graph {
{ a, b } ->
@@ -1728,12 +1755,13 @@ syntax explained in Section~\ref{section-syntax-outgoing-incoming}.
{ e, f }
};
\end{codeexample}
- In the example, only when the edge from |a| to |c| is created, |c|
- is the ``target'' of the edge. Thus, only this edge becomes red.
-
- When an edge already has options set directly, the \meta{options}
- are executed after these direct options, thus, they ``overrule''
- them:
+ %
+ In the example, only when the edge from |a| to |c| is created, |c| is the
+ ``target'' of the edge. Thus, only this edge becomes red.
+
+ When an edge already has options set directly, the \meta{options} are
+ executed after these direct options, thus, they ``overrule'' them:
+ %
\begin{codeexample}[]
\tikz \graph {
{ a, b } -> [blue, thick]
@@ -1741,10 +1769,11 @@ syntax explained in Section~\ref{section-syntax-outgoing-incoming}.
{ e, f }
};
\end{codeexample}
-
- The \meta{options} set in this way will stay attached to the node,
- so also for edges created later on that lead to the node will have
- these options set:
+
+ The \meta{options} set in this way will stay attached to the node, so also
+ for edges created later on that lead to the node will have these options
+ set:
+ %
\begin{codeexample}[]
\tikz \graph {
{ a, b } ->
@@ -1754,15 +1783,16 @@ syntax explained in Section~\ref{section-syntax-outgoing-incoming}.
};
\end{codeexample}
- Multiple uses of this key accumulate. However, you may sometimes
- also wish to ``clear'' these options for a key since at some later
- point you no longer wish the \meta{options} to be added when some
- further edges are added. This can be achieved using the following
- key:
- \begin{key}{/tikz/graphs/target edge clear}
- Clears all \meta{options} for edges with the node as a target and
- also edge labels (see below) for this node.
- \end{key}
+ Multiple uses of this key accumulate. However, you may sometimes also wish
+ to ``clear'' these options for a key since at some later point you no
+ longer wish the \meta{options} to be added when some further edges are
+ added. This can be achieved using the following key:
+ %
+ \begin{key}{/tikz/graphs/target edge clear}
+ Clears all \meta{options} for edges with the node as a target and
+ also edge labels (see below) for this node.
+ \end{key}
+ %
\begin{codeexample}[]
\tikz \graph {
{ a, b } ->
@@ -1770,13 +1800,14 @@ syntax explained in Section~\ref{section-syntax-outgoing-incoming}.
b -> c[target edge clear]
};
\end{codeexample}
+ %
\end{key}
\begin{key}{/tikz/graphs/target edge node=\meta{node specification}}
- This key works like |target edge style|, only the \meta{node
- specification} will not be added as options to any newly created
- edges with the current node as their target, but rather it will be
- added as a node specification.
+ This key works like |target edge style|, only the \meta{node specification}
+ will not be added as options to any newly created edges with the current
+ node as their target, but rather it will be added as a node specification.
+ %
\begin{codeexample}[]
\tikz \graph {
{ a, b } ->
@@ -1784,14 +1815,16 @@ syntax explained in Section~\ref{section-syntax-outgoing-incoming}.
{ e, f }
};
\end{codeexample}
- As for |target edge style| multiple uses of this key accumulate and
- the key |target edge clear| will (also) clear all target edge nodes
- that have been set for a node earlier on.
+ %
+ As for |target edge style| multiple uses of this key accumulate and the key
+ |target edge clear| will (also) clear all target edge nodes that have been
+ set for a node earlier on.
\end{key}
\begin{key}{/tikz/graphs/source edge style=\meta{options}}
- Works exactly like |target edge style|, only now the \meta{options}
- are only added when the node is a source of a newly created edge:
+ Works exactly like |target edge style|, only now the \meta{options} are
+ only added when the node is a source of a newly created edge:
+ %
\begin{codeexample}[]
\tikz \graph {
{ a, b } ->
@@ -1799,70 +1832,78 @@ syntax explained in Section~\ref{section-syntax-outgoing-incoming}.
{ e, f }
};
\end{codeexample}
- If both for the source and also for the target of an edge
- \meta{options} have been specified, the options are applied in the
- following order:
- \begin{enumerate}
- \item First come the options from the edge itself.
- \item Then come the options contributed by the source node using
- this key.
- \item Then come the options contributed by the target node using
- |target node style|.
- \end{enumerate}
+ %
+ If both for the source and also for the target of an edge \meta{options}
+ have been specified, the options are applied in the following order:
+ %
+ \begin{enumerate}
+ \item First come the options from the edge itself.
+ \item Then come the options contributed by the source node using this
+ key.
+ \item Then come the options contributed by the target node using
+ |target node style|.
+ \end{enumerate}
+ %
\begin{codeexample}[]
\tikz \graph {
a [source edge style=red] ->[green]
b [target edge style=blue] % blue wins
};
\end{codeexample}
+ %
\end{key}
\begin{key}{/tikz/graphs/source edge node=\meta{node specification}}
- Works like |source edge style| and |target edge node|.
+ Works like |source edge style| and |target edge node|.
\end{key}
\begin{key}{/tikz/graphs/source edge clear=\meta{node specification}}
- Works like |target edge clear|.
+ Works like |target edge clear|.
\end{key}
-
\subsubsection{Special Syntax for Options For Incoming and Outgoing Edges}
\label{section-syntax-outgoing-incoming}
-The keys |target node style| and its friends are powerful, but a bit
-cumbersome to write down. For this reason, the |graphs| library
-introduces a special syntax that is based on what I call the
-``first-char syntax'' of keys. Inside the options of a node inside a
-graph, the following special rules apply:
+The keys |target node style| and its friends are powerful, but a bit cumbersome
+to write down. For this reason, the |graphs| library introduces a special
+syntax that is based on what I call the ``first-char syntax'' of keys. Inside
+the options of a node inside a graph, the following special rules apply:
+%
\begin{enumerate}
-\item Whenever an option starts with |>|, the rest of the options are
- passed to |target edge style|. For instance, when you write
- |a[>red]|, then this has the same effect as if you had written
+ \item Whenever an option starts with |>|, the rest of the options are
+ passed to |target edge style|. For instance, when you write |a[>red]|,
+ then this has the same effect as if you had written
+ %
\begin{codeexample}[code only]
-a[target edge style={red}]
+a[target edge style={red}]
\end{codeexample}
-\item Whenever an options starts with |<|, the rest of the options are
- passed to |source edge style|.
-\item In both of the above case, in case the options following the |>|
- or |<| sign start with a quote, the created edge label is passed to
- |source edge node| or |target edge node|, respectively.
+ %
+ \item Whenever an options starts with |<|, the rest of the options are
+ passed to |source edge style|.
+ \item In both of the above case, in case the options following the |>| or
+ |<| sign start with a quote, the created edge label is passed to
+ |source edge node| or |target edge node|, respectively.
- This is exactly what you want to happen.
+ This is exactly what you want to happen.
\end{enumerate}
-Additionally, the following styles provide shorthands for ``clearing''
-the target and source options:
+%
+Additionally, the following styles provide shorthands for ``clearing'' the
+target and source options:
+%
\begin{key}{/tikz/graphs/clear >}
- A more easy-to-remember shorthand for |target edge clear|.
+ A more easy-to-remember shorthand for |target edge clear|.
\end{key}
+%
\begin{key}{/tikz/graphs/clear <}
- A more easy-to-remember shorthand for |source edge clear|.
+ A more easy-to-remember shorthand for |source edge clear|.
\end{key}
-These mechanisms make it especially easy to create trees in which the
-edges are labeled in some special way:
+These mechanisms make it especially easy to create trees in which the edges are
+labeled in some special way:
+%
\begin{codeexample}[]
-\tikz
+\tikz
\graph [edge quotes={fill=white,inner sep=1pt},
grow down, branch right] {
/ -> h [>"9"] -> {
@@ -1878,10 +1919,11 @@ edges are labeled in some special way:
\subsubsection{Placing Node Texts on Incoming Edges}
-Normally, the text of a node is shown (only) inside the node. In some
-case, for instance when drawing certain kind of trees, the nodes
-themselves should not get any text, but rather the edge leading to the
-node should be labeled as in the following example:
+Normally, the text of a node is shown (only) inside the node. In some case, for
+instance when drawing certain kind of trees, the nodes themselves should not
+get any text, but rather the edge leading to the node should be labeled as in
+the following example:
+%
\begin{codeexample}[]
\tikz \graph [empty nodes]
{
@@ -1889,87 +1931,90 @@ node should be labeled as in the following example:
a [>"a"],
b [>"b"] -> {
c [>"c"],
- d [>"d"]
+ d [>"d"]
}
}
};
\end{codeexample}
-As the example shows, it is a bit cumbersome that we have to label the
-nodes and then specify the same text once more using the incoming edge
-syntax.
+%
+As the example shows, it is a bit cumbersome that we have to label the nodes
+and then specify the same text once more using the incoming edge syntax.
-For these cases, it would be better if the text of the node where not
-used with the node but, rather, be passed directly to the incoming or
-the outgoing edge. The following styles do exactly this:
+For these cases, it would be better if the text of the node where not used with
+the node but, rather, be passed directly to the incoming or the outgoing edge.
+The following styles do exactly this:
\begin{key}{/tikz/graphs/put node text on incoming edges=\opt{\meta{options}}}
- When this key is used with a node or a group, the following happens:
- \begin{enumerate}
- \item The command |target edge node={node[|\meta{options}|]{\tikzgraphnodetext}}|
- is executed. This means that all incoming edges of the node get a
- label with the text that would usually be displayed in the
- node. You can use keys like |math nodes| normally.
- \item The command |as={}| is executed. This means that the node
- itself will display nothing.
- \end{enumerate}
- Here is an example that show how this command is used.
+ When this key is used with a node or a group, the following happens:
+ %
+ \begin{enumerate}
+ \item The command
+ |target edge node={node[|\meta{options}|]{\tikzgraphnodetext}}| is
+ executed. This means that all incoming edges of the node get a
+ label with the text that would usually be displayed in the node.
+ You can use keys like |math nodes| normally.
+ \item The command |as={}| is executed. This means that the node itself
+ will display nothing.
+ \end{enumerate}
+ %
+ Here is an example that show how this command is used.
+ %
\begin{codeexample}[]
\tikz \graph [put node text on incoming edges,
math nodes, nodes={circle,draw}]
{ a -> b -> {c, d} };
\end{codeexample}
+ %
\end{key}
-\begin{key}{/tikz/graphs/put node text on outgoing
- edges=\opt{\meta{options}}}
- Works like the previous key, only with |target| replaced by |source|.
+\begin{key}{/tikz/graphs/put node text on outgoing edges=\opt{\meta{options}}}
+ Works like the previous key, only with |target| replaced by |source|.
\end{key}
-
\subsection{Graph Operators, Color Classes, and Graph Expressions}
\label{section-library-graphs-color-classes}
-\tikzname's |graph| command employs a powerful mechanism for
-adding edges between nodes and sets of nodes. To a graph theorist,
-this mechanism may be known as a \emph{graph expression}: A graph is
-specified by starting with small graphs and then applying
-\emph{operators} to them that form larger graphs and that connect and
-recolor colored subsets of the graph's node in different ways.
+\tikzname's |graph| command employs a powerful mechanism for adding edges
+between nodes and sets of nodes. To a graph theorist, this mechanism may be
+known as a \emph{graph expression}: A graph is specified by starting with small
+graphs and then applying \emph{operators} to them that form larger graphs and
+that connect and recolor colored subsets of the graph's node in different ways.
\subsubsection{Color Classes}
-
\label{section-library-graph-coloring}
-\tikzname\ keeps track of a \emph{(multi)coloring} of the graph as it
-is being constructed. This does not mean that the
-actual color of the nodes on the page will be different, rather, in
-the following we refer to ``logical'' colors in the way graph
-theoreticians do. These ``logical'' colors are only important while
-the graph is being constructed and they are ``thrown away'' at the end
-of the construction. The actual (``physical'') colors of the nodes are
-set independently of these logical colors.
+\tikzname\ keeps track of a \emph{(multi)coloring} of the graph as it is being
+constructed. This does not mean that the actual color of the nodes on the page
+will be different, rather, in the following we refer to ``logical'' colors in
+the way graph theoreticians do. These ``logical'' colors are only important
+while the graph is being constructed and they are ``thrown away'' at the end of
+the construction. The actual (``physical'') colors of the nodes are set
+independently of these logical colors.
As a graph is being constructed, each node can be part of one or more
overlapping \emph{color classes}. So, unlike what is sometimes called a
-\emph{legal coloring}, the logical colorings that \tikzname\ keeps
-track of may assign multiple colors to the same node and two nodes
-connected by an edge may well have the same color.
+\emph{legal coloring}, the logical colorings that \tikzname\ keeps track of may
+assign multiple colors to the same node and two nodes connected by an edge may
+well have the same color.
-Color classes must be declared prior to use. This is done using the
-following key:
+Color classes must be declared prior to use. This is done using the following
+key:
+%
\begin{key}{/tikz/graphs/color class=\meta{color class name}}
- This sets up a new color class called \meta{color class name}. Nodes
- and whole groups of nodes can now be colored with \meta{color class
- name}. This is done using the following keys, which become
- available inside the current scope:
- \begin{key}{/tikz/graphs/\meta{color class name}}
- This key internally uses the |operator| command to setup an
- operator that will cause all nodes of the current group to get the
- ``logical color'' \meta{color class name}. Nodes retain this color
- in all encompassing scopes, unless it is explicitly changed (see
- below) or unset (again, see below).
+ This sets up a new color class called \meta{color class name}. Nodes and
+ whole groups of nodes can now be colored with \meta{color class name}. This
+ is done using the following keys, which become
+ available inside the current scope:
+ %
+ \begin{key}{/tikz/graphs/\meta{color class name}}
+ This key internally uses the |operator| command to setup an operator
+ that will cause all nodes of the current group to get the ``logical
+ color'' \meta{color class name}. Nodes retain this color in all
+ encompassing scopes, unless it is explicitly changed (see below) or
+ unset (again, see below).
+ %
\begin{codeexample}[]
\tikz \graph [color class=red] {
[cycle=red] % causes all "logically" red nodes to be connected in
@@ -1980,6 +2025,7 @@ following key:
e
};
\end{codeexample}
+ %
\begin{codeexample}[]
\tikz \graph [color class=red, color class=green,
math nodes, clockwise, n=5] {
@@ -1988,161 +2034,177 @@ following key:
{ [green] g_1, g_2, g_3 }
};
\end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/not \meta{color class name}}
- Sets up an operator for the current scope so that all nodes in it
- loose the color \meta{color class name}. You can also use
- |!|\meta{color class name} as an alias for this key.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/not \meta{color class name}}
+ Sets up an operator for the current scope so that all nodes in it loose
+ the color \meta{color class name}. You can also use |!|\meta{color
+ class name} as an alias for this key.
+ %
\begin{codeexample}[]
\tikz \graph [color class=red, color class=green,
math nodes, clockwise, n=5] {
[complete bipartite={red}{green}]
{ [red] r_1, r_2 },
{ [green] g_1, g_2, g_3 },
- g_2 [recolor green by=red]
+ g_2 [not green]
};
\end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/recolor \meta{color class name} by=\meta{new color}}
- Causes all keys having color \meta{color class name} to get
- \meta{new color} instead. They loose having color \meta{color
- class name}, but other colors are not affected.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/recolor \meta{color class name} by=\meta{new color}}
+ Causes all keys having color \meta{color class name} to get \meta{new
+ color} instead. They loose having color \meta{color class name}, but
+ other colors are not affected.
+ %
\begin{codeexample}[]
\tikz \graph [color class=red, color class=green,
math nodes, clockwise, n=5] {
[complete bipartite={red}{green}]
{ [red] r_1, r_2 },
{ [green] g_1, g_2, g_3 },
- g_2 [not green]
+ g_2 [recolor green by=red]
};
\end{codeexample}
- \end{key}
+ \end{key}
\end{key}
The following color classes are available by default:
+%
\begin{itemize}
-\item
- Color class |all|. Every node is part of this class by default. This
- is useful to access all nodes of a (sub)graph, since you can simply
- access all nodes of this color class.
-\item
- Color classes |source| and |target|. These classes are used to
- identify nodes that lead ``into'' a group of nodes and nodes from
- which paths should ``leave'' the group. Details on how these colors
- are assigned are explained in
- Section~\ref{section-library-graphs-join}. By saying |not source| or
- |not target| with a node, you can influence how it is connected:
- \begin{codeexample}[]
-\tikz \graph { a -> { b, c, d } -> e };
+ \item Color class |all|. Every node is part of this class by default. This
+ is useful to access all nodes of a (sub)graph, since you can simply
+ access all nodes of this color class.
+ \item Color classes |source| and |target|. These classes are used to
+ identify nodes that lead ``into'' a group of nodes and nodes from which
+ paths should ``leave'' the group. Details on how these colors are
+ assigned are explained in Section~\ref{section-library-graphs-join}. By
+ saying |not source| or |not target| with a node, you can influence how
+ it is connected:
+ %
+\begin{codeexample}[]
+\tikz \graph { a -> { b, c, d } -> e };
\end{codeexample}
\begin{codeexample}[]
-\tikz \graph { a -> { b[not source], c, d[not target] } -> e };
+\tikz \graph { a -> { b[not source], c, d[not target] } -> e };
\end{codeexample}
-\item
- Color classes |source'| and |target'|. These are temporary colors
- that are also explained in
- Section~\ref{section-library-graphs-join}.
+ %
+ \item Color classes |source'| and |target'|. These are temporary colors
+ that are also explained in Section~\ref{section-library-graphs-join}.
\end{itemize}
-
\subsubsection{Graph Operators on Groups of Nodes}
-Recall that the |graph| command constructs graphs recursively from
-nested \meta{group specifications}. Each such \meta{group
- specification} describes a subset of the nodes of the final graph. A
-\emph{graph operator} is an algorithm that gets the nodes of a group
-as input and (typically) adds edges between these nodes in some
-sensible way. For instance, the |clique| operator will simply add
-edges between all nodes of the group.
+Recall that the |graph| command constructs graphs recursively from nested
+\meta{group specifications}. Each such \meta{group specification} describes a
+subset of the nodes of the final graph. A \emph{graph operator} is an algorithm
+that gets the nodes of a group as input and (typically) adds edges between
+these nodes in some sensible way. For instance, the |clique| operator will
+simply add edges between all nodes of the group.
\begin{key}{/tikz/graphs/operator=\meta{code}}
- This key has an effect in three places:
- \begin{enumerate}
- \item It can be used in the \meta{options} of a \meta{direct node specification}.
- \item It can be used in the \meta{options} of a \meta{group
- specification}.
- \item It can be used in the \meta{options} of an \meta{edge specification}.
- \end{enumerate}
- The first case is a special case of the second, since it is treated
- like a group specification containing a single node. The last case
- is more complicated and discussed in the next section.
- So, let us focus on the second case.
-
- Even though the \meta{options} of a group are given at the beginning
- of the \meta{group specification}, the \meta{code} is only executed
- when the group has been parsed completely and all its nodes have
- been identified. If you use the |operator| multiple times in the
- \meta{options}, the effect accumulates, that is, all code passed to
- the different calls of |operator| gets executed in the order it is
- encountered.
-
- The \meta{code} can do ``whatever it wants,'' but it will typically
- add edges between certain nodes. You can configure what kind of
- edges (directed, undirected, etc.) are created by using the
- following keys:
- \begin{key}{/tikz/graphs/default edge kind=\meta{value} (initially --)}
- This key stores one of the five edge kinds |--|, |<-|, |->|,
- |<->|, and |-!-|. When an operator wishes to create a new edge, it
- should typically set
+ This key has an effect in three places:
+ %
+ \begin{enumerate}
+ \item It can be used in the \meta{options} of a \meta{direct node
+ specification}.
+ \item It can be used in the \meta{options} of a \meta{group
+ specification}.
+ \item It can be used in the \meta{options} of an \meta{edge
+ specification}.
+ \end{enumerate}
+ %
+ The first case is a special case of the second, since it is treated like a
+ group specification containing a single node. The last case is more
+ complicated and discussed in the next section. So, let us focus on the
+ second case.
+
+ Even though the \meta{options} of a group are given at the beginning of the
+ \meta{group specification}, the \meta{code} is only executed when the group
+ has been parsed completely and all its nodes have been identified. If you
+ use the |operator| multiple times in the \meta{options}, the effect
+ accumulates, that is, all code passed to the different calls of |operator|
+ gets executed in the order it is encountered.
+
+ The \meta{code} can do ``whatever it wants'', but it will typically add
+ edges between certain nodes. You can configure what kind of edges
+ (directed, undirected, etc.) are created by using the following keys:
+ %
+ \begin{key}{/tikz/graphs/default edge kind=\meta{value} (initially -\/-)}
+ This key stores one of the five edge kinds |--|, |<-|, |->|, |<->|, and
+ |-!-|. When an operator wishes to create a new edge, it should
+ typically set
+ %
\begin{codeexample}[code only]
-\tikzgraphsset{new \pfkeysvalueof{/tikz/graphs/default edge kind}=...}
-\end{codeexample}
- While this key can be set explicitly, it may be more convenient to
- use the abbreviating keys listed below. Also, this key is
- automatically set to the current value of \meta{edge
- specification} when a joining operator is called, see the
- discussion of joining operators in
- Section~\ref{section-library-graphs-join}.
- \end{key}
- \begin{key}{/tikz/graphs/--}
- Sets the |default edge kind| to |--|.
-\begin{codeexample}[]
-\tikz \graph { subgraph K_n [--, n=5, clockwise, radius=6mm] };
-\end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/->}
- Sets the |default edge kind| to |->|.
-\begin{codeexample}[]
-\tikz \graph { subgraph K_n [->, n=5, clockwise, radius=6mm] };
-\end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/<-}
- Sets the |default edge kind| to |<-|.
-\begin{codeexample}[]
-\tikz \graph { subgraph K_n [<-, n=5, clockwise, radius=6mm] };
-\end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/<->}
- Sets the |default edge kind| to |<->|.
-\begin{codeexample}[]
-\tikz \graph { subgraph K_n [<->, n=5, clockwise, radius=6mm] };
-\end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/-\protect\exclamationmarktext-}
- Sets the |default edge kind| to |-!-|.
- \end{key}
-
- When the \meta{code} of an operator is executed, the following
- commands can be used to find the nodes that should be connected:
- \begin{command}{\tikzgraphforeachcolorednode\marg{color name}\marg{macro}}
- When this command is called inside \meta{code}, the following will
- happen: \tikzname\ will iterate over all nodes inside the
- just-specified group that have the color \meta{color name}. The
- order in which they are iterated over is the order in which they
- appear inside the group specification (if a node is encountered
- several times inside the specification, only the first occurrence
- counts). Then, for each node the \meta{macro} is executed with the
- node's name as the only argument.
-
- In the following example we use an operator to connect every
- node colored |all| inside the subgroup to he node |root|.
- \begin{codeexample}[]
-\def\myconnect#1{\tikzset{graphs/new ->={root}{#1}{}{}}}
+\tikzgraphsset{new \pfkeysvalueof{/tikz/graphs/default edge kind}=...}
+\end{codeexample}
+ %
+ While this key can be set explicitly, it may be more convenient to use
+ the abbreviating keys listed below. Also, this key is automatically set
+ to the current value of \meta{edge specification} when a joining
+ operator is called, see the discussion of joining operators in
+ Section~\ref{section-library-graphs-join}.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/--}
+ Sets the |default edge kind| to |--|.
+ %
+\begin{codeexample}[]
+\tikz \graph { subgraph K_n [--, n=5, clockwise, radius=6mm] };
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/->}
+ Sets the |default edge kind| to |->|.
+ %
+\begin{codeexample}[]
+\tikz \graph { subgraph K_n [->, n=5, clockwise, radius=6mm] };
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/<-}
+ Sets the |default edge kind| to |<-|.
+ %
+\begin{codeexample}[]
+\tikz \graph { subgraph K_n [<-, n=5, clockwise, radius=6mm] };
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/<->}
+ Sets the |default edge kind| to |<->|.
+ %
+\begin{codeexample}[]
+\tikz \graph { subgraph K_n [<->, n=5, clockwise, radius=6mm] };
+\end{codeexample}
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/-\protect\exclamationmarktext-}
+ Sets the |default edge kind| to |-!-|.
+ \end{key}
+
+ When the \meta{code} of an operator is executed, the following commands can
+ be used to find the nodes that should be connected:
+ %
+ \begin{command}{\tikzgraphforeachcolorednode\marg{color name}\marg{macro}}
+ When this command is called inside \meta{code}, the following will
+ happen: \tikzname\ will iterate over all nodes inside the
+ just-specified group that have the color \meta{color name}. The order
+ in which they are iterated over is the order in which they appear
+ inside the group specification (if a node is encountered several times
+ inside the specification, only the first occurrence counts). Then, for
+ each node the \meta{macro} is executed with the node's name as the only
+ argument.
+
+ In the following example we use an operator to connect every node
+ colored |all| inside the subgroup to he node |root|.
+ %
+\begin{codeexample}[]
+\def\myconnect#1{\tikzset{graphs/new ->={root}{#1}{}{}}}
\begin{tikzpicture}
\node (root) at (-1,-1) {root};
-
+
\graph {
x,
{
@@ -2151,26 +2213,26 @@ edges between all nodes of the group.
}
};
\end{tikzpicture}
- \end{codeexample}
- \end{command}
-
- \begin{command}{\tikzgraphpreparecolor\marg{color
- name}\marg{counter}\marg{prefix}}
- This command is used to ``prepare'' the nodes of a certain color
- for random access. The effect is the following: It is counted how
- many nodes there are having color \meta{color name} in the current
- group and the result is stored in \meta{counter}. Next, macros
- named \meta{prefix}|1|, \meta{prefix}|2|, and so on are defined,
- that store the names of the first, second, third, and so on node
- having the color \meta{color name}.
-
- The net effect is that after you have prepared a color, you can
- quickly iterate over them. This is especially useful when you
- iterate over several color at the same time.
-
- As an example, let us create an operator then adds a zig-zag path
- between two color classes:
- \begin{codeexample}[]
+\end{codeexample}
+ \end{command}
+
+ \begin{command}{\tikzgraphpreparecolor\marg{color name}\marg{counter}\marg{prefix}}
+ This command is used to ``prepare'' the nodes of a certain color for
+ random access. The effect is the following: It is counted how many
+ nodes there are having color \meta{color name} in the current group and
+ the result is stored in \meta{counter}. Next, macros named
+ \meta{prefix}|1|, \meta{prefix}|2|, and so on are defined, that store
+ the names of the first, second, third, and so on node having the color
+ \meta{color name}.
+
+ The net effect is that after you have prepared a color, you can quickly
+ iterate over them. This is especially useful when you iterate over
+ several color at the same time.
+
+ As an example, let us create an operator then adds a zig-zag path
+ between two color classes:
+ %
+\begin{codeexample}[]
\newcount\leftshorecount \newcount\rightshorecount
\newcount\mycount \newcount\myothercount
\def\zigzag{
@@ -2187,7 +2249,7 @@ edges between all nodes of the group.
\advance\myothercount by1\relax%
\tikzgraphsset{new <-=
{\csname left shore prefix\the\myothercount\endcsname}
- {\csname right shore prefix\the\mycount\endcsname}{}{}}
+ {\csname right shore prefix\the\mycount\endcsname}{}{}}
\ifnum\myothercount<\leftshorecount\relax
\repeat
}
@@ -2199,160 +2261,159 @@ edges between all nodes of the group.
};
\end{tikzpicture}
\end{codeexample}
- Naturally, in order to turn the above code into a usable operator,
- some more code would be needed (like default values and taking
- care of shores of different sizes).
- \end{command}
+ %
+ Naturally, in order to turn the above code into a usable operator, some
+ more code would be needed (like default values and taking care of
+ shores of different sizes).
+ \end{command}
\end{key}
-There are a number of predefined operators, like |clique| or |cycle|,
-see the reference Section~\ref{section-library-graphs-reference} for a
-complete list.
-
+There are a number of predefined operators, like |clique| or |cycle|, see the
+reference Section~\ref{section-library-graphs-reference} for a complete list.
\subsubsection{Graph Operators for Joining Groups}
\label{section-library-graphs-join}
-When you join two nodes |foo| and |bar| by the edge specification
-|->|, it is fairly obvious, what should happen: An edge from |(foo)|
-to |(bar)| should be created. However, suppose we use an edge
-specification between two node sets like |{a,b,c}| and |{d,e,f}|. In
-this case, it is not so clear which edges should be created. One might
-argue that all possible edges from any node in the first set to any node
-in the second set should be added. On the other hand, one might also
-argue that only a matching between these two sets should be
-created. Things get even more muddy when a longer chain of node sets
-are joined.
-
-Instead of fixing how edges are created between two node sets,
-\tikzname\ takes a somewhat more general, but also more complicated
-approach, which can be broken into two parts. In the following, assume
-that the following chain specification is given:
+When you join two nodes |foo| and |bar| by the edge specification |->|, it is
+fairly obvious, what should happen: An edge from |(foo)| to |(bar)| should be
+created. However, suppose we use an edge specification between two node sets
+like |{a,b,c}| and |{d,e,f}|. In this case, it is not so clear which edges
+should be created. One might argue that all possible edges from any node in the
+first set to any node in the second set should be added. On the other hand, one
+might also argue that only a matching between these two sets should be created.
+Things get even more muddy when a longer chain of node sets are joined.
+
+Instead of fixing how edges are created between two node sets, \tikzname\ takes
+a somewhat more general, but also more complicated approach, which can be
+broken into two parts. In the following, assume that the following chain
+specification is given:
+%
\begin{quote}
- \meta{spec$_1$} \meta{edge specification} \meta{spec$_2$}
+ \meta{spec$_1$} \meta{edge specification} \meta{spec$_2$}
\end{quote}
+%
An example might be |{a,b,c} -> {d, e->f}|.
\medskip
-\textbf{The source and target vertices.} Let us start with the
-question of which vertices of the first node set should be connected to
-vertices in the second node set.
-
-There are two predefined special color classes that are used for this:
-|source| and |target|. For every group specification, some vertices
-are colored as |source| vertices and some vertices are |target|
-vertices (a node can both be a target and a source). Initially, every
-vertex is both a source and a target, but that can change as we will
-see in a moment.
-
-The intuition behind source and target vertices is that, in some
-sense, edges ``from the outside'' lead into the group via the source
-vertices and lead out of the group via the target vertices. To be more
-precise, the following happens:
+\textbf{The source and target vertices.} Let us start with the question of
+which vertices of the first node set should be connected to vertices in the
+second node set.
+
+There are two predefined special color classes that are used for this: |source|
+and |target|. For every group specification, some vertices are colored as
+|source| vertices and some vertices are |target| vertices (a node can both be a
+target and a source). Initially, every vertex is both a source and a target,
+but that can change as we will see in a moment.
+
+The intuition behind source and target vertices is that, in some sense, edges
+``from the outside'' lead into the group via the source vertices and lead out
+of the group via the target vertices. To be more precise, the following
+happens:
+%
\begin{enumerate}
-\item The target vertices of the first group are connected to
- the source vertices of the second group.
-\item In the group resulting from the union of the nodes from
- \meta{spec$_1$} and \meta{spec$_2$}, the source vertices are only
- those from the first group, and the target vertices are only those
- from the second group.
+ \item The target vertices of the first group are connected to the source
+ vertices of the second group.
+ \item In the group resulting from the union of the nodes from
+ \meta{spec$_1$} and \meta{spec$_2$}, the source vertices are only those
+ from the first group, and the target vertices are only those from the
+ second group.
\end{enumerate}
Let us go over the effect of these rules for the example
-|{a,b,c} -> {d, e->f}|. First, each individual node is initially both
-a |source| and a |target| vertex. Then, in |{a,b,c}| all nodes are
-still both source and target vertices since just grouping vertices
-does not change their colors. Now, in |e->f| something interesting
-happens for the first time: the target vertices of the ``group'' |e|
-(which is just the node |e|) are connected to the source vertices of
-the ``group'' |f|. This means, that an edge is added from |e| to
-|f|. Then, in the resulting group |e->f| the only source vertex is |e|
-and the only target vertex is |f|. This implies that in the group
+|{a,b,c} -> {d, e->f}|. First, each individual node is initially both a
+|source| and a |target| vertex. Then, in |{a,b,c}| all nodes are still both
+source and target vertices since just grouping vertices does not change their
+colors. Now, in |e->f| something interesting happens for the first time: the
+target vertices of the ``group'' |e| (which is just the node |e|) are connected
+to the source vertices of the ``group'' |f|. This means, that an edge is added
+from |e| to |f|. Then, in the resulting group |e->f| the only source vertex is
+|e| and the only target vertex is |f|. This implies that in the group
|{d,e->f}| the sources are |d| and |e| and the targets are |d| and~|f|.
-Now, in |{a,b,c} -> {d,e->f}| the targets of |{a,b,c}| (which are all
-three of them) are connected to the sources of |{d,e->f}| (which are
-just |d| and~|e|). Finally, in the whole graph only |a|, |b|, and |c|
-are sources while only |d| and |f| are targets.
-
+Now, in |{a,b,c} -> {d,e->f}| the targets of |{a,b,c}| (which are all three of
+them) are connected to the sources of |{d,e->f}| (which are just |d| and~|e|).
+Finally, in the whole graph only |a|, |b|, and |c| are sources while only |d|
+and |f| are targets.
+%
\begin{codeexample}[]
-\def\hilightsource#1{\fill [green, opacity=.25] (#1) circle [radius=2mm]; }
-\def\hilighttarget#1{\fill [red, opacity=.25] (#1) circle [radius=2mm]; }
+\def\hilightsource#1{\fill [green, opacity=.25] (#1) circle [radius=2mm]; }
+\def\hilighttarget#1{\fill [red, opacity=.25] (#1) circle [radius=2mm]; }
\tikz \graph
[operator=\tikzgraphforeachcolorednode{source}{\hilightsource},
operator=\tikzgraphforeachcolorednode{target}{\hilighttarget}]
{ {a,b,c} -> {d, e->f} };
\end{codeexample}
-The next objective is to make more precise what it means that ``the
-targets of the first graph'' and the ``sources of the second graph''
-should be connected. We know already of a general way of connecting
-nodes of a graph: operators! Thus, we use an operator for this job.
-For instance, the |complete bipartite| operator adds an edge from every node
-having a certain color to every node have a certain other color. This
-is exactly what we need here: The first color is ``the color |target|
-restricted to the nodes of the first graph'' and the second color is
-``the color |source| restricted to the nodes of the second graph.''
-
-However, we cannot really specify that only nodes from a certain
-subgraph are meant -- the |operator| machinery only operates on all
-nodes of the current graph. For this reason, what really happens is
-the following: When the |graph| command encounters \meta{spec$_1$}
-\meta{edge specification} \meta{spec$_2$}, it first computes and
-colors the nodes of the first and the second specification
-independently. Then, the |target| nodes of the first graph are
-recolored to |target'| and the |source| nodes of the second graph are
-recolored to |source'|. Then, the two graphs are united into one
-graph and a \emph{joining operator} is executed, which should add
-edges between |target'| and |source'|. Once this is done,
-the colors |target'| and |source'| get erased. Note that in the
-resulting graph only the |source| nodes from the first graph are still
-|source| nodes and likewise for the |target| nodes of the second graph.
-
+The next objective is to make more precise what it means that ``the targets of
+the first graph'' and the ``sources of the second graph'' should be connected.
+We know already of a general way of connecting nodes of a graph: operators!
+Thus, we use an operator for this job. For instance, the |complete bipartite|
+operator adds an edge from every node having a certain color to every node have
+a certain other color. This is exactly what we need here: The first color is
+``the color |target| restricted to the nodes of the first graph'' and the
+second color is ``the color |source| restricted to the nodes of the second
+graph''.
+
+However, we cannot really specify that only nodes from a certain subgraph are
+meant -- the |operator| machinery only operates on all nodes of the current
+graph. For this reason, what really happens is the following: When the |graph|
+command encounters \meta{spec$_1$} \meta{edge specification} \meta{spec$_2$},
+it first computes and colors the nodes of the first and the second
+specification independently. Then, the |target| nodes of the first graph are
+recolored to |target'| and the |source| nodes of the second graph are recolored
+to |source'|. Then, the two graphs are united into one graph and a
+\emph{joining operator} is executed, which should add edges between |target'|
+and |source'|. Once this is done, the colors |target'| and |source'| get
+erased. Note that in the resulting graph only the |source| nodes from the first
+graph are still |source| nodes and likewise for the |target| nodes of the
+second graph.
\medskip
-\textbf{The joining operators.} The job of a joining operator is
-to add edges between nodes colored |target'| and |source'|. The
-following rule is used to determine which operator should be chosen
-for performing this job:
+\textbf{The joining operators.} The job of a joining operator is to add edges
+between nodes colored |target'| and |source'|. The following rule is used to
+determine which operator should be chosen for performing this job:
+%
\begin{enumerate}
-\item If the \meta{edge specification} explicitly sets the |operator|
- key to something non-empty (and also not to |\relax|), then the
- \meta{code} of this |operator| call is used.
-\item Otherwise, the current value of the following key is used:
- \begin{key}{/tikz/graphs/default edge operator=\meta{key}}
- This key stores the name of a \meta{key} that is executed for every
- \meta{edge specification} whose \meta{options} do not contain the
- |operator| key.
+ \item If the \meta{edge specification} explicitly sets the |operator| key
+ to something non-empty (and also not to |\relax|), then the \meta{code}
+ of this |operator| call is used.
+ \item Otherwise, the current value of the following key is used:
+ %
+ \begin{key}{/tikz/graphs/default edge operator=\meta{key} (initially matching and star)}
+ This key stores the name of a \meta{key} that is executed for every
+ \meta{edge specification} whose \meta{options} do not contain the
+ |operator| key.
+ %
\begin{codeexample}[]
\tikz \graph [default edge operator=matching] {
{a, b} ->[matching and star]
{c, d, e} --[complete bipartite]
- {f, g, h} --
+ {f, g, h} --
{i, j, k}
-};
+};
\end{codeexample}
- \end{key}
+ \end{key}
\end{enumerate}
A typical joining operator is |complete bipartite|. It takes the names of two
-color classes as input and adds edges from all vertices of the first
-class to all vertices of the second class. Now, the trick is that the
-default value for the |complete bipartite| key is |{target'}{source'}|. Thus,
-if you just write |->[complete bipartite]|, the same happens as if you had
-written
+color classes as input and adds edges from all vertices of the first class to
+all vertices of the second class. Now, the trick is that the default value for
+the |complete bipartite| key is |{target'}{source'}|. Thus, if you just write
+|->[complete bipartite]|, the same happens as if you had written
+%
\begin{quote}
-|->[complete bipartite={target'}{source'}]|
+ |->[complete bipartite={target'}{source'}]|
\end{quote}
-This is exactly what we want to happen. The same default values are
-also set for other joining operators like |matching| or |butterfly|.
-
-Even though an operator like |complete bipartite| is typically used
-together with an edge specification, it can also be used as a normal
-operator together with a group specification. In this case, however,
-the color classes must be named explicitly:
+%
+This is exactly what we want to happen. The same default values are also set
+for other joining operators like |matching| or |butterfly|.
+Even though an operator like |complete bipartite| is typically used together
+with an edge specification, it can also be used as a normal operator together
+with a group specification. In this case, however, the color classes must be
+named explicitly:
+%
\begin{codeexample}[]
\begin{tikzpicture}
\graph [color class=red, color class=green, math nodes]
@@ -2366,43 +2427,40 @@ the color classes must be named explicitly:
A list of predefined joining operators can be found in the reference
Section~\ref{section-library-graphs-reference}.
-The fact that joining operators can also be used as normal operators
-leads to a subtle problem: A normal operator will typically use the
-current value of |default edge kind| to decide which kind of edges
-should be put between the identified vertices, while a joining
-operator should, naturally, use the kind of edge specified by the
-\meta{edge specification}. This problem is solved as follows: Like a
-normal operator, a joining operator should also use the current value
-of |default edge kind| for the edges it produces. The trick is that
-this will automatically be set to the current \meta{edge
- specification} when the operator explicitly in the \meta{options} of
-the edge specification or implicitly in the |default edge operator|.
-
-
+The fact that joining operators can also be used as normal operators leads to a
+subtle problem: A normal operator will typically use the current value of
+|default edge kind| to decide which kind of edges should be put between the
+identified vertices, while a joining operator should, naturally, use the kind
+of edge specified by the \meta{edge specification}. This problem is solved as
+follows: Like a normal operator, a joining operator should also use the current
+value of |default edge kind| for the edges it produces. The trick is that this
+will automatically be set to the current \meta{edge specification} when the
+operator explicitly in the \meta{options} of the edge specification or
+implicitly in the |default edge operator|.
\subsection{Graph Macros}
\label{section-library-graphs-macros}
-A \emph{graph macro} is a small graph that is inserted at some point
-into the graph that is currently being constructed. There is special
-support for such graph macros in \tikzname. You might wonder why this
-is necessary -- can't one use \TeX's normal macro mechanism? The
-answer is ``no'': one cannot insert new nodes into a graph using
-normal macros because the chains, groups, and nodes are determined
-prior to macro expansion. Thus, any macro encountered where some node
-text should go will only be expanded when this node is being named and
+A \emph{graph macro} is a small graph that is inserted at some point into the
+graph that is currently being constructed. There is special support for such
+graph macros in \tikzname. You might wonder why this is necessary -- can't one
+use \TeX's normal macro mechanism? The answer is ``no'': one cannot insert new
+nodes into a graph using normal macros because the chains, groups, and nodes
+are determined prior to macro expansion. Thus, any macro encountered where some
+node text should go will only be expanded when this node is being named and
typeset.
A graph macro is declared using the following key:
\begin{key}{/tikz/graphs/declare=\marg{graph name}\marg{specification}}
- This key declares that \meta{graph name} can subsequently be used as
- a replacement for a \meta{node name}. Whenever the \meta{graph name}
- is used in the following, a graph group will be inserted instead
- whose content is exactly \meta{specification}. In case \meta{graph
- name} is used together with some \meta{options}, they are executed
- prior to inserting the \meta{specification}.
+ This key declares that \meta{graph name} can subsequently be used as a
+ replacement for a \meta{node name}. Whenever the \meta{graph name} is used
+ in the following, a graph group will be inserted instead whose content is
+ exactly \meta{specification}. In case \meta{graph name} is used together
+ with some \meta{options}, they are executed prior to inserting the
+ \meta{specification}.
+ %
\begin{codeexample}[]
\tikz \graph [branch down=4mm, declare={claw}{1 -- {2,3,4}}] {
a;
@@ -2410,19 +2468,21 @@ A graph macro is declared using the following key:
b;
};
\end{codeexample}
- In the next example, we use a key to configure a subgraph:
+ %
+ In the next example, we use a key to configure a subgraph:
+ %
\begin{codeexample}[]
\tikz \graph [ n/.code=\def\n{#1}, branch down=4mm,
declare={star}{root -- { \foreach \i in {1,...,\n} {\i} }}]
{ star [n=5]; };
\end{codeexample}
- Actually, the |n| key is already defined internally for a similar
- purpose.
+ %
+ Actually, the |n| key is already defined internally for a similar purpose.
- As a last example, let us define a somewhat more complicated graph
- macro.
+ As a last example, let us define a somewhat more complicated graph macro.
+ %
\begin{codeexample}[]
-\newcount\mycount
+\newcount\mycount
\tikzgraphsset{
levels/.store in=\tikzgraphlevel,
levels=1,
@@ -2447,11 +2507,13 @@ A graph macro is declared using the following key:
}
\tikz \graph [grow down=5mm, branch right=5mm] { bintree [levels=5] };
\end{codeexample}
+ %
\end{key}
-Note that when you use a graph macro several time inside the same
-graph, you will typically have to use the |name| option so that
-different copies of the subgraph are created:
+Note that when you use a graph macro several time inside the same graph, you
+will typically have to use the |name| option so that different copies of the
+subgraph are created:
+%
\begin{codeexample}[]
\tikz \graph [branch down=4mm, declare={claw}{1 -- {2,3,4}}] {
claw [name=left],
@@ -2460,67 +2522,71 @@ different copies of the subgraph are created:
\end{codeexample}
You will find a list of useful graph macros in the reference section,
-Section~\ref{section-library-graphs-reference-macros}.
+Section~\ref{section-library-graphs-reference-macros}.
\subsection{Online Placement Strategies}
\label{section-library-graphs-placement}
-The main job of the |graph| library is to make it easy to specify
-which nodes are present in a graph and how they are connected. In
-contrast, it is \emph{not} the primary job of the library to compute
-good positions for nodes in a graph -- use for instance a |\matrix|,
-specify good positions ``by hand'' or use the graph drawing
-facilities. Nevertheless, some basic support for automatic node
-placement is provided for simple cases. The graph library will provide
-you with information about the position of nodes inside their groups
-and chains.
-
-As a graph is being constructed, a \emph{placement strategy} is used
-to determine a (reasonably good) position for the nodes as they are
-created. These placement strategies get some information about what
-\tikzname\ has already seen concerning the already constructed nodes,
-but it gets no information concerning the upcoming nodes. Because of
-this lack of information concerning the future, the strategies need to
-be what is called an \emph{online strategy} in computer science. (The
-opposite are \emph{offline strategies}, which get information about
-the whole graph and all the sizes of the nodes in it. The graph
-drawing libraries employ such offline strategies.)
+The main job of the |graph| library is to make it easy to specify which nodes
+are present in a graph and how they are connected. In contrast, it is
+\emph{not} the primary job of the library to compute good positions for nodes
+in a graph -- use for instance a |\matrix|, specify good positions ``by hand''
+or use the graph drawing facilities. Nevertheless, some basic support for
+automatic node placement is provided for simple cases. The graph library will
+provide you with information about the position of nodes inside their groups
+and chains.
+
+As a graph is being constructed, a \emph{placement strategy} is used to
+determine a (reasonably good) position for the nodes as they are created. These
+placement strategies get some information about what \tikzname\ has already
+seen concerning the already constructed nodes, but it gets no information
+concerning the upcoming nodes. Because of this lack of information concerning
+the future, the strategies need to be what is called an \emph{online strategy}
+in computer science. (The opposite are \emph{offline strategies}, which get
+information about the whole graph and all the sizes of the nodes in it. The
+graph drawing libraries employ such offline strategies.)
Strategies are selected using keys like |no placement| or
|Cartesian placement|. It is permissible to use different strategies inside
-different parts of a graph, even though the different strategies do
-not always work together in perfect harmony.
+different parts of a graph, even though the different strategies do not always
+work together in perfect harmony.
\subsubsection{Manual Placement}
\label{section-graphs-xy}
\begin{key}{/tikz/graphs/no placement}
- This strategy simply ``switches off'' the whole placement
- mechanism, causing all nodes to be placed at the origin by
- default. You need to use this strategy if you position nodes ``by
- hand''. For this, you can use the |at| key, the |shift| keys:
+ This strategy simply ``switches off'' the whole placement mechanism,
+ causing all nodes to be placed at the origin by default. You need to use
+ this strategy if you position nodes ``by hand''. For this, you can use the
+ |at| key, the |shift| keys:
+ %
\begin{codeexample}[]
\tikz \graph [no placement]
{
a[at={(0:0)}] -> b[at={(1,0)}] -> c[yshift=1cm];
};
\end{codeexample}
- Since the syntax and the many braces and parentheses are a bit
- cumbersome, the following two keys might also be useful:
- \begin{key}{/tikz/graphs/x=\meta{x dimension}}
- When you use this key, it will have the same effect as if you had written
- |at={(|\meta{x dimension}|,|\meta{y dimension}|)}|, where \meta{y
- dimension} is a value set using the |y| key:
+ %
+ Since the syntax and the many braces and parentheses are a bit cumbersome,
+ the following two keys might also be useful:
+ %
+ \begin{key}{/tikz/graphs/x=\meta{x dimension}}
+ When you use this key, it will have the same effect as if you had
+ written |at={(|\meta{x dimension}|,|\meta{y dimension}|)}|, where
+ \meta{y dimension} is a value set using the |y| key:
+ %
\begin{codeexample}[]
\tikz \graph [no placement]
{
a[x=0,y=0] -> b[x=1,y=0] -> c[x=0,y=1];
};
\end{codeexample}
- Note that you can specify an |x| or a |y| key for a whole scope
- and then vary only the other key:
+ %
+ Note that you can specify an |x| or a |y| key for a whole scope and
+ then vary only the other key:
+ %
\begin{codeexample}[]
\tikz \graph [no placement]
{
@@ -2530,35 +2596,35 @@ not always work together in perfect harmony.
};
};
\end{codeexample}
- Note that these keys have the path |/tikz/graphs/|, so they will
- be available inside |graph|s and will not clash with the usual |x|
- and |y| keys of \tikzname, which are used to specify the basic
- lengths of vectors.
- \end{key}
- \begin{key}{/tikz/graphs/y=\meta{y dimension}}
- See above.
- \end{key}
+ %
+ Note that these keys have the path |/tikz/graphs/|, so they will be
+ available inside |graph|s and will not clash with the usual |x| and |y|
+ keys of \tikzname, which are used to specify the basic lengths of
+ vectors.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/y=\meta{y dimension}}
+ See above.
+ \end{key}
\end{key}
-
-
\subsubsection{Placement on a Grid}
\begin{key}{/tikz/graphs/Cartesian placement}
- This strategy is the default strategy. It works, roughly, as
- follows: For each new node on a chain, advance a ``logical width''
- counter and for each new node in a group, advance a ``logical
- depth'' counter. When a chain contains a whole group, then the
- ``logical width'' taken up by the group is the maximum over the
- logical widths taken up by the chains inside the group; and
- symmetrically the logical depth of a chain is the maximum of the
- depths of the groups inside it.
-
- This slightly confusing explanation is perhaps best exemplified. In
- the below example, the two numbers indicate the two logical width
- and depth of each node as computed by the |graph| library. Just
- ignore the arcane code that is used to print these numbers.
+ This strategy is the default strategy. It works, roughly, as follows: For
+ each new node on a chain, advance a ``logical width'' counter and for each
+ new node in a group, advance a ``logical depth'' counter. When a chain
+ contains a whole group, then the ``logical width'' taken up by the group is
+ the maximum over the logical widths taken up by the chains inside the
+ group; and symmetrically the logical depth of a chain is the maximum of the
+ depths of the groups inside it.
+
+ This slightly confusing explanation is perhaps best exemplified. In the
+ below example, the two numbers indicate the two logical width and depth of
+ each node as computed by the |graph| library. Just ignore the arcane code
+ that is used to print these numbers.
+ %
\begin{codeexample}[]
\tikz
\graph [nodes={align=center, inner sep=1pt}, grow right=7mm,
@@ -2576,17 +2642,20 @@ not always work together in perfect harmony.
} -> j,
k -> l
};
-\end{codeexample}
- You will find a detailed description of how these logical units are
- computed, exactly, in Section~\ref{section-library-graphs-new-online}.
-
- Now, even though we talk about ``widths'' and ``depths'' and even
- though by default a graph ``grows'' to the right and down, this is
- by no means fixed. Instead, you can use the following keys to change
- how widths and heights are interpreted:
- \begin{key}{/tikz/graphs/chain shift=\meta{coordinate} (initially {(1,0)})}
- Under the regime of the |Cartesian placement| strategy, each node is
- shifted by the current logical width times this \meta{coordinate}.
+\end{codeexample}
+ %
+ You will find a detailed description of how these logical units are
+ computed, exactly, in Section~\ref{section-library-graphs-new-online}.
+
+ Now, even though we talk about ``widths'' and ``depths'' and even though by
+ default a graph ``grows'' to the right and down, this is by no means fixed.
+ Instead, you can use the following keys to change how widths and heights
+ are interpreted:
+ %
+ \begin{key}{/tikz/graphs/chain shift=\meta{coordinate} (initially {(1,0)})}
+ Under the regime of the |Cartesian placement| strategy, each node is
+ shifted by the current logical width times this \meta{coordinate}.
+ %
\begin{codeexample}[]
\tikz \graph [chain shift=(45:1)] {
a -> b -> c;
@@ -2594,10 +2663,12 @@ not always work together in perfect harmony.
f -> g -> h;
};
\end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/group shift=\meta{coordinate} (initially {(0,-1)})}
- Like for |chain shift|, each node is shifted by the current
- logical depth times this \meta{coordinate}.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/group shift=\meta{coordinate} (initially {(0,-1)})}
+ Like for |chain shift|, each node is shifted by the current logical
+ depth times this \meta{coordinate}.
+ %
\begin{codeexample}[]
\tikz \graph [chain shift=(45:7mm), group shift=(-45:7mm)] {
a -> b -> c;
@@ -2605,152 +2676,183 @@ not always work together in perfect harmony.
f -> g -> h;
};
\end{codeexample}
- \end{key}
+ \end{key}
\end{key}
-
\begin{key}{/tikz/graphs/grow up=\meta{distance} (default 1)}
- Sets the |chain shift| to |(|\meta{distance}|,0)|, so that chains
- ``grow upward.'' The distance by which the center of each new
- element is removed from the center of the previous one is
- \meta{distance}.
+ Sets the |chain shift| to |(|\meta{distance}|,0)|, so that chains ``grow
+ upward''. The distance by which the center of each new element is removed
+ from the center of the previous one is \meta{distance}.
+ %
\begin{codeexample}[]
-\tikz \graph [grow up=7mm] { a -> b -> c};
+\tikz \graph [grow up=7mm] { a -> b -> c};
\end{codeexample}
+ %
\end{key}
+
\begin{key}{/tikz/graphs/grow down=\meta{distance} (default 1)}
- Like |grow up|.
+ Like |grow up|.
+ %
\begin{codeexample}[]
-\tikz \graph [grow down=7mm] { a -> b -> c};
+\tikz \graph [grow down=7mm] { a -> b -> c};
\end{codeexample}
+ %
\end{key}
+
\begin{key}{/tikz/graphs/grow left=\meta{distance} (default 1)}
- Like |grow up|.
+ Like |grow up|.
+ %
\begin{codeexample}[]
-\tikz \graph [grow left=7mm] { a -> b -> c};
+\tikz \graph [grow left=7mm] { a -> b -> c};
\end{codeexample}
+ %
\end{key}
+
\begin{key}{/tikz/graphs/grow right=\meta{distance} (default 1)}
- Like |grow up|.
+ Like |grow up|.
+ %
\begin{codeexample}[]
-\tikz \graph [grow right=7mm] { a -> b -> c};
+\tikz \graph [grow right=7mm] { a -> b -> c};
\end{codeexample}
+ %
\end{key}
+
\begin{key}{/tikz/graphs/branch up=\meta{distance} (default 1)}
- Sets the |group shift| so that groups ``branch upward.'' The
- distance by which the center of each new element is removed from
- the center of the previous one is \meta{distance}.
+ Sets the |group shift| so that groups ``branch upward''. The distance by
+ which the center of each new element is removed from the center of the
+ previous one is \meta{distance}.
+ %
\begin{codeexample}[]
-\tikz \graph [branch up=7mm] { a -> b -> {c, d, e} };
+\tikz \graph [branch up=7mm] { a -> b -> {c, d, e} };
\end{codeexample}
- Note that when you draw a tree, the |branch ...| keys specify how
- siblings (or adjacent branches) are arranged, while the |grow ...|
- keys specify in which direction the branches ``grow''.
+ %
+ Note that when you draw a tree, the |branch ...| keys specify how siblings
+ (or adjacent branches) are arranged, while the |grow ...| keys specify in
+ which direction the branches ``grow''.
\end{key}
+
\begin{key}{/tikz/graphs/branch down=\meta{distance} (default 1)}
+%
\begin{codeexample}[]
-\tikz \graph [branch down=7mm] { a -> b -> {c, d, e}};
+\tikz \graph [branch down=7mm] { a -> b -> {c, d, e}};
\end{codeexample}
+%
\end{key}
+
\begin{key}{/tikz/graphs/branch left=\meta{distance} (default 1)}
+%
\begin{codeexample}[]
-\tikz \graph [branch left=7mm, grow down=7mm] { a -> b -> {c, d, e}};
+\tikz \graph [branch left=7mm, grow down=7mm] { a -> b -> {c, d, e}};
\end{codeexample}
+%
\end{key}
+
\begin{key}{/tikz/graphs/branch right=\meta{distance} (default 1)}
+%
\begin{codeexample}[]
-\tikz \graph [branch right=7mm, grow down=7mm] { a -> b -> {c, d, e}};
+\tikz \graph [branch right=7mm, grow down=7mm] { a -> b -> {c, d, e}};
\end{codeexample}
+%
\end{key}
-The following keys place nodes in a $N\times M$ grid.
+The following keys place nodes in a $N\times M$ grid.
+%
\begin{key}{/tikz/graphs/grid placement}
- This key works similar to |Cartesian placement|. As for that placement
- strategy, a node has logical width and depth 1. However, the computed
- total width and depth are mapped to a $N\times M$ grid.
- The values of $N$ and $M$ depend on the size of the graph and the
- value of |wrap after|. The number of columns $M$ is either set to
- |wrap after| explicitly or computed automatically as
- $\sqrt{\verb!|V|!}$. $N$ is the number of rows needed to lay out the
- graph in a grid with $M$ columns.
+ This key works similar to |Cartesian placement|. As for that placement
+ strategy, a node has logical width and depth 1. However, the computed total
+ width and depth are mapped to a $N\times M$ grid. The values of $N$ and $M$
+ depend on the size of the graph and the value of |wrap after|. The number
+ of columns $M$ is either set to |wrap after| explicitly or computed
+ automatically as $\sqrt{\verb!|V|!}$. $N$ is the number of rows needed to
+ lay out the graph in a grid with $M$ columns.
+ %
\begin{codeexample}[]
% An example with 6 nodes, 3 columns and therefor 2 rows
\tikz \graph [grid placement] { subgraph I_n[n=6, wrap after=3] };
\end{codeexample}
+ %
\begin{codeexample}[]
% An example with 9 nodes with columns and rows computed automatically
\tikz \graph [grid placement] { subgraph Grid_n [n=9] };
\end{codeexample}
+ %
\begin{codeexample}[]
% Directions can be changed
\tikz \graph [grid placement, branch up, grow left] { subgraph Grid_n [n=9] };
\end{codeexample}
- In case a user-defined graph instead of a pre-defined
- |subgraph| is to be layed out using |grid placement|, |n| has to be
- specified explicitly:
+ %
+ In case a user-defined graph instead of a pre-defined |subgraph| is to be
+ laid out using |grid placement|, |n| has to be specified explicitly:
+ %
\begin{codeexample}[]
-\tikz \graph [grid placement] {
- [n=6, wrap after=3]
- a -- b -- c -- d -- e -- f
+\tikz \graph [grid placement] {
+ [n=6, wrap after=3]
+ a -- b -- c -- d -- e -- f
};
\end{codeexample}
+ %
\end{key}
-
\subsubsection{Placement Taking Node Sizes Into Account}
Options like |grow up| or |branch right| do not take the sizes of the
-to-be-positioned nodes into account -- all nodes are placed quite
-``dumbly'' at grid positions. It turns out that the
-|Cartesian placement| can also be used to place notes in such a way
-that their height and/or width is taken into account. Note, however,
-that while the following options may yield an adequate placement in
-many situations, when you need advanced alignments you should use a
-|matrix| or advanced offline strategies to place the nodes.
-
+to-be-positioned nodes into account -- all nodes are placed quite ``dumbly'' at
+grid positions. It turns out that the |Cartesian placement| can also be used to
+place notes in such a way that their height and/or width is taken into account.
+Note, however, that while the following options may yield an adequate placement
+in many situations, when you need advanced alignments you should use a |matrix|
+or advanced offline strategies to place the nodes.
\begin{key}{/tikz/graphs/grow right sep=\meta{distance} (default 1em)}
- This key has several effects, but let us start with the bottom line:
- Nodes along a chain are placed in such a way that the left end of a
- new node is \meta{distance} from the right end of the previous node:
+ This key has several effects, but let us start with the bottom line: Nodes
+ along a chain are placed in such a way that the left end of a new node is
+ \meta{distance} from the right end of the previous node:
+ %
\begin{codeexample}[]
\tikz \graph [grow right sep, left anchor=east, right anchor=west] {
start -- {
long text -- {short, very long text} -- more text,
long -- longer -- longest
} -- end
-};
+};
\end{codeexample}
- What happens internally is the following: First, the |anchor| of the
- nodes is set to |west| (or |north west| or |south west|, see
- below). Second, the logical width of a node is no
- longer |1|, but set to the actual width of the node (which we define
- as the horizontal difference between the |west| anchor and the
- |east| anchor) in points. Third, the |chain shift| is set to
- |(1pt,0pt)|.
+ %
+ What happens internally is the following: First, the |anchor| of the nodes
+ is set to |west| (or |north west| or |south west|, see below). Second, the
+ logical width of a node is no longer |1|, but set to the actual width of
+ the node (which we define as the horizontal difference between the |west|
+ anchor and the |east| anchor) in points. Third, the |chain shift| is set to
+ |(1pt,0pt)|.
\end{key}
+
\begin{key}{/tikz/graphs/grow left sep=\meta{distance} (default 1em)}
+%
\begin{codeexample}[]
-\tikz \graph [grow left sep] { long -- longer -- longest };
+\tikz \graph [grow left sep] { long -- longer -- longest };
\end{codeexample}
+%
\end{key}
+
\begin{key}{/tikz/graphs/grow up sep=\meta{distance} (default 1em)}
\begin{codeexample}[]
\tikz \graph [grow up sep] {
a / $a=x$ --
b / {$b=\displaystyle \int_0^1 x dx$} --
c [draw, circle, inner sep=7mm]
-};
+};
\end{codeexample}
+%
\end{key}
+
\begin{key}{/tikz/graphs/grow down sep=\meta{distance} (default 1em)}
- As above.
+ As above.
\end{key}
\begin{key}{/tikz/graphs/branch right sep=\meta{distance} (default 1em)}
- This key works like |grow right sep|, only it affects groups rather
- than chains.
+ This key works like |grow right sep|, only it affects groups rather than
+ chains.
+ %
\begin{codeexample}[]
\tikz \graph [grow down, branch right sep] {
start -- {
@@ -2758,14 +2860,15 @@ many situations, when you need advanced alignments you should use a
long -- longer -- longest,
some text -- a -- b
} -- end
-};
+};
\end{codeexample}
- When both this key and, say, |grow down sep| are set, instead of the
- |west| anchor, the |north west| anchor will be selected
- automatically.
+ %
+ When both this key and, say, |grow down sep| are set, instead of the |west|
+ anchor, the |north west| anchor will be selected automatically.
\end{key}
\begin{key}{/tikz/graphs/branch left sep=\meta{distance} (default 1em)}
+%
\begin{codeexample}[]
\tikz \graph [grow down sep, branch left sep] {
start -- {
@@ -2773,37 +2876,40 @@ many situations, when you need advanced alignments you should use a
long -- longer,
some text -- a -- b
} -- end
-};
+};
\end{codeexample}
+%
\end{key}
\begin{key}{/tikz/graphs/branch up sep=\meta{distance} (default 1em)}
+%
\begin{codeexample}[]
-\tikz \graph [branch up sep] { a, b, c[draw, circle, inner sep=7mm] };
+\tikz \graph [branch up sep] { a, b, c[draw, circle, inner sep=7mm] };
\end{codeexample}
+%
\end{key}
\begin{key}{/tikz/graphs/branch down sep=\meta{distance} (default 1em)}
\end{key}
-
\subsubsection{Placement On a Circle}
-The following keys place nodes on circles. Note that, typically, you
-do not use |circular placement| directly, but rather use one of the
-two keys |clockwise| or |counterclockwise|.
+The following keys place nodes on circles. Note that, typically, you do not use
+|circular placement| directly, but rather use one of the two keys |clockwise|
+or |counterclockwise|.
\begin{key}{/tikz/graphs/circular placement}
- This key works quite similar to |Cartesian placement|. As for that
- placement strategy, a node has logical width and depth |1|. However,
- the computed total width and depth are mapped to polar coordinates
- rather than Cartesian coordinates.
-
- \begin{key}{/tikz/graphs/chain polar shift=|(|\meta{angle}|:|\meta{radius}|)| (initially {(0:1)})}
- Under the regime of the |circular placement| strategy, each node
- on a chain is shifted by |(|\meta{logical
- width}\meta{angle}|:|\meta{logical width}\meta{angle}|)|.
+ This key works quite similar to |Cartesian placement|. As for that
+ placement strategy, a node has logical width and depth |1|. However, the
+ computed total width and depth are mapped to polar coordinates rather than
+ Cartesian coordinates.
+
+ \begin{key}{/tikz/graphs/chain polar shift=|(|\meta{angle}|:|\meta{radius}|)| (initially {(0:1)})}
+ Under the regime of the |circular placement| strategy, each node on a
+ chain is shifted by
+ |(|\meta{logical width}\meta{angle}|:|\meta{logical width}\meta{angle}|)|.
+ %
\begin{codeexample}[]
\tikz \graph [circular placement] {
a -> b -> c;
@@ -2811,11 +2917,13 @@ two keys |clockwise| or |counterclockwise|.
f -> g -> h;
};
\end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/group polar shift=|(|\meta{angle}|:|\meta{radius}|)| (initially {(45:0)})}
- Like for |group shift|, each node
- on a chain is shifted by |(|\meta{logical
- depth}\meta{angle}|:|\meta{logical depth}\meta{angle}|)|.
+ %
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/group polar shift=|(|\meta{angle}|:|\meta{radius}|)| (initially {(45:0)})}
+ Like for |group shift|, each node on a chain is shifted by
+ |(|\meta{logical depth}\meta{angle}|:|\meta{logical depth}\meta{angle}|)|.
+ %
\begin{codeexample}[]
\tikz \graph [circular placement, group polar shift=(30:0)] {
a -> b -> c;
@@ -2823,6 +2931,7 @@ two keys |clockwise| or |counterclockwise|.
f -> g -> h;
};
\end{codeexample}
+ %
\begin{codeexample}[]
\tikz \graph [circular placement,
chain polar shift=(30:0),
@@ -2832,67 +2941,75 @@ two keys |clockwise| or |counterclockwise|.
f -- g -- h;
};
\end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/radius=\meta{dimension} (initially 1cm)}
- This is an initial value that is added to the total computed
- radius when the polar shift of a node has been
- calculated. Essentially, this key allows you to set the
- \meta{radius} of the innermost circle.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/radius=\meta{dimension} (initially 1cm)}
+ This is an initial value that is added to the total computed radius
+ when the polar shift of a node has been calculated. Essentially, this
+ key allows you to set the \meta{radius} of the innermost circle.
+ %
\begin{codeexample}[]
\tikz \graph [circular placement, radius=5mm] { a, b, c, d };
\end{codeexample}
+ %
\begin{codeexample}[]
\tikz \graph [circular placement, radius=1cm] { a, b, c, d };
\end{codeexample}
- \end{key}
- \begin{key}{/tikz/graphs/phase=\meta{angle} (initially 90)}
- This is an initial value that is added to the total computed
- angle when the polar shift of a node has been
- calculated.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/phase=\meta{angle} (initially 90)}
+ This is an initial value that is added to the total computed angle when
+ the polar shift of a node has been calculated.
+ %
\begin{codeexample}[]
\tikz \graph [circular placement] { a, b, c, d };
\end{codeexample}
+ %
\begin{codeexample}[]
\tikz \graph [circular placement, phase=0] { a, b, c, d };
\end{codeexample}
- \end{key}
+ \end{key}
\end{key}
\label{key-graphs-clockwise}%
\begin{key}{/tikz/graphs/clockwise=\meta{number} (default \string\tikzgraphVnum)}
- This key sets the |group shift| so that if there are exactly
- \meta{number} many nodes in a group, they will form a complete
- circle. If you do not provide a \meta{number}, the current value of
- |\tikzgraphVnum| is used, which is exactly what you want when you
- use predefined graph macros like |subgraph K_n|.
+ This key sets the |group shift| so that if there are exactly \meta{number}
+ many nodes in a group, they will form a complete circle. If you do not
+ provide a \meta{number}, the current value of |\tikzgraphVnum| is used,
+ which is exactly what you want when you use predefined graph macros like
+ |subgraph K_n|.
+ %
\begin{codeexample}[]
\tikz \graph [clockwise=4] { a, b, c, d };
\end{codeexample}
+ %
\begin{codeexample}[]
\tikz \graph [clockwise] { subgraph K_n [n=5] };
\end{codeexample}
+ %
\end{key}
\label{key-graphs-counterclockwise}%
\begin{key}{/tikz/graphs/counterclockwise=\meta{number} (default \string\tikzgraphVnum)}
- Works like |clockwise|, only the direction is inverted.
+ Works like |clockwise|, only the direction is inverted.
\end{key}
\subsubsection{Levels and Level Styles}
-As a graph is being parsed, the |graph| command keeps track of a
-parameter called the \emph{level} of a node. Provided that the graph
-is actually constructed in a tree-like manner, the level is exactly
-equal to the level of the node inside this tree.
+As a graph is being parsed, the |graph| command keeps track of a parameter
+called the \emph{level} of a node. Provided that the graph is actually
+constructed in a tree-like manner, the level is exactly equal to the level of
+the node inside this tree.
\begin{key}{/tikz/graphs/placement/level}
- This key stores a number that is increased for each element on a
- chain, but gets reset at the end of a group:
+ This key stores a number that is increased for each element on a chain, but
+ gets reset at the end of a group:
+ %
\begin{codeexample}[]
\tikz \graph [ branch down=5mm, typeset=
\tikzgraphnodetext:\pgfkeysvalueof{/tikz/graphs/placement/level}]
-{
+{
a -> {
b,
c -> {
@@ -2904,30 +3021,31 @@ equal to the level of the node inside this tree.
}
};
\end{codeexample}
- Unlike the parameters |depth| and |width| described in the next
- section, the key |level| is always available.
+ %
+ Unlike the parameters |depth| and |width| described in the next section,
+ the key |level| is always available.
\end{key}
-In addition to keeping track of the value of the |level| key, the
-|graph| command also executes the following keys whenever it creates a
-node:
+In addition to keeping track of the value of the |level| key, the |graph|
+command also executes the following keys whenever it creates a node:
\begin{stylekey}{/tikz/graph/level=\meta{level}}
- This key gets executed for each newly created node with \meta{level}
- set to the current level of the node. You can use this key to, say,
- reconfigure the node distance or the node color.
+ This key gets executed for each newly created node with \meta{level} set to
+ the current level of the node. You can use this key to, say, reconfigure
+ the node distance or the node color.
\end{stylekey}
\begin{stylekey}{/tikz/graph/level \meta{level}}
- This key also gets executed for each newly created node with
- \meta{level} set to the current level of the node.
+ This key also gets executed for each newly created node with \meta{level}
+ set to the current level of the node.
+ %
\begin{codeexample}[]
\tikz \graph [
branch down=5mm,
level 1/.style={nodes=red},
level 2/.style={nodes=green!50!black},
level 3/.style={nodes=blue}]
-{
+{
a -> {
b,
c -> {
@@ -2939,13 +3057,14 @@ node:
}
};
\end{codeexample}
+ %
\begin{codeexample}[]
\tikz \graph [
branch down=5mm,
level 1/.style={grow right=2cm},
level 2/.style={grow right=1cm},
level 3/.style={grow right=5mm}]
-{
+{
a -> {
b,
c -> {
@@ -2957,26 +3076,26 @@ node:
}
};
\end{codeexample}
+ %
\end{stylekey}
-
\subsubsection{Defining New Online Placement Strategies}
-
\label{section-library-graphs-new-online}
-In the following the details of how to define a new placement strategy
-are explained. Most readers may wish to skip this section.
+In the following the details of how to define a new placement strategy are
+explained. Most readers may wish to skip this section.
-As a graph specification is being parsed, the |graph| library will keep
-track of different numbers that identify the positions of the
-nodes. Let us start with what happens on a chain. First, the following
-counter is increased for each element of the chain:
+As a graph specification is being parsed, the |graph| library will keep track
+of different numbers that identify the positions of the nodes. Let us start
+with what happens on a chain. First, the following counter is increased for
+each element of the chain:
+%
\begin{key}{/tikz/graphs/placement/element count}
- This key stores a number that tells us the position of the node on
- the current chain. However, you only have access to this value
- inside the code passed to the macro |compute position|, explained
- later on.
+ This key stores a number that tells us the position of the node on the
+ current chain. However, you only have access to this value inside the code
+ passed to the macro |compute position|, explained later on.
+ %
\begin{codeexample}[]
\tikz \graph [
grow right sep, typeset=\tikzgraphnodetext:\mynum,
@@ -2987,39 +3106,42 @@ counter is increased for each element of the chain:
d -> {e, f->h} -> j
};
\end{codeexample}
- As can be seen, each group resets the element counter.
+ %
+ As can be seen, each group resets the element counter.
\end{key}
-The second value that is computed is more complicated to explain, but
-it also gives more interesting information:
+The second value that is computed is more complicated to explain, but it also
+gives more interesting information:
+%
\begin{key}{/tikz/graphs/placement/width}
- This key stores the ``logical width'' of the nodes parsed up to now
- in the current group or chain (more precisely, parsed since the last
- call of |place| in an enclosing group). This is not necessarily the
- ``total physical width'' of the nodes, but rather a number
- representing how ``big'' the elements prior to the current element
- were. This \emph{may} be their width, but it may also be their
- height or even their number (which, incidentally, is the default).
- You can use the |width| to perform shifts or rotations of
- to-be-created nodes (to be explained later).
-
- The logical width is defined recursively as follows. First, the
- width of a single node is computed by calling the following key:
- \begin{key}{/tikz/graphs/placement/logical node width=\meta{full
- node name}}
- This key is called to compute a physical or logical width of the
- node \meta{full node name}. You can change the code of this
- key. The code should return the computed value in the macro
- |\pgfmathresult|. By default, this key returns |1|.
- \end{key}
- The width of a chain is the sum of the widths of its elements. The
- width of a group is the maximum of the widths of its elements.
-
- To get a feeling what the above rules imply in practice, let us
- first have a look at an example where each node has logical width
- and height |1| (which is the default). The arcane options at the
- beginning of the code just setup things so that the computed width
- and depth of each node is displayed at the bottom of each node.
+ This key stores the ``logical width'' of the nodes parsed up to now in the
+ current group or chain (more precisely, parsed since the last call of
+ |place| in an enclosing group). This is not necessarily the ``total
+ physical width'' of the nodes, but rather a number representing how ``big''
+ the elements prior to the current element were. This \emph{may} be their
+ width, but it may also be their height or even their number (which,
+ incidentally, is the default). You can use the |width| to perform shifts or
+ rotations of to-be-created nodes (to be explained later).
+
+ The logical width is defined recursively as follows. First, the width of a
+ single node is computed by calling the following key:
+ %
+ \begin{key}{/tikz/graphs/placement/logical node width=\meta{full node name}}
+ This key is called to compute a physical or logical width of the node
+ \meta{full node name}. You can change the code of this key. The code
+ should return the computed value in the macro |\pgfmathresult|. By
+ default, this key returns |1|.
+ \end{key}
+ %
+ The width of a chain is the sum of the widths of its elements. The width of
+ a group is the maximum of the widths of its elements.
+
+ To get a feeling what the above rules imply in practice, let us first have
+ a look at an example where each node has logical width and height |1|
+ (which is the default). The arcane options at the beginning of the code
+ just setup things so that the computed width and depth of each node is
+ displayed at the bottom of each node.
+ %
\begin{codeexample}[]
\tikz
\graph [nodes={align=center, inner sep=1pt}, grow right=7mm,
@@ -3038,11 +3160,12 @@ it also gives more interesting information:
k -> l
};
\end{codeexample}
- In the next example the ``logical'' width and depth actually match
- the ``physical'' width and height. This is caused by the
- |grow right sep| option, which internally sets the
- |logical node width| key so that it returns the width of its
- parameter in points.
+ %
+ In the next example the ``logical'' width and depth actually match the
+ ``physical'' width and height. This is caused by the |grow right sep|
+ option, which internally sets the |logical node width| key so that it
+ returns the width of its parameter in points.
+ %
\begin{codeexample}[]
\tikz
\graph [grow right sep, branch down sep, nodes={align=left, inner sep=1pt},
@@ -3059,15 +3182,18 @@ it also gives more interesting information:
} -> j,
k -> l
};
-\end{codeexample}
+\end{codeexample}
+ %
\end{key}
Symmetrically to chains, as a group is being constructed, counters are
-available for the number of chains encountered so far in the current
-group and for the logical depth of the current group:
+available for the number of chains encountered so far in the current group and
+for the logical depth of the current group:
+%
\begin{key}{/tikz/graphs/placement/element count}
- This key stores a number that tells us the sequence number of the
- chain in the current group.
+ This key stores a number that tells us the sequence number of the
+ chain in the current group.
+ %
\begin{codeexample}[]
\tikz \graph [
grow right sep, branch down=5mm, typeset=\tikzgraphnodetext:\mynum,
@@ -3079,50 +3205,49 @@ group and for the logical depth of the current group:
g -> h
};
\end{codeexample}
+ %
\end{key}
\begin{key}{/tikz/graphs/placement/depth}
- Similarly to the |width| key, this key stores the ``logical depth''
- of the nodes parsed up to now in the current group or chain and, also
- similarly, this key may or may not be related to the actual
- depth/height of the current node.
- As for the |width|, the exact definition is as follows: For a single
- node, the depth is computed by the following key:
- \begin{key}{/tikz/graphs/placement/logical node depth=\meta{full
- node name}}
- The code behind this key should return the ``logical height'' of
- the node \meta{full node name} in the macro |\pgfmathresult|.
- \end{key}
- Second, the depth of a group is the sum of the depths of its
- elements. Third, the depth of a chain is the maximum of the depth of
- its elements.
-\end{key}
-
-The |width|, |depth|, |element count|, and |chain count| keys get
-updated automatically, but do not have an effect by themselves. This
-is to the following two keys:
+ Similarly to the |width| key, this key stores the ``logical depth'' of the
+ nodes parsed up to now in the current group or chain and, also similarly,
+ this key may or may not be related to the actual depth/height of the
+ current node. As for the |width|, the exact definition is as follows: For a
+ single node, the depth is computed by the following key:
+ %
+ \begin{key}{/tikz/graphs/placement/logical node depth=\meta{full node name}}
+ The code behind this key should return the ``logical height'' of the
+ node \meta{full node name} in the macro |\pgfmathresult|.
+ \end{key}
+ %
+ Second, the depth of a group is the sum of the depths of its elements.
+ Third, the depth of a chain is the maximum of the depth of its elements.
+\end{key}
+
+The |width|, |depth|, |element count|, and |chain count| keys get updated
+automatically, but do not have an effect by themselves. This is to the
+following two keys:
\begin{key}{/tikz/graphs/placement/compute position=\meta{code}}
- The \meta{code} is called by the |graph| command just prior to
- creating a new node (the exact moment when this key is called is
- detailed in the description of the |place| key). When the
- \meta{code} is called, all of the keys described above will hold
- numbers computed in the way described above.
-
- The job of the \meta{code} is to setup node options appropriately so
- that the to-be-created node will be placed correctly. Thus, the
- \meta{code} should typically set the key
- |nodes={shift=|\meta{coordinate}|}| where \meta{coordinate} is the
- computed position for the node. The \meta{code} could
- also set other options like, say, the color of a node depending on
- its depth.
-
- The following example appends some code to the standard code of
- |compute position| so that ``deeper'' nodes of a tree are
- lighter. (Naturally, the same effect could be achieved much more
- easily using the |level| key.)
-\begin{codeexample}[]
-\newcount\mycount
+ The \meta{code} is called by the |graph| command just prior to creating a
+ new node (the exact moment when this key is called is detailed in the
+ description of the |place| key). When the \meta{code} is called, all of the
+ keys described above will hold numbers computed in the way described above.
+
+ The job of the \meta{code} is to setup node options appropriately so that
+ the to-be-created node will be placed correctly. Thus, the \meta{code}
+ should typically set the key |nodes={shift=|\meta{coordinate}|}| where
+ \meta{coordinate} is the computed position for the node. The \meta{code}
+ could also set other options like, say, the color of a node depending on
+ its depth.
+
+ The following example appends some code to the standard code of
+ |compute position| so that ``deeper'' nodes of a tree are lighter.
+ (Naturally, the same effect could be achieved much more easily using the
+ |level| key.)
+ %
+\begin{codeexample}[]
+\newcount\mycount
\def\lightendeepernodes{
\pgfmathsetcount{\mycount}{
100-20*\pgfkeysvalueof{/tikz/graphs/placement/width}
@@ -3143,103 +3268,109 @@ is to the following two keys:
}
};
\end{codeexample}
+ %
\end{key}
\begin{key}{/tikz/graphs/placement/place}
- Executing this key has two effects: First, the key
- |compute position| is called to compute a good
- position for future nodes (usually, these ``future nodes'' are just
- a single node that is created immediately). Second, all of the above
- counters like |depth| or |width| are reset (but not |level|).
+ Executing this key has two effects: First, the key |compute position| is
+ called to compute a good position for future nodes (usually, these ``future
+ nodes'' are just a single node that is created immediately). Second, all of
+ the above counters like |depth| or |width| are reset (but not |level|).
- There are two places where this key is sensibly called: First, just
- prior to creating a node, which happens automatically. Second, when
- you change the online strategy. In this case, the computed width and
- depth values from one strategy typically make no sense in the other
- strategy, which is why the new strategy should proceed ``from a
- fresh start.'' In this case, the implicit call of |compute position|
- ensures that the new strategy gets the last place the old strategy
- would have used as its starting point, while the computation of its
- positions is now relative to this new starting point.
+ There are two places where this key is sensibly called: First, just prior
+ to creating a node, which happens automatically. Second, when you change
+ the online strategy. In this case, the computed width and depth values from
+ one strategy typically make no sense in the other strategy, which is why
+ the new strategy should proceed ``from a fresh start''. In this case, the
+ implicit call of |compute position| ensures that the new strategy gets the
+ last place the old strategy would have used as its starting point, while
+ the computation of its positions is now relative to this new starting
+ point.
- For these reasons, when an online strategy like
- |Cartesian placement| is called, this key gets called
- implicitly. You will rarely need to call this key directly, except
- when you define a new online strategy.
+ For these reasons, when an online strategy like |Cartesian placement| is
+ called, this key gets called implicitly. You will rarely need to call this
+ key directly, except when you define a new online strategy.
\end{key}
-
\subsection{Reference: Predefined Elements}
-
\label{section-library-graphs-reference}
-
\subsubsection{Graph Macros}
\label{section-library-graphs-reference-macros}
-\begin{tikzlibrary}{graph.standard}
- This library defines a number of graph macros that are often used in
- the literature. When new graphs are added to this collection, they
- will follow the definitions in the Mathematica program, see
- |mathworld.wolfram.com/topics/SimpleGraphs.html|.
+\begin{tikzlibrary}{graphs.standard}
+ This library defines a number of graph macros that are often used in the
+ literature. When new graphs are added to this collection, they will follow
+ the definitions in the Mathematica program, see
+ \url{mathworld.wolfram.com/topics/SimpleGraphs.html}.
\end{tikzlibrary}
-
\begin{graph}{subgraph I\_n}
- This graph consists just of $n$ unconnected vertices. The following
- key is used to specify the set of these vertices:
- \begin{key}{/tikz/graphs/V=\marg{list of vertices}}
- Sets a list of vertex names for use with graphs like
- |subgraph I_n| and also other graphs. This list is available in
- the macro |\tikzgraphV|. The number of elements of this list is
- available in |\tikzgraphVnum|.
- \end{key}
- \begin{key}{/tikz/graphs/n=\meta{number}}
- This is an abbreviation for
- |V={1,...,|\meta{number}|}, name shore V={name=V}|.
- \end{key}
+ This graph consists just of $n$ unconnected vertices. The following key is
+ used to specify the set of these vertices:
+ %
+ \begin{key}{/tikz/graphs/V=\marg{list of vertices}}
+ Sets a list of vertex names for use with graphs like |subgraph I_n| and
+ also other graphs. This list is available in the macro |\tikzgraphV|.
+ The number of elements of this list is available in |\tikzgraphVnum|.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/n=\meta{number}}
+ This is an abbreviation for
+ |V={1,...,|\meta{number}|}, name shore V/.style={name=V}|.
+ \end{key}
+ %
\begin{codeexample}[]
\tikz \graph [branch right, nodes={draw, circle}]
- { subgraph I_n [V={a,b,c}] };
+ { subgraph I_n [V={a,b,c}] };
\end{codeexample}
- This graph is not particularly exciting by itself. However, it is
- often used to introduce nodes into a graph that are then connected
- as in the following example:
+ %
+ This graph is not particularly exciting by itself. However, it is often
+ used to introduce nodes into a graph that are then connected as in the
+ following example:
+ %
\begin{codeexample}[]
-\tikz \graph [clockwise, clique] { subgraph I_n [n=4] };
+\tikz \graph [clockwise, clique] { subgraph I_n [n=4] };
\end{codeexample}
+ %
\end{graph}
-
\begin{graph}{subgraph I\_nm}
- This graph consists of two sets of once $n$ unconnected vertices and
- then $m$ unconnected vertices. The first set consists of the
- vertices set by the key |V|, the other set consists of the vertices
- set by the key |W|.
-\begin{codeexample}[]
-\tikz \graph { subgraph I_nm [V={1,2,3}, W={a,b,c}] };
-\end{codeexample}
- In order to set the graph path name of the two
- sets, the following keys get executed:
- \begin{stylekey}{/tikz/graphs/name shore V (initially \normalfont empty)}
- Set this style to, say, |name=my V set| in order to set a
- name for the |V| set.
- \end{stylekey}
- \begin{stylekey}{/tikz/graphs/name shore W (initially \normalfont empty)}
- Same as for |name shore V|.
- \end{stylekey}
- \begin{key}{/tikz/graphs/W=\marg{list of vertices}}
- Sets the list of vertices for the |W| set. The elements and
- their number are available in the macros |\tikzgraphW| and
- |\tikzgraphWnum|, respectively.
- \end{key}
- \begin{key}{/tikz/graphs/m=\meta{number}}
- This is an abbreviation for
- |W={1,...,|\meta{number}|}, name shore W={name=W}|.
- \end{key}
- The main purpose of this subgraph is to setup the nodes in a
- bipartite graph:
+ This graph consists of two sets of once $n$ unconnected vertices and then
+ $m$ unconnected vertices. The first set consists of the vertices set by the
+ key |V|, the other set consists of the vertices set by the key |W|.
+ %
+\begin{codeexample}[]
+\tikz \graph { subgraph I_nm [V={1,2,3}, W={a,b,c}] };
+\end{codeexample}
+ %
+ In order to set the graph path name of the two sets, the following keys get
+ executed:
+ %
+ \begin{stylekey}{/tikz/graphs/name shore V (initially \normalfont empty)}
+ Set this style to, say, |name=my V set| in order to set a name for the
+ |V| set.
+ \end{stylekey}
+ %
+ \begin{stylekey}{/tikz/graphs/name shore W (initially \normalfont empty)}
+ Same as for |name shore V|.
+ \end{stylekey}
+ %
+ \begin{key}{/tikz/graphs/W=\marg{list of vertices}}
+ Sets the list of vertices for the |W| set. The elements and their
+ number are available in the macros |\tikzgraphW| and |\tikzgraphWnum|,
+ respectively.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/m=\meta{number}}
+ This is an abbreviation for
+ |W={1,...,|\meta{number}|}, name shore W/.style={name=W}|.
+ \end{key}
+ %
+ The main purpose of this subgraph is to setup the nodes in a bipartite
+ graph:
+ %
\begin{codeexample}[]
\tikz \graph {
subgraph I_nm [n=3, m=4];
@@ -3247,78 +3378,87 @@ is to the following two keys:
V 1 -- { W 2, W 3 };
V 2 -- { W 1, W 3 };
V 3 -- { W 1, W 4 };
-};
+};
\end{codeexample}
+ %
\end{graph}
\begin{graph}{subgraph K\_n}
- This graph is the complete clique on the vertices from the |V| key.
+ This graph is the complete clique on the vertices from the |V| key.
+ %
\begin{codeexample}[]
-\tikz \graph [clockwise] { subgraph K_n [n=7] };
+\tikz \graph [clockwise] { subgraph K_n [n=7] };
\end{codeexample}
+ %
\end{graph}
-
\begin{graph}{subgraph K\_nm}
- This graph is the complete bipartite graph with the two shores |V|
- and |W| as in |subgraph I_nm|.
+ This graph is the complete bipartite graph with the two shores |V| and |W|
+ as in |subgraph I_nm|.
+ %
\begin{codeexample}[]
\tikz \graph [branch right, grow down]
- { subgraph K_nm [V={6,...,9}, W={b,...,e}] };
+ { subgraph K_nm [V={6,...,9}, W={b,...,e}] };
\end{codeexample}
+ %
\begin{codeexample}[]
\tikz \graph [simple, branch right, grow down]
{
subgraph K_nm [V={1,2,3}, W={a,b,c,d}, ->];
subgraph K_nm [V={2,3}, W={b,c}, <-];
-};
+};
\end{codeexample}
+ %
\end{graph}
\begin{graph}{subgraph P\_n}
- This graph is the path on the vertices in |V|.
+ This graph is the path on the vertices in |V|.
+ %
\begin{codeexample}[]
-\tikz \graph [branch right] { subgraph P_n [n=3] };
+\tikz \graph [branch right] { subgraph P_n [n=3] };
\end{codeexample}
+ %
\end{graph}
-
\begin{graph}{subgraph C\_n}
- This graph is the cycle on the vertices in |V|.
+ This graph is the cycle on the vertices in |V|.
+ %
\begin{codeexample}[]
-\tikz \graph [clockwise] { subgraph C_n [n=7, ->] };
+\tikz \graph [clockwise] { subgraph C_n [n=7, ->] };
\end{codeexample}
+ %
\end{graph}
-
\begin{graph}{subgraph Grid\_n}
- This graph is a grid of the vertices in |V|.
- \begin{key}{/tikz/graphs/wrap after=\meta{number}}
- Defines the number of nodes placed in a single row of the grid. This
- value implicitly defines the number of grid columns as well.
- In the following example a |grid placement| is used to visualize the
- edges created between the nodes of a |Grid_n| |subgraph| using
- different values for |wrap after|.
- \begin{codeexample}[]
+ This graph is a grid of the vertices in |V|.
+ %
+ \begin{key}{/tikz/graphs/wrap after=\meta{number}}
+ Defines the number of nodes placed in a single row of the grid. This
+ value implicitly defines the number of grid columns as well. In the
+ following example a |grid placement| is used to visualize the edges
+ created between the nodes of a |Grid_n| |subgraph| using different
+ values for |wrap after|.
+ %
+\begin{codeexample}[]
\tikz \graph [grid placement] { subgraph Grid_n [n=3,wrap after=1] };
\tikz \graph [grid placement] { subgraph Grid_n [n=3,wrap after=3] };
- \end{codeexample}
- \begin{codeexample}[]
+\end{codeexample}
+ %
+\begin{codeexample}[]
\tikz \graph [grid placement] { subgraph Grid_n [n=4,wrap after=2] };
\tikz \graph [grid placement] { subgraph Grid_n [n=4] };
- \end{codeexample}
+\end{codeexample}
\end{key}
\end{graph}
-
% TODO: Implement the Grid_nm subgraph described here:
%
%\begin{graph}{subgraph Grid\_nm}
% This graph is a grid built from the cartesian product of the two node
% sets |V| and |W| which are either defined using the keys
% |/tikz/graphs/V| and |/tikz/graphs/W| or |/tikz/graphs/n| and
-% |/tikz/graphs/m| or a mixture of both.
-%
+% |/tikz/graphs/m| or a mixture of both.
+%
% The resulting |Grid_nm| subgraph has $n$ ``rows'' and $m$ ``columns'' and
% the nodes are named |V i W j| with $1\le i\le n$ and $1\le j\le n$.
% The names of the two shores |V| and |W| can be changed as described in
@@ -3330,18 +3470,17 @@ is to the following two keys:
%\end{graph}
-
\subsubsection{Group Operators}
-The following keys use the |operator| key to setup operators that
-connect the vertices of the current group having a certain color in a
-specific way.
+The following keys use the |operator| key to setup operators that connect the
+vertices of the current group having a certain color in a specific way.
\begin{key}{/tikz/graphs/clique=\meta{color} (default all)}
- Adds an edge between all vertices of the current group having the
- (logical) color \meta{color}. Since, by default, this color is set
- to |all|, which is a color that all nodes get by default, when you
- do not specify anything, all nodes will be connected.
+ Adds an edge between all vertices of the current group having the (logical)
+ color \meta{color}. Since, by default, this color is set to |all|, which is
+ a color that all nodes get by default, when you do not specify anything,
+ all nodes will be connected.
+ %
\begin{codeexample}[]
\tikz \graph [clockwise, n=5] {
a,
@@ -3350,164 +3489,178 @@ specific way.
[clique]
c, d, e
}
-};
+};
\end{codeexample}
+ %
\begin{codeexample}[]
\tikz \graph [color class=red, clockwise, n=5] {
[clique=red, ->]
a, b[red], c[red], d, e[red]
-};
+};
\end{codeexample}
+ %
\end{key}
\begin{key}{/tikz/graphs/induced independent set=\meta{color} (default all)}
- This key is the ``opposite'' of a |clique|: It removes all edges in
- the current group having belonging to color class \meta{color}. More
- precisely, an edge of kind |-!-| is added for each pair of
- vertices. This means that edge only get removed if you specify the
- |simple| option.
+ This key is the ``opposite'' of a |clique|: It removes all edges in the
+ current group having belonging to color class \meta{color}. More precisely,
+ an edge of kind |-!-| is added for each pair of vertices. This means that
+ edge only get removed if you specify the |simple| option.
\begin{codeexample}[]
\tikz \graph [simple] {
subgraph K_n [<->, n=7, clockwise]; % create lots of edges
-
+
{ [induced independent set] 1, 3, 4, 5, 6 }
-};
+};
\end{codeexample}
+ %
\end{key}
-
\begin{key}{/tikz/graphs/cycle=\meta{color} (default all)}
- Connects the nodes colored \meta{color} is a cyclic fashion. The
- ordering is the ordering in which they appear in the whole graph
- specification.
+ Connects the nodes colored \meta{color} is a cyclic fashion. The ordering
+ is the ordering in which they appear in the whole graph specification.
+ %
\begin{codeexample}[]
\tikz \graph [clockwise, n=6, phase=60] {
{ [cycle, ->] a, b, c },
{ [cycle, <-] d, e, f }
-};
+};
\end{codeexample}
+ %
\end{key}
\begin{key}{/tikz/graphs/induced cycle=\meta{color} (default all)}
- While the |cycle| command will only add edges, this key will also
- remove all other edges between the nodes of the cycle, provided we
- are constructing a |simple| graph.
+ While the |cycle| command will only add edges, this key will also remove
+ all other edges between the nodes of the cycle, provided we are
+ constructing a |simple| graph.
+ %
\begin{codeexample}[]
\tikz \graph [simple] {
subgraph K_n [n=7, clockwise]; % create lots of edges
-
+
{ [induced cycle, ->, edge=red] 2, 3, 4, 6, 7 },
-};
+};
\end{codeexample}
+ %
\end{key}
-
+
\begin{key}{/tikz/graphs/path=\meta{color} (default all)}
- Works like |cycle|, only there is no edge from the last to the first
- vertex.
+ Works like |cycle|, only there is no edge from the last to the first
+ vertex.
+ %
\begin{codeexample}[]
\tikz \graph [clockwise, n=6] {
{ [path, ->] a, b, c },
{ [path, <-] d, e, f }
-};
+};
\end{codeexample}
+ %
\end{key}
+
\begin{key}{/tikz/graphs/induced path=\meta{color} (default all)}
- Works like |induced cycle|, only there is no edge from the last to the first
- vertex.
+ Works like |induced cycle|, only there is no edge from the last to the
+ first vertex.
+ %
\begin{codeexample}[]
\tikz \graph [simple] {
subgraph K_n [n=7, clockwise]; % create lots of edges
-
+
{ [induced path, ->, edges=red] 2, 3, 4, 6, 7 },
-};
+};
\end{codeexample}
+ %
\end{key}
\subsubsection{Joining Operators}
The following keys are typically used as options of an \meta{edge
- specification}, but can also be called in a group specification
-(however, then, the colors need to be set explicitly).
+specification}, but can also be called in a group specification (however, then,
+the colors need to be set explicitly).
-\begin{key}{/tikz/graphs/complete bipartite=\meta{from color}\meta{to
- color} (default \char`\{source'\char`\}\char`\{target'\char`\})}
- Adds all possible edges from every node having color \meta{from color}
- to every node having color \meta{to color}:
+\begin{key}{/tikz/graphs/complete bipartite=\meta{from color}\meta{to color} (default \char`\{source'\char`\}\char`\{target'\char`\})}
+ Adds all possible edges from every node having color \meta{from color} to
+ every node having color \meta{to color}:
+ %
\begin{codeexample}[]
\tikz \graph { {a, b} ->[complete bipartite]
{c, d, e} --[complete bipartite]
{g, h, i, j} --[complete bipartite]
- k };
+ k };
\end{codeexample}
+ %
\begin{codeexample}[]
\tikz \graph [color class=red, color class=green, clockwise, n=6] {
[complete bipartite={red}{green}, ->]
a [red], b[red], c[red], d[green], e[green], f[green]
};
\end{codeexample}
+ %
\end{key}
+
\begin{key}{/tikz/graphs/induced complete bipartite}
- Works like the |complete bipartite| operator, but in a |simple|
- graph any edges between the vertices in either shore are removed
- (more precisely, they get replaced by |-!-| edges).
+ Works like the |complete bipartite| operator, but in a |simple| graph any
+ edges between the vertices in either shore are removed (more precisely,
+ they get replaced by |-!-| edges).
+ %
\begin{codeexample}[]
\tikz \graph [simple] {
subgraph K_n [n=5, clockwise]; % Lots of edges
-
+
{2, 3} ->[induced complete bipartite] {4, 5}
};
-\end{codeexample}
+\end{codeexample}
+ %
\end{key}
-\begin{key}{/tikz/graphs/matching=\meta{from color}\meta{to
- color} (default \char`\{source'\char`\}\char`\{target'\char`\})}
- This joining operator forms a maximum
- \emph{matching} between the nodes of the two sets of nodes having
- colors \meta{from color} and \meta{to color}, respectively. The first node of
- the from set is connected to the first node of to set, the second
- node of the from set is connected to the second node of the to set,
- and so on. If the sets have the same
- size, what results is what graph theoreticians call a \emph{perfect
- matching}, otherwise only a maximum, but not perfect matching
- results.
+
+\begin{key}{/tikz/graphs/matching=\meta{from color}\meta{to color} (default \char`\{source'\char`\}\char`\{target'\char`\})}
+ This joining operator forms a maximum \emph{matching} between the nodes of
+ the two sets of nodes having colors \meta{from color} and \meta{to color},
+ respectively. The first node of the from set is connected to the first node
+ of to set, the second node of the from set is connected to the second node
+ of the to set, and so on. If the sets have the same size, what results is
+ what graph theoreticians call a \emph{perfect matching}, otherwise only a
+ maximum, but not perfect matching results.
+ %
\begin{codeexample}[]
\tikz \graph {
{a, b, c} ->[matching]
{d, e, f} --[matching]
{g, h} --[matching]
{i, j, k}
-};
+};
\end{codeexample}
+ %
\end{key}
-\begin{key}{/tikz/graphs/matching and star=\meta{from color}\meta{to
- color} (default \char`\{source'\char`\}\char`\{target'\char`\})}
- The |matching and star| connector works like the |matching|
- connector, only it behaves differently when the two to-be-connected
- sets have different size. In this case, all the surplus nodes get
- connected to the last node of the other set, resulting in what is known
- as a \emph{star} in graph theory. This simple rule allows
- for some powerful effects (since this connector is the default,
- there is no need to add it here):
- \begin{codeexample}[]
-\tikz \graph { a -> {b, c} -> {d, e} -- f};
- \end{codeexample}
- The |matching and star| connector also makes it easy to create trees and
- series-parallel graphs.
+\begin{key}{/tikz/graphs/matching and star=\meta{from color}\meta{to color} (default \char`\{source'\char`\}\char`\{target'\char`\})}
+ The |matching and star| connector works like the |matching| connector, only
+ it behaves differently when the two to-be-connected sets have different
+ size. In this case, all the surplus nodes get connected to the last node of
+ the other set, resulting in what is known as a \emph{star} in graph theory.
+ This simple rule allows for some powerful effects (since this connector is
+ the one initially set, there is no need to add it here):
+ %
+\begin{codeexample}[]
+\tikz \graph { a -> {b, c} -> {d, e} -- f};
+\end{codeexample}
+ %
+ The |matching and star| connector also makes it easy to create trees and
+ series-parallel graphs.
\end{key}
\begin{key}{/tikz/graphs/butterfly=\opt{\meta{options}}}
- The |butterfly| connector is used to create the kind of connections
- present between layers of a so-called \emph{butterfly network}.
- As for other connectors, two sets of nodes are connected, which are
- the nodes having color |target'| and |source'| by default. In a
- \emph{level $l$} connection, the first $l$ nodes of the first set
- are connected to the second $l$ nodes of the second set, while the
- second $l$ nodes of the first set get connected to the first $l$
- nodes of the second set. Then, for next $2l$ nodes of both sets a
- similar kind of connection is installed. Additionally, each node
- gets connected to the corresponding node in the other set with the
- same index (as in a |matching|):
+ The |butterfly| connector is used to create the kind of connections present
+ between layers of a so-called \emph{butterfly network}. As for other
+ connectors, two sets of nodes are connected, which are the nodes having
+ color |target'| and |source'| by default. In a \emph{level $l$} connection,
+ the first $l$ nodes of the first set are connected to the second $l$ nodes
+ of the second set, while the second $l$ nodes of the first set get
+ connected to the first $l$ nodes of the second set. Then, for next $2l$
+ nodes of both sets a similar kind of connection is installed. Additionally,
+ each node gets connected to the corresponding node in the other set with
+ the same index (as in a |matching|):
+ %
\begin{codeexample}[]
\tikz \graph [left anchor=east, right anchor=west,
branch down=4mm, grow right=15mm] {
@@ -3516,24 +3669,27 @@ The following keys are typically used as options of an \meta{edge
subgraph I_n [n=12, name=C]
};
\end{codeexample}
- Unlike most joining operators, the colors of the nodes in the first
- and the second set are not passed as parameters to the |butterfly|
- key. Rather, they can be set using the \meta{options}, which are
- executed with the path prefix |/tikz/graphs/butterfly|.
- \begin{key}{/tikz/graphs/butterfly/level=\meta{level} (initially 1)}
- Sets the level $l$ for the connections.
- \end{key}
- \begin{key}{/tikz/graphs/butterfly/from=\meta{color} (initially target')}
- Sets the color class of the from nodes.
- \end{key}
- \begin{key}{/tikz/graphs/butterfly/to=\meta{color} (initially source')}
- Sets the color class of the to nodes.
- \end{key}
-\end{key}
-
-
-
-%%% Local Variables:
+ %
+ Unlike most joining operators, the colors of the nodes in the first and the
+ second set are not passed as parameters to the |butterfly| key. Rather,
+ they can be set using the \meta{options}, which are executed with the path
+ prefix |/tikz/graphs/butterfly|.
+ %
+ \begin{key}{/tikz/graphs/butterfly/level=\meta{level} (initially 1)}
+ Sets the level $l$ for the connections.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/butterfly/from=\meta{color} (initially target')}
+ Sets the color class of the from nodes.
+ \end{key}
+ %
+ \begin{key}{/tikz/graphs/butterfly/to=\meta{color} (initially source')}
+ Sets the color class of the to nodes.
+ \end{key}
+\end{key}
+
+
+%%% Local Variables:
%%% mode: latex
%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
+%%% End: