diff options
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.tex | 250 |
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} - - |