4.3 Diagrams
Each of the three kinds of model file has a diagram. The diagram is drawn from the text, and every change made in the diagram is an edit of the text. Undo in the editor takes such an edit back.
| File | Diagram |
|---|---|
.kstates, also a fragment | Statechart: the states with their inner states, the transitions, splits, joins and timeouts. |
.kmeta, also an event metamodel | Class diagram: one box per type with its properties, and the relations as lines. |
.kmodel | Object diagram: one box per object with its values, and the has and knows relations as lines. |
4.3.1 Views#
The bar below the editor has the buttons Text, Split and Diagram for a file with a diagram. Text shows only the text, Split shows the text and the diagram side by side, and Diagram shows only the diagram. The choice is not stored in the project file.
While the text has errors, the diagram shows the last text that could be read, with the note The text has errors. This is the diagram of the last text that could be read. A file that has nothing to draw yet shows a sentence such as No state machine to draw yet. The diagram appears once the text can be read. instead of a diagram.
4.3.1.1 Moving around#
Drag the empty canvas or scroll to move the drawing. Ctrl+scroll or Cmd+scroll zooms. The buttons in a corner of the canvas are a minus, the zoom in percent, a plus and Fit. A click on the percent sets it back to 100%, and Fit shows the whole diagram. The zoom runs from 20% to 300%. A new diagram is fitted to its pane.
A click on a box selects its name in the text.
4.3.2 Reading a statechart#
| Element | Drawing |
|---|---|
| Header | A title line above the drawing, in its middle. An attached state machine reads ATTACHED TO Lamp, an attachable one glowing ATTACHABLE TO Lamp, Bulb, a fragment bulb_test FRAGMENT. |
| State | A box with round corners. A state with inner states shows its name in a row at its top, a state without inner states in its middle. |
| Container state | A box like a state without inner states. Below its name a row shows a page mark, a small sheet with a folded corner, and the name of the fragment the state uses. The inner states are those of the fragment, drawn in the diagram of the fragment. |
| Final state | A box like a state, with a ring around a dot in its upper right corner. |
| Initial state | A filled dot above the state. |
| Transition | A line from the source state to the target state, ending in an arrowhead. |
| Caption of a transition | The priority, which is the place of the transition in the text, and a label made from the condition, as in 1: switch/press. A transition without a condition shows the priority only. |
| Split, join | A filled bar. The lines from the source states lead into the bar without an arrowhead, and the lines from the bar to the target states end in arrowheads. |
| Timeout | A dashed line from the state to the state its timeout leads to, with the caption after 10 ticks or after 1 tick. |
| Shallow history | A small circle with H behind the name of the state. |
| Deep history | A small circle with H* behind the name of the state. |
| Breakpoint at entry, at exit | A dot in the error colour on the left border of the state for its entry, on the right border for its exit. |
| Breakpoint at start, at end | A dot in the error colour in front of the caption of the transition for its start, behind it for its end. |
| Code | A small circle with a plus. In a state it is followed by the word limit for the tick limit, entry for the entry actions or do for the do actions. On a transition it stands at the right end of the caption and holds the condition. |
The label of a condition is made of its clauses. EVENT("switch", "press") reads switch/press, VALUE("p") reads p, EVAL { return x > 1 } reads [x > 1] and DONE reads DONE. Several clauses are joined by &. A label longer than 40 characters is cut and ends with …. The mark NOT LOOPING is not drawn.
The title line shows the header of the text and changes with it. It cannot be edited, moved or selected in the diagram: the header is written in the text. The line always stands above the topmost element, so it moves up when a state is dragged above it, and it is not stored in the .vis file, see 4.3.8 Arranging by hand.
4.3.3 Reading a class or object diagram#
| Element | Drawing |
|---|---|
| Type | A box with the name of the type at the top and below a line one row per property, as watts: number. A type that behaves after an attachable state machine shows it in its first row, as behaves after glowing. |
| Object | A box with the title key : Type, underlined, at the top and below a line one row per property value, as watts = 0. Long values are cut with …. |
has relation | A line with a filled diamond at the box that has the other. |
knows relation | A line that ends in an open arrowhead at the box that is known. |
| Label of a relation | The name of the relation, with [*] behind it for a list. |
A relation to a type the file does not declare, or a knows to a key the model does not have, is shown as a row of its box. The class diagram shows the types of its own file only.
4.3.4 Editing a statechart#
A right-click on a state, on a line or its caption, on a timeout or on the empty canvas opens a menu of the changes that fit there. Where a change needs one or more states, a prompt such as Click the state the transition leads to. Right-click to cancel. appears, the states to choose from are marked, and you click one. A right-click or a click beside the states cancels. Rename and the other entries that need a name open a field at the pointer, filled with the current value.
Entries that write a construct of an optional language feature show only while the feature is on, see 4.1.7 Language features. An entry that removes such a construct always shows.
The examples below start from this state machine.
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "off" { }
STATE "on" {
STATE "full" { }
STATE "dimmed" { }
}
}
TRANSITIONS {
TRANSITION "off" -> "on" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "on" -> "off" {
CONDITION { EVENT("switch", "press") }
}
}
}
4.3.4.1 On the canvas#
| Entry | Shown | Effect on the text |
|---|---|---|
| Add state | Always | Adds STATE "state" { } at the end of STATES, drawn where you clicked. The name is state, or state 2 and so on if the name is taken. |
| Add initial state | When no state of the file is initial | Adds INITIAL STATE "state" { } in the same way. A file has one initial state, at any depth, see 2.3.2.2 The initial state. |
| Add container state | The project has a fragment the file can use | Shows the fragments of the project as a second menu and adds CONTAINER STATE "name" USE "name" { } for the one you choose, named after the fragment. A fragment does not offer itself. |
| Add final state | In a fragment | Adds FINAL STATE "done" { } at the end of STATES, or done 2 and so on if the name is taken. |
| Add transition | When there are states | Asks for the start, then the target, and adds a transition without a condition at the end of TRANSITIONS. A final state is never a start. |
| Add split | Splits and joins on, at least three states | Asks for the start and two targets, and adds SPLIT "a" -> "b", "c" { }. A final state is never the start. |
| Add join | Splits and joins on, at least three states | Asks for two starts and the target, and adds JOIN "a", "b" -> "c" { }. A final state is never a start. |
| Edit macros | Macros on | Opens the inside of the MACROS block in a code cell. Code saved into an empty cell creates the block. |
Add state on the canvas of the example adds one line:
STATES {
INITIAL STATE "off" { }
STATE "on" {
STATE "full" { }
STATE "dimmed" { }
}
STATE "state" { }
}
Add transition from full to dimmed adds one line at the end of the transitions:
TRANSITIONS {
TRANSITION "off" -> "on" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "on" -> "off" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "full" -> "dimmed" { }
}
4.3.4.2 On a state#
| Entry | Shown | Effect on the text |
|---|---|---|
| Open page NAME | On a container state that names a fragment | Opens the diagram of the fragment, see 4.3.4.5 Pages. It changes nothing. |
| Rename | Always | Renames the state in its declaration, in every transition and in every timeout that names it. A " in the new name becomes '. |
| Edit as text | Always | Opens the whole state in a code cell titled State <name>. |
| Use another fragment | On a container state, when the project has another fragment | Shows the other fragments as a second menu and writes the one you choose after USE. |
| Add inner state | Not on a container or final state | Adds STATE "state" { } at the end of the state's body. |
| Add inner container state | Not on a container or final state, when the project has a fragment the file can use | Shows the fragments as a second menu and adds a container state that uses the one you choose at the end of the state's body. |
| Add transition from here | Not on a final state | Asks for the target, and adds a transition without a condition. |
| Add entry actions | The state has no ENTRY, not on a container or final state | Adds ENTRY { } after the breakpoints and the tick limit of the state. |
| Add do actions | The state has no DO, not on a container or final state | Adds DO { } after the entry actions. |
| Make initial state | The state is not initial, not on a final state | Writes INITIAL in front of the state and takes it from the state that had it, wherever that state stands in the file. |
| Remember the last inner state (shallow history) | Histories on, the state has inner states or is a container state | Writes SHALLOW HISTORY in front of STATE, or of CONTAINER STATE. |
| Remember the last innermost state (deep history) | Histories on, the state has inner states or is a container state | Writes DEEP HISTORY in the same place. |
| Remove history | The state has a history | Takes the history words out. |
| Add tick limit | Tick limits on, the state has none, not on a final state | Adds TICK LIMIT { DELAY: 1 TICK } after the breakpoints of the state. |
| Add breakpoint at entry, Remove breakpoint at entry | Add needs breakpoints on | Writes or changes BREAKPOINT { ENTRY } as the first line of the body. A block without words is taken out. |
| Add breakpoint at exit, Remove breakpoint at exit | Add needs breakpoints on | The same with EXIT. |
| Make outer state | The state is an inner state | Moves the state with its inner states to the top level. |
| Make inner state of | Another state can take it, not on a final state | Asks for the new outer state and moves the state with its inner states into it. A container state or a final state never takes a state. |
| Delete state | Always | Deletes the state, its inner states and every transition that names one of them. |
The empty room inside a state with inner states belongs to that state.
Add entry actions on off:
INITIAL STATE "off" {
ENTRY { }
}
Add breakpoint at entry on on, with breakpoints switched on:
STATE "on" {
BREAKPOINT { ENTRY }
STATE "full" { }
STATE "dimmed" { }
}
Remember the last inner state on on, with histories switched on:
SHALLOW HISTORY STATE "on" {
STATE "full" { }
STATE "dimmed" { }
}
Make outer state on dimmed:
STATES {
INITIAL STATE "off" { }
STATE "on" {
STATE "full" { }
}
STATE "dimmed" { }
}
Rename off to dark changes the declaration and both transitions:
STATEMACHINE ATTACHED TO "Lamp" {
STATES {
INITIAL STATE "dark" { }
STATE "on" {
STATE "full" { }
STATE "dimmed" { }
}
}
TRANSITIONS {
TRANSITION "dark" -> "on" {
CONDITION { EVENT("switch", "press") }
}
TRANSITION "on" -> "dark" {
CONDITION { EVENT("switch", "press") }
}
}
}
4.3.4.3 On a transition#
A transition is hit on its line or on its caption.
| Entry | Shown | Effect on the text |
|---|---|---|
| Edit as text | Always | Opens the whole transition in a code cell titled Transition <caption>. |
| Wait until the fragment is done (DONE) | The transition or split leaves a container state, or a source of the join is one, and the condition has no DONE | Writes DONE as the first clause of the condition, or adds CONDITION { DONE } after the breakpoints. |
| Remove DONE | The condition has DONE | Takes DONE out. A condition that holds nothing else goes as a whole. |
| Add target | Splits and joins on, on a split | Asks for a state and adds it to the targets of the split, as , "x". |
| Add source | Splits and joins on, on a join | Asks for a state and adds it to the sources of the join. A final state is never a source. |
| Move earlier, to priority N | Not on the first transition | Swaps the transition with the one before it in the text. |
| Move later, to priority N | Not on the last transition | Swaps the transition with the one after it. |
| Mark as not looping, Allow looping | Always | Writes NOT LOOPING behind the states, or takes it out. |
| Add breakpoint at start, Remove breakpoint at start | Add needs breakpoints on | Writes or changes BREAKPOINT { START } as the first line of the body. |
| Add breakpoint at end, Remove breakpoint at end | Add needs breakpoints on | The same with END. |
| Delete transition | Always | Deletes the transition. |
Mark as not looping on the first transition:
TRANSITION "off" -> "on" NOT LOOPING {
CONDITION { EVENT("switch", "press") }
}
Add breakpoint at start on the first transition:
TRANSITION "off" -> "on" {
BREAKPOINT { START }
CONDITION { EVENT("switch", "press") }
}
4.3.4.4 On a timeout#
A timeout stands in the tick limit of its state, as TIMEOUT: AFTER 10 TICKS TRANSITION TO "off". It has no priority, no looping mark and no breakpoints.
| Entry | Shown | Effect on the text |
|---|---|---|
| Edit tick limit as text | Always | Opens the inside of the tick limit in a code cell, the same cell its marker opens. |
| Lead to another state | Tick limits on | Asks for a state and changes the name after TRANSITION TO. |
| Remove timeout | Always | Takes the timeout out of the tick limit. A tick limit without a delay goes as a whole. |
No menu entry adds a timeout. Write it into the tick limit through its code cell.
4.3.4.5 Pages#
A container state runs a fragment, which is a state machine of its own file, as its inner states, see 2.3.12 Pages. The statechart draws each file on its own, so the inner states of a container state are a page of their own: the diagram of the fragment. How a container state differs from a state with inner states is described in 2.3.13 Compound states and container states.
Open page on a container state, or a double-click on it, opens the file of its fragment and shows its diagram, next to the text or alone, as the diagram it came from was shown. The fragment is found by its name, one of the context of the file first. When no file of the project declares the name, a dialog says so and nothing opens.
The diagram of a fragment has a bar above the drawing: Used by: and the names of the files whose container states use the fragment. A click on a name opens that file and shows its diagram the same way. A fragment that no file uses reads No state machine uses this fragment.
The examples below start from the lamp of examples/pages. Add container state on its canvas, with warm_up chosen in the second menu, adds one line:
STATES {
INITIAL STATE "off" { }
CONTAINER STATE "self test" USE "bulb_test" { }
STATE "on" {
CONTAINER STATE "warming" USE "warm_up" { }
STATE "steady" { }
}
CONTAINER STATE "warm_up" USE "warm_up" { }
}
Remove DONE on the transition from self test to off, whose condition holds only DONE, takes the condition out:
TRANSITION "self test" -> "off" { }
Wait until the fragment is done on the transition from wiring to failed in bulb_test.frag.kstates writes DONE in front of the clause it has:
TRANSITION "wiring" -> "failed" {
CONDITION { DONE EVENT("service", "smash") }
}
4.3.5 Editing a class diagram#
The examples start from this metamodel.
type "Bulb" "A light bulb" {
prop("watts", "number")
}
type "Lamp" "A lamp" {
has("bulb", "Bulb")
}
4.3.5.1 On the canvas#
Add type adds a type as the first type of the file, so the root type, which is the last one, stays the same. The name is Type, or Type2 and so on if the name is taken.
type "Type" "" {
}
type "Bulb" "A light bulb" {
prop("watts", "number")
}
type "Lamp" "A lamp" {
has("bulb", "Bulb")
}
4.3.5.2 On a type#
| Entry | Effect on the text |
|---|---|
| Rename | Renames the type and every relation that leads to it. |
| Edit as text | Opens the whole type in a code cell. |
| Describe | Opens a field with the description, the second string of the type, and writes it back. |
| Behaves after | Asks for the name of an attachable state machine and adds behaves after "name" after the description, see 2.1.8 Behaviour of a type. Shown while the type has no such clause. |
| Add property | Asks for the name and adds prop("name", "string") at the end of the type. |
| Add has relation to | Asks for the target type and adds has("bulb", "Bulb"), named after the target with a lower-case first letter and a number if the name is taken. |
| Add knows relation to | The same with knows. |
| Make root type | Moves the type to the end of the file. Not shown on the last type. |
| Delete | Deletes the type and every relation that leads to it. |
Add has relation to Bulb on Lamp, which has bulb already:
type "Lamp" "A lamp" {
has("bulb", "Bulb")
has("bulb2", "Bulb")
}
Rename Bulb to Light:
type "Light" "A light bulb" {
prop("watts", "number")
}
type "Lamp" "A lamp" {
has("bulb", "Light")
}
4.3.5.3 On a row or a line#
A right-click on a row gives Edit as text, a one-line field with the statement behind the row, such as prop("watts", "number"), and Delete, which deletes the statement. The row behaves after glowing gives Behaves after, a field with the name of the state machine that changes the name in the clause, and Remove behaves after, which takes the clause out of the header of the type.
Behaves after glowing on Bulb:
type "Bulb" "A light bulb" behaves after "glowing" {
prop("watts", "number")
}
``` A right-click on the line of a relation gives
Rename relation, Edit as text, a code cell titled `Relation <name>`, and Delete relation.
## 4.3.6 Editing an object diagram
The examples start from this model.
```kmodel
make object "lamp":"Lamp" {
prop("mode") -> "off"
has("bulb") -> make object "bulb":"Bulb" {
prop("watts") -> "0"
}
}
4.3.6.1 On an object#
| Entry | Effect on the text |
|---|---|
| Rename | Renames the key of the object and every knows that leads to it. |
| Edit as text | Opens the whole object in a code cell. |
| Add property | Asks for the name and adds prop("name") -> "" at the end of the object. |
| Add object | Asks for the relation, then for the type, and adds has("relation") -> make object "relation":"Type" { }. The key of the new object is the name of the relation, with a number if the key is taken. |
| Add reference to | Asks for the object and adds knows("ref") -> "key". Shown when the model has another object. |
| Delete | Deletes the has statement that makes the object, the objects it holds and every knows that leads to one of them. Not shown on the outermost object. |
Add object on lamp, with the relation spare and the type Bulb:
make object "lamp":"Lamp" {
prop("mode") -> "off"
has("bulb") -> make object "bulb":"Bulb" {
prop("watts") -> "0"
}
has("spare") -> make object "spare":"Bulb" { }
}
Add reference to lamp on bulb:
make object "lamp":"Lamp" {
prop("mode") -> "off"
has("bulb") -> make object "bulb":"Bulb" {
prop("watts") -> "0"
knows("ref") -> "lamp"
}
}
The type of a new object is typed in. The menu does not list the types of the metamodel.
4.3.6.2 On a row or a line#
A row and a line have the same entries as in a class diagram. Deleting a has line deletes the object it makes. The empty canvas of an object diagram has no menu entries.
4.3.7 Code cells#
Code that a diagram shows folded up opens in a code cell over the diagram: the tick limit, the entry actions and the do actions of a state, and the condition of a transition. A click on its marker opens it. Edit as text opens a whole state, transition, type, object or relation in the same kind of cell.
| Cell | Title |
|---|---|
| Tick limit | Tick limit of <state> |
| Entry actions | Entry actions of <state> |
| Do actions | Do actions of <state> |
| Condition | Condition of <sources> to <targets> |
| Edit as text | State <name>, Transition <caption>, Relation <name> or the title of the box |
The head of a cell shows its title and the buttons Save and Close. Cmd+Enter / Ctrl+Enter saves too. Drag the head to move the cell, and a side or a corner to size it. The next cell opens at the same size.
Saving writes the code between the braces of its block. A tick limit whose code is deleted is taken out of its state. A transition without a condition has an empty cell, and code saved into it becomes CONDITION { ... }. A condition whose code is deleted is taken out, and the transition keeps an empty body { }. In a cell of Edit as text, saving an empty text deletes the construct.
A cell is the text editor on its part of the file, so an action block in a cell completes and checks ATTACH and EXCHANGE with the names of the attachable state machines like the editor. It completes with Ctrl+M, on Windows also Ctrl+Space, shows what a name is when the mouse rests on it, and underlines errors and warnings with the language features of the project. It shows only the problems of its own code. Go to definition does nothing in a cell. A cell closes without saving when the text of the file changes under it.
4.3.8 Arranging by hand#
The IDE places every element of a diagram by itself. A drag changes that.
| Drag | Effect |
|---|---|
| A box | Moves it. |
| The bar of a split or join | Moves the bar. |
| A side or a corner of a state with inner states | Sizes the state. It never gets smaller than its inner states need. |
| The caption or label of a line | Moves the caption. It keeps its distance to the line when the line moves. |
| A waypoint | Moves the waypoint and bends the line. |
While you drag, a grid of dots shows, and the element moves from point to point. A right-click on a line gives Add waypoint, and a right-click on a waypoint gives Remove waypoint. The waypoints of a line show while the pointer is near the line. Each line between a state and the bar of a split or join bends on its own.
The first change by hand fixes every element where it is. From then on only new elements are placed by the IDE. The arrangement is kept next to the file, with .vis added to its name, as in lamp.kstates.vis. It is a JSON file that the IDE writes and that opens read-only. The text always wins: what the .vis file says about an element that the text no longer has is dropped. To go back to the automatic layout, delete the .vis file.
4.3.9 Renaming between diagram and text#
A rename in the diagram renames in the text, and the element keeps its place. A rename of a state, a type or an object in the text is recognized as well, and the element keeps its place in the diagram. A rename stays in its file. Other files that use the name, such as a model that names a renamed type or a descriptor that names a renamed object, are not changed and must be updated by hand.
4.3.10 While a model runs#
While a run is selected in the Runtime tool window and observation is on, the statechart of each running state machine marks its active states with a strong border, and the innermost active state is lightly filled. A fired transition is not marked.
When several objects run the state machine of the file, as the instances of a definition do, the statechart marks the states of one of them. While the statechart is shown, the bar below the editor then has the button row Live: with one button per instance, labelled with the key of its object and the definition, such as gen_Bulb_0 (glowing). The button of the instance shown is selected, and a click on another shows that one. At first the statechart shows the instance the runtime announced first. When the chosen instance ends, it shows the first one left, and when none is left, it marks nothing. See 4.5.4.7 State machine instances.
While a run is paused at a breakpoint, the statechart marks the place in the warning colour: a dashed frame around the state, or the lines of the transition drawn wide with a dashed frame around its caption and its bar. It then shows the instance that halted, and the other buttons of the row take no clicks until the run goes on. See 4.6 Debugging.
A state machine composed of pages runs as one flat state machine, see 4.5.4.8 Pages. The statechart of its own file marks a container state as active while the run is inside it. The states of the fragment are marked in the statechart of the fragment's file, under the names written there. Each container state that uses the fragment is a use of its own, and so is each object that runs it. While the statechart of a fragment is shown, the row Live: names every use by the key of the object and the container state, such as lamp: self test or lamp: self test/wiring for a fragment that another fragment uses, and it shows the row also for a single use. At first the statechart shows the first use.
A pause inside a fragment shows in the statechart of the fragment, at the state or transition of the use that halted, and that use is shown while the run is paused. The statechart of the file around it marks the container state as active but shows no pause.
4.3.11 Limits#
- Macros are edited as text only, in the cell of Edit macros.
-
ATTACHandEXCHANGEare written in the cells of the entry and do actions. No menu entry adds them. - No menu entry adds a timeout.
- A rename together with another change in one edit of the text is not recognized as a rename.
- A change of the arrangement cannot be undone, and there is no command that goes back to the automatic layout.
-
Renaming or deleting a model file leaves its
.visfile behind. -
A state whose name contains
/from:or/to:, or ends in#and digits, can lose the waypoints of its lines. - The badge of a history can overlap the code markers in a narrow state.
- The caption of a transition can cover another line.
- The choice of Text, Split or Diagram is not stored in the project file.
- A file with nothing to draw has no canvas, so its menu is not there.
- The diagram of a state machine does not show the states of the fragments its container states use. Each fragment has its own diagram.
- The bar of the users of a fragment names files by their names only, so two files of the same name in different folders read alike.