4 The custom shape module allows you to create new shapes for Dia
5 without writing any C code. Instead, you just have to write a simple
6 XML file describing the shape. This opens up the job of creating new
7 shapes for dia to non programmers as well.
9 The actual shape is described using a subset of the SVG
10 specification. The line, polyline, polygon, rect, circle, ellipse,
11 path and g elements are supported. Note that the path element only
12 supports the M,m,L,l,H,h,V,v,C,c,S,s,Z and z commands.
13 Transformations and CSS units are not supported (only `user' units
14 are), and only a limited set of the CSS attributes are supported.
16 A number of connection points can be associated with the shape, which
17 are specified in the same coordinate system as the shape description.
19 A text box can be associated with the shape. The text box is also
20 specified in the same coordinate system as the shape description.
22 To choose size and position of the text box, you can think of one
23 rectangle to contain the text box, and another one to contain all
24 other svg elements (call it the image rectangle): When you get the
25 shape to the canvas, and write some text, all of it has to go inside
26 the text box; if necessary, this text box will grow, and, in the same
27 proportion, the image rectangle will also grow.
31 The rest is taken care of for you (resizing, moving, line connection,
32 loading, saving, undo, etc).
38 A typical shape file may look something like this:
41 <shape xmlns="http://www.daa.com.au/~james/dia-shape-ns"
42 xmlns:svg="http://www.w3.org/2000/svg">
43 <name>Circuit with identifiers - NPN Transistor</name>
51 <aspectratio type="fixed"/>
53 <textbox x1="4" y1="-3" x2="12" y2="3" />
56 <svg:line x1="0" y1="0" x2="3" y2="0" />
57 <svg:line x1="3" y1="-3" x2="3" y2="3" />
58 <svg:line x1="3" y1="-2" x2="6" y2="-4" />
59 <svg:line x1="3" y1="2" x2="6" y2="4" />
61 <svg:polyline points="5,4 6,4 5.6154,3.0769" />
66 Only the name and svg elements are required in the shape file. The
69 The name element give the name of the object. The
70 name is a unique identifier for this shape that is used for saving and
73 As in the example, you may use "compound names". Many shapes have first
74 part of its name to indicate the sheet in which they appear, but this
77 The icon element specifies an xpm file or a png file that is used as
78 the icon in the dia toolbox. The filename can be relative to the shape
79 file. If it is not given, a default custom shape icon will be used.
81 The connections section specifies a number of connection points for
82 the shape. The coordinate system for these points is the same as the
83 coordinate system used in the svg shape description.
85 The aspectratio element allows you to specify how the shape can be
86 distorted. The three possibilities are:
87 <aspectratio type="free"/> Any aspect ratio is OK (the default)
88 <aspectratio type="fixed"/> Fix the aspect ratio for this shape.
89 <aspectratio type="range" min="n" max="m"/> Give a range of values.
91 The last option allows you to specify a range of allowable amounts of
92 distortion, which may be useful in some cases.
94 The textbox element allows you to associate some text with
95 the shape. The syntax is:
96 <textbox x1="left" y1="top" x2="right" y2="bottom"/>
97 (Only one textbox per shape) Where the attributes give the bounds of
98 the text box in the same coordinate system as the SVG shape description.
101 The svg element describes the shape. The width and height attributes
102 are ignored, and only given to comply with the SVG specification. For
103 more information on SVG, see the W3C pages about the format at:
104 http://www.w3.org/Graphics/SVG/
106 The next section details what parts of the SVG spec can be used in
110 The Shape Description
111 =====================
113 The Scalable Vector Graphics format is used to describe the shape.
114 That is why the separate namespace is used for that part of the file.
116 Each of the SVG drawing elements understands the style attribute. The
117 attribute should be of the form:
118 <svg:whatever style="name1: value1; name2: value2; ... name42: value42"/>
120 Currently only the following style attributes are understood:
121 stroke-width - The width of the line, relative to the user specified
123 stroke-linecap - The line cap style. One of butt, round, square,
124 projecting (a synonym for square), or default.
125 stroke-linejoin - The line join style. One of miter, round, bevel or
127 stroke-pattern - The dash pattern. One of none, dashed, dash-dot,
128 dash-dot-dot, dotted or default.
129 stroke-dashlength - The length of the dashes in the dash pattern, in
130 relation to the user selected value (default is a
133 stroke - The stroke colour. You can use one of the symbolic
134 names foreground, fg, default, background, bg inverse,
135 text or none, or use a hex colour value of the form #rrggbb.
136 fill - The fill colour. The same values as for stroke are used,
137 except that the meaning of default and inverse are
138 exchanged. By default, elements are not filled, so to get
139 the default fill, use "fill: default"
141 So to draw a rectangle with a hairline stroke, the following would do
143 <svg:rect style="stroke-width: 0" x="..." y="..." width="..." height="..."/>
146 Ordinates x and y grow as in Dia.
148 The recognised drawing elements are:
151 This is the group element. You can place other drawing elements
152 inside it. The contents of the style attribute on a group element
153 will propagate to the contained elements (unless they override it).
155 <svg:line x1="..." y1="..." x2="..." y2="..."/>
156 This element is a line.
158 <svg:polyline points="...."/>
159 This is a polyline. That is, a number of connected line segments.
160 The points attribute holds the coordinates of the end points for the
161 line segments. The coordinates are separated by white space or
162 commas. The suggested format is "x1,y1 x2,y2 x3,y3 ...".
164 <svg:polygon points="...."/>
165 This is a polygon. The points argument has the same format as the
168 <svg:rect x1="..." y1="..." width="..." height="..."/>
169 This is a rectangle. The upper left corner is (x1,y1), and the lower
170 right corner is (x1+width,y1+height).
172 <svg:image x1="..." y1="..." width="..." height="..." xlink:href="..." />
173 This is an external image. The upper left corner is (x1,y1), and the
174 lower right corner is (x1+width,y1+height).
175 Their are two forms of links supported, an absolute filename of the form
176 "file:///home/user/image.png" or a relative one without the file:// prefix
177 like in "image.png". The latter form is preferred cause it is installation
178 independent. The filename is relative to the shape file placement. In the
179 above example PNG and shape need to be in the same directory.
181 <svg:circle cx="..." cy="..." r="..."/>
182 This is a circle with centre (cx,cy) and radius r.
184 <svg:ellipse cx="..." cy="..." rx="..." ry="..."/>
185 This is a ellipse with centre (cx, cy) and radius rx in the x direction
186 and ry in the y direction.
189 This is the most complicated drawing element. It describes a path
190 made up of line segments and bezier curves. It currently does not
191 support the elliptic arc or quadratic bezier curves. The d string
192 is made up of a number of commands of the form "x arg1 arg2 ..."
193 where x is a character code identifying the command, and the
194 arguments are numbers separated by white space or commas. Each
195 command has an absolute and relative variant. The absolute one are
196 spelled with an upper case letter. The relative ones are spelled with
197 a lower case letter, and use the end point of the previous command
200 The supported commands are:
202 L x,y Draw a line to (x,y)
203 H x Draw a horizontal line to x
204 V y Draw a vertical line to y
205 C x1,y1 x2,y2, x3,y3 Draw a bezier curve to (x3,y3) with (x1,y1)
206 and (x2,y2) as control points.
207 S x1,y1 x2,y2 Same as above, but draw a `smooth' bezier.
208 That is, infer the first control point from
212 If the path is closed with z or Z, then it can be filled.
213 Otherwise, it will just be drawn.
215 <svg:text x="..." y="..." style="...">...</svg:text>
216 A text in the shape. The text has to be enclosed in the tags
219 x,y The text position
220 style Text formatting options
222 The following style options are supported:
223 font-size: font size in pt
225 The Sheet description
226 =====================
228 You can put several shapes in one sheet: the shapes you create or any
229 other shape or object "belonging" to other sheets.
231 A simple sheet file may look something as this:
234 <?xml version="1.0" encoding="utf-8"?>
235 <sheet xmlns="http://www.lysator.liu.se/~alla/dia/dia-sheet-ns">
236 <name>Circuit with identifiers</name>
237 <name xml:lang="es">Circuito con identificadores</name>
238 <description>Components for circuit diagrams</description>
239 <description xml:lang="es">Componentes para diagramas de circuitos</description>
241 <object name="Circuit with identifiers - NPN Transistor">
242 <description>A bipolar npn transistor</description>
243 <description xml:lang="es">Un transistor bipolar npn identificable</description>
245 <object name="UML - Objet">
246 <description>An UML object</description>
247 <description xml:lang="es">Un objeto UML</description>
252 How Dia helps to create and manage sheets and shapes.
253 =====================================================
255 You can use Dia with its available elements to draw a shape and then
256 export it to a shape file, by using
257 File (of diagram)->Export->By extension->Shape.
258 But until now, this shapes don't have any text box. (They are expected
259 to manage some svg:text but not a text box). If you need one, you can
261 Together with the shape file, you get a png file (after accepting the
262 proposed size) which can be used for the shape's icon.
265 File(of principal menu)->Sheets and Objects
266 you can create new sheets; and add, remove and parcially edit shapes;
267 and copy or move shapes from one sheet to other.
272 The custom shape code is designed so that a sheet of objects can be
273 self contained in a single directory. Installing new shapes can be as
274 easy as untaring a .tar.gz file to ~/.dia/shapes or
275 $(prefix)/share/dia/shapes, with the sheet description going to
284 If you have any suggestions for this code, please tell me.
287 James Henstridge <james@daa.com.au>
288 with some modifications written by
289 Dolores Alia de Saravia<loli@unsa.edu.ar>