The Stateflow® Application Programming Interface (API) is a tool you use to create or change Stateflow charts through 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 graphical and nongraphical objects
of a Stateflow chart. For example, API object of type
Transition represent states and transitions in a Stateflow chart. The correspondence between API objects and objects in a chart is
bidirectional. 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 affects the
corresponding API object.
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 objects contain or are contained by other API objects. 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. Rules of containment define the
Stateflow hierarchy and the Stateflow API 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 Stateflow API hierarchy of objects.
The Stateflow API hierarchy consists of these layers of containment:
Root — The
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 Simulink® model objects. You automatically create the
Root object when you load a Simulink model containing a Stateflow chart or call the function
sfnew to create a model
with a Stateflow chart.
Machine — The Stateflow machine contains all the charts in a Simulink model.
Machine objects are equivalent to
Simulink models from a Stateflow perspective. All
Machine objects are
contained in the
objects can hold
Chart objects that represent Stateflow charts, state transition tables, and truth table
Chart — Within any
Machine object there can be any number of
Chart objects. Each object of type
Chart can contain objects that represent states,
transitions, junctions, boxes, functions, annotations, data, events, and
messages. These objects represent the components of a Stateflow chart.
States, Functions, and Boxes — Nested
within objects of type
Box, there can be other
objects that represent states, transitions, junctions, boxes, functions,
annotations, data, events, and messages. Levels of nesting can continue
The hierarchy diagram shows two object types that exist outside of 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
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,
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.
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
rt = sfroot
Once you have a
Root object handle, you can find a handle to
the Model object for the Stateflow machine with which you want to work. Once you have a handle to a
Machine 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 Charts by Using the Stateflow API.
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 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 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
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
Each API object also has properties and methods unique to its type. For
State object has a
property containing the spatial coordinates for the state it represents in the
Stateflow Editor. A
Data object, however, has no