#### 9.13.2 Symbols

Currently Msc-generator can draw circles (ellipses), ellipses (three dots), cross symbols (a big ‘`X`’), arbitrary shapes, rectangles (optionally with text) or just plain text. We call these symbols.

    symbol symbol_type at entity [attributes];
    symbol symbol_type marker-marker hpos1 hpos2 [attributes];

By specifying either `arc`, `rectangle`, `...`, `text`, `cross` or `shape` after the `symbol` keyword one instructs Msc-generator to draw one circle/ellipsis, rectangle, ellipses, plain text56, a cross symbol or a shape, respectively.

The vertical position of the symbols can be specified two ways. Either they are in-line, which means they occupy space and the layout engine takes them into account when laying out entities above below. In this case symbols will be drawn at the vertical position where they are specified in the file, just like any other element (except verticals). To achieve in-line placement, use the first, simpler syntax or the second one without markers (and the dash in-between).

Otherwise it is possible to specify the vertical position where the symbol should appear. This can be done via markers, similar as for verticals, see Verticals. In this case however, the layout engine will ignore the symbol when placing other elements and the symbol may end up drawn overlapping other elements (this may be your intention).

The vertical size of the object can be specified two ways. Either you specify two markers (as above), in which case the symbol will vertically span from one to the other; or you omit one of the markers, in which case the `ysize` attribute specifies the height (in points)57. If the dash is in front of the marker, the bottom of the symbol will be aligned with the marker. If the dash is after the marker, then the marker designates the top of the symbol.

In the example below we see three rectangles. One stretches between two markers, the second is bottom aligned, while the third is top aligned.

The horizontal position of the symbol is specified via one or two horizontal position specifiers. They specify the horzontal position of either the left or right edge of the symbol or of its center. This is governed by the first keyword

    left|center|right at entity-entity [number]
    left|center|right at entity--
    left|center|right at entity-
    left|center|right at entity [number]
    left|center|right at entity+
    left|center|right at entity++

Then, after the `at` keyword one specifies either one entity with additional modifiers or two entities. In the former case the horizontal position will be at the middle of the entity’s line or somewhat left or right of it depending on the modifiers. In the latter the horizontal position will be between the two entities. Two of the forms can also take a number, which is interpreted as pixels and will shift the position to the right for positive values and to the left for negative values.

If you specify two such horizontal position specifiers one after the other, they describe both the placement of the symbol and its width. If you specify one, the width of the symbol can be specified using the `xsize` attribute58. This may sound a bit complicated, so here is an example with 5 in-line symbols.

Whether the symbol is drawn behind or in front of other elements can be controlled by the ‘`draw_time`’ attribute. It can take the following values.

`before_background`

  Elements with this property will be drawn before the background. This has effect only if the background is transparent (to some degree or part).

`before_entity_lines`

  Elements with this property will be drawn before the entity lines are laid out in the order as they are specified in the chart description.

`after_entity_lines`

  Elements with this property will be drawn just after the entity lines are laid out, but before regular elements are drawn.

`default`

  This is the default, elements with no `draw_time` will be drawn this time in the order as specified in the chart description.

`after_default`

  Elements with this property will be drawn last, after all the above elements in the order as they are specified in the chart description.

Note that from v3.3.4 any element can specify the `draw_time` attribute. It will not impact thet layout only the drawing order (what is called the z-order).

As you can see the first (leftmost) rectangle was drawn below the entity lines, the second (middle) one between the entity lines and the arrows, while the last (rightmost) one was drawn on top of the arrows.

Finally we show a few examples of how symbols may be used.

#### Footnotes

##### (56)

We have to note that `text` is just syntactic sugar for a `rectangle` with no line or fill. Rectangles can also contain text.

##### (57)

In case of rectangles and text, you can use the natural size of the label you specify as the height of the symbol by omitting the `ysize` attribute. If you specify a shape, it is enough to specify one of the sizes, the other will be calculated to keep the original aspect ratio of the shape.

##### (58)

Similar to height, in case of rectangles and text, you can use the natural size of the label you specify as the width of the symbol by omitting the `xsize` attribute.