doc/custom-shapes

   1 Custom Shape Module
   2 ===================
   3
   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.
   8
   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.
  15
  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.
  18
  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.
  21
  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.
  28
  29
  30
  31 The rest is taken care of for you (resizing, moving, line connection,
  32 loading, saving, undo, etc).
  33
  34
  35 Shapes
  36 ======
  37
  38 A typical shape file may look something like this:
  39   <?xml version="1.0"?>
  40
  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>
  44     <icon>npn.xpm</icon>
  45     <connections>
  46       <point x="0" y="0"/>
  47       <point x="6" y="-4"/>
  48       <point x="6" y="4"/>
  49     </connections>
  50
  51     <aspectratio type="fixed"/>
  52
  53     <textbox x1="4" y1="-3" x2="12" y2="3" />
  54
  55     <svg:svg>
  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" />
  60
  61       <svg:polyline points="5,4 6,4 5.6154,3.0769" />
  62     </svg:svg>
  63
  64   </shape>
  65
  66 Only the name and svg elements are required in the shape file.  The
  67 rest are optional.
  68
  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
  71 loading.
  72
  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
  75 is optional.
  76
  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.
  80
  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.
  84
  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.
  90
  91 The last option allows you to specify a range of allowable amounts of
  92 distortion, which may be useful in some cases.
  93
  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.
  99
 100
 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/
 105
 106 The next section details what parts of the SVG spec can be used in
 107 shape files.
 108
 109
 110 The Shape Description
 111 =====================
 112
 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.
 115
 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"/>
 119
 120 Currently only the following style attributes are understood:
 121   stroke-width - The width of the line, relative to the user specified
 122                  width.
 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
 126                       default.
 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
 131                       synonym for 1.0).
 132
 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"
 140
 141 So to draw a rectangle with a hairline stroke, the following would do
 142 the trick:
 143   <svg:rect style="stroke-width: 0" x="..." y="..." width="..." height="..."/>
 144
 145
 146 Ordinates x and y grow as in Dia.
 147
 148 The recognised drawing elements are:
 149
 150 <svg:g>
 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).
 154
 155 <svg:line x1="..." y1="..." x2="..." y2="..."/>
 156   This element is a line.
 157
 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 ...".
 163
 164 <svg:polygon points="...."/>
 165   This is a polygon.  The points argument has the same format as the
 166   polyline.
 167
 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).
 171
 172 <svg:circle cx="..." cy="..." r="..."/>
 173   This is a circle with centre (cx,cy) and radius r.
 174
 175 <svg:ellipse cx="..." cy="..." rx="..." ry="..."/>
 176   This is a ellipse with centre (cx, cy) and radius rx in the x direction
 177   and ry in the y direction.
 178
 179 <svg:path d="...."/>
 180   This is the most complicated drawing element.  It describes a path
 181   made up of line segments and bezier curves.  It currently does not
 182   support the elliptic arc or quadratic bezier curves.  The d string
 183   is made up of a number of commands of the form "x arg1 arg2 ..."
 184   where x is a character code identifying the command, and the
 185   arguments are numbers separated by white space or commas.  Each
 186   command has an absolute and relative variant.  The absolute one are
 187   spelled with an upper case letter. The relative ones are spelled with
 188   a lower case letter, and use the end point of the previous command
 189   as the origin.
 190
 191   The supported commands are:
 192     M x,y                 Move cursor
 193     L x,y                 Draw a line to (x,y)
 194     H x                   Draw a horizontal line to x
 195     V y                   Draw a vertical line to y
 196     C x1,y1 x2,y2, x3,y3  Draw a bezier curve to (x3,y3) with (x1,y1)
 197                           and (x2,y2) as control points.
 198     S x1,y1 x2,y2         Same as above, but draw a `smooth' bezier.
 199                           That is, infer the first control point from
 200                           the previous bezier.
 201     Z                     Close the path.
 202
 203   If the path is closed with z or Z, then it can be filled.
 204   Otherwise, it will just be drawn.
 205
 206 <svg:text x="..." y="..." style="...">...</svg:text>
 207   A text in the shape. The text has to be enclosed in the tags
 208
 209   The parameters are:
 210   x,y                     The text position
 211   style                   Text formatting options
 212
 213   The following style options are supported:
 214   font-size: font size in pt
 215
 216 The Sheet description
 217 =====================
 218
 219 You can put several shapes in one sheet: the shapes you create  or any
 220 other shape or object "belonging" to other sheets.
 221
 222 A simple sheet file may look something as this:
 223
 224
 225 <?xml version="1.0" encoding="utf-8"?>
 226 <sheet xmlns="http://www.lysator.liu.se/~alla/dia/dia-sheet-ns">
 227   <name>Circuit with identifiers</name>
 228   <name xml:lang="es">Circuito con identificadores</name>
 229   <description>Components for circuit diagrams</description>
 230   <description xml:lang="es">Componentes para diagramas de circuitos</description>
 231   <contents>
 232     <object name="Circuit with identifiers - NPN Transistor">
 233      <description>A bipolar npn transistor</description>
 234      <description xml:lang="es">Un transistor bipolar npn identificable</description>
 235     </object>
 236     <object name="UML - Objet">
 237      <description>An UML object</description>
 238      <description xml:lang="es">Un objeto UML</description>
 239     </object>
 240    </contents>
 241 </sheet>
 242
 243 How Dia helps to create and manage sheets and shapes.
 244 =====================================================
 245
 246 You can use Dia with its available elements to draw a shape and then
 247 export it to a shape file, by using
 248    File (of  diagram)->Export->By extension->Shape.
 249 But until now, this shapes  don't have any text box. (They are expected
 250 to manage some svg:text but not a text box). If you need one,  you can
 251 edit the file.
 252 Together with the shape file, you get a png file (after accepting the
 253 proposed size) which can be used for the shape's icon.
 254
 255 By using
 256       File(of principal menu)->Sheets and Objects
 257 you can create  new sheets;  and add,  remove and parcially edit  shapes;
 258 and copy or move shapes from one sheet to other.
 259
 260 Design Notes
 261 ============
 262
 263 The custom shape code is designed so that a sheet of objects can be
 264 self contained in a single directory.  Installing new shapes can be as
 265 easy as untaring a .tar.gz file to ~/.dia/shapes or
 266 $(prefix)/share/dia/shapes, with the sheet description going to
 267 ~/.dia/sheets
 268
 269
 270
 271
 272
 273
 274
 275 If you have any suggestions for this code, please tell me.
 276
 277
 278   James Henstridge <james@daa.com.au>
 279  with some modifications written by
 280  Dolores Alia de Saravia<loli@unsa.edu.ar>
 281
 282
 283