svgdx 0.17.1

create SVG diagrams easily
Documentation 
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

# Layout

Most SVG elements are placed on the canvas using absolute coordinates; easy
for SVG-generating tools and GUI applications to handle, but difficult to
manage by hand for anything but the most simple diagrams.

`svgdx` provides various mechanisms to help with laying out diagrams.

> NOTE: `svgdx` assumes that 'User Coordinates' are used for all positioning,
> i.e. [without units](https://www.w3.org/TR/SVG11/coords.html#Units).

> NOTE: Changes to the coordinate system (e.g. using the `transform` attribute)
> are currently ignored when `svgdx` calculates layout.

> NOTE: Bounding boxes calculations for `<path>` elements are incomplete,
> (in particular arcs and curves are not handled) so these may not position
> effectively.

## Uniform Attributes

SVG requires different approaches to specifying position and size depending
on the shape being used; `svgdx` makes this uniform by determining axis-aligned
bounding boxes around every element, and placing objects appropriately.

Every object has a width and height (the `wh` attribute), and is located at a
particular point denoting the top-left of the bounding box (the `xy` attribute).
Alternatively, the *center* of an object can be given (via the `cxy` attribute)
along with the width and height.

As usual, mixing and matching with standard SVG attributes is possible, so
an `rx`, `ry` pair may be given alongside an `xy` attribute to define the
position and size of an `<ellipse>` element, for example.

## Relative Positioning

Rather than requiring absolute positions for elements, `svgdx` allows elements
to be placed relative to other elements. Since `xy` defaults to "0" if not
specified, many diagrams will not need _any_ absolute positions to be specified.

The following concepts are defined, and can be combined to make a 'relative
specifier', or 'relspec'.

**Element Reference** - ('elref') may be either 'the previous element' (denoted with
`^`) or an element referenced by its `id`, as `#<id>`, for example `#abc`.

**Location Spec** - ('locspec') a specific point on a given element,
for example 'top-left', 'center', or '75% along the top edge'.
These are given by one of the following abbreviations:

* `tl` - top-left
* `t` - top, i.e. center of the top edge of the bounding box
* `tr` - top-right
* `r` - right, i.e. center of the right-hand edge of the bounding box
* `br` - bottom-right
* `b` - bottom, i.e. center of the bottom edge of the bounding box
* `bl` - bottom-left
* `l` - left, i.e. center of the left-hand edge of the bounding box
* `c` - center of the bounding box

Together an 'elref' and a 'locspec' denote a point in 2D user coordinates.

**Edge-based LocSpec** - as a special case of 'locspec', those locations
which define the edge of an element (i.e. t,r,b,l) may be followed by an offset to
vary the resulting point position along the edge. The offset is separated from the
locspec by a colon (`:`), and may be either a number or a percentage.

Each edge starts at the 'left' (`t` / `b` edges) or 'top' (`l` / `r` edges) and
ends at the right/bottom of the edge respectively.

If a percentage is given (e.g. `:30%`), this represents that percentage along the
edge from the start. This implies that `#abc@t:0%` is equivalent to `#abc@tl`, and
`#abc@t:100%` is equivalent to `#abc@tr`. Note that the value given is not restricted
to 0%..100%, but can exceed this range.

If the value is a number rather than a percentage, it is treated differently. A
positive value is an offset from the start of the edge, while a negative offset
moves *backwards* from the end of the edge. This is analogous to slice indexing in
the Python language, where `a[-1]` represents the last item in the sequence `a`.

Edge offsets can be useful where many connector lines are joining an element and
it would be clearer to keep them separate; rather than having four connectors all
join an element at `@b` for example, consider joining them at `@b:20%`, `@b:40%`,
`@b:60%` and `@b:80%`.

**Direction Spec** - ('dirspec') denotes a directional relation between
two objects. The following dirspec values are supported:

* `h` - place horizontally to the right of the associated elref
* `H` - place horizontally to the left of the associated elref
* `v` - place vertically below the associated elref
* `V` - place horizontally above the associated elref

### Relspec

The above pieces fit together according to the following grammar.

```
dirspec    := : [h|H|v|V]
locspec    := @ [tl|t|tr|r|br|b|bl|l|c] | ([t|r|b|l] : length)
length     := number | (number %)

elref      := prevspec | ref
prevspec   := ^
ref        := # ident
ident      := alphanumeric

relspec  := elref [dirspec | locspec]
```

Following the `relspec` as defined above, additional values may be given to define
margins or deltas.

When used as part of a dirspec (e.g. `#abc:H`), a single value defines the 'gap'
between the referenced element and the one being positioned.

When used as part of a locspec (e.g. `@tl`), a pair of values may be provided which
define the `dx` and `dy` offsets to apply.

Some simple examples:

* `xy="#abc:h 5"` - position this element 5 units to the right of the element
  with `id="abc"`.
* `cxy="^"` - position this element to have its center on the center of the
  previous element.
* `xy="^:V"` - position this element directly above the previous element.
* `xy="^@br"` - position this element at the bottom-right of the
  previous element.
* `xy="#thing@tr 5 10"` - position this element at the top-right of
  element with `id="thing"`, offset by (5, 10).