11.2. Shapes
Prev | Chapter 11. Custom Shape Module | Next

## 11.2. Shapes

A typical shape file may look something like this:

`
<?xml version="1.0"?>
<shape xmlns="http://www.daa.com.au/~james/dia-shape-ns"
xmlns:svg="http://www.w3.org/2000/svg">
<name>Circuit with identifiers - NPN Transistor</name>
<icon>npn.xpm</icon>
<connections>
<point x="0" y="0"/>
<point x="6" y="-4" main="yes"/>
<point x="6" y="4"/>
</connections>
<aspectratio type="fixed"/>
<textbox x1="4" y1="-3" x2="12" y2="3" />
<svg:svg>
<svg:line x1="0" y1="0" x2="3" y2="0" />
<svg:line x1="3" y1="-3" x2="3" y2="3" />
<svg:line x1="3" y1="-2" x2="6" y2="-4" />
<svg:line x1="3" y1="2" x2="6" y2="4" />
<svg:polyline points="5,4 6,4 5.6154,3.0769" />
</svg:svg>
</shape>
`

Only the `name` and `svg` elements are required in the shape file. The rest are optional.

The `name` element give the name of the object. The name is a unique identifier for this shape that is used for saving and loading.

As in the example, you may use "compound names". Many shapes have first part of its name to indicate the sheet in which they appear, but this is optional.

The `icon` element specifies an xpm file or a png file that is used as the icon in the dia toolbox. The filename can be relative to the shape file. If it is not given, a default custom shape icon will be used.

The `connections` section specifies a number of connection points for the shape. The coordinate system for these points is the same as the coordinate system used in the svg shape description.

The `aspectratio` element allows you to specify how the shape can be distorted. The three possibilities are:

- `<aspectratio type="free"/>` - Any aspect ratio is OK (the default)
- `<aspectratio type="fixed"/>` - Fix the aspect ratio for this shape.
- `<aspectratio type="range" min="n" max="m"/>` - Give a range of values.

The last option allows you to specify a range of allowable amounts of distortion, which may be useful in some cases.

The `textbox` element allows you to associate some text with the shape. The syntax is:

`
<textbox x1="left" y1="top" x2="right" y2="bottom"/>
`

(Only one textbox per shape) Where the attributes give the bounds of the text box in the same coordinate system as the SVG shape description.

There are some optional attributes on <textbox/> namely

resize="no" :
  by default the textbox is resized with the text
align="center" :
  "center" is default, also "left" and "right" can be used

Shapes are given a default size on creation. If that default size does not fit your needs you can overwrite it by (one or both): <default-width>1cm</default-width> <default-height>3cm</default-height> The default unit "cm" can be omitted.

The `svg` element describes the shape. The width and height attributes are ignored, and only given to comply with the SVG specification. For more information on SVG, see the W3C pages about the format at: http://www.w3.org/Graphics/SVG

The next section details what parts of the SVG spec can be used in shape files.

Prev | Up | Next
Chapter 11. Custom Shape Module | Home | 11.3. The Shape Description