Overview of the Stateflow API

The Stateflow^® application programming interface (API) allows you to create or change Stateflow charts from the MATLAB^® Command Window. By placing Stateflow API commands in a MATLAB function or script, you can:

Automate your chart modification operations by executing several editing steps in a single command.
Eliminate repetitive chart creation steps by producing a "base" Stateflow chart that you can reuse as a template for your applications.
Produce a specialized report of your model.

The Stateflow API consists of objects that represent the graphical and nongraphical objects of a Stateflow chart. For example, the API objects Stateflow.State and Stateflow.Transition represent states and transitions in a Stateflow chart. When you modify the properties of an API object or call one of its object functions, you affect the corresponding object in the Stateflow chart. When you use the Stateflow Editor to perform an operation on an object in the chart, you affect the corresponding API object.

Note

You cannot undo any operation in the Stateflow Editor that you perform by using the Stateflow API. If you perform an editing operation through the API, the Undo and Redo buttons in the quick access toolbar are disabled.

Hierarchy of Stateflow API Objects

Stateflow API objects are organized in a containment hierarchy. For example, if state A contains state B in a Stateflow chart, then the API object for state A contains the API object for state B. The Stateflow API hierarchy follows the same rules of containment as the Stateflow object hierarchy. For example, charts can contain states, but states cannot contain charts. For more information, see Overview of Stateflow Objects.

This diagram shows the hierarchy of objects in the Stateflow API.

Diagram showing the four levels of the hierarchy of API objects.

The hierarchy consists of four levels of containment:

Root — The Simulink.Root object is the parent of all Stateflow API objects. It is a placeholder at the top of the Stateflow API hierarchy that distinguishes Stateflow objects from other objects in a Simulink^® model. You automatically create the Simulink.Root object when you add a Stateflow chart, a State Transition Table block, a Truth Table block, or a MATLAB Function block to a Simulink model, or when you load a model that contains one of these blocks.
Machine — From a Stateflow perspective, Stateflow.Machine objects are equivalent to Simulink models. A Stateflow.Machine object contains objects that represent the Stateflow charts, State Transition Table blocks, Truth Table blocks, and MATLAB Function blocks in a model.
Chart — Stateflow.Chart, Stateflow.StateTransitionTableChart, Stateflow.TruthTableChart, and Stateflow.EMChart objects represent Stateflow charts, State Transition Table blocks, Truth Table blocks, and MATLAB Function blocks, respectively. Objects in this level of the hierarchy can contain objects that represent states, functions, boxes, data, events, messages, transitions, junctions, entry and exit ports, and annotations.
States, Functions, and Boxes — This level of the hierarchy includes Stateflow.State, Stateflow.Function, and Stateflow.Box objects that represent states, functions, and boxes, respectively. These objects can contain other objects that represent states, functions, boxes, data, events, messages, transitions, junctions, entry and exit ports, and annotations. Levels of nesting can continue indefinitely.

The hierarchy diagram shows two object types that exist outside of the containment hierarchy:

Editor — Stateflow.Editor objects provide access to the graphical aspects of charts and state transition tables. For each Stateflow.Chart or Stateflow.StateTransitionTableChart object, there is a Stateflow.Editor object that you can use to control the position, size, and magnification level of the Stateflow Editor. For more information, see Zoom in on Stateflow Chart, Zoom out on Stateflow Chart, and Set Zoom Factor.
Clipboard — The Stateflow.Clipboard object has two functions, copy and pasteTo, that use the clipboard as a staging area to implement copy-and-paste functionality in the Stateflow API. For more information, see Copy and Paste by Grouping and Copy and Paste Array of Objects.

Access Stateflow API Objects

To use the Stateflow API, you begin by accessing the Simulink.Root object, which is the parent of all objects in the Stateflow API. You use the Simulink.Root object to access the other API objects in your model. For example:

Create a Simulink model with an empty Stateflow chart by calling the function sfnew.
```
sfnew
```
Use the function sfroot to access the Simulink.Root object.
```
rt = sfroot;
```
Call the find function to access the Stateflow.Chart object that corresponds to the chart in your model.
```
ch = find(rt,'-isa','Stateflow.Chart');
```
Call the Stateflow.State function to add a state to the chart. This function returns an Stateflow.State object that corresponds to the new state.
```
st = Stateflow.State(ch);
```
Display the new state in the Stateflow Editor.
```
view(st)
```

For more information, see Access Objects in Your Stateflow Chart and Create Charts by Using the Stateflow API.

Modify Properties of API Objects

API objects have properties that correspond to the values you set in the Stateflow Editor. For example, to use the editor to change the position of a state, you click and drag the state. With the Stateflow API, you change the position of a state by modifying the Position property of the corresponding Stateflow.State object:

st.Position = [10 20 100 80];

For more information, see Modify Properties and Call Functions of Stateflow Objects.

Call API Object Functions

API objects have functions that correspond to actions in the Stateflow Editor. For example, to use the editor to open the Properties dialog box for a transition, you right-click the transition and select Properties. With the Stateflow API, you open this dialog box by calling the dialog function of the corresponding Stateflow.Transition object:

dialog(tr);

For more information, see Modify Properties and Call Functions of Stateflow Objects.