QM  4.0.1
Working with Submachine States

Submachine State represents an instance of a given Submachine Diagram and is semantically equivalent to inserting the whole Submachine Diagram in a given place of your state machine.

Each Submachine State represents a distinct instance of a Submachine, even when multiple Submachine States reference the same Submachine, such as "operand1" and "operand2" Submachine States both reference Submachine "operand" in the picture below:

sm_smstate.png
Submachine State instances

A Submachine State presents the interface defined in the associated Submachine. This interface consists of Entry Points to be used as targets for transitions to specific substates and eXit Points for attaching eXit Point Segments.

A Submachine State can have also incoming transition that terminate on the boundary of the Submachine State and don't target any Entry-Points. Such incoming transitions enter the associated Submachine through its initial transition (if available).

Finally, a Submachine State can have outgoing transitions that don't originate on any of its Exit-Points. Such outgoing transitions are unique to this particular Submachine State.

Note
A Submachine State cannot have nested states. The entire internal structure of the Submachine State is determined by the associated Submachine.
Attention
All eXit-Points of a Submachine State must be connected to eXit-Point Segments. Otherwise the QM Code Generator will report errors.

Adding a Submachine State

Note
In order to add a submachine state, 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 Submachine 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.


Moving a Sumachine State

To move a submachine 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.


Resizing a Submachine State

You can resize all four edges of a submachine 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 submachine 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.


Deleting a Submachine State

To delete a submachine 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 submachine 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.


Submachine State Property Sheet

Submachine State item can be configured by its specific Property Sheet.

subm_state_prop.png
Submachine State Property Sheet

The Submachine-State item property sheet contains the following properties:

Submachine State Name

The Submachine State name should be a valid function name in C or C++. Typically, you should strive for a name that captures the nature of the Submachine State and is somehow related to the instantiated Submachine Diagram. For example, a submachine state that instantiates *Submachine Diagram" named "operand" could be named "operand1". To keep with the naming conventions used in @ref gs_examples "QM examples", it is recommended to name use lower-case names of submachine states.

Submachine

The submachine property associates the Submachine State with the given Submachine Diagram. This property is editable via a drop-down box, which contains all Submachine Diagrams defined for this state machine.

Documentation

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


Next: Working with eXit-Point Segments