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,S,s,A,a,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).