summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex339
1 files changed, 166 insertions, 173 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex
index d5848375067..46b1d5db041 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-display-layer.tex
@@ -15,159 +15,155 @@
\section{The Display Layer}
+\label{section-gd-display-layer}
{\noindent {\itshape{by Till Tantau}}}
-\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
-\label{section-gd-display-layer}
\begin{quote}
- \itshape You do not need to read this section in order to write new
- graph drawing algorithms. It is of interest only to those wishing to
- write programs that wish to ``use'' the graph drawing system in a
- similar way that \tikzname\ does for laying out graphs that are
- generated and then passed down from the program to the graph drawing
- system.
+ \itshape You do not need to read this section in order to write new graph
+ drawing algorithms. It is of interest only to those wishing to write
+ programs that wish to ``use'' the graph drawing system in a similar way
+ that \tikzname\ does for laying out graphs that are generated and then
+ passed down from the program to the graph drawing system.
\end{quote}
\subsection{Introduction: The Interplay of the Different Layers}
-The job of the graph drawing system is to run graph drawing algorithms
-on graphs. Since graph drawing is useful in many different contexts,
-not only in the context of \tikzname\ for which the present system was
-originally developed, the graph drawing system was designed in such a
-way that it can be used independently of \tikzname. To achieve this,
-the \emph{display layer} provides an interface via which an arbitrary
-program (\tikzname, a graph editor, a command line interface, etc.)
-``talk'' to the graph drawing system.
-
-To better understand how this works, let us consider the following
-setup:
+The job of the graph drawing system is to run graph drawing algorithms on
+graphs. Since graph drawing is useful in many different contexts, not only in
+the context of \tikzname\ for which the present system was originally
+developed, the graph drawing system was designed in such a way that it can be
+used independently of \tikzname. To achieve this, the \emph{display layer}
+provides an interface via which an arbitrary program (\tikzname, a graph
+editor, a command line interface, etc.) ``talk'' to the graph drawing system.
+To better understand how this works, let us consider the following setup:
+%
\begin{itemize}
-\item A program would like to communicate with the graph
- drawing system. It is written in Java and its job is to analyse social
- networks. This software would like to use graph drawing to produce
- drawings of some ``social graphs'' arising from its analyses. This
- software will be called ``the display system'' in the following.
-\item There are two algorithms that the display system would like to apply to
- the graphs its produces. Let us call these algorithms ``A'' and
- ``B''. However, the display system would also, ideally, wish to make it
- possible that its user chooses other algorithms ``C'' that are not
- necessarily part of its binary.
-\item The display system has internally generated a ``social graph'' that it
- would now like to draw.
+ \item A program would like to communicate with the graph drawing system. It
+ is written in Java and its job is to analyse social networks. This
+ software would like to use graph drawing to produce drawings of some
+ ``social graphs'' arising from its analyses. This software will be
+ called ``the display system'' in the following.
+ \item There are two algorithms that the display system would like to apply
+ to the graphs its produces. Let us call these algorithms ``A'' and
+ ``B''. However, the display system would also, ideally, wish to make it
+ possible that its user chooses other algorithms ``C'' that are not
+ necessarily part of its binary.
+ \item The display system has internally generated a ``social graph'' that
+ it would now like to draw.
\end{itemize}
-For this setup, the communication between the different layers of the
-graph drawing system is as follows:
-
+For this setup, the communication between the different layers of the graph
+drawing system is as follows:
+%
\begin{enumerate}
-\item The display system, being written in Java, must embed Lua to use the
- graph drawing system.
-\item The display system must initialize the graph drawing system. For this,
- it must use |require| on the file |InterfaceToDisplay|, which, as
- the name suggests, contains the interface between the display
- system and the graph drawing system.
-
- It must also create a so-called ``binding'' between the
- graph drawing system and the display layer. See
- Section~\ref{section-gd-binding-layer} for more information on
- bindings.
-\item The display system now needs to load the declarations of the
- algorithms A and B. For this, it just needs to apply |require| to
- the files in which the algorithms reside. This will cause the
- |declare| function to be called. This function is declared by
- |InterfaceToAlgorithms| and allows files to declare that certain
- algorithms and options are now available.
-
- Once this is done, the graph drawing system is fully initialized and
- can be used.
-\item Later on, the display system wishes to lay out a social graph. Note
- that this is known as ``drawing the graph'' in the graph drawing
- community, even though this only means the coordinates are computed
- for the nodes of the graph. The actual ``rendering'' of the graph on
- the display is the job of the display system (hence the name ``display
- layer'').
-\item To start the layout process, the display system calls the function
- |beginGraphDrawingScope| of the class |InterfaceToDisplay|.
-\item Next, for each vertex the function |createVertex| of the
- interface class must be called and similarly for each edge. These
- calls will cause an internal model of the graph to be created on the
- algorithm layer. Options that are attached to nodes and edges are
- also communicated to the graph drawing system through function calls
- like |pushOption|.
-\item When the graph is fully specified, the method
- |runGraphDrawingAlgorithm| must be called, which is once more a
- method of the interface class. This function will internally discern
- which algorithms have been chosen (via options) and invoke the code
- of the appropriate algorithms.
-\item Next, the function |renderGraph| must be called. Its job is to
- ``communicate back'' which coordinates have been computed. It will
- use the binding for this communication, see
- Section~\ref{section-gd-binding-layer}.
-\item Finally, by calling |endGraphDrawingScope|, the resources needed
- for the layout process for the social graph are freed once more.
+ \item The display system, being written in Java, must embed Lua to use the
+ graph drawing system.
+ \item The display system must initialize the graph drawing system. For
+ this, it must use |require| on the file |InterfaceToDisplay|, which, as
+ the name suggests, contains the interface between the display system
+ and the graph drawing system.
+
+ It must also create a so-called ``binding'' between the graph drawing
+ system and the display layer. See
+ Section~\ref{section-gd-binding-layer} for more information on
+ bindings.
+ \item The display system now needs to load the declarations of the
+ algorithms A and B. For this, it just needs to apply |require| to the
+ files in which the algorithms reside. This will cause the |declare|
+ function to be called. This function is declared by
+ |InterfaceToAlgorithms| and allows files to declare that certain
+ algorithms and options are now available.
+
+ Once this is done, the graph drawing system is fully initialized and
+ can be used.
+ \item Later on, the display system wishes to lay out a social graph. Note
+ that this is known as ``drawing the graph'' in the graph drawing
+ community, even though this only means the coordinates are computed for
+ the nodes of the graph. The actual ``rendering'' of the graph on the
+ display is the job of the display system (hence the name ``display
+ layer'').
+ \item To start the layout process, the display system calls the function
+ |beginGraphDrawingScope| of the class |InterfaceToDisplay|.
+ \item Next, for each vertex the function |createVertex| of the interface
+ class must be called and similarly for each edge. These calls will
+ cause an internal model of the graph to be created on the algorithm
+ layer. Options that are attached to nodes and edges are also
+ communicated to the graph drawing system through function calls like
+ |pushOption|.
+ \item When the graph is fully specified, the method
+ |runGraphDrawingAlgorithm| must be called, which is once more a method
+ of the interface class. This function will internally discern which
+ algorithms have been chosen (via options) and invoke the code of the
+ appropriate algorithms.
+ \item Next, the function |renderGraph| must be called. Its job is to
+ ``communicate back'' which coordinates have been computed. It will use
+ the binding for this communication, see
+ Section~\ref{section-gd-binding-layer}.
+ \item Finally, by calling |endGraphDrawingScope|, the resources needed for
+ the layout process for the social graph are freed once more.
\end{enumerate}
A few points may be noteworthy:
+%
\begin{itemize}
-\item The whole communication between the display system and the graph
- drawing system goes through the interface class via function
- calls. This makes it easy to communicate with display system whose
- internal model of graphs is quite different from the one used in Lua
- (as is certainly the case for \TeX, but also the ``social graph''
- mentioned above need not even exist as a separate entity inside the
- display system).
-
- \emph{The display system should only rely on the interface
- class. All communication has to go through this class, the
- display system may not access the internals of the internally
- constructed graphs directly.}
-\item New algorithms can be loaded at runtime, as long as the
- |require| method is supported.
-\item The display system can also use the interface class to query which
- algorithms and which options are available in principle (and display
- this information to the user). The display system can even get access the
- documentation of the options at runtime since the documentation is
- stored in fields of the declared options.
+ \item The whole communication between the display system and the graph
+ drawing system goes through the interface class via function calls.
+ This makes it easy to communicate with display system whose internal
+ model of graphs is quite different from the one used in Lua (as is
+ certainly the case for \TeX, but also the ``social graph'' mentioned
+ above need not even exist as a separate entity inside the display
+ system).
+
+ \emph{The display system should only rely on the interface class. All
+ communication has to go through this class, the display system may not
+ access the internals of the internally constructed graphs directly.}
+ \item New algorithms can be loaded at runtime, as long as the |require|
+ method is supported.
+ \item The display system can also use the interface class to query which
+ algorithms and which options are available in principle (and display
+ this information to the user). The display system can even get access
+ the documentation of the options at runtime since the documentation is
+ stored in fields of the declared options.
\end{itemize}
-
In the following, we first present a simple display system other than
-\tikzname. The remainder of the section then encompasses a
-documentation of the different functions of the class
-|InterfaceToDisplay|.
-
+\tikzname. The remainder of the section then encompasses a documentation of the
+different functions of the class |InterfaceToDisplay|.
\subsection{An Example Display System}
-In the following, we present the code of a very simple display system
-written in Lua (another such display system is \tikzname\ itself, but
-the minimal system will allow us to focus on what is really
-needed). You will also find it in |pgf.gd.examples.ASCIIDisplayer|.
-
-The job of this display system is to parse a string that encodes a graph
-and to call the appropriate functions of |InterfaceToDisplay| to lay
-out the graph. The actual calls for rendering the graph are part of
-the binding, which is documented in
-Section~\ref{section-gd-binding-layer-example}.
-
-The syntax of the to-be-laid-out graph is a reduced version of
-\tikzname's |graph| syntax: The string must start with
-|graph[|\meta{algorithm's name}|]{| and end with |}|. Between the
-braces, all lines must either be of the form \meta{node name}|;| or
-\meta{name 1}|->|\meta{name 2}|;| with optional spaces around the node
-names.
-
-Let us now have a look at what we must do to use the graph drawing
-system. First, we load some libraries and initialize the binding (see
-Section~\ref{section-gd-binding-layer-example} for details on the
-binding; we can ignore it for now).
-
+In the following, we present the code of a very simple display system written
+in Lua (another such display system is \tikzname\ itself, but the minimal
+system will allow us to focus on what is really needed). You will also find it
+in |pgf.gd.examples.ASCIIDisplayer|.
+
+The job of this display system is to parse a string that encodes a graph and to
+call the appropriate functions of |InterfaceToDisplay| to lay out the graph.
+The actual calls for rendering the graph are part of the binding, which is
+documented in Section~\ref{section-gd-binding-layer-example}.
+
+The syntax of the to-be-laid-out graph is a reduced version of \tikzname's
+|graph| syntax: The string must start with |graph[|\meta{algorithm's name}|]{|
+and end with |}|. Between the braces, all lines must either be of the form
+\meta{node name}|;| or \meta{name 1}|->|\meta{name 2}|;| with optional spaces
+around the node names.
+
+Let us now have a look at what we must do to use the graph drawing system.
+First, we load some libraries and initialize the binding (see
+Section~\ref{section-gd-binding-layer-example} for details on the binding; we
+can ignore it for now).
+%
\begin{codeexample}[code only]
local InterfaceToDisplay = require "pgf.gd.interface.InterfaceToDisplay"
InterfaceToDisplay.bind(require "pgf.gd.examples.BindingToASCII")
@@ -178,13 +174,14 @@ require "pgf.gd.layered.library"
require "pgf.gd.force.library"
\end{codeexample}
-Now comes some preparation code that starts a graph drawing scope and
-sets up the algorithm to the string provided between the square
-brackets:
+Now comes some preparation code that starts a graph drawing scope and sets up
+the algorithm to the string provided between the square \todosp{should
+\texttt{.pushPhase} be \texttt{.pushOption}? (bug \#396)} brackets:
+%
\begin{codeexample}[code only]
local algorithm = io.read():match("%s*graph%s*%[(.-)%]")
-
+
InterfaceToDisplay.pushPhase(algorithm, "main", 1)
InterfaceToDisplay.pushOption("level distance", 6, 2)
InterfaceToDisplay.pushOption("sibling distance", 8, 3)
@@ -192,13 +189,11 @@ InterfaceToDisplay.beginGraphDrawingScope(3)
InterfaceToDisplay.pushLayout(4)
\end{codeexample}
-The numbers |1| to |4| are the positions on the options stack at which
-the options should be placed. See the description of |pushOption| for
-more details.
-
-We are now ready to create the vertices and edges via a very simple
-parser:
+The numbers |1| to |4| are the positions on the options stack at which the
+options should be placed. See the description of |pushOption| for more details.
+We are now ready to create the vertices and edges via a very simple parser:
+%
\begin{codeexample}[code only]
for line in io.lines() do
if line:match("}") then
@@ -213,24 +208,23 @@ for line in io.lines() do
end
\end{codeexample}
-The graph is now completely constructed inside the graph drawing
-system. We can now invoke the algorithms:
-
+The graph is now completely constructed inside the graph drawing system. We can
+now invoke the algorithms:
+%
\begin{codeexample}[code only]
InterfaceToDisplay.runGraphDrawingAlgorithm()
InterfaceToDisplay.renderGraph()
InterfaceToDisplay.endGraphDrawingScope()
\end{codeexample}
-We can now run the resulting file using the Lua interpreter. If we
-provide the input shown on the left, we get the output shown on the
-right:
+We can now run the resulting file using the Lua interpreter. If we provide the
+input shown on the left, we get the output shown on the right:
\bigskip
\noindent
\begin{minipage}[t]{.5\textwidth}
-\emph{Input given to ASCIIDisplayer:}
-
+\emph{Input given to ASCIIDisplayer:}
+
\begin{verbatim}
graph [layered layout] {
Alice;
@@ -250,38 +244,38 @@ graph [layered layout] {
George -> Eve;
George -> Fritz;
Alice -> George;
-}
+}
\end{verbatim}
\end{minipage}%
\begin{minipage}[t]{.49\textwidth}
-\emph{Output produced by ASCIIDisplayer:}
-
+\emph{Output produced by ASCIIDisplayer:}
+
\begin{verbatim}
- Alice
- .......
- .. . . .
- ... . . .
- ... .. . ..
- .. . . .
- Charly Bob . .
- .. . . .
- . . . .
- . . . .
- .. . . .
- .. . .
- Dave George .
- .. . ... .
- . . .. .
- . . ...
- .. . . ...
- .. . ..
- Eve . ..
- .. . ..
- . . .
- . . .
- .. . ..
- ...
- Fritz
+ Alice
+ .......
+ .. . . .
+ ... . . .
+ ... .. . ..
+ .. . . .
+ Charly Bob . .
+ .. . . .
+ . . . .
+ . . . .
+ .. . . .
+ .. . .
+ Dave George .
+ .. . ... .
+ . . .. .
+ . . ...
+ .. . . ...
+ .. . ..
+ Eve . ..
+ .. . ..
+ . . .
+ . . .
+ .. . ..
+ ...
+ Fritz
\end{verbatim}
\end{minipage}
@@ -289,4 +283,3 @@ graph [layered layout] {
\subsection{The Interface to Display Systems}
\includeluadocumentationof{pgf.gd.interface.InterfaceToDisplay}
-