An example layout sheet - modelint/flatland-model-diagram-editor GitHub Wiki

Let’s see how all this works with a simple Executable UML class model example. In your Aicraft.xmm model file you have specified an Aircraft and a Pilot class with a single relationship named R1 between the two of them. There may be a lot of other information in your model file, but you won’t need to refer to any of that in your layout file.

The layout refers only to those elements in the model file that can be represented as either a node or a connector. A node is a rectangle containing text in one or more compartments. A connector is a set of named or unnamed line segments that draw a path from one node face to another.

Now before we start placing these elements, we need to specify some setup information for our diagram first. Here are the first few lines you must include at the top of your layout file. These lines can appear in any order:

diagram class
notation Starr
presentation default
sheet letter // That's A4 for the rest of the world!
orientation landscape

You can’t sprinkle these keywords throughout your file, they all need to be up at the top before you get to the node and connector sections. We’ll refer to this collection of keywords as the header.

Diagram type

The diagram keyword chooses the type of diagram you want to draw. In our case it is a class diagram (as opposed to a state machine diagram for example). This piece of information tells Flatland what node and connector types are used in this kind of diagram.

Flatland is nit-picky about spacing by design. This ensures that files all have a consistent look. The keyword must not be indented and there is at least one space between the keyword and its argument.

Notation

Flatland distinguishes between a diagram type and a notation. A given diagram type may support more than one notation. For example, you could specify Starr, xUML or Shlaer-Mellor notation for your class diagram.

Presentation

The presentation is a set of styles that are applied when the diagram is drawn. One presentation might use Palatino 12 font for class names and thick border lines while another might use Verdana 10 and thin blue border lines. If you choose the diagnostic presentation, you might see a lot of vibrant colors highlighting graphical components, helpful for diagnostics, but that wouldn’t be of interest to an end user. It’s easiest to just choose the default styles for your diagram type and notation.

Sheet

Flatland outputs a single diagram sheet as a PDF file, so you must specify your desired sheet size and orientation.

That’s it for the header (for this simple example, anyway).

Comments

You can sprinkle comments anywhere in your layouts. Any text including and after two forward slashes // is ignored by the layout sheet parser.

The node section

After the header comes the node section.

Flatland employs a spreadsheet-like grid to specify place node placement. So instead of fussing with measurement units like points, inches, pixels, centimeters and so forth, we refer instead to grid locations. A node can be positioned alone in a cell or it can span multiple cells. To prevent unsightly node overlap, no two nodes may occupy the same grid cell.

The node section begins with the unindented nodes keyword, followed by one indented node placement specification for each node.

To align both classes in our model example horizontally, we’ll put them in the same row:

nodes
    Aircraft 1,1  // row 1, Column 1
    Pilot 1,3

We have positioned the Aircraft node at row 1, column 1. Flatland uses positive Cartesian coordinates so that cell 1,1 is the lower left corner. This makes it easy to build a model up working left to right and upward.

The grid grows and flexes as you add elements. Flatland always starts with zero rows and columns and then adds and sizes them to accommodate each new node placement.

There is a minimum height and width for any node type and, if a node contains enough text, it may exceed those minimums. So a really small node will be surrounded by extra space in its cell. A large node will widen its row, column or both to fit. Any smaller node sharing the same row or column will end up surrounded by some empty space in its cell.

The Pilot node is two columns to the right of the Aircraft node. This ensures that there is some extra space to draw the connector.

Those are the basics for node placement. There are some more advanced options such as column or row spanning and internal cell alignment explained later in this guide.

You must indent each node placement specification exactly four spaces under the nodes keyword. There is at least one space after the node name and there is no space on either side of the row-column comma. So 3, 2 will trigger an error.

The connector section

After the node section comes the connector section. It starts with the unindented connectors keyword. In our example there is just one connector placement specification since there is only one relationship in the model, R1.

We’ll place the R1 connector in a centered, straight line between our two nodes.

connectors
    -R1 : +/1 r|Aircraft : +/2 l*|Pilot  // Binary connector

You can see that the layout instruction is split into three pieces delimited by a : symbol and surrounding whitespace. We’ll take these pieces one at a time moving left to right.

Connector name

The first section places the connector name: -R1. The minus sign tells us that the name should appear below the connector line. Had our line been vertical, the - sign would specify that the name goes on the left side of the connector line. In this, and all Flatland layout specifications, plus and minus signs indicate increasing or decreasing coordinate values on the x or y axis. Since we have a Cartesian coordinate system, values increase upward and to the right.

Stem name and face anchor

Next we place the end of the connector attached to the Aircraft class: +/1 r|Aircraft. This is called a stem placement specification. A stem is the short bit of a connector attached to a node face. Depending on your notation, there may be a text label like 0..1 or some decoration such as arrow heads, circles, dots or crosses on the stem. Our example stem specification tells us what to do with the stem attached to the Aircraft node. The + tells us that, if there is a name associated with the stem, put it above the stem line. In our model the stem is named is flying. The /1 tells us to keep the name text all in one line. Think of this symbol as ‘dividing’ the text among n lines.

The r|Aircraft specifies that the stem attaches to the (r)ight face of the Aircraft node. The | symbol is intended to make you think of a node face. Since no offset was specified, the stem will attach to the center of the node face. We’ll get to offsets later. For now, let’s stay centered.

After the rightmost : symbol we see our second stem specification, +/2 l*|Pilot. This is the stem that attaches to the Pilot node. Here the stem name is kept on a single line above the stem and attaches to the left face of the Pilot node. The * symbol represents a floating anchor. (It sort looks like a cloud right?) By ‘float’ we mean that the stem does not meet the node face at any explicit point. Instead, the stem connects wherever a straight line projecting from the Aircraft right face meets the Pilot left face. The pairing of anchored and floating stems ensures that we always get a straight line. By design, Flatland does not draw diagonal connector lines. So whenever you specify a non-bending connector between two node faces, one stem is firmly anchored while the other floats. If you leave out the * or specify two floating or two anchored stems in the same connector, you will get an error and no diagram. But you may reverse the specification and place the * on the Aircraft side instead. If both the Pilot and Aircraft nodes are the same size or centered vertically within the row (we’ll get to row/column alignment later), it won’t make any difference which side you choose. But if one node is larger and the other is aligned with one side or the other of its row/column it will make a difference since the floating stem won’t necessarily be centered on its node face.

The full specification

Here’s our complete specification:

diagram class
notation Starr
presentation default
sheet letter  // 8.5 x 11 inches
orientation landscape
nodes
    Aircraft 1,1 // Row 1, Column 1
    Pilot 1,3
connectors
    -R1 : +/1 r|Aircraft : +/2 l*|Pilot  // Binary connector

We type the following command in the terminal:

% flatland -m aircraft1.xmm -l ac_horizontal -G

The -G option on the command line gives us a diagnostic grid which can be helpful when you are building up a new diagram.

The lower left of the resultant pdf should look like this:

images/layout-sheet-guide/intro/20-intro.png

Model elements are drawn only in the diagram area which is a subset of the entire canvas which itself represents the area within the full sheet dimensions. Here the diagram origin is slightly offset from the canvas corner. Later in this guide we’ll see how you can move the diagram origin away from the lower left edge of the canvas and size the diagram as desired using the padding keyword in the header section.

So that’s our tour of the basic layout features. A comprehensive set of features and options are detailed in the remainder of this guide.

Layout file keywords

Now let’s dive deeper and look at the full syntax and all advanced options for keywords you can use in the layout file sections. We’ll start with the header section and work our way down through the node and connector sections with a variety of examples.