Overview of the Stateflow API

What Is the Stateflow API?

The Stateflow® Application Programming Interface (API) is a tool you use to create or change Stateflow charts with MATLAB® commands. By placing Stateflow API commands in a MATLAB script, you can automate chart editing processes in a single command.

Applications for the Stateflow API include:

  • Creating a script that performs common graphical edits and simplifies editing of Stateflow charts

  • Creating a script that creates a repetitive "base" Stateflow chart

  • Creating a script that produces a specialized report of your model

The Stateflow API consists of objects that represent actual Stateflow objects. For example, an API object of type State represents a Stateflow state, an API object of type Junction represents a Stateflow junction.

Each API object has properties and methods you use to perform editing operations on it. The correspondence between API object and Stateflow object is so close that what you do to a Stateflow API object affects the object it represents in the Stateflow Editor, and what you do to a graphical object in the Stateflow Editor affects the Stateflow API object that represents it.


You cannot undo any operation in the Stateflow Editor that you perform using the Stateflow API. If you perform an editing operation through the API, the undo and redo buttons are disabled from undoing and redoing any prior operations.

Stateflow API Object Hierarchy

Stateflow API objects represent actual Stateflow objects in a Stateflow chart. Like Stateflow objects, API objects contain or are contained by other Stateflow objects. For example, if state A contains state B in the Stateflow Editor, then the API object for state A contains the API object for state B.

This diagram shows the Stateflow API hierarchy of objects:

Rules of containment define the Stateflow hierarchy and the Stateflow API object hierarchy. For example, charts can contain states but states cannot contain charts. The hierarchy of Stateflow objects appears in the section Stateflow Hierarchy of Objects. The Stateflow API hierarchy consists of these layers of containment:

  • Root — The Root object (only one exists) is the parent of all Stateflow API objects. It is a placeholder at the top of the Stateflow API hierarchy to distinguish Stateflow objects from other objects, such as Simulink® model objects. You automatically create the Root object when you load a model containing a Stateflow chart or call the function sfnew to create a new model with a Stateflow chart.

  • Model — Objects of type Model are available through the Stateflow Root object. Model objects are equivalent to Simulink models from a Stateflow chart perspective. Model objects can hold objects of type Chart, Data, Event, and Message.

  • Chart — Within any Model object (model) there can be any number of chart objects. Within each object of type Chart, there can be objects of type State, Function, Box, Note, Data, Event, Message, Transition, and Junction. These objects represent the components of a Stateflow chart.

  • State/Function/Box — Nested within objects of type State, Function, and Box, there can be other objects of type State, Function, Box, Note, Junction, Transition, Data, Event, and Message. Levels of nesting can continue indefinitely.

The preceding figure also shows two object types that exist outside the Stateflow containment hierarchy:

  • Editor — Though not a part of the Stateflow containment hierarchy, an object of type Editor provides access to the purely graphical aspects of objects of type Chart. For each Chart object, there is an Editor object that provides API access to the Stateflow Editor.

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

Getting a Handle on Stateflow API Objects

You manipulate Stateflow objects by manipulating the Stateflow API objects that represent them. You manipulate Stateflow API objects through a MATLAB variable called a handle.

The first handle you need in the Stateflow API is a handle to the Root object, which is the parent of all objects in the Stateflow API. In this command, the function sfroot returns a handle to the Root object:

rt = sfroot

Once you have a Root object handle, you can find a handle to the Model object for the Simulink model with which you want to work. Once you have a handle to a Model object, you can find a handle to a Chart object for the chart you want to edit. Later, when you create objects or find existing objects in a Stateflow chart, you receive a handle to the object that you can use to manipulate the actual object in the Stateflow Editor.

To learn how to use API object handles to create and edit Stateflow charts, see Create and Access Charts Using the Stateflow API.

What Are API Object Properties and Methods?

Once you obtain handles to Stateflow API objects, you can manipulate the Stateflow objects that they represent through the properties and methods that each Stateflow API object possesses. You access the properties and methods of an object through a handle to the object.

API Object Properties

API properties correspond to values that you normally set for an object through the user interface of the Stateflow Editor. For example, you can change the position of a transition by changing the Position property of the Transition object that represents the transition. In the Stateflow Editor, you can click-drag the source, end, or midpoint of a transition to change its position.

API Object Methods

API methods are similar to functions for creating, finding, changing, or deleting the objects they belong to. They provide services that are normally provided by the Stateflow Editor. For example, you can delete a transition in the Stateflow Editor by calling the delete method of the Transition object that represents the transition. Deleting a transition in the Stateflow Editor is normally done by selecting a transition and pressing the Delete key.

Common API Properties and Methods

Stateflow API objects have some common properties and methods. For example, all API objects have an Id and a Description property. All API objects have a get and a set method for viewing or changing the properties of an object, respectively. Most API objects also have a delete method. Methods held in common among all Stateflow objects are listed in the reference section Methods That Apply to All API Objects.

Unique API Properties and Methods

Each API object also has properties and methods unique to its type. For example, a State object has a Position property containing the spatial coordinates for the state it represents in the Stateflow Editor. A Data object, however, has no Position property.

Was this topic helpful?