|On this page…|
Creating Stateflow® objects through the Stateflow API gives you an immediate handle to the newly created objects (see Create Stateflow Objects). You can also connect to Stateflow objects that already exist for which you have no current API handle.
There are several object methods that you use to traverse the Stateflow hierarchy to locate existing objects. For example, you can use the find method.
With the find method, you specify what to search for by specifying combinations of these types of information:
The type of object to find
A property name for the object to find and its value
This example searches through Model object m to return every State object with the name 'On'.
onState = m.find('-isa','Stateflow.State','-and','Name','On');
If a find command finds more than one object that meets its specifications, it returns an array of qualifying objects. This example returns an array of all charts in your model:
chartArray = m.find('-isa','Stateflow.Chart');
Use array indexing to access individual properties and methods for a chart. For example, if the preceding command returns three charts, this command returns the Name property of the second chart found:
name2 = chartArray(2).Name;
Tip To access the property of a Stateflow object in a linked library chart, do one of the following:
Doing one of those steps loads a library model into the Simulink® workspace. Just opening a main model that refers to a linked Stateflow chart does not guarantee that the Stateflow API can find a linked chart.
By default, the find command finds objects at all depths of containment within an object. This includes the zeroth level of containment, which is the searched object itself. For example, suppose that state A, which corresponds to State object sA, contains two states, A1 and A2. Use a find command that finds all the states in A:
The preceding command finds three states: A, A1, and A2.
Note: Be careful when specifying the objects you want to find with the find method for a Root or Model object. Using the find method for these objects can return Simulink objects matching the arguments you specify. For example, if rt is a handle to the Root object, the command find('Name', 'ABC') might return a Simulink subsystem or block named ABC. See the reference for the find method for a full description of the method and its parameters.
Once you find a particular object in a Stateflow chart by its name or another property, you might want to find the objects that it contains (children), or the object that contains it (parent). To find child objects, use the find method. To find a parent object, use the method up.
The find method finds objects at the depth of containment within an object that you specify. If you want to limit the containment search depth with the find command, use the depth switch. For example, to find all the objects in State object sA at the first level of containment, use this command:
objArray = sA.find('-depth', 1);
Don't forget, however, that the find command always includes the zeroth level of containment, which is the object itself. So, the preceding command also includes state A in the list of objects found. However, you can exclude state A from the vector of objects in objArray with the MATLAB® function setdiff as follows:
objArray = setdiff(objArray, sA);
This command returns a collection of all junctions at the first level of containment inside the state A that is represented by State object sA:
juncArray = sA.find('-isa','Stateflow.Junction','-depth',1);
This command returns an array of all transitions inside state A at all levels of containment:
transArray = sA.find('-isa','Stateflow.Transition');
The up method finds the parent container object of any given object. Suppose that you have a chart where state A contains states A1 and A2. Also, state A1 contains state A11. In the example, sA11 is a handle to the state A11. This means that
>> pA11 = sA11.up; >> pA11.Name ans = A1
returns a handle pA11 to the state A1, the parent of state A11, and
>> ppA11 = pA11.up; >> ppA11.Name ans = A
returns a handle ppA11 to the state A, the parent of state A1.
You can retrieve the most recently selected objects in a chart by using the sfgco function. This function returns object handles or a vector of handles depending on these conditions:
|If...||Then sfgco returns...|
|There are no open charts||An empty matrix|
|There is no selection list||Handle of the chart most recently clicked|
|You select one object in a chart||Handle to the selected object|
|You select multiple objects in a chart||Vector of handles for the selected objects|
|You select objects in multiple charts||Handles of the most recently selected objects in the most recently selected chart|
For example, suppose that you run the sf_boiler model and open the Bang-Bang Controller chart. If you select the Off state in the chart, sfgco returns:
ans = Path: 'sf_boiler/Bang-Bang Controller/Heater' Id: 20 Machine: [1x1 Stateflow.Machine] Name: 'Off' Description: '' LabelString: [1x27 char] FontSize: 12 ArrowSize: 8 TestPoint: 0 Chart: [1x1 Stateflow.Chart] BadIntersection: 0 Subviewer: [1x1 Stateflow.Chart] Document: '' Tag:  RequirementInfo: '' ExecutionOrder: 0 HasOutputData: 0 Position: [31.7440 40.9730 214.1807 88.1000] Decomposition: 'EXCLUSIVE_OR' Type: 'OR' IsSubchart: 0 IsGrouped: 1 Debug: [1x1 Stateflow.StateDebug]
Once you obtain a particular object, you can access its properties directly or through the get method. For example, you obtain the description for a State object s with one of these commands:
od = s.Description;
od = s.get('Description');
od = get(s, 'Description');
You change the properties of an object directly or through the set method. For example, you change the description of the State object s with one of these commands:
s.Description = 'This is the On state.';
s.set('Description', 'This is the On state.');
set(s, 'Description', 'This is the On state.');