Specifying Arrows

Arrows are probably the most important elements in a message sequence chart. They represent the actual messages. Arrows can be specified using the following syntax. 

entityname arrowsymbol entityname [attr = value | style, ...];

arrowsymbol can be any of ‘->’, ‘<-’ or ‘<->’, the latter for bidirectional arrows. a->b is equivalent to b<-a. This produces an arrow between the two entities specified using a solid line. Using ‘>’/‘<>’, ‘>>’/‘<<>>’ or ‘=>’/‘<=>’, will result in dotted, dashed or double line arrows, respectively. These settings can be redefined using styles, see Defining Styles.

It is possible to omit one of the entity names, e.g., a->;. In this case the arrow will expand to/from the chart edge, as if going to/coming from an external entity.

It is possible to specify multi-segment arrows, such as a->b->c in which case the the arrow will expand from ‘a’ to ‘c’, but an arrow head will be drawn at ‘b’, as well. This is used to indicate that ‘b’ also processes the message indicated by the arrow. The arrow may contain any number of segments, and may also start and end without an entity, e.g., ->a->b->c->d->;. As a syntax relaxation, additional line segments can be abbreviated with a dash (‘-’), such as a<=>b-c-d;. Subsequent segments inherit the line type and direction of the first one. This enables quick changes to these attributes with minimal typing, as only the first arrow symbol needs to be changed. As a further possibility, different arrow symbols can also be used for different segments, such as a->b=>c>>d-e;, but all the arrow symbols must be of the same direction. It is therefore not possible to mix arrows of different directions, such as a->b<-c; or a->b<->c;. Note that specifying different arrow symbols affect only the line attributes of the segments, not the arrowhead, text or other attributes.

If the entities in a multi-segment arrow are not listed in the same (or exact reverse) order as in the chart, Msc-generator gives an error and ignores the arrow. This is to protect against unwanted output after rearranging entity order.

Arrows can also be defined starting and ending at the same entity, e.g., a->a;. In this case the arrow will start at the vertical line of the entity and curve back to the very same line. Such arrows cannot be multi-segmented.

Only non-grouped entities can be used in an arrow definition. If an entity used to define an arrow is not shown due to the collapse of its group entity, Msc-generator will automatically use the collapsed group entity when drawing the arrow, instead. If the arrow becomes degenerate (spanning between only a single collapsed group entity) or disappears entirely, an indicator will be shown instead, if the ‘indicator’ attribute of the collapsed group entity was set to yes (default).

Lost Messages

Sometimes one want to express that a message is lost. You can do this in Msc-generator in two ways. Either, you can add an asterisk between the two entities where the message is lost; or you can add a ’lost at’ clause after the arrow specification before the label or attributes. This causes a small x to be drawn at the place specified and the dimming of the remainder of the arrow.

The first three ones are the quick one. The message lost will be indicated around the entity after or before the asterisk. Specifically, it will be between this and its neighbouring visible entity. If that visible entity is also part of the arrow, the loss will be at one third the distance between them, else it will be halfway. Using the second form, you can specify exactly where the loss happened. It can be placed onto an entity, left or right from it, or between two entities. These are specified as ‘lost at <entity>’, ‘lost at <entity>-’, ‘lost at <entity>+’ or ‘lost at <entity1>-<entity2>’, respectively. You can add two plus or minus symbols to increase distance. You can also specify any offset in addition by adding a number after, such as in ‘lost at <entity> <number>’. The number will be interpreted in pixels and shifts the vertical left or right depending on its sign.

The appearance of the loss symbol (the x) can be influenced using the x.line.width, x.line.color and the x.size attributes. The latter takes the same values as arrowhead sizes: tiny, small, normal, big or huge, with normal as default.

The appearance of the lost portion of the message can also be influenced via the lost.text.*, lost.line.* and the lost.arrow.* attributes. Anything specified here will be added to the text, line and arrowhead format of the arrow. Currently only the color of the line and the arrowhead is overlaid with ++white,128 (for plain designs), making them weaker, but you can change to dash lines, specifly a narrower line or empty arrowheads.

Arrow Attributes

Arrows can have the following attributes.

label

This is the text associated with the arrow. See Labels for more information on how to specify labels. In Msc-generator the first line of the label is written above the arrow, while subsequent lines are written under it. Future versions may make this behaviour more flexible.

text.*

All text formatting attributes described in Common Attributes can be used to manipulate the appearance of the label[19].

number

Can be set to yes, no or to a number, to turn numbering on or off, or to specify a number, respectively. See Numbering.

refname

Can be set to any string and is used to give a name to the arrow, which can be used to reference this arrow. Use the \r(name) escape in labels to insert the number of the referenced arrow. See Numbering.

