DrawML Specification

Embedding

A DrawML drawing is embedded in the SGML/XML document. If required parent DTD elements can be embedded in the DrawML drawing. Compare to a CALS table, where the content model for a cell is declared in the main DTD. In DrawML it is possible to insert paragraphs, lists, images, tables, etc. inside a drawing.

There are several advantages accruing from a tight integration of the document and the drawings it contains.

• It is easy to cut and paste objects between a drawings and its surroundings.

• Simpler, unified interface for handling text.

• Text inside drawings is searchable, can be spell-checked, its case can be changed, etc.

• A drawing can contain complex SGML/XML text structure (paragraphs, lists, tables).

• There is no need for external entities.

• References (id/idref, XLink) can be made to and from drawings.

The drawml element introduces a drawing in a document. At this point the "rendering engine" enters the DrawML mode in which the elements inside the drawing are drawn in accordance with the rules set forth in this specification. Somewhere in the drawing we want to include other non drawing elements. The lmward element (drawml spelled backwards!) temporarily leaves the DrawML mode and enters the ordinary rendering mode.

In the following example a paragraph with an emphasized word is written inside a rectangular shape.

<drawml>
 <shape type="rectangle">
  <lmward>
   <p>This is <em>my</em> text</p>
  </lmward>
 </shape>
</drawml>

Automatic Sizing

We expect a table cell to adjust to its content and a paragraph to adjust to the frame width and we should expect similar functionality in a drawing.

One of the important concepts underlying DrawML is that shapes adjust to their content by default (just like cells in a table). A DrawML shape may contain other shapes.

For instance a shape will expand if the text placed inside it does not fit.

<drawml>
 <shape type="rectangle"></shape>
 <shape type="rectangle" width="100">
  <lmward>
   <p>This is <em>my</em> text</p>
  </lmward>
 </shape>
</drawml>

In the above case the width of the rectangle was explicitly set, which forced the text in the paragraph to wrap.

Automatic Positions

By placing shapes inside other shapes it is possible to arrange and group intelligently. The parent shape can be invisible and thus be used for the sole purpose of grouping. By default, shapes are arranged horizontally.

<drawml>
 <shape type="rectangle">
  <shape type="rectangle">
   <lmward>Hello</lmward>
  </shape>
  <shape type="rectangle">
   <lmward>World</lmward>
  </shape>
 </shape>
</drawml>

DrawML drawings work with structures rather than coordinate positions. When the user adds a new shape in the structure the application will make room for the new shape automatically.

<drawml>
 <shape type="rectangle">
  <shape type="rectangle">
   <lmward>Hello</lmward>
  </shape>
  <shape type="rectangle">
   <lmward>new</lmward>
  </shape>
  <shape type="rectangle">
   <lmward>World</lmward>
  </shape>
 </shape>
</drawml>

Shapes can also be arranged vertically.

<drawml>
 <shape type="rectangle" arrange="vertical">
  <shape type="rectangle">
   <lmward>Hello</lmward>
  </shape>
  <shape type="oval"></shape>
  <shape type="oval"></shape>
  <shape type="rectangle">
   <lmward>World</lmward>
  </shape>
 </shape>
</drawml>

A position can be explicitly defined using a coordinate. This coordinate is relative to its parent shape so when a parent is moved, its child is moved with it. Each shape defines a coordinate system for its children.

<drawml>
 <shape type="rectangle">
  <shape type="oval" x="100" y="20">
  </shape>
 </shape>
</drawml>

Automatic Connections

Drawing objects are often connected, e.g., an arrow points from one object to another, a group of objects are connected to a parent object in a hierarchical structure, etc. If objects are moved connections should adjust to the new layout. This effect is often referred to as the "rubber band" effect.

In DrawML shapes may have one or more hook positions. These positions are suitable connection points. Connections are defined with the line element. A connection consists of two or more positions (pos elements). Each position is either glued to a hook position in a shape or explicitly assigned a coordinate position.

