summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/Orientation.lua
blob: 10f5ecdf47155afb2577e9bac63f4f3edd60e036 (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
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
-- 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$




---
-- @section subsection {Orienting a Graph}
--
-- \label{subsection-library-graphdrawing-standard-orientation}
--
-- Just as a graph drawing algorithm cannot know \emph{where} a graph
-- should be placed on a page, it is also often unclear which
-- \emph{orientation} it should have. Some graphs, like trees, have a
-- natural direction in which they ``grow'', but for an ``arbitrary''
-- graph the ``natural orientation'' is, well, arbitrary.
--
-- There are two ways in which you can specify an orientation: First,
-- you can specify that the line from a certain vertex to another
-- vertex should have a certain slope. How these vertices and slopes
-- are specified in explained momentarily. Second, you can specify a
-- so-called ``growth direction'' for trees. 
--
-- @end


-- Namespace
require("pgf.gd.control").Orientation = Orientation



-- Imports
local declare    = require "pgf.gd.interface.InterfaceToAlgorithms".declare


---

declare {
  key = "orient",
  type = "direction",
  default = 0,

  summary = [["  
       This key specifies that the straight line from the |orient tail| to
       the |orient head| should be at an angle of \meta{direction} relative to
       the right-going $x$-axis. Which vertices are used as tail an head
       depends on where the |orient| option is encountered: When used with
       an edge, the tail is the edge's tail und the head is the edge's
       head. When used with a node, the tail or the head must be specified
       explicitly and the node is used as the node missing in the
       specification. When used with a graph as a whole, both the head and
       tail nodes must be specified explicitly.
  "]],
  documentation = [["
       Note that the \meta{direction} is independent of the actual to-path
       of an edge, which might define a bend or more complicated shapes. For
       instance, a \meta{angle} of |45| requests that the end node is ``up
       and right'' relative to the start node. 

       You can also specify the standard direction texts |north| or |south east|
       and so forth as \meta{direction} and also |up|, |down|, |left|, and |right|. Also, you 
       can specify |-| for ``right'' and \verb!|! for ``down.''
  "]],        
  examples = {
    [["
       \tikz \graph [spring layout]
       {
         a -- { b, c, d, e -- {f, g, h} };
         h -- [orient=30] a;
       };
    "]],
    [["
       \tikz \graph [spring layout]
       {
         a -- { b, c, d[> orient=right], e -- {f, g, h} };
         h -- a;
       };
    "]]
  }
}


---

declare {
  key = "orient'",
  type = "direction",
  default = 0,

  summary = [["  
       Same as |orient|, only the rest of the graph should be
       flipped relative to the connection line.
  "]],
  examples = [["
       \tikz \graph [spring layout]
       {
         a -- { b, c, d[> orient'=right], e -- {f, g, h} };
         h -- a;
       };
  "]]
}

---

declare {
  key = "orient tail",
  type = "string",

  summary = [["  
       Specifies the tail vertex for the orientation of a graph. See
       |orient| for details.
  "]],
  examples = {
    [["
       \tikz \graph [spring layout] {
         a [orient=|, orient tail=f] -- { b, c, d, e -- {f, g, h} };
         { h, g } -- a;
       };
    "]],
    [["
       \tikz \graph [spring layout] {
         a [orient=down, orient tail=h] -- { b, c, d, e -- {f, g, h} };
         { h, g } -- a;
       };
    "]]
  }
}
    




---

declare {
  key = "orient head",
  type = "string",

  summary = [["  
       Specifies the head vertex for the orientation of a graph. See
       |orient| for details.
  "]],
  examples = {     
    [["
       \tikz \graph [spring layout]
       {
         a [orient=|, orient head=f] -- { b, c, d, e -- {f, g, h} };
         { h, g } -- a;
       };
    "]],
    [["
       \tikz \graph [spring layout] { a -- b -- c -- a };
       \tikz \graph [spring layout, orient=10,
                     orient tail=a, orient head=b] { a -- b -- c -- a };
    "]]
  }
}

---

declare {
  key = "horizontal",
  type = "string",

  summary = [["  
       A shorthand for specifying |orient tail|, |orient head| and
       |orient=0|. The tail will be everything before the part ``| to |''
       and the head will be everything following it. 
  "]],
  examples = [["     
       \tikz \graph [spring layout]                    { a -- b -- c -- a };
       \tikz \graph [spring layout, horizontal=a to b] { a -- b -- c -- a };
  "]]
}
       



---

declare {
  key = "horizontal'",
  type = "string",

  summary = [["  
       Like |horizontal|, but with a flip.
  "]]
}
    






---

declare {
  key = "vertical",
  type = "string",

  summary = [["  
       A shorthand for specifying |orient tail|, |orient head| and
       |orient=-90|.
  "]],
  examples = [["
       \tikz \graph [spring layout]                  { a -- b -- c -- a };
       \tikz \graph [spring layout, vertical=a to b] { a -- b -- c -- a };
  "]]
}
       




---

declare {
  key = "vertical'",
  type = "string",

  summary = [["  
       Like |vertical|, but with a flip.
  "]]
}



---

declare {
  key = "grow",
  type = "direction",

  summary = [["  
       This key specifies in which direction the neighbors of a node
       ``should grow.'' For some graph drawing algorithms, especially for
       those that layout trees, but also for those that produce layered
       layouts, there is a natural direction in which the ``children'' of
       a node should be placed. For instance, saying |grow=down| will cause
       the children of a node in a tree to be placed in a left-to-right
       line below the node (as always, you can replace the \meta{angle}
       by direction texts). The children are requested to be placed in a
       counter-clockwise fashion, the |grow'| key will place them in a
       clockwise fashion.
  "]],
  documentation = [["        
       Note that when you say |grow=down|, it is not necessarily the case
       that any particular node is actually directly below the current
       node; the key just requests that the direction of growth is
       downward.
        
       In principle, you can specify the direction of growth for each node 
       individually, but do not count on graph drawing algorithms to
       honour these wishes.
       
       When you give the |grow=right| key to the graph as a whole, it will
       be applied to all nodes. This happens to be exactly what you want:
  "]],
  examples = {     
    [["
       \tikz \graph [layered layout, sibling distance=5mm]
       {
         a [grow=right] -- { b, c, d, e -- {f, g, h} };
         { h, g } -- a;
       };
    "]],      
    [["
       \tikz \graph [layered layout, grow=right, sibling distance=5mm]
       {
         a -- { b, c, d, e -- {f, g, h} };
         { h, g } -- a;
       };
    "]],      
    [["
       \tikz
         \graph [layered layout, grow=-80]
         {
           {a,b,c} --[complete bipartite] {e,d,f}
                   --[complete bipartite] {g,h,i};
         };
    "]]
  }
}


---

declare {
  key = "grow'",
  type = "direction",

  summary = "Same as |grow|, only with the children in clockwise order.",
  examples = [["
       \tikz \graph [layered layout, sibling distance=5mm]
       {
         a [grow'=right] -- { b, c, d, e -- {f, g, h} };
         { h, g } -- a;
       };
  "]]
}


-- Done

return Orientation