Create and Destroy Stateflow Objects

About Creating and Destroying API Objects

You create (construct), parent (contain), and delete (destroy) objects in Stateflow® charts through constructor methods in the Stateflow API. For all but the Editor and Clipboard objects, creating objects establishes a handle to them that you can use for accessing their properties and methods to modify the chart.

Stateflow objects are contained (parented) by other objects as defined in the Stateflow hierarchy of objects (see Hierarchy of Stateflow API Objects). You control containment of nongraphical objects in the Model Explorer.

Create Stateflow Objects

You create a Stateflow object as the child of a parent object through API constructor methods. Each Stateflow object type has its own constructor method. See Constructor Methods for a list of the valid constructor methods.

Use this process to create Stateflow objects with the Stateflow API:

  1. Get a handle to the parent object, as described in Access Objects in Your Stateflow Chart.

  2. Call the appropriate constructor method for the creation of the object using the parent (containing) object as an argument.

    For example, this command creates and returns a handle s to a new state object in the chart object with the handle ch:

    s = Stateflow.State(ch);

    By default, the newly created state from the preceding command appears in the upper left corner of the chart.

    The constructor returns a handle to an API object for the newly created Stateflow object. Use this handle to display or change the object through its properties and methods.

  3. Use the object handle returned by the constructor to make changes to the object in the chart.

    For example, you can now use the handle s to set its name (Name property) and position (Position property). You can also connect it to other states or junctions by creating a Transition object and setting its Source or Destination property to s.

Use the preceding process to create all Stateflow objects in your chart. For an example of how to create states, transitions, and data object in a chart, see Create Charts by Using the Stateflow API.


There is no constructor for a Stateflow chart. To create a chart with the Stateflow API, use the sfnew function.

Establish the Parent (Container) of an Object

As discussed in the previous section, Create Stateflow Objects, the Stateflow API constructor establishes the parent for a newly created object by taking a handle for the parent object as an argument to the constructor.

Graphical Object Parentage

When you create graphical objects (states, boxes, notes, functions, transitions, junctions), they appear completely inside their containing parent object. In the chart, graphical containment is a necessary and sufficient condition for establishing the containing parent.

Repositioning a graphical object through its Position property can change its parent or cause an undefined parent error condition. Parsing a chart in which the edges of one object overlap with another produces an undefined parent error condition that the Stateflow parser cannot resolve. You can check for this condition by examining the value of the BadIntersection property of a Chart object, which equals 1 if the edges of a graphical object overlap with other objects. Set the size and position of objects so that they are separate from other objects.

Nongraphical Object Parentage

When you create nongraphical objects (data, events, messages), they appear in the Model Explorer at the hierarchical level of their owning object. Containment for nongraphical objects is established through the Model Explorer only. See Use the Model Explorer with Stateflow Objects.

Destroy Stateflow Objects

Most Stateflow objects have a destructor method named delete. In this example, a State object, s, is deleted:


The preceding command is equivalent to performing a mouse select and keyboard delete operation in the chart. Upon deletion, graphical Stateflow objects are sent to the clipboard; nongraphical objects, such as data, events, and message are deleted. The workspace variable s still exists but is no longer a handle to the deleted state.

Related Topics