summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/bindings/Binding.lua
blob: 6ffb4168f5214b359e70677158de4a5b42360975 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
-- Copyright 2012 by Till Tantau
--
-- This file may be distributed an/or modified
--
-- 1. under the LaTeX Project Public License and/or
-- 2. under the GNU Public License
--
-- See the file doc/generic/pgf/licenses/LICENSE for more information

-- @release $Header$


-- Imports
local Storage = require "pgf.gd.lib.Storage"


---
-- This class provides a (non-functional) default implementation of a
-- binding between a display layer and the algorithm layer. Subclasses
-- must implement most of the member functions declared in this class.
--
-- A instance of a subclass of this class encapsulates the complete
-- implementation of all specific code needed for the communication
-- between the display layer and the graph drawing engine.
--
-- Note that you never call the methods of a |Binding| object
-- directly, neither from the display layer nor from the algorithm
-- layer. Instead, you use the more powerful and more easy to use
-- functions from |InterfaceToDisplay| and
-- |InterfaceToAlgorithms|. They call the appropriate |Binding|
-- methods internally.
--
-- Because of the above, in order to use the graph drawing system
-- inside a new display layer, you need to subclass |Binding| and
-- implement all the functions. Then you need to write the display
-- layer in such a way that it calls the appropriate functions from
-- |InterfaceToDisplay|.
--
-- @field storage A |Storage| storing the information passed from the
-- display layer. The interpretation of this left to the actual
-- binding.

local Binding = {
  storage = Storage.newTableStorage ()
}
Binding.__index = Binding

-- Namespace
require("pgf.gd.bindings").Binding = Binding





--
-- This method gets called whenever the graph drawing coroutine should
-- be resumed. First, the binding layer should ask the display layer
-- to execute the |code|, then, after this is done, the function
-- |InterfaceToDisplay.resumeGraphDrawingCoroutine| should be called
-- by this function.
--
-- @param code Some code to be executed by the display layer.

function Binding:resumeGraphDrawingCoroutine(code)
  -- Does nothing by default
end


---
-- Declare a new key. This callback is called by |declare|. It is the job
-- of the display layer to make the parameter |t.key| available to the
-- parsing process. Furthermore, if |t.initial| is not |nil|, the
-- display layer must convert it into a value that is stored as the
-- initial value and call |InterfaceToDisplay.setOptionInitial|.
--
-- @param t See |InterfaceToAlgorithms.declare| for details.

function Binding:declareCallback(t)
  -- Does nothing by default
end




-- Rendering

---
-- This function and, later on, |renderStop| are called whenever the
-- rendering of a laid-out graph starts or stops. See
-- |InterfaceToDisplay.render| for details.

function Binding:renderStart()
  -- Does nothing by default
end

---
-- See |renderStart|.

function Binding:renderStop()
  -- Does nothing by default
end





---
-- This function and the corresponding |...Stop...| functions are
-- called whenever a collection kind should be rendered. See
-- |InterfaceToDisplay.render_collections| for details.
--
-- @param kind The kind (a string).
-- @param layer The kind's layer (a number).

function Binding:renderCollectionStartKind(kind, layer)
  -- Does nothing by default
end


---
-- The counterpart to |renderCollectionStartKind|.
--
-- @param kind The kind.
-- @param layer The kind's layer.

function Binding:renderCollectionStopKind(kind, layer)
  -- Does nothing by default
end


---
-- Renders a single collection, see |renderCollectionStartKind| for
-- details.
--
-- @param collection The collection object.

function Binding:renderCollection(collection)
  -- Does nothing by default
end



---
-- This function and the corresponding |...Stop...| functions are
-- called whenever a vertex should be rendered. See
-- |InterfaceToDisplay.render_vertices| for details.
--

function Binding:renderVerticesStart()
  -- Does nothing by default
end


---
-- The counterpart to |renderVerticesStop|.
--

function Binding:renderVerticesStop()
  -- Does nothing by default
end


---
-- Renders a single vertex, see |renderVertexStartKind| for
-- details.
--
-- @param vertex The |Vertex| object.

function Binding:renderVertex(vertex)
  -- Does nothing by default
end



---
-- This method is called by the interface to the display layer after
-- the display layer has called |createVertex| to create a new
-- vertex. After having done its internal bookkeeping, the interface
-- calls this function to allow the binding to perform further
-- bookkeeping on the node. Typically, this will be done using the
-- information stored in |Binding.infos|.
--
-- @param v The vertex.

function Binding:everyVertexCreation(v)
  -- Does nothing by default
end





---
-- This function and the corresponding |...Stop...| functions are
-- called whenever an edge should be rendered. See
-- |InterfaceToDisplay.render_edges| for details.
--

function Binding:renderEdgesStart()
  -- Does nothing by default
end


---
-- The counterpart to |renderEdgesStop|.
--

function Binding:renderEdgesStop()
  -- Does nothing by default
end


---
-- Renders a single vertex, see |renderEdgeStartKind| for
-- details.
--
-- @param edge The |Edge| object.

function Binding:renderEdge(edge)
  -- Does nothing by default
end


---
-- Like |everyVertexCreation|, only for edges.
--
-- @param e The edge.

function Binding:everyEdgeCreation(e)
  -- Does nothing by default
end


---
-- Generate a new vertex. This method will be called when the
-- \emph{algorithm} layer wishes to trigger the creation of a new
-- vertex. This call will be made while an algorithm is running. It is
-- now the job of the binding to cause the display layer to create the
-- node. This is done by calling the |yield| method of the scope's
-- coroutine.
--
-- @param init  A table of initial values for the node. The following
-- fields will be used:
-- %
-- \begin{itemize}
--   \item |name| If present, this name will be given to the
--     node. If not present, an internal name is generated. Note that,
--     unless the node is a subgraph node, this name may not be the name
--     of an already present node of the graph; in this case an error
--     results.
--   \item |shape| If present, a shape of the node.
--   \item |generated_options| A table that is passed back to the
--     display layer as a list of key--value pairs.
--   \item |text| The text of the node, to be passed back to the
--     higher layer. This is what should be displayed as the node's text.
-- \end{itemize}

function Binding:createVertex(init)
  -- Does nothing by default
end




return Binding