A rectangle, for example, typically has four hook positions; W, N, E and S (west, north, east and south).

<drawml>
 <shape type="rectangle" shape-id="d1">
  <lmward>Hello</lmward>
 </shape>
 <shape type="rectangle" x="50" y="50" shape-id="d2">
  <lmward>World</lmward>
 </shape>
 <line>
  <pos attach-to="d1" attach-point="S"/>
  <pos attach-to="d2" attach-point="N"/>
 </line>
</drawml>

Sometimes we may want to connect to the nearest point on a shape. This point is defined with the reserved hook name $nearest.

<drawml>
 <shape type="oval" shape-id="d1">
  <lmward>Hello</lmward>
 </shape>
 <shape type="oval" x="50" y="50" shape-id="d2">
  <lmward>World</lmward>
 </shape>
 <line>
  <pos attach-to="d1" attach-point="$nearest"/>
  <pos attach-to="d2" attach-point="$nearest"/>
 </line>
</drawml>

A line may connect several shapes. The line is by default drawn from shape to shape in the order of the positions.

On the other hand, a line can connect the involved shapes in three other ways: horizontally, vertically or centrally. The "centre of gravity" gives the renderer a default "central position" to be used as visualized below.

The "central position" can be specified explicitly.

Shapes in Java

The success of a standard often depends on its extendability. In DrawML all shapes are defined using Java, including rectangles and circles. The power of a programming language such as Java gives shape developers the necessary flexibility.

The following example is a house shape.

<drawml>
 <shape type="house">
 </shape>
</drawml>

When child shapes are positioned inside the shape the house should be bigger. It is the shape that decides how the house should adapt to its children. Note that the roof is not getting any higher, ,just wider.

<drawml>
 <shape type="house">
    <lmward>A house</lmward>
 </shape>
</drawml>

The Java shapes have a CalcSize() method that calculates each size. The renderer calls these routines when calculating the individual positions. The interesting point is that each shape asks the renderer for the size of the shape's children.

public void CalcSize()
{
   SetW( 7 + 5 + GetWChild() + 5 + 7 );   // Set shape width
   SetH( 10 + 5 + GetHChild() + 5 );      // Set shape height
}

After calculating positions the renderer then calls the DrawShape() routine for each shape. The Java class uses a PAINTER class to do the actual drawing.

The Java-code to draw the house is as follows:

public void DrawShape()
{
   Painter.NewPath();                          // Clear painter
   Painter.MoveTo( 0, 10 );
   Painter.LineTo( MyW()/2, 0 );
   Painter.LineTo( MyW(), 10 );
   Painter.ClosePath();
   Painter.Stroke();                           // Draw roof
   Painter.NewPath();
   Painter.MoveTo( 7, 10 );
   Painter.LineTo( MyW() - 7, 10 );
   Painter.LineTo( MyW() - 7, MyH() );
   Painter.LineTo( 7, MyH() );
   Painter.ClosePath();
   Painter.Stroke();                           // Draw front
}

Elements and Attributes

Units

The unit for coordinates and dimensions is the point. Examples of valid values:

0
-4
64.75
99999

A color is specified as in the CSS standard, either with a predefined name, e.g. "red" or with an RGB value, e.g. rgb(255,0,0).

The DTD

The DrawML element and attribute definitions are in a separate file and should be included in the DTD in the following manner.

<!ENTITY % drawml SYSTEM "drawml.elm" >
%drawml;

Shape development

DrawML shapes are implemented with Java. When the renderer reads a DrawML drawing it discovers shapes of various types. Each shape type should correspond to a Java class file. The renderer then asks each Java shape to report its size, its hooks and where its first child, if any, should be positioned. When all this information is collected the renderer is able to calculate the coordinate position for each shape. It then calls each shape to draw itself.

A Java shape should extend the DrawMLShape base class. The actual drawing of a shape is accomplished through the DrawMLPainter class.