### 4.2 Defining Entities

Msc-generator, by default draws the entities from left to right in the order they appear in the chart description. In the examples above, the first entity to appear was always the ‘`Client`’, the second ‘`Server`’ and the third ‘`Backend`’.

Often one wants to control, in which order entities appear on the chart. This is possible, by listing the entities before actual use. On the example below, the order of the enties are reversed. Note that we have reversed the first arrow to arrive to the ‘`Client`’ from the right.

Often the name of the entity need to be multi-line or need to contain formatting characters, or is just too long to type many times. You can overcome this problem by specifying a label for entities. The name of the entity then will be used in the chart description, but on the chart the label of the entity will be displayed. The ‘`label`’ is an attribute of the entity and can be specified between square brackets after the entity name, before the comma, as shown below. (You can specify entity attributes only when explicitly defining an entity and not if you just start using them without listing them first.)

You can also use the colon-notation to specify entity labels, similar to arrows. The above example can thus be written as below. Note that the entity definitions are now terminated by a semicolon – commas would be treated as part of the label.

Entities can also be specified as ‘`weak`’ or ‘`strong`’, by applying these styles the same way as for arrows. You can also assign various shapes to the entity headings via the `shape` attribute.

Entities can be turned on and off at certain points in the chart. An entity that is turned off, will not have its vertical line displayed. This is useful if the chart has many entities, but one is involved only in a small part of the process. An entity can be turned off by typing `hide` followed by the name of the entity. You can turn it later back on with the `show` keyword followed by the entities to turn on. When `hide` is used for an entity right at its definition, it will start hidden and its heading is not drawn at the place of definition. However, when it is later turned on, a heading will be shown.

Not showing an entity from the beginning of the chart can also be achieved by simply defining the entity later. Note that this is different from simply starting to use an entity later. When you start using an entity without explicitly defining it first, it will appear at the top of the chart, not only where started using it first. (See earlier examples.)

Sometimes the vertical space between entities is just not enough to display a longer label for an arrow. In this case use the ‘`hscale`’ chart option to increase the horizontal spacing. It can be set to a numerical value, 1 being the default.

Or you can simply set it to ‘`auto`’, which creates variable spacing, just as much as is needed.

Alternatively, you can instruct Msc-generator to apply word wrapping to the labels of arrows, to fit into the available space, by setting the ‘`text.wrap`’ chart option to ‘`yes`’.

It is possible to define entity groups, to indicate logical relations between various entities. Use curly braces (‘`{`’ and ‘`}`’) after an entity definition (after any potential label and attributes).

Instead of a group heading, you can also shade the background behind entities in an entity group.

It is also possible to collapse a group entity hiding details of the process. This can be done either via the ‘`collapsed`’ attribute or, on Windows, using the GUI. Elements that disappear leave a small indicator (box with 3 dots). The collapsed entity group also includes an indicator to show that further entities are hidden within. (Indicators can be turned off by the ‘`indicator`’ chart option.

Entities can be activated. This results in the entity line becoming a thin rectangle instead. If you do this immediately after an arrow the activation will happen at the tip of the arrow indicating that the cause of the activation is the arrow.