QM  4.0.3
Working with Submachine Diagrams

Submachine Diagram allows you to specify a composite state and all its nested substates and transitions (submachine) in such a way that it can be instantiated (and thus reused), possibly multiple times, in the context of a given state machine.

To enable reuse of a Submachine Diagram without revealing its internal structure ("black-box"), the Submachine Diagram must provide a well-defined interface on its boundary, which consists of Entry Points for attaching any incoming transitions targeting specific substates and eXit Points for attaching outgoing transitions originating in specific substates.

sm_subm.png
Submachine Diagram
Attention
The QM code generator supports Submachine Diagrams only for the QMsm-style state machine implementation strategy. This means that the class to which you add Submachine Diagram must be a subclass of QMsm or QMActive base classes.

Adding a Blank Submachine Diagram

To add an new, blank Submachine Diagram, in the Model Explorer right-click on the State Machine (SM) to which you want to add the Submachine Diagram and select Add Sub-Machine from the popup menu.

sm_subm_add.png
Adding a Submachine to a given State Machine diagram
Note
In order to add a Submachine Diagram, the State Machine must be unlocked ().

Creating a Submachine Diagram from State

Alternatively, you can create a Submchine Diagram from an existing (composite) state. The advantage of this method is that the created Submachine will contain all the internals of the chosen composite state, including the entry actions, exit action, initial transition, as well as all the nested substates and transitions.

To create a new Submachine Diagram from a given state right-click on this state in the diagram (or in the Model Explorer) and select Add Sub-Machine from State from the popup menu.

sm_subm_from_state.png
Creating a Submachine from a Composite State

Resizing a Submachine Diagram

As all diagrams in QM, the Submachine Diagram has a Drawing Canvas, which can be resized by dragging the outside edges or the bottom-right corner of the diagram. However, the special feature of Submachine Diagram is that resizing the canvas always simultaneously resizes the outline of the composite state (shown in green).

sm_subm_resize.png
Resizing a Submachine Diagram

Deleting a Submachine Diagram

To delete a Submachine Diagram, you need to select it as the Current Item, either by clicking on the (green) state outline or in the Model Explorer. After this, you can delete the Submachine 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).

Note
Deleting a Submachine Diagram removes the reference to this Submachine in all Submachine States based on this Submachine.

Submachine Diagram Property Sheet

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

sm_subm_prop.png
State Property Sheet

The state-item property sheet contains the following properties:

Submachine Name

The submachine 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 submachine. For example, a submachine 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 submachines.

Submachine Documentation

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

Submachine Entry Action

A submachine can have optional entry action. You provide this action in the Submachine Property Sheet (see also the screen shot above). If defined, the entry action shows up in the upper-left corner of the submachine outline. The Submachine entry action behaves in exactly the same way as the entry action to a state.

Note
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.

Submachine Exit Action

A submachine can have optional exit action. You provide this action in the Submachine Property Sheet (see also the screen shot above). If defined, the exit action shows up in the upper-left corner of the submachine outline (below the entry action, if present). The Submachine exit action behaves in exactly the same way as the exit action to a state.

Note
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.

Next: Working with Entry-Point Segments