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.

exJ2_cshexJ2

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.

exB6_cshexB6

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.

ex76_cshex76

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.

ex77_csh ex77

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).

ex78_cshex78

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.

ex79_csh ex79

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.