summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex250
1 files changed, 121 insertions, 129 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex
index 422d7d8d0a2..b677de2175a 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-gd-binding-layer.tex
@@ -15,66 +15,66 @@
\section{The Binding Layer}
-
\label{section-gd-binding-layer}
-\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}
-This section explains how the \emph{binding} of the graph drawing
-system to a particular display layer works. Let me stress
-that all of this is important only for readers who
+This section explains how the \emph{binding} of the graph drawing system to a
+particular display layer works. Let me stress that all of this is important
+only for readers who
+%
\begin{itemize}
-\item either wish to write new display system (see
- Section~\ref{section-gd-display-layer})
-\item or wish to know more about how the graph drawing system works on
- the pure \pgfname\ layer (this is were the binding occurs).
+ \item either wish to write new display system (see
+ Section~\ref{section-gd-display-layer})
+ \item or wish to know more about how the graph drawing system works on the
+ pure \pgfname\ layer (this is were the binding occurs).
\end{itemize}
-\emph{Bindings} are used to encapsulate the details of the
-communication between the graph drawing system and a display system
-(see Section~\ref{section-gd-display-layer} for an introduction to
-display systems).
-
-Consider a display system that communicates with the graph drawing
-system. At some point, the display system would like to run an
-algorithm to lay out a graph. To achieve this, it will call different
-functions from the class |InterfaceToDisplay| and the effect of this
-is that a representation of the to-be-drawn graph is constructed
-internally and that the appropriate algorithms are run. All of this is
-in some sense independent of the actual display system, the class
-|InterfaceToDisplay| offers the same standard interface to all display
-systems.
-
-At some point, however, the graph drawing system may need to ``talk
-back'' to the display system. For instance, once the graph has been
-laid out, to trigger the actual rendering of the graph, the graph
-drawing system must ``tell'' the display layer where the vertices
-lie. For some display systems this is easy: if the display system
-itself is written in Lua, it could just access the syntactic digraph
-directly. However, for systems like \tikzname\ or systems written in
-another language, the graph drawing system needs a set of functions
-that it can call that will tell the display system what is going
-on. This is were bindings come in.
-
-The class |Binding| is an interface that defines numerous methods that
-will be called by the graph drawing system in different situations (see
-the documentation below for details). For instance, there is a
-function |renderVertex| that is called by the graph drawing system
-whenever a vertex should be rendered by the display system. The class
-is really just an interface in the sense of object-oriented
-programming. For each display system you need to create a subclass of
-|Binding| like |BindingToPGF| or |BindingToASCII| that implement the
-methods declared by |Binding|. The number of methods that need to be
-implemented depends on the display system.
-
-In the following, you will find the documentation of the |Binding|
-class in Section~\ref{section-gd-binding-doc}. Following this, we
-first have a quick look at how the |BindingToPGF| works and then go
-over a simple example of a binding to a more or less imaginary
-display system. This example should help readers interested in
-implementing their own bindings.
+\emph{Bindings} are used to encapsulate the details of the communication
+between the graph drawing system and a display system (see
+Section~\ref{section-gd-display-layer} for an introduction to display systems).
+
+Consider a display system that communicates with the graph drawing system. At
+some point, the display system would like to run an algorithm to lay out a
+graph. To achieve this, it will call different functions from the class
+|InterfaceToDisplay| and the effect of this is that a representation of the
+to-be-drawn graph is constructed internally and that the appropriate algorithms
+are run. All of this is in some sense independent of the actual display system,
+the class |InterfaceToDisplay| offers the same standard interface to all
+display systems.
+
+At some point, however, the graph drawing system may need to ``talk back'' to
+the display system. For instance, once the graph has been laid out, to trigger
+the actual rendering of the graph, the graph drawing system must ``tell'' the
+display layer where the vertices lie. For some display systems this is easy: if
+the display system itself is written in Lua, it could just access the syntactic
+digraph directly. However, for systems like \tikzname\ or systems written in
+another language, the graph drawing system needs a set of functions that it can
+call that will tell the display system what is going on. This is were bindings
+come in.
+
+The class |Binding| is an interface that defines numerous methods that will be
+called by the graph drawing system in different situations (see the
+documentation below for details). For instance, there is a function
+|renderVertex| that is called by the graph drawing system whenever a vertex
+should be rendered by the display system. The class is really just an interface
+in the sense of object-oriented programming. For each display system you need
+to create a subclass of |Binding| like |BindingToPGF| or |BindingToASCII| that
+implement the methods declared by |Binding|. The number of methods that need to
+be implemented depends on the display system.
+
+In the following, you will find the documentation of the |Binding| class in
+Section~\ref{section-gd-binding-doc}. Following this, we first have a quick
+look at how the |BindingToPGF| works and then go over a simple example of a
+binding to a more or less imaginary display system. This example should help
+readers interested in implementing their own bindings.
\subsection{The Binding Class and the Interface Core}
@@ -94,15 +94,15 @@ implementing their own bindings.
\label{section-gd-binding-layer-example}
In the present section a complete binding is presented to an imaginary
-``\textsc{ascii} art display system'' is presented. The idea is that
-this display system will depict graphs using just normal letters and
-spaces so that, when the text is typeset in a monospace font, a
-visualization of the graph results. For instance:
+``\textsc{ascii} art display system'' is presented. The idea is that this
+display system will depict graphs using just normal letters and spaces so that,
+when the text is typeset in a monospace font, a visualization of the graph
+results. For instance:
\bigskip
\noindent
\begin{minipage}[t]{.5\textwidth}
-\emph{Graph rendered by |BindingToPGF|:}
+\emph{Graph rendered by |BindingToPGF|:}
\medskip
\tikz [anchor=base]\graph [layered layout,level distance=2.35cm,sibling
@@ -127,44 +127,44 @@ distance=1.2cm,edges={rounded corners,>=spaced stealth'}] {
};
\end{minipage}%
\begin{minipage}[t]{.49\textwidth}
-\emph{Graph rendered by |BindingToASCII|:}
-
+\emph{Graph rendered by |BindingToASCII|:}
+
\begin{verbatim}
- Alice
- .......
- .. . . .
- ... . . .
- ... .. . ..
- .. . . .
- Charly Bob . .
- .. . . .
- . . . .
- . . . .
- .. . . .
- .. . .
- Dave George .
- .. . ... .
- . . .. .
- . . ...
- .. . . ...
- .. . ..
- Eve . ..
- .. . ..
- . . .
- . . .
- .. . ..
- ...
- Fritz
+ Alice
+ .......
+ .. . . .
+ ... . . .
+ ... .. . ..
+ .. . . .
+ Charly Bob . .
+ .. . . .
+ . . . .
+ . . . .
+ .. . . .
+ .. . .
+ Dave George .
+ .. . ... .
+ . . .. .
+ . . ...
+ .. . . ...
+ .. . ..
+ Eve . ..
+ .. . ..
+ . . .
+ . . .
+ .. . ..
+ ...
+ Fritz
\end{verbatim}
\end{minipage}
\bigskip
-The binding will reside in a file |BindingToASCII.lua|, whose contents
-is detailed below, and which is used by calling the |bind| function of
+The binding will reside in a file |BindingToASCII.lua|, whose contents is
+detailed below, and which is used by calling the |bind| function of
|InterfaceToDisplay|, see its documentation for details.
The binding's code starts with some initializations:
-
+%
\begin{codeexample}[code only]
-- File BindingToASCII.lua
@@ -175,19 +175,18 @@ local lib = require "pgf.gd.lib"
local BindingToASCII = lib.class { base_class = require "pgf.gd.bindings.Binding" }
\end{codeexample}
-The interesting code is the code for
-``rendering'' a graph. The graph drawing system will invoke the
-binding's methods |renderStart| and |renderStop| to signal that the
-graph drawing algorithms have finished and that the vertices and edges
-can now be drawn.
-
-In our \textsc{ascii} renderer, we use a two-dimensional field holding
-characters that severs as the ``drawing canvas''. At the beginning of
-the rendering, we initialize it with blanks:
+The interesting code is the code for ``rendering'' a graph. The graph drawing
+system will invoke the binding's methods |renderStart| and |renderStop| to
+signal that the graph drawing algorithms have finished and that the vertices
+and edges can now be drawn.
+In our \textsc{ascii} renderer, we use a two-dimensional field holding
+characters that severs as the ``drawing canvas''. At the beginning of the
+rendering, we initialize it with blanks:
+%
\begin{codeexample}[code only]
local canvas
-
+
function BindingToASCII:renderStart()
canvas = {}
-- Clear the canvas
@@ -200,29 +199,26 @@ function BindingToASCII:renderStart()
end
\end{codeexample}
-In order to ``render'' a vertex, the graph drawing system will call
-the |renderVertex| method. The binding of \tikzname\ does a lot of
-complicated things in this method to retrieve the underlying node's
-box from internal table and to somehow reinstall the box in \TeX's
-output stream; for our \textsc{ascii} binding things are much simpler:
-We simply put the vertex's name at the canvas position corresponding
-to the vertex's |pos| coordinate. Note that this simple version of an
-\textsc{ascii} renderer does not try to scale things; thus, array out
-of bounds might occur here.
-
+In order to ``render'' a vertex, the graph drawing system will call the
+|renderVertex| method. The binding of \tikzname\ does a lot of complicated
+things in this method to retrieve the underlying node's box from internal table
+and to somehow reinstall the box in \TeX's output stream; for our
+\textsc{ascii} binding things are much simpler: We simply put the vertex's name
+at the canvas position corresponding to the vertex's |pos| coordinate. Note
+that this simple version of an \textsc{ascii} renderer does not try to scale
+things; thus, array out of bounds might occur here.
+%
\begin{codeexample}[code only]
function BindingToASCII:renderVertex(v)
canvas [math.floor(v.pos.x)][math.floor(v.pos.y)] = v.name
end
\end{codeexample}
-The rendering of edges is a more complicated process. Given two
-vertices, we put dots at the canvas positions between them; provided
-there are no vertices (so edges are behind the nodes). Here is the
-essential part of the code (for the complete code, have a look at
-|pgf/gd/examples/BindingToASCII.lua|):
-
-
+The rendering of edges is a more complicated process. Given two vertices, we
+put dots at the canvas positions between them; provided there are no vertices
+(so edges are behind the nodes). Here is the essential part of the code (for
+the complete code, have a look at |pgf/gd/examples/BindingToASCII.lua|):
+%
\begin{codeexample}[code only]
function BindingToASCII:renderEdge(e)
local function connect (p,q)
@@ -235,33 +231,31 @@ function BindingToASCII:renderEdge(e)
local slope = delta_y/delta_x
for i=x1,x2 do
local x,y = i, math.floor(y1 + (i-x1)*slope + 0.5)
-
+
if canvas[x][y] == " " then
canvas[x][y] = '.'
end
end
...
end
-
+
-- Iterate over all points on the path from tail to head:
local p = e.tail.pos
for i=1,#e.path do
connect(p, e.tail.pos + e.path[i])
p = e.tail.pos + e.path[i]
- end
+ end
connect(p, e.head.pos)
end
\end{codeexample}
-
-The methods |renderVertex| and |renderEdge| will be called once for
-each vertex and edge of the to-be-rendered graph. At the end, the
-|renderStop| method is called. In our case, this method will output
-the canvas using |print|. A slight complication arises when node names
-are longer than just one character. In this case, the following code
-``centers'' them on their coordinate and makes sure that they do not
-get overwritten by the dots forming edges:
-
+The methods |renderVertex| and |renderEdge| will be called once for each vertex
+and edge of the to-be-rendered graph. At the end, the |renderStop| method is
+called. In our case, this method will output the canvas using |print|. A slight
+complication arises when node names are longer than just one character. In this
+case, the following code ``centers'' them on their coordinate and makes sure
+that they do not get overwritten by the dots forming edges:
+%
\begin{codeexample}[code only]
function BindingToASCII:renderStop()
for y=10,-30,-1 do
@@ -281,9 +275,7 @@ end
\end{codeexample}
At the end, we need to return the created object:
-
+%
\begin{codeexample}[code only]
return BindingToASCII
\end{codeexample}
-
-