<drawing>

A <drawing> input element lets you display a two dimensional drawing. It lets you create simple drawing items such as lines, rectangles, ovals, pictures, polygons and text. The user may interact with the drawing by clicking on designated hotspots.

NOTE: This document describes the input drawing element. For the output element, see drawing (output)

Example

<input>
  <drawing>
   <about>
    <label>Element</label>
    <description>Select the element.</description>
   </about>
   <background></background>
   <substitutions></substitutions>
   <components></components>
  </drawing>
</input>

Drawing Items

A <drawing> element may contain one or more drawing items (polygon, line, rectangle, oval, text, or picture). The drawing items are described in the <components> element.

  <drawing>
   <components>
     drawing items...
   </components>
  </drawing>

Rectangle Item

The <rectangle> drawing item draws a rectangle at the specified coordinates which are the corners of the rectangle. The rectangle can be filled or transparent. It may have an outline border.

   <rectangle>
     <coords>.25 .25 .75 .75</coords> 
      <outline>black</outline>
      <fill>blue</fill>  
      <linewidth>2</linewidth>
   </rectangle>

<coords>

X-Y coordinates of the rectangle. The 4 values represent opposite corners of the rectangle.

<fill>

Set the color of the filled interior of the rectangle. If the fill color is not set, the rectangle will not be filled (transparent).

<outline>

Set the color to outline of the rectangle. The outline color defaults to black. If the outline color is blank, the outline will not be drawn.

<linewidth>

Width of the outline. The default is 1 pixel.

Line Item

The <line> drawing item displays a polyline of one or more segments. You can specify the color and width of the lines. The line may have arrowheads on either or both ends.

   <line>
     <coords>.25 .75 .75 .75</coords>
     <color>black</color>
     <linewidth>2</linewidth>
     <arrow>both</arrow>
   </line>

<coords>

X-Y coordinates of the line. There must be at least 4 values representing the coordinates the line segment. Polylines can be created by specifying more coordinate pairs.

<color>

Set the color of the line. The default is black.

<linewidth>

Width of the line. The default is 1 pixel.

<arrow>

Specifies whether the line is displayed with arrow heads. The value given indicates whether or not arrowheads are to be drawn at one or both ends of the line. Where must have one of the values none (for no arrowheads), first (for an arrowhead at the first point of the line), last (for an arrowhead at the last point of the line), or both (for arrowheads at both ends). The default is none.

Text Item

The <text> drawing item displays text at the specified coordinates. You can designate the font and the color of the text.

  <text>
    <coords>.5 .8</coords>
    <color>black</color>
    <font>Arial 9</font>
    <anchor>c</anchor>
    <text>Feature Length = ${flen}</text>
    <hotspot>inline</hotspot>
  </text>

<anchor>

Tells how to position the text relative to the positioning point for the item; it may have be one of the following: c, n, s, e, w, nw, sw, ne, or se. For example, if the anchor is c (center) then the text is centered on the point; if anchor is n then the item will be drawn such that the top center point of the rectangular region occupied by the text will be at the positioning point. The default is c.

<color>

Set the color of the text. The default text color is black.

<coords>

X-Y coordinate of the text. The 2 values in addition to the <anchor> will designate the location of the text.

<font>

Specifies the font to use for the text item. The font name is a list in the form "family ?size? ?style? ?style ...?". The first element is the font family, the optional second element is the desired size. The many be more elements specifying the style such as bold or italic. The default is "Arial 10".

<hotspot>

Indicates to display hotspots right before any substitution in the text. This can be "yes", "no", "on", "off", "true", or "false". When hotspots are off, the text is still displayed, but there will no control to edit the text. The default is "off".

<text>

Specifies the text of item. The text may contain variable substitutions.

Oval Item

The <oval> drawing item displays an oval at the specified coordinates. The oval can be filled or transparent. It may have an outline border.

  <oval>
    <coords>.25 .25 .75 .75</coords>
    <outline>black</outline>
    <fill>green</fill>
    <linewidth>2</linewidth>
  </oval>

<coords>

X-Y coordinates of the oval. The 4 values represent opposite corners of the oval.

<fill>

Set the color of the filled interior of the oval. If the fill color is not set, the oval will not be filled (transparent).

<outline>

Set the color to outline of the oval. If the outline color is blank, the outline will not be drawn. The default outline color is black.

<linewidth>

Width of the outline. The default is 1 pixel.

