Stateflow.Box

Box in chart, state, box, or function

Description

Use Stateflow.Box objects to organize objects such as functions and states in your chart. You can also use a box to encapsulate states and functions in a separate namespace. For more information, see Group Chart Objects by Using Boxes.

Creation

Syntax

box = Stateflow.Box(parent)

Description

box = Stateflow.Box(parent) creates a Stateflow.Box object in a parent chart, state, box, or graphical function.

Input Arguments

parent — Parent for new box

Stateflow.Chart object | Stateflow.State object | Stateflow.Box object | Stateflow.Function object

Parent for the new box, specified as a Stateflow^® API object of one of these types:

• Stateflow.Box

• Stateflow.Chart

• Stateflow.Function

• Stateflow.State

Properties

Stateflow API objects have properties that correspond to the values you set in the Stateflow Editor. To access or modify a property, use dot notation. To access or modify multiple properties for multiple API objects, use the get and set functions, respectively. For more information, see Modify Properties and Call Functions of Stateflow Objects.

Content

Name — Name of box

"" (default) | string scalar | character vector

Name of the box, specified as a string scalar or character vector.

LabelString — Label for box

"?" (default) | string scalar | character vector

Label for the box, specified as a string scalar or character vector.

IsExplicitlyCommented — Whether to comment out box

false or 0 (default) | true or 1

Whether to comment out the box, specified as a numeric or logical 1 (true) or 0 (false). Setting this property to true is equivalent to right-clicking the box and selecting Comment Out. For more information, see Comment Out Objects in a Stateflow Chart.

IsImplicitlyCommented — Whether box is implicitly commented out

true or 1 | false or 0

This property is read-only.

Whether the box is implicitly commented out, specified as a numeric or logical 1 (true) or 0 (false). The box is implicitly commented out when you explicitly comment out an object that contains it. If the box is contained in an atomic subchart or an atomic box, this property is false unless the explicitly commented object is also contained in the atomic subchart or atomic box.

IsCommented — Whether box is commented out

true or 1 | false or 0

Since R2023a

This property is read-only.

Whether the box is commented out, specified as a numeric or logical 1 (true) or 0 (false). This property is true when either IsExplicitlyCommented or IsImplicitlyCommented is true.

CommentText — Comment text

"" (default) | string scalar | character vector

Comment text for the box, specified as a string scalar or character vector. This property applies only when the IsExplicitlyCommented property is true. In the Stateflow Editor, when you point to the comment badge on the box, the text appears as a tooltip. When you set the IsExplicitlyCommented property to false, the value of CommentText reverts to "".

Graphical Appearance

Position — Position and size of box

[0 0 90 60] (default) | [left top width height]

Position and size of the box, specified as a four-element numeric vector of the form [left top width height].

BadIntersection — Whether box intersects a box, state, or function

true or 1 | false or 0

This property is read-only.

Whether the box graphically intersects a box, state, or function, specified as a numeric or logical 1 (true) or 0 (false).

IsGrouped — Whether box is a grouped box

false or 0 (default) | true or 1

Whether the box is a grouped box, specified as a numeric or logical 1 (true) or 0 (false). When you copy and paste a grouped box, you copy not only the box but all of its contents. For more information, see Copy and Paste by Grouping.

IsSubchart — Whether box is a subchart

false or 0 (default) | true or 1

Whether the box is a subchart, specified as a numeric or logical 1 (true) or 0 (false).

ContentPreviewEnabled — Whether to display preview of box contents

false or 0 (default) | true or 1

Whether to display a preview of the box contents, specified as a numeric or logical 1 (true) or 0 (false). This property applies only when the IsSubchart property is true.

FontSize — Font size for box label

scalar

Font size for the box label, specified as a scalar. The StateFont.Size property of the chart that contains the box sets the initial value of this property.

State Decomposition

ExecutionOrder — Execution order in parallel (AND) decomposition

scalar

Since R2022b

Execution order for the substates of the box in parallel (AND) decomposition, specified as an integer scalar. This property applies only when both of these conditions are satisfied:

• The Decomposition property of the parent state or chart is "PARALLEL_AND".

• The UserSpecifiedStateTransitionExecutionOrder property of the chart that contains the box is true.

Hierarchy

Chart — Chart that contains box

Stateflow.Chart object

This property is read-only.

Chart that contains the box, specified as a Stateflow.Chart object.

Subviewer — Subviewer for box

Stateflow.Chart object | Stateflow.State object | Stateflow.Box object | Stateflow.Function object

This property is read-only.

Subviewer for the box, specified as a Stateflow.Chart, Stateflow.State, Stateflow.Box, or Stateflow.Function object. The subviewer is the chart or subchart where you can graphically view the box.

Machine — Machine that contains box

Stateflow.Machine object

This property is read-only.

Machine that contains the box, specified as a Stateflow.Machine object.

Path — Location of parent in model hierarchy

character vector

This property is read-only.

Location of the parent of the box in the model hierarchy, specified as a character vector.

Identification

Description — Description

"" (default) | string scalar | character vector

Description for the box, specified as a string scalar or character vector.

Document — Document link

"" (default) | string scalar | character vector

Document link for the box, specified as a string scalar or character vector.

Tag — User-defined tag

[] (default) | any data type

User-defined tag for the box, specified as data of any type.

Id — Unique identifier

scalar

This property is read-only.

Unique identifier, specified as an integer scalar. Use this property to distinguish the box from other objects in the model. The value of this property is reassigned every time you start a new MATLAB^® session and may be recycled after an object is deleted.

Object Functions

find	Identify specified objects in hierarchy
getChildren	Identify children of object
getParent	Identify parent of object
getReferences	Identify references to symbol name
renameReferences	Rename symbol and update references to symbol name
commentedBy	Identify objects that implicitly comment out a graphical object
dialog	Open properties dialog box
view	Display object in editing environment
highlight	Highlight graphical object
fitToView	Zoom in on graphical object

Examples

Add Box to Chart

Add a box in the chart ch. Set its name to A.

box = Stateflow.Box(ch);
box.Name = "A";

Version History

Introduced before R2006a

R2023a: New object functions and properties

Stateflow.Box objects have new object functions and properties:

• The object function getReferences returns the locations where a chart refers to the name of a box.

• The object function renameReferences renames a box and updates all references to the box name in the chart.

• The object function commentedBy identifies the explicitly commented objects that cause a box to be commented out.

• The property IsCommented indicates whether a box is commented out. This property replaces the object function isCommented.

R2022b: ExecutionOrder property

The ExecutionOrder property specifies the order of execution for the substates of the box in parallel (AND) decomposition.