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.
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.
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, 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, 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.
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.
API objects have properties that correspond to values that you normally set for an
object through the Stateflow Editor. For example, to change the position of a state, you normally
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];
API objects have functions that provide services that are normally provided by the
Stateflow Editor. For example, to open the Properties dialog box for a
transition, you typically 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);
Stateflow.Box
| Stateflow.Chart
| Stateflow.Clipboard
| Stateflow.Editor
| Stateflow.EMChart
| Stateflow.Function
| Stateflow.Machine
| Stateflow.State
| Stateflow.StateTransitionTableChart
| Stateflow.Transition
| Stateflow.TruthTableChart