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_typeat
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.
We have to note
that text
is just syntactic sugar for a rectangle
with no line or
fill. Rectangles can also contain text.
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.
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.