Picture Item

   <picture>
     <coords>-1 1  1 -1</coords>
     <anchor>nw</anchor>
     <width>3</width>
     <height>2</height>
     <contents>file://foo.gif</contents>
   </picture>

<coords>

If you specify a single coordinate (x-y pair), then it is treated as the item's anchor point. This and the <anchor> element will determine exactly where the picture is placed on the drawing.

If you specify two coordinates, they represent the opposite corners of the picture. The picture will be scaled to fit the area designated.

<anchor>

Tells how to position the picture relative to the positioning point for the item; it may have be one of the following: c, n, s, e, w, nw, sw, ne, or se. For example, if the anchor is c (center) then the picture is centered on the point; if anchor is n then the item will be drawn such that the top center point of the rectangular region occupied by the picture will be at the positioning point. The default is c.

<width>

Set the width of the picture.

<height>

Set the height of the picture.

Either width or height is required to set the scale of the picture. If both are specified, then the picture can be scaled without preserving its aspect ratio. If only one is specified, we use the aspect ratio to figure out the other. If neither is specified, warn on stderr and pick 1/4 of the overall width to move forward.

Polygon Item

The <polygon> drawing item displays polygonal or curved filled regions. The coordinates must represent a least 3 coordinate pairs that define a polygon. The first point should not be repeated as the last to close the shape. The polygon will automatically close the periphery between the first and last points.

 <polygon>
   <coords>.25 .75  .75 .75  .75 .25  .25 .25</coords>
   <outline>black</outline>
   <fill>red</fill>
   <linewidth>2</linewidth>
 </polygon>

<coords>

X-Y coordinates of the polygon. There must be at least 6 values representing the coordinates the polygon.

<linewidth>

Width of the outline. The default is 1 pixel.

<fill>

Set the color of the filled interior of the polygon. If the fill color is not set, the polygon will not be filled (transparent).

<outline>

Set the color to outline of the polygon. If the outline color is blank, the outline will not be drawn. The default outline color is black.

Grid Item

  <grid>
    <xcoords>0 .1 .2 .3 .4 .5 .6 .7 .8 .9 1</xcoords>
    <ycoords>.2 .3 .4 .5 .6 .7</ycoords>
    <color>grey70</color>
    <linewidth>1</linewidth>
    <dash>4 2</dash>
  </grid>

Hotspots

  <hotspot>
    <coords>0 0</coords>
    <color>blue</color>
    <controls>input.phase(1).group(sizes).boolean(tip)</controls>
    <controls>input.phase(1).group(sizes).number(flen)</controls>
    <controls>input.phase(1).group(sizes).group(props)</controls>
  </hotspot>

<anchor>

Tells how to position the text relative to the positioning point for the item; it may have be one of the following: c, n, s, e, w, nw, sw, ne, or se. For example, if the anchor is c (center) then the text is centered on the point; if anchor is n then the item will be drawn such that the top center point of the rectangular region occupied by the text will be at the positioning point. The default is c.

<color>

Set the color of the text. The default text color is black.

<coords>

X-Y coordinate of the text. The 2 values in addition to the <anchor> will designate the location of the text.

<font>

Specifies the font to use for the text item. The font name is a list in the form "family ?size? ?style? ?style ...?". The first element is the font family, the optional second element is the desired size. The many be more elements specifying the style such as bold or italic. The default is "Arial 10".

<Background>

  <background>
     <color>black</color>
     <coordinates>0 0 at 50% 50% 1 1 at 100% 100%</coordinates>
     <aspect>2 1</aspect>
   </background>

<color>

Sets the background color of the drawing. The default is white.

<coordinates>

Specifies the range coordinates for the drawing background. Items draw outside of these ranges will not be visible. The coordinates comes in the following forms:

x0 y0 x1 y1
Specifies the range of coordinates at the corners of the drawing. x0 y0 at screenx screeny x1 y1 at screenx screeny Specifies the range of coordinates designating points at specific screen locations.

The screenx/screeny values are optional, so you can also say something like "-.1 0 1.1 1" as you had in your example. This lets you put the origin at a specific point on screen,

and also define the directions of the axes. We still compute the overall bounding box. In the example below, the bounding box goes from -1,1 in the upper-left corner to 1,-1 in the lower right.

<height>

Sets the width of the drawing area. The default is 400 pixels. If you set the width to zero, the contents of the drawing will indicate the width of the drawing.

<width>

Sets the height of the drawing area. The default is 300 pixels. If you set the width to zero, the contents of the drawing will indicate the height of the drawing area.

Substitutions