compress

Can be set to yes or no to turn compressing of this arrow on or off. See Compression and Vertical Spacing.

vspacing

Can be set to a number interpreted in pixels or to the string compress. Governs how much vertical space is added before the arrow (can be negative). This attribute is another form (superset) of the compress attribute; compress=yes is equivalent to vspacing=compress, whereas compress=no is equivalent to vspacing=0.

angle

This takes a number in degrees and makes the arrow slanted. Arrows pointing to the same entity cannot have such an attribute. This attribute takes its default value from the angle chart option (or is zero in the absence of such an option, which corresponds to horizontal arrows).

slant_depth

This is similar in effect to the angle attribute, but instead of specifying the angle of the slant in degrees, you can use this attribute to specify how many pixels shall the end of the arrow be below the start of it. If you specify both the angle attribute and slant_depth the latter takes effect.

color

This specifies the color of the text, arrow and arrowheads. It is a shorthand to setting text.color, line.color and arrow.color to the same value.

line.color, line.width

Set the color and the width of the line, see Common Attributes.

line.corner

This attribute specifies how the line shall be drawn at corners. It impacts boxes and entities drawn with this line, for arrows it is effective for arrows that start and end at the same entity. Its value can be none, round, bevel or note. See the example below. Setting line.corner without line.radius will result in the default radius of 10.

line.radius

For arrows starting and ending at the same entity, this specifies the roundness of the arrow corners. 0 is fully sharp (equivalent to line.corner=none, positive values are meant in pixels, a negative value will result in a single arc (for any corner setting). If only line.radius is set and not line.corner the result will be a round corner.

arrow.size

The size of the arrowheads. It can be tiny, small, normal, big or huge, with small as default.

arrow.color

The color of the arrowheads.

arrow.type

Specity the arrowhead type. The values can be half, line, empty, solid, which draw a single line, a two-line arrow, an empty triangle and a filled triangle, respectively. The above 4 types also exist in double and triple variants, which draw two or three of them. sharp and empty_sharp draws a bit more pointier arrowhead, filled or empty, respectively. diamond and empty_diamond draws a filled or empty diamond, while dot and empty_dot draws a filled or empty circle. Specifying none will result in no arrowhead at all. This attribute sets both the endtype and midtype, see below.

arrow.endtype

Sets the arrow type for arrow endings only. This refers to the end of the arrow, where it points to. In case of bidirectional arrows, both ends are drawn with this type. It defaults to a filled triangle.

arrow.midtype

This attribute sets the arrowhead type used for intermediate entities of a multi-segment arrow. It defaults to a filled triangle.

arrow.starttype

This attribute sets the arrowhead type used at the starting point of an arrow. It defaults to no arrowhead.

arrow.xmul , arrow.ymul

These attributes change the width or the height of the arrowhead. The default value is ‘1’. They are multipiers, thus the value of ‘1.1’ results in a 10% increase, for example.

lost.text.*

The values specified here will be added to the values of text.* when drawing the label of the lost part of the message.

lost.line.*

The values specified here will be added to the values of line.* when drawing the line of the lost part of the message.

lost.arrow.*

The values specified here will be added to the values of arrow.* when drawing the arrowheads in the lost part of the message.

x.size

The size of the loss symbol for lost messages. It can be tiny, small, normal, big or huge, with normal as default.

x.line.width , x.line.color

The linewidth and color of the loss symbol for lost messages.

Note that default values can be changed using styles, see Defining Styles.

Block Arrows

When typing block in front of any arrow definition, it will become a block arrow. The label of a block arrow is displayed inside it. In addition to the attributes above, block arrows also have fill and shadow attributes, similar to entities.

All arrowheads explained above for regular arrows are supported, except the double and triple ones. In general, types with empty in them, draws a variant of the arrowhead which is not taller that the body of the block arrow. The ones with line draw the same as the ones without. Three additional types empty_inv, ‘stripes’ and ‘triangle_stripes’ types are supported, as well. See the example below for a detailed list of all types supported for block arrows.

If the arrow has multiple segments and the type of the inner arrowheads is either of half, line, empty, solid or sharp the block arrow is split into multiple smaller arrows. In this case the arrow label is placed into the leftmost, rightmost or middle one of the smaller arrows, depending on the value of the text.ident attribute.

It is also possible to use different arrow symbols leading to different line types, but only if the middle arrow type is such that the arrow is split into multiple contours. If not, the whole arrow is drawn with the line type of the first segment.

Block arrows can also be slanted using the angle attribute.


[19] A special note on left and right text margins (to be specified via \ml() and \mr() escapes). Msc-generator always adds enough text margins to prevent the label to overlap with the arrowhead. Thus, if you specify less margin, it will have no effect.