#### 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 rel_pos [refname] [attributes];
    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 text62, a cross symbol or a shape, respectively. The position of the symbol can be specified three ways as above.

The first (most natural) method places the symbol relative to another element. This element can be specified using its `refname` attribute. If the reference name is omitted, then the last element before the symbol is used. (This is similar to how Verticals can be laid out, see Verticals.) The rel_pos can be one of `leftof`, `rightof`, `above`, `below` or `around` specifying what relation the symbol shall be to the referenced element. The `around` option will also size the symbol to encompass all of the referenced element, useful for `cross`, `rectangle` or `arc`. Using this placement method makes the symbol a by ref symbol. Such symbols (and verticals) are positioned in relation to another element and are laid out together with that element. If there are multiple such by ref symbols (or verticals) attached for an element, they are laid out in the order they appear in the source file. For such symbols the following additional attributes are available.

`align`

  This specifies where along the side of the referenced element the symbol shall be placed. It can be set to `left`, `center` or `right` for `above`/`below` and `top`, `center` or `bottom` for `leftof`/`rightof`. The `above_centerline`, `centerline` and `below_centerline` values are also available for `leftof`/`rightof`. Not applicable for `around`. The default is `center`.

`offset`

  This shall be a number (defaults to 0). The symbol is shifted by this number of pixels left (negative) or right (positive) for `above`/`below` and up (negative) or down (positive) for `leftof`/`rightof`. Not applicable for `around`.

`distance`

  This shall be a number (defaults to 0). The symbol is placed by this number of pixels further away from (positive) or closer to (negative) the referenced element. For `around` it effectively expands or shrinks the symbol (applying a distance on all 4 sides).

`adjust`

  This attribute can be used to adjust the left/right/top/bottom edge of th symbol after placement. You can specify one to four numbers. If one is specified, it applies to all edges, if two they apply to left/right, respectively, if three, they apply to left/right/top, and if four they apply to left/right/top/bottom. The numbers are interpreted as pixels.

The second method (using `at`) places the symbol at the horizontal position of an entity. You can also use `--`, `-`, `+` or `++` to place the symbol left or right of the entity line (or maybe a bit further out) and you can also use a number after the entity to shift the symbol to the right (positive) or to the left (negative). The symbol is drawn at the vertical position where they are specified in the file, just like regular elements and the space occupied by the symbol is considered at layout.

With the third method, the symbol will be placed after the layout of the chart. 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). You have complete freedom in selecting both its horizontal and vertical position. Vertical position is specified via markers, similar as for verticals, see Verticals. 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)63. 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` attribute64. 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 the 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

##### (62)

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

##### (63)

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.

##### (64)

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.