summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/model/Edge.lua
blob: 87b06661e54a4715146949246b82907a7d8ebb93 (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
-- 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$


--- 
-- An |Edge| is a ``syntactic'' connection between two
-- vertices that represents a connection present in the syntactic
-- digraph. Unlike an |Arc|, |Edge| objects are not controlled by the
-- |Digraph| class. Also unlike |Arc| objects, there can be several
-- edges betwen the same vertices, namely whenever several such edges
-- are present in the syntactic digraph.
--
-- In detail, the relationship between arcs and edges is as follows:
-- If there is an |Edge| between two vertices $u$ and $v$ in the
-- syntactic digraph, there will be an |Arc| from $u$ to $v$ and the
-- array |syntactic_edges| of this |Arc| object will contain the
-- |Edge| object. In particular, if there are several edges between
-- the same vertices, all of these edges will be part of the array in
-- a single |Arc| object.
--
-- Edges, like arcs, are always directed from a |tail| vertex to a
-- |head| vertex; this is true even for undirected vertices. The
-- |tail| vertex will always be the vertex that came first in the
-- syntactic specification of the edge, the |head| vertex is the
-- second one. Whether
-- an edge is directed or not depends on the |direction| of the edge, which
-- may be one of the following:
--
-- \begin{enumerate}
-- \item |"->"|
-- \item |"--"|
-- \item |"<-"|
-- \item |"<->"|
-- \item |"-!-"|
-- \end{enumerate}
-- 
--
-- @field head The head vertex of this edge.
--
-- @field tail The tail vertex of this edge.
--
-- @field event The creation |Event| of this edge.
--
-- @field options A table of options that contains user-defined options.
--
-- @field direction One of the directions named above.
--
-- @field path A |Path| object that describes the path of the
-- edge. The path's coordinates are interpreted \emph{absolutely}.
--
-- @field generated_options This is an options array that is generated
-- by the algorithm. When the edge is rendered later on, this array
-- will be passed back to the display layer. The syntax is the same as
-- for the |declare_parameter_sequence| function, see
-- |InterfaceToAlgorithms|.
--
-- @field animations An array of animations, see the |animations|
-- field of the |Vertex| class for the syntax. 

local Edge = {}
Edge.__index = Edge


-- Namespace

require("pgf.gd.model").Edge = Edge


-- Imports

local Path         = require "pgf.gd.model.Path"


--- 
-- Create a new edge. The |initial| parameter allows you to setup
-- some initial values.
--
-- @usage 
--\begin{codeexample}[code only, tikz syntax=false]
--local v = Edge.new { tail = v1, head = v2 }
--\end{codeexample} 
--
-- @param initial Values to override defaults. --
-- @return A new edge object.
--
function Edge.new(values)
  local new = {}
  for k,v in pairs(values) do
    new[k] = v
  end
  new.generated_options = new.generated_options or {}
  new.animations = new.animations or {}
  if not new.path then
    local p = Path.new ()
    p:appendMoveto(Edge.tailAnchorForEdgePath(new))
    p:appendLineto(Edge.headAnchorForEdgePath(new))
    new.path = p
  end

  return setmetatable(new, Edge)
end




---
-- This method returns a ``coordinate factory'' that can be used as
-- the coordinate of a |moveto| at the beginning of a path starting at
-- the |tail| of the arc. Suppose you want to create a path starting
-- at the tail vertex, going to the coordinate $(10,10)$ and ending at
-- the head vertex. The trouble is that when you create the path
-- corresponding to this route, you typically do not know where the
-- tail vertex is going to be. In this case, you use this
-- method to get a function that will, later on, compute the correct
-- position of the anchor as needed.
--
-- Note that you typically do not use this function, but use the
-- corresponding function of the |Arc| class. Use this function only
-- if there are multiple edges between two vertices that need to be
-- routed differently. 
--
-- Here is the code you would use to create the abovementioned path:
--
--\begin{codeexample}[code only, tikz syntax=false]
--local a = g:connect(tail,head)
--local e = a.syntactic_edges[1]
--...
--e.path = Path.new()
--e.path:appendMoveto(e:tailAnchorForEdgePath())
--e.path:appendLineto(10, 10)
--e.path:appendLineto(e:headAnchorForEdgePath())
--\end{codeexample}
--
-- As for the |Arc| class, you can also setup a polyline more easily:
--
--\begin{codeexample}[code only, tikz syntax=false]
--e:setPolylinePath { Coordinate.new (10, 10) }
--\end{codeexample}

function Edge:tailAnchorForEdgePath()
  return function ()
	   local a = self.options['tail anchor']
	   if a == "" then
	     a = "center"
	   end
	   return self.tail:anchor(a) + self.tail.pos
	 end
end

---
-- See |Arc:tailAnchorForArcPath|.

function Edge:headAnchorForEdgePath()
  return function ()
	   local a = self.options['head anchor']
	   if a == "" then
	     a = "center"
	   end
	   return self.head:anchor(a) + self.head.pos
	 end
end



---
-- Setup the |path| field of an edge in such a way that it corresponds
-- to a sequence of straight line segments starting at the tail's
-- anchor and ending at the head's anchor.
--
-- @param coordinates An array of |Coordinates| through which the line
-- will go through.

function Edge:setPolylinePath(coordinates)
  local p = Path.new ()

  p:appendMoveto(self:tailAnchorForEdgePath())

  for _,c in ipairs(coordinates) do
    p:appendLineto(c)
  end

  p:appendLineto(self:headAnchorForEdgePath())
  
  self.path = p
end



--
-- Returns a string representation of an edge. This is mainly for debugging.
--
-- @return The Edge as a string.
--
function Edge:__tostring()
  return tostring(self.tail) .. self.direction .. tostring(self.head)
end


-- Done

return Edge