QM  4.0.1
Working with States

The concept of State is a very effective mechanism of decomposing event-driven behavior. States divide the overall behavior of a class into separate parts, each part (state) handling events in a specific way. Any change in handling of any event requires a change of state, that is, a state transition. States are represented in UML as rounded-corner rectangles with the state name at the top.


Adding a State

Note
In order to add states, you first need to create and show a state diagram. Also, to add, move, resize, or edit states, the State Machine diagram must be unlocked ().

Make sure that the State Machine subwindow is active. In the State Machine Toolbox click on the State tool and release the mouse button (don't drag the tool off the toolbar). At this point, when you hover the mouse over the active state diagram, the mouse pointer changes shape to the state tool. To add a state, move the mouse to the desired location of the top-left corner of the state shape and press the left mouse button. At this point you create a state shape of minimal size at the mouse position. You can release the mouse button immediately or you can drag the mouse to the desired location of the bottom-right corner of the state shape. In any case, you can resize the state shape at any later time.

sm_state-add.gif
Adding a State

Nesting of States

One of the most important features of Hierarchical State Machines (HSMs) (UML Statecharts) is that states can nest within other states, thus forming state hierarchies. In fact, QM™ has been specifically designed for ease of working with such hierarchically nested states.

QM™ determines state nesting by the geometric arrangement of states in the diagram, whereas state nesting is determined only by the position of the top-left corner of the state rectangle. This state hierarchy is immediately reflected in the hierarchical model view in the Model Explorer dock window.

Note
The rule of using just the top-left corner to determine state nesting (as opposed to complete enclosure of one state by another) turns out to be more useful in practice, because it leads to fewer inadvertent changes in state nesting when states are rearranged during diagram editing.
sm_state_nest.png
Example of Nested States

For example, the screen shot above shows state2 nested in state1, as identified clearly in the Model Explorer on the left of the picture. Please note that only the upper-left corner of state2 is inside state1, instead of being entirely enclosed by state1. On the other hand, state state3 nests entirely inside state2, and indirectly in state1 as well.

Note
The state nesting is also reflected in the Superstate property in the State Property Sheet.

Moving a State

To move a state, hover the mouse over the state until you get the move cursor. Click the mouse and drag the state shape to the desired location.

sm_state-move.gif
Moving a State

Resizing a State

You can resize all four edges of a state shape. The top and bottom edges can be resized up and down, while left and right edges can be resized left and right. Additionally, the right-bottom corner can be resized diagonally (i.e., both horizontally and vertically).

To resize the desired edge of a state, hover the mouse over the state edge until you get the resize cursor. Click the mouse and drag the state edge to the desired location.

sm_state-resize.gif
Resizing a State
Note
The state shape cannot be made smaller than the entry box and exit box in the state.

Deleting a State

To delete a state, you need to select it as the Current Item, either by clicking on it in the state diagram or in the Model Explorer. After this, you can delete the state in several ways: (1) click the button in the Explorer Toolbar; (2) press the Del keyboard shortcut; or (3) right-click on the state diagram and choose the Delete item option from the pop-up menu (see the screen animation below).

sm_state-del.gif
Deleting a State
Note
Deleting a state is not recursive, meaning that any substates nested within the deleted state are not deleted.

State Property Sheet

State item can be configured by the State-Specific Property Sheet.

sm_state_prop.png
State Property Sheet

The state-item property sheet contains the following properties:

State Name

The state name should be a valid function name in C or C++. Typically, you should strive for a short and punchy name that captures the nature of the state. For example, a state in which a system remains on could be named on. To keep with the naming conventions used in QM examples, it is recommended to name use lower-case names of states.

Superstate

The superstate property is not directly editable in the State Property Sheet, because the superstate of the given state is determined geometrically.

Note
If a state is placed directly on the drawing canvas and does not nest in any other state, the superstate property shows "top", which is the implicit top-most state that encloses all states in the diagram and is the ultimate root of the state hierarchy.

State Documentation

The documentation entry in the State Property Sheet allows you to provide documentation to the state. The QM code generator parses the documentation entry and can generate comments from it in the auto-generated code.

State Entry Action

A state can have optional entry action. You provide this action in the State Property Sheet (see also the screen shot below). If defined, the entry action shows up in the upper-left corner of the state shape.

An entry action is considered defined if the corresponding pseudocode or code entries in the State Property Sheet are not empty. Once an entry action is defined the state shape shows the entry box in the upper-left corner just below the name compartment.

Note
The pseudocode property is designed to avoid clutter in the diagram by minimizing the amount of text to display inside the state shape in the diagram. Pseudocode is intended only for displaying in the diagram and has no implications for code generation.

The actual algorithm QM uses to display action text in the entry box is as follows: If both the pseudocode and code entries in the State Property Sheet are empty, the corresponding entry action is considered undefined and is not displayed at all in the state shape. If the pseduocode entry is not empty, regardless of the contents of the code entry, the pseudocode is displayed in the same line as the e/ (entry) text. Finally, if the pseudocode is empty, but the code entry is not empty, the code is displayed in the entry text box of the state shape, however, the actual code is displayed in a line below the e/ text. Of course, to see the text, you need to expand the entry text box in the state shape.

sm_state-entry.gif
Resizing the State Entry Box

Once the state shape is selected as the Current Item, you can resize the entry box by dragging the lower-right handle of the box (see the screen animation above).

State Exit Action

A state can have optional exit action. You provide this action in the State Property Sheet (see also the screen shot below). If defined, the exit action shows up just below the entry action (if defined) in the upper-left corner of the state shape.

An exit action is considered defined if the corresponding pseudocode or code entries in the State Property Sheet are not empty. Once an exit action is defined the state shape shows the exit box in the upper-left corner just below the entry action.

Attention
The pseudocode property is designed to avoid clutter in the diagram by minimizing the amount of text to display inside the state shape. Pseudocode is intended only for displaying in the diagram and has no implications for code generation. Only the Code entry of the exit property matters for code generation.
Note
The actual algorithm QM uses to display action text in the exit box is as follows: If both the pseudocode and code entries in the State Property Sheet are empty, the corresponding exit action is considered undefined and is not displayed at all in the state shape. If the pseduocode entry is not empty, regardless of the contents of the code entry, the pseudocode is displayed in the same line as the x/ (exit) text. Finally, if the pseudocode is empty, but the code entry is not empty, the code is displayed in the exit text box of the state shape, however, the actual code is displayed in a line below the x/ text. Of course, to see the text, you need to expand the exit text box in the state shape.
sm_state-exit.gif
Resizing the State Exit Box

Once the state shape is selected as the Current Item, you can resize the exit box by dragging the lower-right handle of the box (see the screen animation above).


Next: Working with Transitions