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.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.
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
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.Rootobject 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.Rootobject 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.Machineobjects are equivalent to Simulink models. A
Stateflow.Machineobject contains objects that represent the Stateflow charts, State Transition Table blocks, Truth Table blocks, and MATLAB Function blocks in a model.
Stateflow.EMChartobjects 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.Boxobjects 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:
Stateflow.Editorobjects provide access to the graphical aspects of charts and state transition tables. For each
Stateflow.StateTransitionTableChartobject, there is a
Stateflow.Editorobject 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.Clipboardobject has two functions,
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
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
Use the function
sfrootto access the
rt = sfroot;
findfunction to access the
Stateflow.Chartobject that corresponds to the chart in your model.
ch = find(rt,"-isa","Stateflow.Chart");
Stateflow.Statefunction to add a state to the chart. This function returns an
Stateflow.Stateobject that corresponds to the new state.
st = Stateflow.State(ch);
Display the new state in the Stateflow Editor.
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
st.Position = [10 20 100 80];
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