Accessing Existing Stateflow Objects

On this page…
About Stateflow Object Handles Finding Objects and Properties Finding Objects at Different Levels of Containment Retrieving Recently Selected Objects Getting and Setting the Properties of Objects

About Stateflow Object Handles

Creating Stateflow objects through the Stateflow API gives you an immediate handle to the newly created objects (see Creating Stateflow Objects). You can also connect to Stateflow objects that already exist for which you have no current API handle.

Back to Top

Finding Objects and Properties

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: Open the library model explicitly. View a linked subsystem or block in the main model. Compile or simulate the model. 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:

states= sA.find('-isa','Stateflow.State');

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.

Back to Top

Finding Objects at Different Levels of Containment

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.

Finding Child Objects

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');

Finding a Parent Object

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.

Back to Top

Retrieving Recently Selected Objects

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 demo 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]

Back to Top

Getting and Setting the Properties of Objects

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.');

Back to Top

Creating and Destroying API Objects

Moving Graphical Objects

© 1984-2012- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS