Overview of the Stateflow API

The Stateflow^® application programming interface (API) is a tool to create or change Stateflow charts by using MATLAB^® commands. 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, API objects of type State and Transition represent states and transitions in a Stateflow chart. When you modify the property of an API object or call one of its methods, 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 are disabled in the quick access toolbar.

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 layers of containment:

Root — The 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 Root object when you call the function sfnew or load a Simulink model containing a Stateflow chart.
Machine — The Stateflow machine contains all charts, state transition tables, and truth table blocks in a Simulink model. From a Stateflow perspective, Machine objects are equivalent to Simulink models. All Machine objects are contained in the Root object. Machine objects can hold one or more Chart objects.
Chart — Chart objects represent Stateflow charts, state transition tables, and truth table blocks. Each Chart object can contain objects that represent states, functions, boxes, data, events, messages, transitions, junctions, and annotations. These objects represent the components of a Stateflow chart.
States, Functions, and Boxes — State, Function, and Box objects can contain other objects that represent states, functions, boxes, data, events, messages, transitions, junctions, and annotations. Levels of nesting can continue indefinitely.

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

Editor — Although not a part of the containment hierarchy, Editor objects provide access to the graphical aspects of Chart objects. For each Chart object, there is an Editor object that provides API access to the Stateflow Editor. For more information, see Modify the Graphical Properties of Your Chart.
Clipboard — The Clipboard object has two methods, 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 Stateflow Objects.

Manipulate Stateflow API Objects

You manipulate Stateflow API objects through MATLAB variables called handles. Once you have a handle to an API object, you can manipulate the corresponding object in the Stateflow Editor. For example, you can change properties of the object, call methods on the object, and add new objects inside the object.

Get Handles to API Objects

To use the Stateflow API, you begin by finding a handle to the Root object, which is the parent of all objects in the Stateflow API. Once you have a Root object handle, you can find the handles to the API objects that correspond to the Stateflow objects with which you want to work. For example:

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

For more information, see Create Charts by Using the Stateflow API.

Modify API Properties

API objects have properties that correspond to values that you normally set for an object through the Stateflow Editor. For example, you can change the position of a state by changing the Position property of the corresponding State object:

st.Position = [10 20 100 80];

In the Stateflow Editor, you click and drag a state to change its position.

Call API Methods

API objects have methods that provide services that are normally provided by the Stateflow Editor. For example, you can delete a transition in a chart by calling the delete method of the corresponding Transition object:

tr.delete;

In the Stateflow Editor, you typically delete a transition by clicking it and pressing the Delete key.

For more information, see Access Properties and Methods of Stateflow Objects.

Documentation