Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-gd-binding-layer.tex

raw
1 % Copyright 2010-2019 by Renée Ahrens
2 % Copyright 2010-2019 by Olof Frahm
3 % Copyright 2010-2019 by Jens Kluttig
4 % Copyright 2010-2019 by Matthias Schulz
5 % Copyright 2010-2019 by Stephan Schuster
6 % Copyright 2019 by Jannis Pohlmann
7 % Copyright 2019 by Till Tantau
8 %
9 % This file may be distributed and/or modified
10 %
11 % 1. under the LaTeX Project Public License and/or
12 % 2. under the GNU Free Documentation License.
13 %
14 % See the file doc/generic/pgf/licenses/LICENSE for more details.
15
16
17 \section{The Binding Layer}
18 \label{section-gd-binding-layer}
19
20 \ifluatex
21 \else
22 This section of the manual can only be typeset using Lua\TeX.
23 \expandafter\endinput
24 \fi
25
26
27 \subsection{Overview}
28
29 This section explains how the \emph{binding} of the graph drawing system to a
30 particular display layer works. Let me stress that all of this is important
31 only for readers who
32 %
33 \begin{itemize}
34 \item either wish to write new display system (see
35 Section~\ref{section-gd-display-layer})
36 \item or wish to know more about how the graph drawing system works on the
37 pure \pgfname\ layer (this is were the binding occurs).
38 \end{itemize}
39
40 \emph{Bindings} are used to encapsulate the details of the communication
41 between the graph drawing system and a display system (see
42 Section~\ref{section-gd-display-layer} for an introduction to display systems).
43
44 Consider a display system that communicates with the graph drawing system. At
45 some point, the display system would like to run an algorithm to lay out a
46 graph. To achieve this, it will call different functions from the class
47 |InterfaceToDisplay| and the effect of this is that a representation of the
48 to-be-drawn graph is constructed internally and that the appropriate algorithms
49 are run. All of this is in some sense independent of the actual display system,
50 the class |InterfaceToDisplay| offers the same standard interface to all
51 display systems.
52
53 At some point, however, the graph drawing system may need to ``talk back'' to
54 the display system. For instance, once the graph has been laid out, to trigger
55 the actual rendering of the graph, the graph drawing system must ``tell'' the
56 display layer where the vertices lie. For some display systems this is easy: if
57 the display system itself is written in Lua, it could just access the syntactic
58 digraph directly. However, for systems like \tikzname\ or systems written in
59 another language, the graph drawing system needs a set of functions that it can
60 call that will tell the display system what is going on. This is were bindings
61 come in.
62
63 The class |Binding| is an interface that defines numerous methods that will be
64 called by the graph drawing system in different situations (see the
65 documentation below for details). For instance, there is a function
66 |renderVertex| that is called by the graph drawing system whenever a vertex
67 should be rendered by the display system. The class is really just an interface
68 in the sense of object-oriented programming. For each display system you need
69 to create a subclass of |Binding| like |BindingToPGF| or |BindingToASCII| that
70 implement the methods declared by |Binding|. The number of methods that need to
71 be implemented depends on the display system.
72
73 In the following, you will find the documentation of the |Binding| class in
74 Section~\ref{section-gd-binding-doc}. Following this, we first have a quick
75 look at how the |BindingToPGF| works and then go over a simple example of a
76 binding to a more or less imaginary display system. This example should help
77 readers interested in implementing their own bindings.
78
79
80 \subsection{The Binding Class and the Interface Core}
81 \label{section-gd-binding-doc}
82
83 \includeluadocumentationof{pgf.gd.bindings.Binding}
84 \includeluadocumentationof{pgf.gd.interface.InterfaceCore}
85
86
87 \subsection{The Binding To PGF}
88
89 \includeluadocumentationof{pgf.gd.bindings.BindingToPGF}
90
91
92 \subsection{An Example Binding Class}
93
94 \label{section-gd-binding-layer-example}
95
96 In the present section a complete binding is presented to an imaginary
97 ``\textsc{ascii} art display system'' is presented. The idea is that this
98 display system will depict graphs using just normal letters and spaces so that,
99 when the text is typeset in a monospace font, a visualization of the graph
100 results. For instance:
101
102 \bigskip
103 \noindent
104 \begin{minipage}[t]{.5\textwidth}
105 \emph{Graph rendered by |BindingToPGF|:}
106 \medskip
107
108 \tikz [anchor=base]\graph [layered layout,level distance=2.35cm,sibling
109 distance=1.2cm,edges={rounded corners,>={Stealth[round,sep]}}] {
110 Alice;
111 Bob;
112 Charly;
113 Dave;
114 Eve;
115 Fritz;
116 George;
117 Alice -> Bob;
118 Alice -> Charly;
119 Charly -> Dave;
120 Bob -> Dave;
121 Dave -> Eve;
122 Eve -> Fritz;
123 Fritz -> Alice;
124 George -> Eve;
125 George -> Fritz;
126 Alice -> George;
127 };
128 \end{minipage}%
129 \begin{minipage}[t]{.49\textwidth}
130 \emph{Graph rendered by |BindingToASCII|:}
131
132 \begin{verbatim}
133 Alice
134 .......
135 .. . . .
136 ... . . .
137 ... .. . ..
138 .. . . .
139 Charly Bob . .
140 .. . . .
141 . . . .
142 . . . .
143 .. . . .
144 .. . .
145 Dave George .
146 .. . ... .
147 . . .. .
148 . . ...
149 .. . . ...
150 .. . ..
151 Eve . ..
152 .. . ..
153 . . .
154 . . .
155 .. . ..
156 ...
157 Fritz
158 \end{verbatim}
159 \end{minipage}
160 \bigskip
161
162 The binding will reside in a file |BindingToASCII.lua|, whose contents is
163 detailed below, and which is used by calling the |bind| function of
164 |InterfaceToDisplay|, see its documentation for details.
165
166 The binding's code starts with some initializations:
167 %
168 \begin{codeexample}[code only]
169 -- File BindingToASCII.lua
170
171 -- Imports
172 local lib = require "pgf.gd.lib"
173
174 -- Subclass the Binding class:
175 local BindingToASCII = lib.class { base_class = require "pgf.gd.bindings.Binding" }
176 \end{codeexample}
177
178 The interesting code is the code for ``rendering'' a graph. The graph drawing
179 system will invoke the binding's methods |renderStart| and |renderStop| to
180 signal that the graph drawing algorithms have finished and that the vertices
181 and edges can now be drawn.
182
183 In our \textsc{ascii} renderer, we use a two-dimensional field holding
184 characters that severs as the ``drawing canvas''. At the beginning of the
185 rendering, we initialize it with blanks:
186 %
187 \begin{codeexample}[code only]
188 local canvas
189
190 function BindingToASCII:renderStart()
191 canvas = {}
192 -- Clear the canvas
193 for x=-30,30 do
194 canvas [x] = {}
195 for y=-30,30 do
196 canvas[x][y] = ' '
197 end
198 end
199 end
200 \end{codeexample}
201
202 In order to ``render'' a vertex, the graph drawing system will call the
203 |renderVertex| method. The binding of \tikzname\ does a lot of complicated
204 things in this method to retrieve the underlying node's box from internal table
205 and to somehow reinstall the box in \TeX's output stream; for our
206 \textsc{ascii} binding things are much simpler: We simply put the vertex's name
207 at the canvas position corresponding to the vertex's |pos| coordinate. Note
208 that this simple version of an \textsc{ascii} renderer does not try to scale
209 things; thus, array out of bounds might occur here.
210 %
211 \begin{codeexample}[code only]
212 function BindingToASCII:renderVertex(v)
213 canvas [math.floor(v.pos.x)][math.floor(v.pos.y)] = v.name
214 end
215 \end{codeexample}
216
217 The rendering of edges is a more complicated process. Given two vertices, we
218 put dots at the canvas positions between them; provided there are no vertices
219 (so edges are behind the nodes). Here is the essential part of the code (for
220 the complete code, have a look at |pgf/gd/examples/BindingToASCII.lua|):
221 %
222 \begin{codeexample}[code only]
223 function BindingToASCII:renderEdge(e)
224 local function connect (p,q)
225 -- Connect the points p and q
226 local x1, y1, x2, y2 = math.floor(p.x+0.5), math.floor(p.y+0.5), math.floor(q.x+0.5), math.floor(q.y+0.5)
227 ...
228 local delta_x = x2-x1
229 local delta_y = y2-y1
230 ...
231 local slope = delta_y/delta_x
232 for i=x1,x2 do
233 local x,y = i, math.floor(y1 + (i-x1)*slope + 0.5)
234
235 if canvas[x][y] == " " then
236 canvas[x][y] = '.'
237 end
238 end
239 ...
240 end
241
242 -- Iterate over all points on the path from tail to head:
243 local p = e.tail.pos
244 for i=1,#e.path do
245 connect(p, e.tail.pos + e.path[i])
246 p = e.tail.pos + e.path[i]
247 end
248 connect(p, e.head.pos)
249 end
250 \end{codeexample}
251
252 The methods |renderVertex| and |renderEdge| will be called once for each vertex
253 and edge of the to-be-rendered graph. At the end, the |renderStop| method is
254 called. In our case, this method will output the canvas using |print|. A slight
255 complication arises when node names are longer than just one character. In this
256 case, the following code ``centers'' them on their coordinate and makes sure
257 that they do not get overwritten by the dots forming edges:
258 %
259 \begin{codeexample}[code only]
260 function BindingToASCII:renderStop()
261 for y=10,-30,-1 do
262 local t = {}
263 for x=-30,30 do
264 local s = canvas[x][y]
265 for i=1,#s do
266 pos = x+30+i-math.floor(#s/2)
267 if not t[pos] or t[pos] == " " or t[pos] == "." then
268 t[pos] = string.sub(s,i,i)
269 end
270 end
271 end
272 print(table.concat(t))
273 end
274 end
275 \end{codeexample}
276
277 At the end, we need to return the created object:
278 %
279 \begin{codeexample}[code only]
280 return BindingToASCII
281 \end{codeexample}