Group Chart Objects by Using Boxes

A box is a graphical object that defines a namespace that you can use to organize objects in your chart, such as states, functions, and data. Boxes allow you to quickly glance at your chart and recognize which states or functions work together to perform certain tasks.

Boxes have square corners to distinguish them from states, which have rounded corners. Boxes are not supported in standalone Stateflow^® charts in MATLAB^®.

Note

To add notes to your Stateflow chart, use annotations instead of boxes. For more information, see Add Descriptive Comments in a Chart.

In this chart, the box Heater groups together the related states Off and On.

For more information about this example, see Model Bang-Bang Temperature Control System.

Semantics of Stateflow Boxes

Hierarchy of Graphical Objects in Boxes

Boxes add a level of hierarchy to Stateflow charts. If you refer to a box-parented function or state from outside of the box, you must include the box name in the path. See Group Functions Using a Box.

Guidelines for Using Boxes

When you use a box:

• Include the box name in the path when you use dot notation to refer to a box-parented function or state from a location outside of the box.

• You can add data to a box so that all the elements in the box can share the same data.

• You can group a box and its contents into a single graphical element. See Group States.

• You can subchart a box to hide its elements. See Encapsulate Modal Logic by Using Subcharts.

• You cannot define action statements for a box, such as entry, during, and exit actions.

• You cannot define a transition to or from a box. However, you can define a transition to or from a state within a box.

Draw and Edit a Box

Create a Box

You create boxes in your chart by using the Box icon in the object palette.

1. In the object palette, click the Box tool .

2. On the chart canvas, click the location for the new box. The new box appears with the cursor in place to add a name.

3. Enter a name for the box and then click outside of the box.

Delete a Box

To delete a box, click the box and press the Delete key.

Examples of Using Boxes

Group Functions Using a Box

This chart shows a box named Status that groups two MATLAB functions.

The chart executes in this order:

1. The state Cold activates first.

2. Upon entry, the state Cold invokes the function Status.msgCold.

   This function displays a status message that the temperature is cold.

   Note

   Because the MATLAB function resides inside a box, the path of the function call must include the box name Status. If you omit this prefix, an error message appears.

3. If the value of the input data temp exceeds 80, a transition to the state Warm occurs.

4. Upon entry, the state Warm invokes the function Status.msgWarm.

   This function displays a status message that the temperature is warm.

5. If the value of the input data temp drops below 60, a transition to the state Cold occurs.

6. Steps 2 through 5 repeat until the simulation ends.

Group States Using a Box

This chart shows a box named Status that groups related states.

In this chart:

• The state Temp wakes up first, followed by the state Wind_Chill. Then, the state Monitor wakes up.

  This activation order occurs because Temp and Wind_Chill are in a box with a priority of 1. If you remove the box, the activation order changes to Temp, Monitor, then Wind_Chill, because the states were created in this order. For more information, see Order Maintenance for Parallel States.

  

• Based on the input data temp, transitions between substates occur in the parallel states Status.Temp and Status.Wind_Chill.

• When the transition from Status.Temp.Cold to Status.Temp.Warm occurs, the transition condition in(Status.Temp.Warm) becomes true.

• When the transition from Status.Temp.Warm to Status.Temp.Cold occurs, the transition condition in(Status.Temp.Cold) becomes true.

  Because the substates Status.Temp.Cold and Status.Temp.Warm are inside a box, the argument of the in operator must include the box name Status. If you omit this prefix, an error message appears. For information about the in operator, see Check State Activity by Using the in Operator.