### 11.2 Block Types and Definition ¶

There are several types of blocks.

1. Boxes are the most common type. They are rectangular in shape, may have rounded or bevelled corners, may contain a label and/or other blocks. They can be defined via the `box <name>` or `boxcol <name>` commands. The former will have its content oriented left-to-right (as a row), while the second top-to-bottom (as a column), see more on block alignment below. The name is case sensitive and optional.

2. Shapes behave like boxes, but may have arbitrary shape, defined by the `defshape` command. They can be defined via the `shape <shape> <name>` command or using an asterisk as a shorthand `*<shape> <name>`. The name is case sensitive and optional. `text` is a special kind of shape, that has no outline or fill, just a label. You can invoke it via the `text <name>` command, usually adding the label.

3. Any box or shape can be made into a multiblock series by specifying the `multi` keyword and an optional number before them. This makes the original block appear in several overlapped versions. The content (if any) is kept only once: for the front block in the series. The name of content blocks remain the same as without the multi clause. That is, in case `multi box A { box B;}` block `B` will have the full name `A.B`. The name `A` will refer to the entire multiblock series, while `A.front` and `A.back` will only refer to the front or back block of the series. These may be important when routing arrows to elements of a block series. You can use the optional number after the `multi` keyword to specify the number of instances (defaults to 3) and the `multi_offset.x` and `multi_offset.y` attributes to specify in which direction and how much shall the subsequent instances appear.

4. Invisible containers are rectangular blocks that contain other blocks, but have no visual appearance: no line, fill or shadow and no label either. They have zero margin, as well. They are only used to group other boxes and to govern their default layout. They can be defined using the `row <name>`, `col <name>` or `cell <name>` commands and their name is also case sensitive and optional. Using `row <name>` or `col <name>` will result in a default row or column arrangement of blocks inside, respectively. In contrast, blocks in a `cell` are continued to be laid out by default as in the parent block. `cell` is useful when you want to temporarily break a row or column, add a small comment, for example, and then continue the row or column, as in the example below.

5. Other charts (of any language supported by Msc-generator) can be included as a block. This is done via the `chart <language> <name>` command. The name is case sensitive and optional. After potential attributes, you can specify the chart to include enclosed between `<<<` and `>>>` tokens. The natural size of the block will be the size of the included chart.

6. There are two special kinds of blocks, that do not appear, but control layout only. Spaces are merely adding extra distance between two blocks in an easy way without any visual appearance. You can define them via the `space <number>` command, where the number is a distance in pixels added and is optional.68 Breaks do not even add space, merely separate blocks in a sequence, see Default alignment. You can add them, via the `break;` command.
7. You can encircle other blocks via the `around` command. List the blocks to include separated by plus signs and follow by a box or shape specification. Msc-generator will prepare a block as big as to just include the listed blocks into its content area. You can specify a label, too. You can also specify content, which will be included into the content area, but will by default be in no aligment relation to the encircled blocks. I am not sure what this feature is good for. By default around blocks have no fill.

8. You can define blocks that are joins of other blocks. Use the `join` keyword followed by the blocks to join separated by plus signs. This is useful to quickly create new shapes from existing ones, such as an L-shape from two boxes.

   The unison of the surface area of those other blocks is taken to be the surface of the join block. No name, label or content can be specified. Join blocks can have only line, fill and shadow attributes (not even alignment as their position is fully determined by the joined blocks). If they have any of the above three attribute set, the corresponding attribute in the joined blocks is removed. Thus, for example, if the join block has line attributes (the default), the joined blocks do not draw a line.

   On the example below, we created three blocks (original), then joined them with leaving only the line attribute of the join set (Line); or unsetting line and setting fill attributes (Fill); or unsetting line and setting shadow attributes (Shadow). Note that the second is useful to apply a smooth gradient fill to the entire joined area and that in this case the joined area must be drawn before the blocks joined (so that the fill is behind them). In the last example the join only draws the shadow.

Blocks (except space and break) can be followed by attributes, see Common Attributes (including a colon-label, see Labels) and contained blocks enclosed in braces.

The definition of blocks and arrows must be ended with a semicolon (‘`;`’). However, if a block contains other blocks, its closing brace (‘`}`’) does not have to be followed by a semicolon (to adhere to C syntax better). In fact, no closing brace in Block Diagrams needs a semicolon after (including design definitions, etc.).

Block and shape definition commands can be used to define multiple blocks in one command. Simply list multiple names separated by commas instead of a single name. You must give a name to all blocks defined like that. Any attributes and content you specify will apply to all blocks defined that way.

If the `pedantic` chart option is set to `no` then you can define blocks without the `box` keyword or without specifyin a shape, just by typing the block name. (Unnamed blocks cannot be defined this way.) The block created will take its attributes from its default style and the running style. Its shape will be taken from the running style (defaults to a box).

You can specify more than one block name separated by commas. If you specify any attribute (including a potential colon label), it will apply to all the blocks defined. However, if there already exists a block with the name you list no new block will be created, only its attributes will be updated. This is true if the block of a given name exists outside this scope. Finally, block names used in arrow specifications will also get auto-created. Let us see a few examples.

Note that the above makes it impossible to forward-reference a block from an arrow definition (as it will get auto-created). To allow that you need `pedantic` set to `yes`. In that case, blocks can only be created by the `box` or `shape` commands or via the asterisk abbreviation. You can still change their attributes later, however.

#### Footnotes

##### (68)

If the number is omitted space will try to add "just the right amount" of space. Currently this is the not so clever, fixed 10 pixels, but it may changle later.