diff options
author | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-01-05 22:40:38 +0000 |
commit | 22536bb2b5257046d271b1eaa11b4a275d5ec041 (patch) | |
tree | 2500eaf5c26b11e00ebd33a64fccfa332cd5a66c /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex | |
parent | cf794f0e2db6857972a9d48d4466a4f03a7057a0 (diff) |
pgf (5jan19)
git-svn-id: svn://tug.org/texlive/trunk@49607 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex | 1064 |
1 files changed, 513 insertions, 551 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex index 095e3f771a4..961f1e1076f 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-usage-pgf.tex @@ -14,100 +14,94 @@ % See the file doc/generic/pgf/licenses/LICENSE for more details. - \section{Using Graph Drawing in PGF} - \label{section-gd-pgf} {\noindent {\emph{by Till Tantau}}} \begin{purepgflibrary}{graphdrawing} - This package provides the core support for graph drawing inside - \pgfname. It does so by providing \pgfname\ macros for controlling - the graph drawing system, but also implements the binding to the - graph drawing system (see Section~\ref{section-gd-binding-layer} for - details on bindings). + This package provides the core support for graph drawing inside \pgfname. + It does so by providing \pgfname\ macros for controlling the graph drawing + system, but also implements the binding to the graph drawing system (see + Section~\ref{section-gd-binding-layer} for details on bindings). \end{purepgflibrary} -\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{Overview} -Just like everywhere else in \pgfname, \tikzname\ is ``just a -convenient syntax'' in the context of graph drawing. The ``hard work'' -of binding the internal representations of nodes and edges with the graph -drawing system written in Lua is not done by \tikzname, but rather by -a set of macros that are part of the basic \pgfname\ layer. +\subsection{Overview} -The documentation of the \pgfname\ part of the graph drawing system -that is presented in the following includes only those macros that -other \TeX\ packages could conceivably call in order to use the graph -drawing system without using \tikzname; for instance, for efficiency -reasons. (The internal callback functions defined in the graph drawing -library that are part of the binding between \pgfname\ and the graph -drawing system are not documented, should not be called, and may -change in the future.) +Just like everywhere else in \pgfname, \tikzname\ is ``just a convenient +syntax'' in the context of graph drawing. The ``hard work'' of binding the +internal representations of nodes and edges with the graph drawing system +written in Lua is not done by \tikzname, but rather by a set of macros that are +part of the basic \pgfname\ layer. +The documentation of the \pgfname\ part of the graph drawing system that is +presented in the following includes only those macros that other \TeX\ packages +could conceivably call in order to use the graph drawing system without using +\tikzname; for instance, for efficiency reasons. (The internal callback +functions defined in the graph drawing library that are part of the binding +between \pgfname\ and the graph drawing system are not documented, should not +be called, and may change in the future.) \subsection{How Graph Drawing in PGF Works} The core idea behind graph drawing in \pgfname\ is that inside special -\emph{graph drawing scopes} whenever \pgfname\ creates a node, we -intercept this node creation and \emph{do not} immediately place the -node. Rather, we pass it down to Lua part of the graph drawing system -via calls to appropriate methods of the (Lua) class -|InterfaceToDisplay|. The effect will be that the nodes are ``tucked -away'' in some internal tables. For edges, we introduce a -special command called |\pgfgdedge| that tells the graph drawing -system that there is an edge between two tucked-away nodes. Then, -at the end of the graph drawing scope, a graph drawing algorithm -written in Lua starts to work on the graph by computing new positions -for the nodes. Once the algorithm has finished, the graph drawing -system starts sending back the nodes and edges to \pgfname\ via the -methods of the class |BindingToPGF|. These methods reinsert some code -into the \TeX\ output stream that finally places the nodes at -their final positions. Note that graph drawing algorithms are -perfectly oblivious to all of this; indeed, the graph drawing -algorithms can even be used independently of \TeX. - -Let us have a look at a simple example to see what happens when a -graph is specified: - +\emph{graph drawing scopes} whenever \pgfname\ creates a node, we intercept +this node creation and \emph{do not} immediately place the node. Rather, we +pass it down to Lua part of the graph drawing system via calls to appropriate +methods of the (Lua) class |InterfaceToDisplay|. The effect will be that the +nodes are ``tucked away'' in some internal tables. For edges, we introduce a +special command called |\pgfgdedge| that tells the graph drawing system that +there is an edge between two tucked-away nodes. Then, at the end of the graph +drawing scope, a graph drawing algorithm written in Lua starts to work on the +graph by computing new positions for the nodes. Once the algorithm has +finished, the graph drawing system starts sending back the nodes and edges to +\pgfname\ via the methods of the class |BindingToPGF|. These methods reinsert +some code into the \TeX\ output stream that finally places the nodes at their +final positions. Note that graph drawing algorithms are perfectly oblivious to +all of this; indeed, the graph drawing algorithms can even be used +independently of \TeX. + +Let us have a look at a simple example to see what happens when a graph is +specified: +% \begin{codeexample}[] \tikz[tree layout] \graph {root [as=Hello] -> World[fill=blue!20]}; \end{codeexample} The key |tree layout| internally calls the key |request scope and layout|, -which in turn calls the macro |\pgfgdbeginscope|, which starts a graph -drawing scope inside the graph drawing system. Once this macro has been -called, until the next call of |\pgfgdendscope|, all nodes that are -created actually get passed down to the graph drawing engine. This is -implemented on the lowest layer, namely by directly intercepting -nodes freshly created using |\pgfnode|. In our example, this happens -in two places: For the |root| node and for the |World| node. The -|graph| library and \tikzname\ internally call the |\pgfnode| macro -for these two nodes (after a large number of internal syntax -translations, but the graph drawing system does not care about them). - -Note that the node boxes will have been fully created before they are -passed down to the graph drawing engine -- only their final position -is not yet fixed. It is not possible to modify the size of nodes -inside the graph drawing engine, but you can create new nodes in -certain situations. - -In contrast, the single edge of the graph that is created by the |->| -command is not fully created before it is passed down to the -graph drawing system. This would not really make sense since before the final -positions of the nodes are fixed, we cannot even begin to compute the -length of this edge, let alone where it should start or end. For this -reason, on the upper \tikzname\ layer, the normal edge creation that -would be caused by |->| via |new ->| is suppressed. Instead, the -command |\pgfgdedge| is called. Similarly, inside a graph drawing -scope, \tikzname\ will suppress both the |edge| and the -|edge from parent| command and cause |\pgfgdedge| to be called -instead. +which in turn calls the macro |\pgfgdbeginscope|, which starts a graph drawing +scope inside the graph drawing system. Once this macro has been called, until +the next call of |\pgfgdendscope|, all nodes that are created actually get +passed down to the graph drawing engine. This is implemented on the lowest +layer, namely by directly intercepting nodes freshly created using |\pgfnode|. +In our example, this happens in two places: For the |root| node and for the +|World| node. The |graph| library and \tikzname\ internally call the |\pgfnode| +macro for these two nodes (after a large number of internal syntax +translations, but the graph drawing system does not care about them). + +Note that the node boxes will have been fully created before they are passed +down to the graph drawing engine -- only their final position is not yet fixed. +It is not possible to modify the size of nodes inside the graph drawing engine, +but you can create new nodes in certain situations. + +In contrast, the single edge of the graph that is created by the |->| command +is not fully created before it is passed down to the graph drawing system. This +would not really make sense since before the final positions of the nodes are +fixed, we cannot even begin to compute the length of this edge, let alone where +it should start or end. For this reason, on the upper \tikzname\ layer, the +normal edge creation that would be caused by |->| via |new ->| is suppressed. +Instead, the command |\pgfgdedge| is called. Similarly, inside a graph drawing +scope, \tikzname\ will suppress both the |edge| and the |edge from parent| +command and cause |\pgfgdedge| to be called instead. An overview of what happens is illustrated by the following call graph: @@ -118,131 +112,132 @@ An overview of what happens is illustrated by the following call graph: object node/.style={draw,minimum size=15pt, fill=yellow!20}, p/.style={->,>=spaced stealth'}, livespan/.style={very thick}, - xscale=0.8] - % class names above - \node (tikz) at (0,4) [class name] {\tikzname\ layer (\TeX)}; - \node (tex) at (6,4) [class name] {\pgfname\ layer (\TeX)}; - \node (interface) at (13,4) [class name] {Display layer (Lua)}; - % lines from the class names to the bottom of the picture - \draw[livespan] (tikz) -- (0,-6.5); - \draw[livespan] (tex) -- (6,-6.5); - \draw[livespan] (interface) -- (13,-6.5); - % first command: \graph{ -- generates new graph in lua interface - \node (tikz-begin-graph) at (0,3) [object node] {|\graph[... layout]{|}; %} - \node (tex-begin-graph) at (6,3) [object node] {|\pgfgdbeginscope|}; - \node (interface-new-graph) at (13,3) [object node] {|beginGraphDrawingScope(|...|)|}; - \draw [p] (tikz-begin-graph.east) -- (tex-begin-graph.west); - \draw [p] (tex-begin-graph.east) -- (interface-new-graph.west); - % second command: a -> b -- generates two nodes in lua - % and one edge - \node (tikz-node) at (0,2) [object node] {|a -> b;|}; - \node (tex-node) at (6,2) [object node, double copy shadow] {|\pgfnode|}; - \draw[p] (tikz-node.east) -- (tex-node.west); - - \node (interface-add-node) at (13,2) [object node, double copy shadow] {|createVertex(|...|)|}; - \draw[p] (tex-node.east) -- (interface-add-node.west); - - \node (tex-add-edge) at (6,1) [object node, double copy shadow] {|\pgfgdedge|}; - \node (interface-add-edge) at (13,1) [object node, double copy shadow] {|createEdge(|...|)|}; - \draw[p] (tikz-node.east) -- (1.5,2) -- (1.5,1) -- (tex-add-edge.west); - \draw[p] (tex-add-edge.east) -- (interface-add-edge.west); - - % scope ends -- cloes graph, layouts it and draws it - \node (tikz-end) at (0,0) [object node] {|};|}; - \node (tex-end) at (6,0) [object node] {|\pgfgdendscope|}; - \node (interface-draw-graph) at (13,0) [object node] {|runGraphDrawingAlgorithm()|}; - \node (interface-finish-graph) at (13,-2) [object node] {|endGraphDrawingScope()|}; - - \node (invoke-algorithm) at (15.5,-1) [object node] {invoke algorithm}; - \draw[p] (tikz-end.east) -- (tex-end.west); - \draw[p] (tex-end.east) -- (interface-draw-graph.west); - \draw[p] (interface-draw-graph.east) -| (invoke-algorithm.20); - \draw[p] (tex-end.east) -- (9.5,0) -- (9.5,-2) -- (interface-finish-graph.west); - - % begin shipout - \node (tex-begin-shipout) at (6,-3) [object node] {|\pgfgdcallbackbeginshipout|}; - - \node (tex-puttexbox) at (6,-4) [object node, double copy shadow] {|\pgfgdcallbackrendernode|}; - \node (tex-putedge) at (6,-5) [object node, double copy shadow] {|\pgfgddefaultedgecallback|}; - - \node (tex-end-shipout) at (6,-6) [object node] {|\pgfgdcallbackendshipout|}; - - \draw [p] (interface-finish-graph.-170) |- (tex-begin-shipout.east); - \draw [p] (interface-finish-graph.-170) |- (tex-puttexbox.east); - \draw [p] (interface-finish-graph.-170) |- (tex-putedge.east); - \draw [p] (interface-finish-graph.-170) |- (tex-end-shipout.east); - %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-4) -- (sys-puttexbox.west); - - % put edge - %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-5) -- (sys-put-edge.west); - % end shipout - %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-6) -- (sys-end-shipout.west); + xscale=0.8, +] + % class names above + \node (tikz) at (0,4) [class name] {\tikzname\ layer (\TeX)}; + \node (tex) at (6,4) [class name] {\pgfname\ layer (\TeX)}; + \node (interface) at (13,4) [class name] {Display layer (Lua)}; + % lines from the class names to the bottom of the picture + \draw[livespan] (tikz) -- (0,-6.5); + \draw[livespan] (tex) -- (6,-6.5); + \draw[livespan] (interface) -- (13,-6.5); + % first command: \graph{ -- generates new graph in lua interface + \node (tikz-begin-graph) at (0,3) [object node] {|\graph[... layout]{|}; %} + \node (tex-begin-graph) at (6,3) [object node] {|\pgfgdbeginscope|}; + \node (interface-new-graph) at (13,3) [object node] {|beginGraphDrawingScope(|...|)|}; + \draw [p] (tikz-begin-graph.east) -- (tex-begin-graph.west); + \draw [p] (tex-begin-graph.east) -- (interface-new-graph.west); + % second command: a -> b -- generates two nodes in lua + % and one edge + \node (tikz-node) at (0,2) [object node] {|a -> b;|}; + \node (tex-node) at (6,2) [object node, double copy shadow] {|\pgfnode|}; + \draw[p] (tikz-node.east) -- (tex-node.west); + + \node (interface-add-node) at (13,2) [object node, double copy shadow] {|createVertex(|...|)|}; + \draw[p] (tex-node.east) -- (interface-add-node.west); + + \node (tex-add-edge) at (6,1) [object node, double copy shadow] {|\pgfgdedge|}; + \node (interface-add-edge) at (13,1) [object node, double copy shadow] {|createEdge(|...|)|}; + \draw[p] (tikz-node.east) -- (1.5,2) -- (1.5,1) -- (tex-add-edge.west); + \draw[p] (tex-add-edge.east) -- (interface-add-edge.west); + + % scope ends -- cloes graph, layouts it and draws it + \node (tikz-end) at (0,0) [object node] {|};|}; + \node (tex-end) at (6,0) [object node] {|\pgfgdendscope|}; + \node (interface-draw-graph) at (13,0) [object node] {|runGraphDrawingAlgorithm()|}; + \node (interface-finish-graph) at (13,-2) [object node] {|endGraphDrawingScope()|}; + + \node (invoke-algorithm) at (15.5,-1) [object node] {invoke algorithm}; + \draw[p] (tikz-end.east) -- (tex-end.west); + \draw[p] (tex-end.east) -- (interface-draw-graph.west); + \draw[p] (interface-draw-graph.east) -| (invoke-algorithm.20); + \draw[p] (tex-end.east) -- (9.5,0) -- (9.5,-2) -- (interface-finish-graph.west); + + % begin shipout + \node (tex-begin-shipout) at (6,-3) [object node] {|\pgfgdcallbackbeginshipout|}; + + \node (tex-puttexbox) at (6,-4) [object node, double copy shadow] {|\pgfgdcallbackrendernode|}; + \node (tex-putedge) at (6,-5) [object node, double copy shadow] {|\pgfgddefaultedgecallback|}; + + \node (tex-end-shipout) at (6,-6) [object node] {|\pgfgdcallbackendshipout|}; + + \draw [p] (interface-finish-graph.-170) |- (tex-begin-shipout.east); + \draw [p] (interface-finish-graph.-170) |- (tex-puttexbox.east); + \draw [p] (interface-finish-graph.-170) |- (tex-putedge.east); + \draw [p] (interface-finish-graph.-170) |- (tex-end-shipout.east); + %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-4) -- (sys-puttexbox.west); + + % put edge + %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-5) -- (sys-put-edge.west); + % end shipout + %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-6) -- (sys-end-shipout.west); \end{tikzpicture} \medskip -The above diagram glosses over the fact that the display layer does -not actually call any of the macros of \TeX\ directly, but uses a so -called \emph{binding} (see the class |BindingToPGF|). However, this -will not be important for the present section since you cannot access -the binding directly. - +The above diagram glosses over the fact that the display layer does not +actually call any of the macros of \TeX\ directly, but uses a so called +\emph{binding} (see the class |BindingToPGF|). However, this will not be +important for the present section since you cannot access the binding directly. \subsubsection{Graph Drawing Scopes} - \label{section-gd-scopes} -When the graph drawing system is active, some pretty basic things -inside \pgfname\ change -- such as the fact that nodes are no longer -created in the normal manner. For this reason, the graph drawing -system must be switched on and of explicitly through opening and -closing a so called \emph{graph drawing scope}. These scopes can, in -principle, be nested, namely a graph contains a node that -contains some text that in turn contains a subpicture that contains a -drawing of a graph. However, this is \emph{not} the same as subgraphs -nodes and sublayouts, which are all part of the same graph drawing -scope. Normally, graph drawing scopes are not nested. +When the graph drawing system is active, some pretty basic things inside +\pgfname\ change -- such as the fact that nodes are no longer created in the +normal manner. For this reason, the graph drawing system must be switched on +and of explicitly through opening and closing a so called \emph{graph drawing +scope}. These scopes can, in principle, be nested, namely a graph contains a +node that contains some text that in turn contains a subpicture that contains a +drawing of a graph. However, this is \emph{not} the same as subgraphs nodes and +sublayouts, which are all part of the same graph drawing scope. Normally, graph +drawing scopes are not nested. Graph drawing scopes are created using the following commands: \begin{command}{\pgfgdbeginscope} - This macro starts a \TeX\ scope inside which the following things - happen: - \begin{enumerate} - \item The display layer method |beginGraphDrawingScope| is - called, which created a new graph drawing scope inside the graph - drawing system and places it on top of an internal stack. From now - on, all subsequent interface calls will refer to this scope until - |\pgfgdendscope| is called, which will pop the scope once more. - \item Inside the \TeX\ scope, nodes are not placed - immediately. Rather, |\pgfpositionnodelater|, see - Section~\ref{section-shapes-deferred-node-positioning}, is used to - call |InterfaceToDisplay.createVertex| for all nodes created - inside the scope. This will cause them to be put inside some internal - table. - \item Some additional \meta{code} is executed, which has been set - using the following command: - \begin{command}{\pgfgdaddspecificationhook\marg{code}} - This command adds the \meta{code} to the code that is executed - whenever a graph drawing scope starts. For instance, the - \tikzname\ library |graphdrawing| uses this macro to add some - \meta{code} that will redirect the |edge| and |edge from parent| - path commands to |\pgfgdedge|. - \end{command} - \item |\pgftransformreset| is called. - \item The following \TeX-if is set to true: - { - \let\ifpgfgdgraphdrawingscopeactive=\relax - \begin{textoken}{\ifpgfgdgraphdrawingscopeactive} - Will be true inside a graph drawing scope. - \end{textoken} - } - \end{enumerate} - The above has a number of consequences for what can happen inside a - graph drawing scope: - \begin{itemize} - \item Since nodes are not actually created before the end of the - scope, you cannot reference these nodes. Thus, you cannot write + This macro starts a \TeX\ scope inside which the following things happen: + % + \begin{enumerate} + \item The display layer method |beginGraphDrawingScope| is called, + which created a new graph drawing scope inside the graph drawing + system and places it on top of an internal stack. From now on, all + subsequent interface calls will refer to this scope until + |\pgfgdendscope| is called, which will pop the scope once more. + \item Inside the \TeX\ scope, nodes are not placed immediately. Rather, + |\pgfpositionnodelater|, see + Section~\ref{section-shapes-deferred-node-positioning}, is used to + call |InterfaceToDisplay.createVertex| for all nodes created inside + the scope. This will cause them to be put inside some internal + table. + \item Some additional \meta{code} is executed, which has been set using + the following command: + % + \begin{command}{\pgfgdaddspecificationhook\marg{code}} + This command adds the \meta{code} to the code that is executed + whenever a graph drawing scope starts. For instance, the + \tikzname\ library |graphdrawing| uses this macro to add some + \meta{code} that will redirect the |edge| and + |edge from parent| path commands to |\pgfgdedge|. + \end{command} + \item |\pgftransformreset| is called. + \item The following \TeX-if is set to true: + { + \let\ifpgfgdgraphdrawingscopeactive=\relax + \begin{textoken}{\ifpgfgdgraphdrawingscopeactive} + Will be true inside a graph drawing scope. + \end{textoken} + } + \end{enumerate} + % + The above has a number of consequences for what can happen inside a graph + drawing scope: + % + \begin{itemize} + \item Since nodes are not actually created before the end of the scope, + you cannot reference these nodes. Thus, you cannot write + % \begin{codeexample}[code only] \tikz [spring layout] { \node (a) {a}; @@ -250,318 +245,296 @@ Graph drawing scopes are created using the following commands: \draw (a) -- (b); } \end{codeexample} - The problem is that we cannot connect |(a)| and |(b)| via a - straight line since these nodes do not exist at that point (they - are available only deeply inside the Lua). - \item In order to create edges between nodes inside a graph drawing - scope, you need to call the |\pgfgdedge| command, described below. - \end{itemize} - - Additionally, when \tikzname\ is used, the following things also - happen: - \begin{itemize} - \item If the |graphs| library has been loaded, the default - positioning mechanisms of this library are switched off, leaving - the positioning to the graph drawing engine. Also, when an edge is - created by the |graphs| library, this is signalled to the graph - drawing library. (To be more precise: The keys |new ->| and so on - are redefined so that they call |\pgfgdedge| instead of creating - an edge. - \item The |edge| path command is modified so that it also calls - |\pgfgdedge| instead of immediately creating any edges. - \item The |edge from parent| path command is modified so that is - also calls |\pgfgdedge|. - \item The keys |append after command| and |prefix after command| - keys are modified so that they are executed only via - |late options| when the node has ``reached its final parking - position''. - \end{itemize} - - Note that inside a graph drawing scope you first have to open a - (main) layout scope (using the |\pgfgdbeginlayout| command described - later on) before you can add nodes and edges to the scope. + % + The problem is that we cannot connect |(a)| and |(b)| via a + straight line since these nodes do not exist at that point (they + are available only deeply inside the Lua). + \item In order to create edges between nodes inside a graph drawing + scope, you need to call the |\pgfgdedge| command, described below. + \end{itemize} + + Additionally, when \tikzname\ is used, the following things also happen: + % + \begin{itemize} + \item If the |graphs| library has been loaded, the default positioning + mechanisms of this library are switched off, leaving the + positioning to the graph drawing engine. Also, when an edge is + created by the |graphs| library, this is signalled to the graph + drawing library. (To be more precise: The keys |new ->| and so on + are redefined so that they call |\pgfgdedge| instead of creating an + edge. + \item The |edge| path command is modified so that it also calls + |\pgfgdedge| instead of immediately creating any edges. + \item The |edge from parent| path command is modified so that is also + calls |\pgfgdedge|. + \item The keys |append after command| and |prefix after command| keys + are modified so that they are executed only via |late options| when + the node has ``reached its final parking position''. + \end{itemize} + + Note that inside a graph drawing scope you first have to open a (main) + layout scope (using the |\pgfgdbeginlayout| command described later on) + before you can add nodes and edges to the scope. \end{command} - \begin{command}{\pgfgdendscope} - This macro is used to end a graph drawing scope. It must be given on - the same \TeX\ grouping level as the corresponding - |\pgfgdbeginscope|. When the macro is called, it triggers a lot of - new calls: - \begin{enumerate} - \item The special treatment of newly created boxes is ended. Nodes - are once more created normally. - \item The effects of the \meta{code} that was inserted via the - specification hook command also ends (provided it had no global - effects). - \item We call |InterfaceToDisplay.runGraphDrawingAlgorithm|. This - will cause the algorithm(s) for the graph to be executed (since a - graph can have sublayouts, several algorithms may be run). See - Section~\ref{section-gd-layout-scopes} below. - \item Next, we call |InterfaceToDisplay.endGraphDrawingScope|. - This causes all nodes that were intercepted during the - graph drawing scope to be reinserted into the output stream at the - positions that were computed for them. Also, for each edge that - was requested via |\pgfgdedge|, the callback macro is - called (see below). - \end{enumerate} + This macro is used to end a graph drawing scope. It must be given on the + same \TeX\ grouping level as the corresponding |\pgfgdbeginscope|. When the + macro is called, it triggers a lot of new calls: + % + \begin{enumerate} + \item The special treatment of newly created boxes is ended. Nodes are + once more created normally. + \item The effects of the \meta{code} that was inserted via the + specification hook command also ends (provided it had no global + effects). + \item We call |InterfaceToDisplay.runGraphDrawingAlgorithm|. This will + cause the algorithm(s) for the graph to be executed (since a graph + can have sublayouts, several algorithms may be run). See + Section~\ref{section-gd-layout-scopes} below. + \item Next, we call |InterfaceToDisplay.endGraphDrawingScope|. This + causes all nodes that were intercepted during the graph drawing + scope to be reinserted into the output stream at the positions that + were computed for them. Also, for each edge that was requested via + |\pgfgdedge|, the callback macro is called (see below). + \end{enumerate} \end{command} - -Inside a graph drawing scope, nodes are -automatically passed down to the graph drawing engine, while for edges -a command has to be called explicitly: - -\begin{command}{\pgfgdedge\marg{first node}\marg{second - node}\marg{edge direction}\marg{edge options}\marg{edge nodes}} - This command is used to tell the graph drawing engine that there is - an edge between \meta{first node} and \meta{second node} in your - graph. The ``kind'' of connection is indicated by \meta{direction}, - which may be one of the following: - \begin{itemize} - \item - |->| indicates a directed edge (also known as an arc) from - \meta{first node} to \meta{second node}. - \item |--| indicates an undirected edge between \meta{first node} - and \meta{second node}, - \item |<-| indicates a directed edge from \meta{second node} to - \meta{first node}, but with the ``additional hint'' that this is a - ``backward'' edge. A graph drawing algorithm may or may not take - this hint into account. - \item |<->| indicates a bi-directed edge between \meta{first node} - and \meta{second node}. - \item |-!-| indicates that the edge from \meta{first node} to - \meta{second node} is ``missing''. - \end{itemize} - Note that in all cases, the syntatic digraph will contain an arc - from \meta{first node} to \meta{second node}, regardless of the - value of \meta{direction}. The \meta{direction} is ``just'' a - ``semantic annotation''. - - The parameters \meta{edge options} and \meta{edge nodes} are a bit - more tricky. When an edge between two vertices of a graph is created - via |\pgfgdedge|, nothing is actually done immediately. After all, - without knowing the final positions of the nodes \meta{first node} - and \meta{second node}, there is no way of creating the actual - drawing commands for the edge. Thus, the actual drawing of the edge - is done only when the graph drawing algorithm is done (namely in the - macro |\pgfgdedgecallback|, see later). - - Because of this ``delayed'' drawing of edges, options that influence - the edge must be retained until the moment when the edge is actually - drawn. Parameters \meta{edge options} and \meta{edge nodes} store such - options. - - Let us start with \meta{edge options}. This parameter should be set - to a list of key-value pairs like +Inside a graph drawing scope, nodes are automatically passed down to the graph +drawing engine, while for edges a command has to be called explicitly: + +\begin{command}{\pgfgdedge\marg{first node}\marg{second node}\marg{edge direction}\marg{edge options}\marg{edge nodes}} + This command is used to tell the graph drawing engine that there is an edge + between \meta{first node} and \meta{second node} in your graph. The + ``kind'' of connection is indicated by \meta{direction}, which may be one + of the following: + % + \begin{itemize} + \item |->| indicates a directed edge (also known as an arc) from + \meta{first node} to \meta{second node}. + \item |--| indicates an undirected edge between \meta{first node} and + \meta{second node}, + \item |<-| indicates a directed edge from \meta{second node} to + \meta{first node}, but with the ``additional hint'' that this is a + ``backward'' edge. A graph drawing algorithm may or may not take + this hint into account. + \item |<->| indicates a bi-directed edge between \meta{first node} and + \meta{second node}. + \item |-!-| indicates that the edge from \meta{first node} to + \meta{second node} is ``missing''. + \end{itemize} + % + Note that in all cases, the syntactic digraph will contain an arc from + \meta{first node} to \meta{second node}, regardless of the value of + \meta{direction}. The \meta{direction} is ``just'' a ``semantic + annotation''. + + The parameters \meta{edge options} and \meta{edge nodes} are a bit more + tricky. When an edge between two vertices of a graph is created via + |\pgfgdedge|, nothing is actually done immediately. After all, without + knowing the final positions of the nodes \meta{first node} and \meta{second + node}, there is no way of creating the actual drawing commands for the + edge. Thus, the actual drawing of the edge is done only when the graph + drawing algorithm is done (namely in the macro |\pgfgdedgecallback|, see + later). + + Because of this ``delayed'' drawing of edges, options that influence the + edge must be retained until the moment when the edge is actually drawn. + Parameters \meta{edge options} and \meta{edge nodes} store such options. + + Let us start with \meta{edge options}. This parameter should be set to a + list of key--value pairs like + % \begin{codeexample}[code only] /tikz/.cd, color=red, very thick, orient=down \end{codeexample} - Some of these options may be of interest to the graph drawing - algorithm (like the last option) while others will - only be important during the drawing of edge (like the first - option). The options that are important for the graph drawing - algorithm must be pushed onto the graph drawing system's option - stack. - - The tricky part is that options that are of interest to the graph - drawing algorithm must be executed \emph{before} the algorithm starts, - but the options as a whole are usually only executed during the - drawing of the edges, which is \emph{after} the algorithm has finished. - To overcome this problem, the following happens: - - The options in \meta{edge options} are executed ``tentatively'' inside - |\pgfgdedge|. However, this execution is done in a ``heavily guarded - sandbox'' where all effects of the options (like changing the - color or the line width) do not propagate beyond the sandbox. Only - the changes of the graph drawing edge parameters leave the - sandbox. These parameters are then passed down to the graph drawing - system. - - Later, when the edge is drawn using |\pgfgdedgecallback|, the - options \meta{edge options} are available once more and then they - are executed normally. - - Note that when the options in \meta{edge options} are executed, no - path is preset. Thus, you typically need to start it with, say, - |/tikz/.cd|. Also note that the sandbox is not perfect and changing - global values will have an effect outside the sandbox. Indeed, - ``putting things in a sandbox'' just means that the options are - executed inside a \TeX\ scope inside an interrupted path inside a - \TeX\ box that is thrown away immediately. - - The text in \meta{edge nodes} is some ``auxilliary'' text that is - simply stored away and later directed to |\pgfgdedgecallback|. This - is used for instance by \tikzname\ to store its node labels. + % + Some of these options may be of interest to the graph drawing algorithm + (like the last option) while others will only be important during the + drawing of edge (like the first option). The options that are important for + the graph drawing algorithm must be pushed onto the graph drawing system's + option stack. + + The tricky part is that options that are of interest to the graph drawing + algorithm must be executed \emph{before} the algorithm starts, but the + options as a whole are usually only executed during the drawing of the + edges, which is \emph{after} the algorithm has finished. To overcome this + problem, the following happens: + + The options in \meta{edge options} are executed ``tentatively'' inside + |\pgfgdedge|. However, this execution is done in a ``heavily guarded + sandbox'' where all effects of the options (like changing the color or the + line width) do not propagate beyond the sandbox. Only the changes of the + graph drawing edge parameters leave the sandbox. These parameters are then + passed down to the graph drawing system. + + Later, when the edge is drawn using |\pgfgdedgecallback|, the options + \meta{edge options} are available once more and then they are executed + normally. + + Note that when the options in \meta{edge options} are executed, no path is + preset. Thus, you typically need to start it with, say, |/tikz/.cd|. Also + note that the sandbox is not perfect and changing global values will have + an effect outside the sandbox. Indeed, ``putting things in a sandbox'' just + means that the options are executed inside a \TeX\ scope inside an + interrupted path inside a \TeX\ box that is thrown away immediately. + + The text in \meta{edge nodes} is some ``auxiliary'' text that is simply + stored away and later directed to |\pgfgdedgecallback|. This is used for + instance by \tikzname\ to store its node labels. \end{command} - \begin{command}{\pgfgdsetedgecallback\marg{macro}} - This command allows you to change the \meta{macro} that gets called - form inside the graph drawing system at the end of the creation of a - graph, when the nodes have been positioned. The \meta{macro} will be - called once for each edge with the following parameters: - \begin{quote} - \meta{macro}\marg{first node}\marg{second - node}\marg{direction}\marg{edge options}\marg{edge - nodes}\\ - \marg{algorithm-generated options}\marg{bend information} - \end{quote} - - The first five parameters are the original values that were passed - down to the |\pgfgdedge| command. - - The \meta{algorithm-generated options} have been ``computed by the - algorithm''. For instance, an algorithm might have determined, say, - flow capacities for edges and it might now wish to communicate this - information back to the upper layers. These options should be - executed with the path |/graph drawing|. - - The parameter \meta{bend information} contains - algorithmically-computed information concerning how the - edge should bend. This will be a text like - |(10pt,20pt)--(30pt,40pt)| in \tikzname-syntax and may include the - path commands |--|, |..| (followed by B\'ezier coordintes), and - |--cycle|. - - The default \meta{macro} simply draws a line between the nodes. When - the |graphdrawing| library of the \tikzname\ layer is loaded, a more - fancy \meta{macro} is used that takes all of the parameters into - account. + This command allows you to change the \meta{macro} that gets called form + inside the graph drawing system at the end of the creation of a graph, when + the nodes have been positioned. The \meta{macro} will be called once for + each edge with the following parameters: + % + \begin{quote} + \meta{macro}\marg{first node}\marg{second node}\marg{direction}\marg{edge options}\marg{edge nodes}\\ + \marg{algorithm-generated options}\marg{bend information}\marg{animations} + \end{quote} + + The first five parameters are the original values that were passed down to + the |\pgfgdedge| command. + + The \meta{algorithm-generated options} have been ``computed by the + algorithm''. For instance, an algorithm might have determined, say, flow + capacities for edges and it might now wish to communicate this information + back to the upper layers. These options should be executed with the path + |/graph drawing|. + + The parameter \meta{bend information} contains algorithmically-computed + information concerning how the edge should bend. This will be a text like + |(10pt,20pt)--(30pt,40pt)| in \tikzname-syntax and may include the path + commands |--|, |..| (followed by Bézier coordinates), and |--cycle|. + + The parameter \meta{animations} contains algorithmically-generated + animation commands (calls to |\pgfanimateattribute|. The |whom| will be set + to |pgf@gd|. + + The default \meta{macro} simply draws a line between the nodes. When the + |graphdrawing| library of the \tikzname\ layer is loaded, a more fancy + \meta{macro} is used that takes all of the parameters into account. \end{command} - \subsection{Layout Scopes} \label{section-gd-layout-scopes} -As described in Section~\ref{section-gd-sublayouts}, the graph drawing -engine does not always apply only a single algorithm. Rather, several -different algorithm may be applied to different parts of the -graph. How this happens, exactly, is goverened by a hierarchy of -layouts, which are setup using the commands |\pgfgdbeginlayout| and -|\pgfgdendlayout|. - +As described in Section~\ref{section-gd-sublayouts}, the graph drawing engine +does not always apply only a single algorithm. Rather, several different +algorithm may be applied to different parts of the graph. How this happens, +exactly, is governed by a hierarchy of layouts, which are setup using the +commands |\pgfgdbeginlayout| and |\pgfgdendlayout|. \begin{command}{\pgfgdbeginlayout} - This command first starts a new \TeX\ scope and then informs the - display layer that a new (sub)layout should be started. For each - graph there may be a hierarchy of layouts, each of which contains a - certain number of vertices and edges. This hierarchy is created - through calls to this macros and the corresponding calls of - |\pgfgdendlayout|. For each graph drawing scope there has to be - exactly one main layout that encompasses all nodes and edges and - also all sublayouts. Thus, after a graph drawing scope has been - opened, a layout scope also needs to be opened almost immediately. - - For each layout created via this macro, a graph drawing algorithm - will be run later on on the subgraph of all nodes that make up the - layout. Which algorithm is run for the layout is dictated by which - layout key (one of the |... layout| keys) is ``in force'' when the - macro is called. Thus, using a layout key for selecting an algorithm - must always be done \emph{before} the layout is started. (However, - see the discussion of layout keys in the next subsection for more - details on what really happens.) - - A vertex can be part of several layouts, either because they are - nested or because they overlap (this happens when a node is later on - added to another layout by calling |\pgfgdsetlatenodeoption|). This - means that it is not immediately obvious how conflicts arising from - the different ways different algorithms ``would like to place - nodes'' should be resolved. The method for this resolving is - detailed in Section~\ref{section-gd-layout-resolve}. + This command first starts a new \TeX\ scope and then informs the display + layer that a new (sub)layout should be started. For each graph there may be + a hierarchy of layouts, each of which contains a certain number of vertices + and edges. This hierarchy is created through calls to this macros and the + corresponding calls of |\pgfgdendlayout|. For each graph drawing scope + there has to be exactly one main layout that encompasses all nodes and + edges and also all sublayouts. Thus, after a graph drawing scope has been + opened, a layout scope also needs to be opened almost immediately. + + For each layout created via this macro, a graph drawing algorithm will be + run later on the subgraph of all nodes that make up the layout. Which + algorithm is run for the layout is dictated by which layout key (one of the + |... layout| keys) is ``in force'' when the macro is called. Thus, using a + layout key for selecting an algorithm must always be done \emph{before} the + layout is started. (However, see the discussion of layout keys in the next + subsection for more details on what really happens.) + + A vertex can be part of several layouts, either because they are nested or + because they overlap (this happens when a node is later on added to another + layout by calling |\pgfgdsetlatenodeoption|). This means that it is not + immediately obvious how conflicts arising from the different ways different + algorithms ``would like to place nodes'' should be resolved. The method for + this resolving is detailed in Section~\ref{section-gd-layout-resolve}. \end{command} \begin{command}{\pgfgdendlayout} - This command ends the \TeX\ scope of the current layout. Once - closed, no nodes or edges can be added to a layout. + This command ends the \TeX\ scope of the current layout. Once closed, no + nodes or edges can be added to a layout. \end{command} - \begin{command}{\pgfgdsetlatenodeoption\marg{node name}} - This command can only be called when the node named \meta{node name} - has already been created inside the current graph drawing scope. The - effect of calling this macro will be that all options currently on - the graph drawing system's option stack will be added to the node's - option, possibly overwriting the original option - settings. Furthermore, the node will become part of all layouts - currently on the option stack. This means that you can use this - command to add a node to several layouts that are not included in - one another. + This command can only be called when the node named \meta{node name} has + already been created inside the current graph drawing scope. The effect of + calling this macro will be that all options currently on the graph drawing + system's option stack will be added to the node's option, possibly + overwriting the original option settings. Furthermore, the node will become + part of all layouts currently on the option stack. This means that you can + use this command to add a node to several layouts that are not included in + one another. \end{command} - \subsection{Layout Keys} -\emph{Layout keys} are keys like |tree layout| -or |layered layout| that are used to select a specific graph drawing -algorithm. From the graph drawing system's point of view, these keys -``just'' select an algorithm and when several layout keys are used in -a row, the last one would ``win''; just as when you say |orient=90| directly -followed by |orient=0|, the result is that the |orient| key is set to -|0| because the last key ``wins.'' - -Unfortunately, if keys like |tree layout| were ``just'' to select an -algorithm, we would still need a key or some special syntax to -actually start a (sub)layout. In early versions of the system this was -exactly what people had to do and this was somewhat awkward. Because -of this problem, the behaviour of the layout keys in \pgfname\ (and -only there, other display layers need to implement their own -behaviour) is now a bit more involved. When you use a key like -|tree layout| (more precisely, any key that -was declared as an algorithm key on the algorithm layer of the graph -drawing system) in any scope in \pgfname, the following happens: +\emph{Layout keys} are keys like |tree layout| or |layered layout| that are +used to select a specific graph drawing algorithm. From the graph drawing +system's point of view, these keys ``just'' select an algorithm and when +several layout keys are used in a row, the last one would ``win''; just as when +you say |orient=90| directly followed by |orient=0|, the result is that the +|orient| key is set to |0| because the last key ``wins''. + +Unfortunately, if keys like |tree layout| were ``just'' to select an algorithm, +we would still need a key or some special syntax to actually start a +(sub)layout. In early versions of the system this was exactly what people had +to do and this was somewhat awkward. Because of this problem, the behaviour of +the layout keys in \pgfname\ (and only there, other display layers need to +implement their own behaviour) is now a bit more involved. When you use a key +like |tree layout| (more precisely, any key that was declared as an algorithm +key on the algorithm layer of the graph drawing system) in any scope in +\pgfname, the following happens: +% \begin{enumerate} -\item The graph drawing system is told that a specific algorithm has - been selected (the Reingold--Tilford-algorithm in this case; this - information was communicated to the graph drawing system during the - declaration of the algorithm). Being ``told'' about this means that - a special entry is pushed onto the current options stack of the - graph drawing system. -\item An internal ``request'' for a ``scope and a layout'' is - made. This has several effects: -\item - We first test whether we are already inside a layout scope. If not, - we use |\pgfgdbeginscope| to open a graph drawing scope. This - scope will be closed appropriately (see |\pgfgdsetrequestcallback| - for details). -\item - Next, a layout scope is opened using |\pgfgdbeginlayout|. It will - also be closed appropriately. + \item The graph drawing system is told that a specific algorithm has been + selected (the Reingold--Tilford-algorithm in this case; this + information was communicated to the graph drawing system during the + declaration of the algorithm). Being ``told'' about this means that a + special entry is pushed onto the current options stack of the graph + drawing system. + \item An internal ``request'' for a ``scope and a layout'' is made. This + has several effects: + \item We first test whether we are already inside a layout scope. If not, + we use |\pgfgdbeginscope| to open a graph drawing scope. This scope + will be closed appropriately (see |\pgfgdsetrequestcallback| for + details). + \item Next, a layout scope is opened using |\pgfgdbeginlayout|. It will + also be closed appropriately. \end{enumerate} -The net effect of the above is that the first use of a layout key in a -picture starts both a graph drawing scope and also a main layout, -while subsequent uses of layout keys inside a picture will only open -sublayouts. +The net effect of the above is that the first use of a layout key in a picture +starts both a graph drawing scope and also a main layout, while subsequent uses +of layout keys inside a picture will only open sublayouts. \begin{command}{\pgfgdsetrequestcallback\marg{macro}} - This command sets up \meta{macro} as the macro that is called - whenever a layout key ``requests'' that a layout and, possibly, a - graph drawing scope is opened. When \meta{macro} is called, it gets - two parameters, the \meta{begin code} and the \meta{end code}. In - addition to whatever setup the \meta{macro} would like to do, it - should execute the \meta{begin code} at the beginning of a \TeX\ - scope (the code will open graph drawing and layout scopes) and the - \meta{end code} at the end of the same \TeX\ scope. - - The need for this slightly strange macro arises from the fact that - in \tikzname\ we often write things like - |[spring layout,node sep=2cm]|. The point is that when the - |spring layout| key is executed, we do \emph{not} wish to open a - layout scope immediately. Rather, this should happen only after the - option |nodes sep=2cm| has been executed. For this reason, \tikzname\ - sets up a special \meta{macro} that ``delays'' the execution of the - \meta{begin code} until the end of the opening of the next scope. - - Because of this, in \tikzname\ layout keys can only be used as an - option when a \tikzname\ scope is started. Thus, you can - pass them to |\tikz|, to |{tikzpicture}|, to |\scoped|, to |{scope}|, - to |graph|, and to |{graph}|. For instance, the |tree layout| option can - be used in the following ways: + This command sets up \meta{macro} as the macro that is called whenever a + layout key ``requests'' that a layout and, possibly, a graph drawing scope + is opened. When \meta{macro} is called, it gets two parameters, the + \meta{begin code} and the \meta{end code}. In addition to whatever setup + the \meta{macro} would like to do, it should execute the \meta{begin code} + at the beginning of a \TeX\ scope (the code will open graph drawing and + layout scopes) and the \meta{end code} at the end of the same \TeX\ scope. + + The need for this slightly strange macro arises from the fact that in + \tikzname\ we often write things like |[spring layout,node sep=2cm]|. The + point is that when the |spring layout| key is executed, we do \emph{not} + wish to open a layout scope immediately. Rather, this should happen only + after the option |nodes sep=2cm| has been executed. For this reason, + \tikzname\ sets up a special \meta{macro} that ``delays'' the execution of + the \meta{begin code} until the end of the opening of the next scope. + + Because of this, in \tikzname\ layout keys can only be used as an option + when a \tikzname\ scope is started. Thus, you can pass them to |\tikz|, to + |{tikzpicture}|, to |\scoped|, to |{scope}|, to |graph|, and to |{graph}|. + For instance, the |tree layout| option can be used in the following ways: + % \begin{codeexample}[] -\tikz [tree layout] \graph {1 -> {b,c}}; +\tikz [tree layout] \graph {1 -> {b,c}}; \tikz \graph [tree layout] {2 -> {b,c}}; \tikz \path graph [tree layout] {3 -> {b,c}}; @@ -571,17 +544,17 @@ sublayouts. \begin{tikzpicture} \scoped [tree layout] \graph {5 -> {b,c}}; - + \begin{scope}[tree layout, xshift=1.5cm] \graph {6 -> {b,c}}; \end{scope} \end{tikzpicture} \end{codeexample} - You can \emph{not} use layout keys with a single - node or on a path. In particular, to typeset a tree given in the - |child| syntax somewhere inside a |{tikzpicture}|, you must prefix - it with the |\scoped| command: + You can \emph{not} use layout keys with a single node or on a path. In + particular, to typeset a tree given in the |child| syntax somewhere inside + a |{tikzpicture}|, you must prefix it with the |\scoped| command: + % \begin{codeexample}[] \begin{tikzpicture} \scoped [tree layout] @@ -590,132 +563,121 @@ sublayouts. child { node {right child} }; \end{tikzpicture} \end{codeexample} - Naturally, the above could have been written more succinctly as + % + Naturally, the above could have been written more succinctly as + % \begin{codeexample}[] \tikz [tree layout] \node {root} child { node {left child} } child { node {right child} }; \end{codeexample} - Or even more succinctly: + % + Or even more succinctly: + % \begin{codeexample}[] \tikz \graph [tree layout] { root -- {left child, right child} }; \end{codeexample} + % \end{command} - \subsection{Parameters} \label{section-gd-parameters} -When a graph drawing algorithm starts working, a set of options, -called ``graph drawing parameters'' or just ``parameters'' can influence -the way the algorithm works. For instance, a graph drawing parameter -might be the average distance between vertices which the algorithm -should take into account. Another example might be the fact the -certain nodes are special nodes and that a certain edge should have -a large label. +When a graph drawing algorithm starts working, a set of options, called ``graph +drawing parameters'' or just ``parameters'' can influence the way the algorithm +works. For instance, a graph drawing parameter might be the average distance +between vertices which the algorithm should take into account. Another example +might be the fact the certain nodes are special nodes and that a certain edge +should have a large label. -These graph drawing parameters are different from ``usual'' \pgfname\ -options: An alogrithmic parameter influences the way the algorithm -works, while usual options influence the way the result -looks like. For instance, the fact that a node is red is not a -graph drawing parameter, while the shape of a node might be an graph -drawing parameter. +These graph drawing parameters are different from ``usual'' \pgfname\ options: +An algorithmic parameter influences the way the algorithm works, while usual +options influence the way the result looks like. For instance, the fact that a +node is red is not a graph drawing parameter, while the shape of a node might +be an graph drawing parameter. -The possible graph parameters are declared by the algorithmic layer -through the |declare| method; you cannot declare parameters on the -\pgfname\ layer since this would not be compatible across different -display systems. +The possible graph parameters are declared by the algorithmic layer through the +|declare| method; you cannot declare parameters on the \pgfname\ layer since +this would not be compatible across different display systems. -Users use a graph parameter in the same way as a normal key. The -difference is that each time a key representing a graph drawing -parameter is used, a special function of the graph drawing system's -interface is called to ``push'' the parameter onto an internal option -stack (and elements are popped from this stack whenever the \TeX\ -scope closes in which the key was used). - -The net effect of all of this is that the graph drawing system keeps -track of a stack of option in parallel to \TeX. You cannot, however, -access the current values of graph drawing parameters from \TeX\ since -they are tucked away deep inside the graph drawing system. +Users use a graph parameter in the same way as a normal key. The difference is +that each time a key representing a graph drawing parameter is used, a special +function of the graph drawing system's interface is called to ``push'' the +parameter onto an internal option stack (and elements are popped from this +stack whenever the \TeX\ scope closes in which the key was used). +The net effect of all of this is that the graph drawing system keeps track of a +stack of option in parallel to \TeX. You cannot, however, access the current +values of graph drawing parameters from \TeX\ since they are tucked away deep +inside the graph drawing system. \subsection{Events} -\emph{Events} are used to pass information from the parser about the -syntactic structure of a graph to graph drawing algorithms. Consider, -for instance, a graph that is actually a tree in which some node -``misses'' its first child. In this case, the information that the -child is missing is neither part of any node (because the node is -missing, after all) nor is it an option of the whole graph. However, -events are created by the parser the allow an algorithm to reconstruct -the fact that the child is missing. Naturally, graph drawing +\emph{Events} are used to pass information from the parser about the syntactic +structure of a graph to graph drawing algorithms. Consider, for instance, a +graph that is actually a tree in which some node ``misses'' its first child. In +this case, the information that the child is missing is neither part of any +node (because the node is missing, after all) nor is it an option of the whole +graph. However, events are created by the parser the allow an algorithm to +reconstruct the fact that the child is missing. Naturally, graph drawing algorithms may choose to ignore events and most will. -Most of the creation and handling of events is done automatically. The -only reason you might wish to use the following commands is when you -write a ``parser extension'' together with a new graph drawing -algorithm. For instance, you might come up with new options that, when -used, trigger events. +Most of the creation and handling of events is done automatically. The only +reason you might wish to use the following commands is when you write a +``parser extension'' together with a new graph drawing algorithm. For instance, +you might come up with new options that, when used, trigger events. \begin{command}{\pgfgdevent\marg{kind}\marg{parameter}} - Calls |createEvent| of the graph drawing system's interface - class. This creates a new |Event| object on the Lua layer whose - |kind| field is set to \meta{kind} and the |parameters| field to - \meta{parameter}. You must be inside a graph drawing scope to use - this command. + Calls |createEvent| of the graph drawing system's interface class. This + creates a new |Event| object on the Lua layer whose |kind| field is set to + \meta{kind} and the |parameters| field to \meta{parameter}. You must be + inside a graph drawing scope to use this command. \end{command} \begin{command}{\pgfgdbegineventgroup\marg{parameter}} - Starts an event group. This just means that an |Event| of kind - |begin| is created with the given \meta{parameter}. + Starts an event group. This just means that an |Event| of kind |begin| is + created with the given \meta{parameter}. \end{command} \begin{command}{\pgfgdendeventgroup} - Ends an event group. This is done by adding an event of kind |end| - without any parameters to the event string. + Ends an event group. This is done by adding an event of kind |end| without + any parameters to the event string. \end{command} \begin{command}{\pgfgdeventgroup\marg{parameters}} - Starts an event group just like |\pgfgdbegineventgroup|, but adds a - corresponding closing |end| event at the end of the current \TeX\ - group (using |\aftergroup|). + Starts an event group just like |\pgfgdbegineventgroup|, but adds a + corresponding closing |end| event at the end of the current \TeX\ group + (using |\aftergroup|). \end{command} \subsection{Subgraph Nodes} \begin{command}{\pgfgdsubgraphnode\marg{name}\marg{node options}\marg{node text}} - A subgraph node is a node that ``surrounds'' the nodes 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 availble immediately as a normal node in the sense - that you can connect edges to it. - - What happens internally is that subgraph nodes get ``registered'' - immediately both on the \pgfname\ level and on the Lua level, but the - actual node is only created inside the layout pipeline using a - callback. The actual node creation happens when the innermost layout - in which the subgraph node is declared has finished. - - When you create a subgraph node using this macro, you also start a - collection (of an internal kind) that stores the subgraph. All - following nodes in the current \TeX\ scope will become part of this - collection. - - The \meta{name} is the node name by which you can refer to this node - in the following. The \meta{node options} are normal \pgfname\ - options (like |red| or |draw| or |circle|) that will influence the - appearance when it is created later on. The \meta{node text} is the - text that will be passed to |\pgfnode| upon creation of the node. - - See |InterfaceToDisplay.pushSubgraphVertex| for more details. + A subgraph node is a node that ``surrounds'' the nodes 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. + + What happens internally is that subgraph nodes get ``registered'' + immediately both on the \pgfname\ level and on the Lua level, but the + actual node is only created inside the layout pipeline using a callback. + The actual node creation happens when the innermost layout in which the + subgraph node is declared has finished. + + When you create a subgraph node using this macro, you also start a + collection (of an internal kind) that stores the subgraph. All following + nodes in the current \TeX\ scope will become part of this collection. + + The \meta{name} is the node name by which you can refer to this node in the + following. The \meta{node options} are normal \pgfname\ options (like |red| + or |draw| or |circle|) that will influence the appearance when it is + created later on. The \meta{node text} is the text that will be passed to + |\pgfnode| upon creation of the node. + + See |InterfaceToDisplay.pushSubgraphVertex| for more details. \end{command} - - - - - |