summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex627
1 files changed, 306 insertions, 321 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex
index 222898b66e7..bbedfc01db9 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-tikz.tex
@@ -13,78 +13,82 @@
{\noindent {\emph{by Till Tantau}}}
\begin{tikzlibrary}{graphdrawing}
- This package provides capabilities for automatic graph drawing. It
- requires that the document is typeset using Lua\TeX. This package
- should work with Lua\TeX\ 0.54 or higher.
+ This package provides capabilities for automatic graph drawing. It requires
+ that the document is typeset using Lua\TeX. This package should work with
+ Lua\TeX\ 0.54 or higher.
\end{tikzlibrary}
-\ifluatex\else This section of the manual can only be typeset using Lua\TeX.\expandafter\endinput\fi
+\ifluatex
+\else
+ This section of the manual can only be typeset using Lua\TeX.
+ \expandafter\endinput
+\fi
\subsection{Choosing a Layout and a Library}
The graph drawing engine is initialized when you load the library
-|graphdrawing|. This library provides the basic framework for graph
-drawing, including all options and keys described in the present
-section. However, this library does \emph{not} load any actual
-algorithms for drawing graphs. For this, you need to use the following
-command, which is defined by the |graphdrawing| library:
+|graphdrawing|. This library provides the basic framework for graph drawing,
+including all options and keys described in the present section. However, this
+library does \emph{not} load any actual algorithms for drawing graphs. For
+this, you need to use the following command, which is defined by the
+|graphdrawing| library:
\begin{command}{\usegdlibrary\marg{list of libraries}}
- This command is used to load the special graph drawing libraries
- (the |gd| in the name of the command stands for ``graph
- drawing''). The \meta{list of libraries} is a comma-separated list
- of library written in the Lua programming language (which is why a
- special command is needed).
-
- In detail, this command does the following. For each \meta{name} in
- the \meta{list of libraries} we do:
- \begin{enumerate}
- \item Check whether Lua\TeX\ can call |require| on the library file
- |pgf.gd.|\meta{name}|.library|. Lua\TeX's usual file search
- mechanism will search the texmf-trees in the usual manner and the
- dots in the file name get converted into directory slashes.
- \item If the above failed, try to |require| the string
- |pgf.gd.|\meta{name}.
- \item If this fails, try to |require| the string
- \meta{name}|.library|.
- \item If this fails, try to |require| the string \meta{name}. If
- this fails, print an error message.
- \end{enumerate}
- The net effect of the above is the following: Authors of graph
- drawing algorithms can bundle together multiple algorithms in a
- library by creating a |...xyz/library.lua| file that internally just
- calls |require| for all files containing declarations. On the other
- hand, if a graph drawing algorithm completely fits inside a single
- file, it can also be read directly using |\usegdlibrary|.
+ This command is used to load the special graph drawing libraries (the |gd|
+ in the name of the command stands for ``graph drawing''). The \meta{list of
+ libraries} is a comma-separated list of library written in the Lua
+ programming language (which is why a special command is needed).
+
+ In detail, this command does the following. For each \meta{name} in the
+ \meta{list of libraries} we do:
+ %
+ \begin{enumerate}
+ \item Check whether Lua\TeX\ can call |require| on the library file
+ |pgf.gd.|\meta{name}|.library|. Lua\TeX's usual file search
+ mechanism will search the texmf-trees in the usual manner and the
+ dots in the file name get converted into directory slashes.
+ \item If the above failed, try to |require| the string
+ |pgf.gd.|\meta{name}.
+ \item If this fails, try to |require| the string \meta{name}|.library|.
+ \item If this fails, try to |require| the string \meta{name}. If this
+ fails, print an error message.
+ \end{enumerate}
+ %
+ The net effect of the above is the following: Authors of graph drawing
+ algorithms can bundle together multiple algorithms in a library by creating
+ a |...xyz/library.lua| file that internally just calls |require| for all
+ files containing declarations. On the other hand, if a graph drawing
+ algorithm completely fits inside a single file, it can also be read
+ directly using |\usegdlibrary|.
+ %
\begin{codeexample}[code only]
\usetikzlibrary{graphdrawing}
-\usegdlibrary{trees,force}
+\usegdlibrary{trees,force}
\end{codeexample}
- The different graph drawing libraries are documented in the following
- Sections~\ref{section-first-graphdrawing-library-in-manual} to
- \ref{section-last-graphdrawing-library-in-manual}.
+ The different graph drawing libraries are documented in the following
+ Sections~\ref{section-first-graphdrawing-library-in-manual} to
+ \ref{section-last-graphdrawing-library-in-manual}.
\end{command}
-Note that in addition to the graph \emph{drawing} libraries, you may
-also wish to load the normal \tikzname\ library |graphs|. It provides
-the powerful |graph| path command with its easy-to-use syntax for
-specifying graphs, but you can use the graph drawing engine
-independently of the |graphs| library, for instance in conjunction
-with the |child| or the |edge| syntax. Here is a typical setup:
-
+Note that in addition to the graph \emph{drawing} libraries, you may also wish
+to load the normal \tikzname\ library |graphs|. It provides the powerful
+|graph| path command with its easy-to-use syntax for specifying graphs, but you
+can use the graph drawing engine independently of the |graphs| library, for
+instance in conjunction with the |child| or the |edge| syntax. Here is a
+typical setup:
+%
\begin{codeexample}[code only]
\usetikzlibrary{graphs, graphdrawing}
-\usegdlibrary{trees, layered}
+\usegdlibrary{trees, layered}
\end{codeexample}
-Having set things up, you must then specify for which scopes the
-graph drawing engine should apply a layout algorithm to the nodes in
-the scope. Typically, you just add an option ending with |... layout|
-to the |graph| path operation and then let the graph drawing do its
-magic:
-
+Having set things up, you must then specify for which scopes the graph drawing
+engine should apply a layout algorithm to the nodes in the scope. Typically,
+you just add an option ending with |... layout| to the |graph| path operation
+and then let the graph drawing do its magic:
+%
\begin{codeexample}[]
\tikz [rounded corners]
\graph [layered layout, sibling distance=8mm, level distance=8mm]
@@ -93,92 +97,87 @@ magic:
b,
c -> { d, e }
} ->
- f ->
+ f ->
a
- };
+ };
\end{codeexample}
Whenever you use such an option, you can:
+%
\begin{itemize}
-\item Create nodes in the usual way. The nodes will be created
- completely, but then tucked away in an internal table. This means
- that all of \tikzname's options for nodes can be applied. You can
- also name a node and reference it later.
-\item Create edges using either the syntax of the |graph| command
- (using |--|, |<-|, |->|, or |<->|), or using the |edge| command,
- or using the |child| command. These edges will, however, not be
- created immediately. Instead, the basic layer's command
- |\pgfgdedge| will be called, which stores ``all the information
- concerning the edge.'' The actual drawing of the edge will only
- happen after all nodes have been positioned.
-\item Most of the keys that can be passed to an edge will work as
- expected. In particular, you can add labels to edges using the
- usual |node| syntax for edges.
-\item The |label| and |pin| options can be used in the usual manner
- with nodes inside a graph drawing scope. Only, the labels and
- nodes will play no role in the positioning of the nodes and they
- are added when the nodes are finally positioned.
-\item Similarly, nodes that are placed ``on an edge'' using the
- implicit positioning syntax can be used in the usual manner.
+ \item Create nodes in the usual way. The nodes will be created completely,
+ but then tucked away in an internal table. This means that all of
+ \tikzname's options for nodes can be applied. You can also name a node
+ and reference it later.
+ \item Create edges using either the syntax of the |graph| command (using
+ |--|, |<-|, |->|, or |<->|), or using the |edge| command, or using the
+ |child| command. These edges will, however, not be created immediately.
+ Instead, the basic layer's command |\pgfgdedge| will be called, which
+ stores ``all the information concerning the edge''. The actual drawing
+ of the edge will only happen after all nodes have been positioned.
+ \item Most of the keys that can be passed to an edge will work as expected.
+ In particular, you can add labels to edges using the usual |node|
+ syntax for edges.
+ \item The |label| and |pin| options can be used in the usual manner with
+ nodes inside a graph drawing scope. Only, the labels and nodes will
+ play no role in the positioning of the nodes and they are added when
+ the nodes are finally positioned.
+ \item Similarly, nodes that are placed ``on an edge'' using the implicit
+ positioning syntax can be used in the usual manner.
\end{itemize}
+%
Here are some things that will \emph{not} work:
+%
\begin{itemize}
-\item Only edges created using the graph syntax, the |edge| command,
- or the |child| command will correctly pass their connection
- information to the basic layer. When you write |\draw (a)--(b);|
- inside a graph drawing scope, where |a| and |b| are nodes that
- have been created inside the scope, you will get an error
- message / things will look wrong. The reason is that the usual
- |--| is not ``caught'' by the graph drawing engine and, thus,
- tries to immediately connect two nodes that do not yet exist
- (except inside some internal table).
-\item The options of edges are executed twice: Once when the edge is
- ``examined'' by the |\pgfgdedge| command (using some magic to shield
- against the side effects) and then once more when the edge is
- actually created. Fortunately, in almost all cases, this will not be
- a problem; but if you do very evil magic inside your edge options,
- you must roll a D100 to see what strange things will happen. (Do no
- evil, by the way.)
+ \item Only edges created using the graph syntax, the |edge| command, or the
+ |child| command will correctly pass their connection information to the
+ basic layer. When you write |\draw (a)--(b);| inside a graph drawing
+ scope, where |a| and |b| are nodes that have been created inside the
+ scope, you will get an error message / things will look wrong. The
+ reason is that the usual |--| is not ``caught'' by the graph drawing
+ engine and, thus, tries to immediately connect two nodes that do not
+ yet exist (except inside some internal table).
+ \item The options of edges are executed twice: Once when the edge is
+ ``examined'' by the |\pgfgdedge| command (using some magic to shield
+ against the side effects) and then once more when the edge is actually
+ created. Fortunately, in almost all cases, this will not be a problem;
+ but if you do very evil magic inside your edge options, you must roll a
+ D100 to see what strange things will happen. (Do no evil, by the way.)
\end{itemize}
-If you are really interested in the ``fine print'' of what happens,
-please see Section~\ref{section-gd-pgf}.
+If you are really interested in the ``fine print'' of what happens, please see
+Section~\ref{section-gd-pgf}.
\subsection{Graph Drawing Parameters}
-Graph drawing algorithms can typically be configured in some way. For
-instance, for a graph drawing algorithm that visualizes its nodes as a
-tree, it will typically be useful when the user can change the
-so-called \emph{level distance} and the \emph{sibling distance}. For
-other algorithms, like force-based algorithms, a large number of
-parameters influence the way the algorithms work.
-Options that influence graph drawing algorithms will be called
-\emph{(graph drawing) parameters} in the following. From the user's
-point of view, these parameters look like normal \tikzname\ keys and
-you set them in the usual way. Internally, they are treated a bit
-differently from normal keys since their ``effect'' becomes apparent
-only later on, namely during the run of the graph drawing algorithm.
-
-A graph drawing algorithm may or may not take different graph
-parameters into account. After all, these options may even outright
-contradict each other, so an algorithm can only try to ``do its
-best''. While many graph parameters are very specific to a single
-algorithm, a number of graph parameters will be important for many
-algorithms and they are documented in the course of the present
-section. Here is an example of an option the ``always works'':
-
+Graph drawing algorithms can typically be configured in some way. For instance,
+for a graph drawing algorithm that visualizes its nodes as a tree, it will
+typically be useful when the user can change the so-called \emph{level
+distance} and the \emph{sibling distance}. For other algorithms, like
+force-based algorithms, a large number of parameters influence the way the
+algorithms work. Options that influence graph drawing algorithms will be called
+\emph{(graph drawing) parameters} in the following. From the user's point of
+view, these parameters look like normal \tikzname\ keys and you set them in the
+usual way. Internally, they are treated a bit differently from normal keys
+since their ``effect'' becomes apparent only later on, namely during the run of
+the graph drawing algorithm.
+
+A graph drawing algorithm may or may not take different graph parameters into
+account. After all, these options may even outright contradict each other, so
+an algorithm can only try to ``do its best''. While many graph parameters are
+very specific to a single algorithm, a number of graph parameters will be
+important for many algorithms and they are documented in the course of the
+present section. Here is an example of an option the ``always works'':
+%
\begin{codeexample}[]
-\tikz \graph [spring layout, vertical=1 to 2] { 1--2--3--1 };
+\tikz \graph [spring layout, vertical=1 to 2] { 1--2--3--1 };
\end{codeexample}
-
\includeluadocumentationof{pgf.gd.control.Distances}
\includeluadocumentationof{pgf.gd.control.Anchoring}
\includeluadocumentationof{pgf.gd.control.Orientation}
-
-
\includeluadocumentationof{pgf.gd.control.FineTune}
\includeluadocumentationof{pgf.gd.control.Components}
@@ -193,46 +192,43 @@ section. Here is an example of an option the ``always works'':
\subsection{Using Several Different Layouts to Draw a Single Graph}
-
\label{section-gd-sublayouts}
-Inside each graph drawing scope, a main algorithm is used to perform
-the graph drawing. However, parts of the graph may be drawn using
-different algorithms: For instance, a graph might consist of
-several, say, cliques that are arranged in a tree-like fashion. In
-this case, it might be useful to layout each clique using a circular
-layout, but then lay out all laid out cliques using a tree drawing
-algorithm.
+Inside each graph drawing scope, a main algorithm is used to perform the graph
+drawing. However, parts of the graph may be drawn using different algorithms:
+For instance, a graph might consist of several, say, cliques that are arranged
+in a tree-like fashion. In this case, it might be useful to layout each clique
+using a circular layout, but then lay out all laid out cliques using a tree
+drawing algorithm.
-In order to lay out a graph using multiple algorithms, we need two
-things: First, we must be able to \emph{specify} which algorithms
-should be used where and, second, we must be able to \emph{resolve}
-conflicts that may result from different algorithms ``having different
-ideas'' concerning where nodes should be placed.
+In order to lay out a graph using multiple algorithms, we need two things:
+First, we must be able to \emph{specify} which algorithms should be used where
+and, second, we must be able to \emph{resolve} conflicts that may result from
+different algorithms ``having different ideas'' concerning where nodes should
+be placed.
\subsubsection{Sublayouts}
-Specifying different layouts for a graph is easy: Inside a graph
-drawing scope, simply open scopes, in which you use an option like
-|tree layout| for the nodes mentioned in this scope. Inside these
-scopes, you can open even subscopes for sublayouts, and so
-on. Furthermore, the |graphs| library has special support for
-sublayouts.
-
-Let us start with the ``plain'' syntax for opening sublayouts: You
-pass a key for creating layouts to a |scope|:
+Specifying different layouts for a graph is easy: Inside a graph drawing scope,
+simply open scopes, in which you use an option like |tree layout| for the nodes
+mentioned in this scope. Inside these scopes, you can open even subscopes for
+sublayouts, and so on. Furthermore, the |graphs| library has special support
+for sublayouts.
+Let us start with the ``plain'' syntax for opening sublayouts: You pass a key
+for creating layouts to a |scope|:
+%
\begin{codeexample}[]
\tikz [spring layout] {
- \begin{scope}[tree layout]
+ \begin{scope}[tree layout]
\node (a) {a};
\node (b) {b};
\node (c) {c};
\draw (a) edge (b) edge (c);
\end{scope}
-
- \begin{scope}[tree layout]
+
+ \begin{scope}[tree layout]
\node (1) {1};
\node (2) {2};
\draw (1) edge (2);
@@ -242,27 +238,26 @@ pass a key for creating layouts to a |scope|:
}
\end{codeexample}
-Let us see, what is going on here. The main layout (|spring layout|)
-contains two sublayouts (the two |tree layouts|). Both of them are
-laid out independently (more on the details in a moment). Then, from
-the main layout's point of view, the sublayouts behave like ``large
-nodes'' and, thus, the edge between |a| and |1| is actually the only
-edge that is used by the |spring layout| -- resulting in a simple
-layout consisting of one big node at the top and a big node at the
-bottom.
-
-The |graphs| library has a special support for sublayouts: The syntax
-is as follows: wherever a normal node would go, you can write
+Let us see, what is going on here. The main layout (|spring layout|) contains
+two sublayouts (the two |tree layouts|). Both of them are laid out
+independently (more on the details in a moment). Then, from the main layout's
+point of view, the sublayouts behave like ``large nodes'' and, thus, the edge
+between |a| and |1| is actually the only edge that is used by the
+|spring layout| -- resulting in a simple layout consisting of one big node at
+the top and a big node at the bottom.
+The |graphs| library has a special support for sublayouts: The syntax is as
+follows: wherever a normal node would go, you can write
+%
\begin{quote}
- |//| \opt{\oarg{layout options}} |{|\meta{sublayout}|}|
+ |//| \opt{\oarg{layout options}} |{|\meta{sublayout}|}|
\end{quote}
-Following the double slash, you may provide
-\meta{layout options} in square brackets. However, you \emph{must}
-provide a sublayout in braces. The contents of \meta{sublayout} will
-be parsed using the usual |graph| syntax, but will form a sublayout.
-
+Following the double slash, you may provide \meta{layout options} in square
+brackets. However, you \emph{must} provide a sublayout in braces. The contents
+of \meta{sublayout} will be parsed using the usual |graph| syntax, but will
+form a sublayout.
+%
\begin{codeexample}[]
\tikz \graph [spring layout] {
// [tree layout] { a -- {b, c} };
@@ -271,17 +266,16 @@ be parsed using the usual |graph| syntax, but will form a sublayout.
};
\end{codeexample}
-
-In the above example, there is no node before the double slash, which
-means that the two sublayouts will be part of the main graph, but will
-not be indicated otherwise.
-
-\begin{codeexample}[]
+In the above example, there is no node before the double slash, which means
+that the two sublayouts will be part of the main graph, but will not be
+indicated otherwise.
+%
+\begin{codeexample}[]
\tikz \graph [simple necklace layout] {
// [simple necklace layout] { a -> b -> c -> d -> e -> f -> a };
-
+
// [tree layout] { % first tentacle
- a -> {1, 2};
+ a -> {1, 2};
};
// [tree layout] {% second tentacle
@@ -290,24 +284,23 @@ not be indicated otherwise.
};
\end{codeexample}
-In the above example, the first sublayout is the one for the nodes
-with letter names. These nodes are arranged using a simple necklace layout
-as the sublayout inherits this option from the main layout. The two
-small trees (|a -> {1, 2}| and the tree starting at the |d| node)
-are also sublayouts, triggered by the |tree layout| option. They are
-also arranged. Then, all of the layouts are merged (as described
-later). The result is actually a single node, so the main layout
-does nothing here.
+In the above example, the first sublayout is the one for the nodes with letter
+names. These nodes are arranged using a simple necklace layout as the sublayout
+inherits this option from the main layout. The two small trees (|a -> {1, 2}|
+and the tree starting at the |d| node) are also sublayouts, triggered by the
+|tree layout| option. They are also arranged. Then, all of the layouts are
+merged (as described later). The result is actually a single node, so the main
+layout does nothing here.
Compare the above to the following code:
-
-\begin{codeexample}[]
+%
+\begin{codeexample}[]
\tikz \graph [simple necklace layout] {
// [tree layout] { % first ``giant node''
- a -> {1, 2};
+ a -> {1, 2};
};
-
- a -> b -> c -> d;
+
+ a -> b -> c -> d;
// [tree layout] {% second ``giant node''
d -> {3, 4 -> {5, 6}}
@@ -315,37 +308,35 @@ Compare the above to the following code:
d -> e -> f -> a;
};
-\end{codeexample}
+\end{codeexample}
-Here, only the two trees are laid out first. They are then
-contracted into ``giant nodes'' and these are then part of the set
-of nodes that are arranged by the |simple necklace layout|. For details of
-how this contracting works, see below.
+Here, only the two trees are laid out first. They are then contracted into
+``giant nodes'' and these are then part of the set of nodes that are arranged
+by the |simple necklace layout|. For details of how this contracting works, see
+below.
\subsubsection{Subgraph Nodes}
-A \emph{subgraph node} is a special kind of node that ``surrounds''
-the vertices of a subgraph. The special property of a subgraph node
-opposed to a normal node is that it is created only after the subgraph
-has been laid out. However, the difference to a collection like
-|hyper| is that the node is available immediately as a normal node in
-the sense that you can connect edges to it.
-
-The syntax used to declare a subgraph node in a |graph| specification
-is as follows:
+A \emph{subgraph node} is a special kind of node that ``surrounds'' the
+vertices of a subgraph. The special property of a subgraph node opposed to a
+normal node is that it is created only after the subgraph has been laid out.
+However, the difference to a collection like |hyper| is that the node is
+available immediately as a normal node in the sense that you can connect edges
+to it.
+The syntax used to declare a subgraph node in a |graph| specification is as
+follows:
+%
\begin{quote}
- \opt{|"|}\meta{node
- name}\opt{|"|}\opt{|/|\opt{|"|}\meta{text}\opt{|"|}}
- \opt{\oarg{node options}}
- |//| \opt{\oarg{layout options}} |{|\meta{subgraph}|}|
+ \opt{|"|}\meta{node name}\opt{|"|}\opt{|/|\opt{|"|}\meta{text}\opt{|"|}}
+ \opt{\oarg{node options}} |//| \opt{\oarg{layout options}} |{|\meta{subgraph}|}|
\end{quote}
-The idea ist that a subgraph node is declared like a normal node
-specification, but is followed by a double slash and a subgraph:
-
-\begin{codeexample}[width=5cm]
+The idea ist that a subgraph node is declared like a normal node specification,
+but is followed by a double slash and a subgraph:
+%
+\begin{codeexample}[width=5cm]
\tikz \graph [simple necklace layout] {
tree 1[draw, circle] // [tree layout] { a -> {1, 2}; }
-> b
@@ -355,191 +346,185 @@ specification, but is followed by a double slash and a subgraph:
-> f
-> tree 1;
};
-\end{codeexample}
-
-Note how the two subgraph nodes |tree 1| and |tree 2| surround the two
-smaller trees. In the example, both had trees as contents and these
-trees were rendered using a sublayout. However, a subgraph layout does
-not need to have its own layout: If you do \emph{not} provide a layout
-name after the double slash, the subgraph node will simply surround
-all nodes that were placed by the main layout wherever they were
-placed:
+\end{codeexample}
-\begin{codeexample}[]
+Note how the two subgraph nodes |tree 1| and |tree 2| surround the two smaller
+trees. In the example, both had trees as contents and these trees were rendered
+using a sublayout. However, a subgraph layout does not need to have its own
+layout: If you do \emph{not} provide a layout name after the double slash, the
+subgraph node will simply surround all nodes that were placed by the main
+layout wherever they were placed:
+%
+\begin{codeexample}[]
\tikz [subgraph text bottom=text centered,
subgraph nodes={font=\itshape}]
\graph [tree layout] {
a -> { b -> {c, d}, e -> {f, g -> h} };
-
+
left [draw] // { b, c, d };
right [draw] // { e, f, g, h};
-
+
left <-> right;
};
-\end{codeexample}
-
-
+\end{codeexample}
-Every time a subgraph node is created, the following style is execute:
+Every time a subgraph node is created, the following style is execute:
\begin{key}{/tikz/every subgraph node}
- Set a subgraph node style.
+ Set a subgraph node style.
\end{key}
\begin{key}{/tikz/subgraph nodes=\meta{style}}
- Sets the |every subgraph node| style to \meta{style}.
-\begin{codeexample}[]
+ Sets the |every subgraph node| style to \meta{style}.
+ %
+\begin{codeexample}[]
\tikz [subgraph text bottom=text centered,
subgraph nodes=red]
\graph [tree layout] {
a -> { b -> {c, d}, e -> {f, g -> h} };
-
+
left [draw] // { b, c, d };
right [draw] // { e, f, g, h};
-
+
left <-> right;
};
-\end{codeexample}
+\end{codeexample}
+ %
\end{key}
\begin{key}{/tikz/subgraph text none}
- When this option is used, the text of a subgraph node is not
- shown. Adding a slash after the node name achieves roughly the same
- effect, but this option is useful in situations when subgraph nodes
- generally should not have any text inside them.
-\begin{codeexample}[]
+ When this option is used, the text of a subgraph node is not shown. Adding
+ a slash after the node name achieves roughly the same effect, but this
+ option is useful in situations when subgraph nodes generally should not
+ have any text inside them.
+ %
+\begin{codeexample}[]
\tikz [subgraph text none]
\graph [tree layout] {
a -> { b -> {c, d}, e -> {f, g -> h} };
-
+
left [draw] // { b, c, d };
right [draw] // { e, f, g, h};
-
+
left <-> right;
};
-\end{codeexample}
-
+\end{codeexample}
+ %
\end{key}
-\begin{key}{/tikz/subgraph text top=\meta{text alignment
- options} (default text ragged right)}
- Specifies that the text of a subgraph node should be placed at the
- top of the subgraph node: Still inside the node, but above all nodes
- inside the subgraph node.
-\begin{codeexample}[]
+\begin{key}{/tikz/subgraph text top=\meta{text alignment options} (default text ragged right)}
+ Specifies that the text of a subgraph node should be placed at the top of
+ the subgraph node: Still inside the node, but above all nodes inside the
+ subgraph node.
+ %
+\begin{codeexample}[]
\tikz [subgraph text top=text ragged left]
\graph [tree layout] {
a -> { b -> {c, d}, e -> {f, g -> h} };
-
+
left [draw] // { b, c, d };
right [draw] // { e, f, g, h};
-
+
left <-> right;
};
-\end{codeexample}
- You can pass any of the \meta{text alignment options} understood by
- \tikzname, such as |text centered|:
-\begin{codeexample}[width=5cm]
+\end{codeexample}
+ %
+ You can pass any of the \meta{text alignment options} understood by
+ \tikzname, such as |text centered|:
+ %
+\begin{codeexample}[width=5cm]
\tikz [subgraph text top=text centered]
\graph [tree layout] {
a -> { b -> {c, d}, e -> {f, g -> h} };
-
+
left [draw, circle] // { b, c, d };
};
-\end{codeexample}
- To place a label \emph{outside} the subgraph node, use a label,
- typically defined using the |quotes| library:
-\begin{codeexample}[]
+\end{codeexample}
+ %
+ To place a label \emph{outside} the subgraph node, use a label, typically
+ defined using the |quotes| library:
+ %
+\begin{codeexample}[]
\tikz \graph [tree layout] {
a -> { b -> {c, d}, e -> {f, g -> h} };
-
+
/ ["left", draw] // { b, c, d } <->
/ ["right", draw] // { e, f, g, h};
};
-\end{codeexample}
+\end{codeexample}
+ %
\end{key}
-
-\begin{key}{/tikz/subgraph text bottom=\meta{text alignment
- options} (default ragged right)}
- Works like |subgraph text top|, only the text placed at the bottom.
+\begin{key}{/tikz/subgraph text bottom=\meta{text alignment options} (default ragged right)}
+ Works like |subgraph text top|, only the text placed at the bottom.
\end{key}
-Note that there are no keys |subgraph text left| or |... right|,
-for somewhat technical reasons.
+Note that there are no keys |subgraph text left| or |... right|, for somewhat
+technical reasons.
\begin{key}{/tikz/subgraph text sep=\meta{dimension} (initially .1em)}
- Some space added between the inner nodes of a subgraph node and the
- text labels.
+ Some space added between the inner nodes of a subgraph node and the text
+ labels.
\end{key}
\subsubsection{Overlapping Sublayouts}
-
\label{section-gd-layout-resolve}
-Nodes and edges can be part of several layouts. This
-will inevitably lead to conflicts because algorithm will disagree on
-where a node should be placed on the canvas. For this reason, there
-are some rules governing how such conflicts are resolved: Given a
-layout, starting with the main layout, the graph drawing system does
-the following:
-
-\begin{enumerate}
-\item We start by first processing the (direct) sublayouts of the
- current layout (recursively). Sublayouts may overlap (they may share
- one or more nodes), but we run the specified layout algorithm for
- each sublayout independently on a ``fresh copy'' of all the nodes
- making up the sublayout. In particular, different, conflicting
- positions may be computed for nodes when they are present in several
- sublayouts.
-\item Once all nodes in the sublayouts have been laid out in this way,
- we \emph{join} overlapping elements. The idea is that if two layouts
- share exactly one vertex, we can shift them around so that his
- vertex is at the same position in both layouts. In more detail, the
- following happens:
-
- We build a (conceptual) graph whose nodes are the sublayouts and in
- which there is an edge between two nodes if the sublayouts
- represented by these elements have a node in common.
- Inside the resulting graph, we treat each connected component
- separately. Each component has the property that the sublayouts
- represented by the nodes in the component overlap by at least one
- node. We now \emph{join} them as follows: We start with the first
- sublayout in the component (``first'' with respect to the order in
- which they appear in the input graph) and ``mark'' this
- sublayout. We loop the following instructions as long as possible:
- Search for the first sublayout (again, with respect to the order in
- which they appear in the input) that is connect by an edge to a
- marked sublayout. The sublayout will now have at least one node in
- common with the marked sublayouts (possibly, even more). We
- consider the first such node (again, first respect to the input
- ordering) and shift the whole sublayout is such a way that this
- particular node is at the position is has in the marked
- sublayouts. Note that after the shift, other nodes that are also
- present in the marked sublayouts may lie at a different position in
- the current sublayout. In this case, the position in the marked
- sublayouts ``wins.'' We then mark the sublayout.
-\item When the above algorithm has run, we will have computed
- positions for all nodes in all sublayouts of each of the
- components. For each component, we contract all
- nodes of the component to a single node. This new
- node will be ``large'' in the sense that its convex hull is the
- convex hull of all the nodes in the component. All nodes that used
- to be part of the component are removed and the new large node is
- added (with arcs adjusted appropriately).
-\item We now run the layout's algorithm on the resulting nodes
- (the remaining original nodes and the contracted nodes).
-\item In a last step, once the graph has been laid out, we expand the
- nodes that were previously contracted. For this, the
- nodes that were deleted earlier get reinserted, but shifted by
- whatever amount the contraction node got shifted.
+Nodes and edges can be part of several layouts. This will inevitably lead to
+conflicts because algorithm will disagree on where a node should be placed on
+the canvas. For this reason, there are some rules governing how such conflicts
+are resolved: Given a layout, starting with the main layout, the graph drawing
+system does the following:
+%
+\begin{enumerate}
+ \item We start by first processing the (direct) sublayouts of the current
+ layout (recursively). Sublayouts may overlap (they may share one or
+ more nodes), but we run the specified layout algorithm for each
+ sublayout independently on a ``fresh copy'' of all the nodes making up
+ the sublayout. In particular, different, conflicting positions may be
+ computed for nodes when they are present in several sublayouts.
+ \item Once all nodes in the sublayouts have been laid out in this way, we
+ \emph{join} overlapping elements. The idea is that if two layouts share
+ exactly one vertex, we can shift them around so that his vertex is at
+ the same position in both layouts. In more detail, the following
+ happens:
+
+ We build a (conceptual) graph whose nodes are the sublayouts and in
+ which there is an edge between two nodes if the sublayouts represented
+ by these elements have a node in common. Inside the resulting graph, we
+ treat each connected component separately. Each component has the
+ property that the sublayouts represented by the nodes in the component
+ overlap by at least one node. We now \emph{join} them as follows: We
+ start with the first sublayout in the component (``first'' with respect
+ to the order in which they appear in the input graph) and ``mark'' this
+ sublayout. We loop the following instructions as long as possible:
+ Search for the first sublayout (again, with respect to the order in
+ which they appear in the input) that is connect by an edge to a marked
+ sublayout. The sublayout will now have at least one node in common with
+ the marked sublayouts (possibly, even more). We consider the first such
+ node (again, first respect to the input ordering) and shift the whole
+ sublayout is such a way that this particular node is at the position is
+ has in the marked sublayouts. Note that after the shift, other nodes
+ that are also present in the marked sublayouts may lie at a different
+ position in the current sublayout. In this case, the position in the
+ marked sublayouts ``wins''. We then mark the sublayout.
+ \item When the above algorithm has run, we will have computed positions for
+ all nodes in all sublayouts of each of the components. For each
+ component, we contract all nodes of the component to a single node.
+ This new node will be ``large'' in the sense that its convex hull is
+ the convex hull of all the nodes in the component. All nodes that used
+ to be part of the component are removed and the new large node is added
+ (with arcs adjusted appropriately).
+ \item We now run the layout's algorithm on the resulting nodes (the
+ remaining original nodes and the contracted nodes).
+ \item In a last step, once the graph has been laid out, we expand the nodes
+ that were previously contracted. For this, the nodes that were deleted
+ earlier get reinserted, but shifted by whatever amount the contraction
+ node got shifted.
\end{enumerate}
\subsection{Miscellaneous Options}
\includeluadocumentationof{pgf.gd.control.library}
-
-\endinput
-