Custom Shape Module =================== The custom shape module allows you to create new shapes for Dia without writing any C code. Instead, you just have to write a simple XML file describing the shape. This opens up the job of creating new shapes for dia to non programmers as well. The actual shape is described using a subset of the SVG specification. The line, polyline, polygon, rect, circle, ellipse, path and g elements are supported. Note that the path element only supports the M,m,L,l,H,h,V,v,C,c,A,a,S,s,Z and z commands. Transformations and CSS units are not supported (only `user' units are), and only a limited set of the CSS attributes are supported. A number of connection points can be associated with the shape, which are specified in the same coordinate system as the shape description. A text box can be associated with the shape. The text box is also specified in the same coordinate system as the shape description. To choose size and position of the text box, you can think of one rectangle to contain the text box, and another one to contain all other svg elements (call it the image rectangle): When you get the shape to the canvas, and write some text, all of it has to go inside the text box; if necessary, this text box will grow, and, in the same proportion, the image rectangle will also grow. The rest is taken care of for you (resizing, moving, line connection, loading, saving, undo, etc). Shapes ====== A typical shape file may look something like this: Circuit with identifiers - NPN Transistor npn.xpm 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: Any aspect ratio is OK (the default) Fix the aspect ratio for this shape. 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 can-parent element allows to enable parenting for a shape. This is only useful for rectangular shapes, which should work as a container of other shapes or objects. So typical shapes wont have it. The textbox element allows you to associate some text with the shape. The syntax is: (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 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): 1cm 3cm 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. The Shape Description ===================== The Scalable Vector Graphics format is used to describe the shape. That is why the separate namespace is used for that part of the file. Each of the SVG drawing elements understands the style attribute. The attribute should be of the form: Currently only the following style attributes are understood: stroke-width - The width of the line, relative to the user specified width. stroke-linecap - The line cap style. One of butt, round, square, projecting (a synonym for square), or default. stroke-linejoin - The line join style. One of miter, round, bevel or default. stroke-pattern - The dash pattern. One of none, dashed, dash-dot, dash-dot-dot, dotted or default. stroke-dashlength - The length of the dashes in the dash pattern, in relation to the user selected value (default is a synonym for 1.0). stroke-opacity - alpha value between 0..1.0 fill-opacity - alpha value between 0..1.0 stroke - The stroke colour. You can use one of the symbolic names foreground, fg, default, background, bg inverse, text or none, or use a hex colour value of the form #rrggbb. fill - The fill colour. The same values as for stroke are used, except that the meaning of default and inverse are exchanged. By default, elements are not filled, so to get the default fill, use "fill: default" So to draw a rectangle with a hairline stroke, the following would do the trick: Ordinates x and y grow as in Dia. The recognised drawing elements are: This is the group element. You can place other drawing elements inside it. The contents of the style attribute on a group element will propagate to the contained elements (unless they override it). This element is a line. This is a polyline. That is, a number of connected line segments. The points attribute holds the coordinates of the end points for the line segments. The coordinates are separated by white space or commas. The suggested format is "x1,y1 x2,y2 x3,y3 ...". This is a polygon. The points argument has the same format as the polyline. This is a rectangle. The upper left corner is (x1,y1), and the lower right corner is (x1+width,y1+height). To get rounded corners either rx or ry or both can be given for the single supported corner radius. If both are given the average gets used. This is an external image. The upper left corner is (x1,y1), and the lower right corner is (x1+width,y1+height). Their are two forms of links supported, an absolute filename of the form "file:///home/user/image.png" or a relative one without the file:// prefix like in "image.png". The latter form is preferred because it is installation independent. The filename is relative to the shape file placement. In the above example PNG and shape need to be in the same directory. Inlined image data is also supported with xlink:href="data:image/png;base64,..." This is a circle with centre (cx,cy) and radius r. This is a ellipse with centre (cx, cy) and radius rx in the x direction and ry in the y direction. This is the most complicated drawing element. It describes a path made up of line segments and bezier curves. It currently does not support the elliptic arc or quadratic bezier curves. The d string is made up of a number of commands of the form "x arg1 arg2 ..." where x is a character code identifying the command, and the arguments are numbers separated by white space or commas. Each command has an absolute and relative variant. The absolute one are spelled with an upper case letter. The relative ones are spelled with a lower case letter, and use the end point of the previous command as the origin. The supported commands are: M x,y Move cursor L x,y Draw a line to (x,y) H x Draw a horizontal line to x V y Draw a vertical line to y C x1,y1 x2,y2, x3,y3 Draw a bezier curve to (x3,y3) with (x1,y1) and (x2,y2) as control points. S x1,y1 x2,y2 Same as above, but draw a `smooth' bezier. That is, infer the first control point from the previous bezier. Z Close the path. If the path is closed with z or Z, then it can be filled. Otherwise, it will just be drawn. ... A text in the shape. The text has to be enclosed in the tags The parameters are: x,y The text position style Text formatting options The following style options are supported: font-size: font size in pt(?) Shapes in Shapes aka. Subshapes =============================== Adding indepentently resizable symbols into your custom shapes is possible by creating subshapes. This is done by some extra attributes on the group element. v_anchor The vertical anchoring of the subshape. Supported values are: "fixed.top", "fixed.bottom", "proportional" h_anchor The horizontal anchoring of the subshape. Supported values are: "fixed.left", "fixed.right", "proportional" default_scale currently unused Extented Attributes =================== To extend your custom shape with custom attributes you can put something like: between the tags. The effect will be some custom properties in your object. They are editable by the properties dialog and will be loaded and saved with your diagram. To programatically access them use "custom:" The Sheet description ===================== You can put several shapes in one sheet: the shapes you create or any other shape or object "belonging" to other sheets. A simple sheet file may look something as this: Circuit with identifiers Circuito con identificadores Components for circuit diagrams Componentes para diagramas de circuitos

How Dia helps to create and manage sheets and shapes. ===================================================== You can use Dia with its available elements to draw a shape and then export it to a shape file, by using File (of diagram)->Export->By extension->Shape. But until now, this shapes don't have any text box. (They are expected to manage some svg:text but not a text box). If you need one, you can edit the file. Together with the shape file, you get a png file (after accepting the proposed size) which can be used for the shape's icon. By using File(of principal menu)->Sheets and Objects you can create new sheets; and add, remove and parcially edit shapes; and copy or move shapes from one sheet to other. Design Notes ============ The custom shape code is designed so that a sheet of objects can be self contained in a single directory. Installing new shapes can be as easy as untaring a .tar.gz file to ~/.dia/shapes or $(prefix)/share/dia/shapes, with the sheet description going to ~/.dia/sheets If you have any suggestions for this code, please discuss on dia-list@gnome.org. James Henstridge with some modifications written by Dolores Alia de Saravia