Main Content

Stateflow.State

State in chart, state, or box

    Description

    Use Stateflow.State objects to describe an operating mode of a reactive system. For more information, see Represent Operating Modes by Using States.

    Creation

    Description

    example

    state = Stateflow.State(parent) creates a Stateflow.State object in a parent chart, state, or box.

    Input Arguments

    expand all

    Parent for the new state, specified as a Stateflow® API object of one of these types:

    Properties

    expand all

    Stateflow API objects have properties that correspond to the values you set in the Stateflow Editor. To access or modify a property, use dot notation. To access or modify multiple properties for multiple API objects, use the get and set functions, respectively. For more information, see Modify Properties and Call Functions of Stateflow Objects.

    Content

    Name of the state, specified as a string scalar or character vector.

    Label for the state, specified as a string scalar or character vector. For more information, see Specify Labels in States and Transitions Programmatically.

    This property is read-only.

    State during action, specified as a character vector. The value of this property depends on the LabelString property for the state. For more information, see Specify Labels in States and Transitions Programmatically. This property is not supported in Moore charts.

    This property is read-only.

    State entry action, specified as a character vector. The value of this property depends on the LabelString property for the state. For more information, see Specify Labels in States and Transitions Programmatically. This property is not supported in Moore charts.

    This property is read-only.

    State exit action, specified as a character vector. The value of this property depends on the LabelString property for the state. For more information, see Specify Labels in States and Transitions Programmatically. This property is not supported in Moore charts.

    This property is read-only.

    State action in a Moore chart, specified as a character vector. The value of this property depends on the LabelString property for the state. For more information, see Specify Labels in States and Transitions Programmatically. This property is supported only in Moore charts. For more information, see Design Guidelines for Moore Charts.

    This property is read-only.

    State on actions, specified as a cell array of character vectors in the form

    {'trigger1','action1',...,'triggerN','actionN'}

    The value of this property depends on the LabelString property for the state. For more information, see Specify Labels in States and Transitions Programmatically. This property is not supported in Moore charts.

    Whether to comment out the state, specified as a numeric or logical 1 (true) or 0 (false). Setting this property to true is equivalent to right-clicking the state and selecting Comment Out. For more information, see Comment Out Objects in a Stateflow Chart.

    This property is read-only.

    Whether the state is implicitly commented out, specified as a numeric or logical 1 (true) or 0 (false). The state is implicitly commented out when you explicitly comment out an object that contains it. If the state is contained in an atomic subchart, this property is false unless the explicitly commented object is also contained in the atomic subchart.

    Since R2023a

    This property is read-only.

    Whether the state is commented out, specified as a numeric or logical 1 (true) or 0 (false). This property is true when either IsExplicitlyCommented or IsImplicitlyCommented is true.

    Comment text added to the state, specified as a string scalar or character vector. This property applies only when the IsExplicitlyCommented property is true. In the Stateflow Editor, when you point to the comment badge on the state, the text appears as a tooltip. When you set the IsExplicitlyCommented property to false, the value of CommentText reverts to "".

    Graphical Appearance

    Position and size of the state, specified as a four-element numeric vector of the form [left top width height].

    This property is read-only.

    Whether the state graphically intersects a box, state, or function, specified as a numeric or logical 1 (true) or 0 (false).

    Whether the state is a grouped state, specified as a numeric or logical 1 (true) or 0 (false). When you copy and paste a grouped state, you copy not only the state but all of its contents. For more information, see Copy and Paste by Grouping.

    Whether the state is a subchart, specified as a numeric or logical 1 (true) or 0 (false).

    Whether to display a preview of the state contents, specified as a numeric or logical 1 (true) or 0 (false). This property applies only when the IsSubchart property is true.

    Size of incoming transition arrows, specified as a scalar.

    Font size for the state label, specified as a scalar. The StateFont.Size property of the chart that contains the state sets the initial value of this property.

    State Decomposition

    Decomposition of substates at the top level of containment in the state, specified as "EXCLUSIVE_OR" or "PARALLEL_AND". For more information, see Specify Substate Decomposition.

    This property is read-only.

    Decomposition of sibling states, specified as 'AND' or 'OR'. The state inherits this property from the Decomposition property of its parent state or chart.

    Execution order for the state in parallel (AND) decomposition, specified as an integer scalar. This property applies only when both of these conditions are satisfied:

    • The Type property of the state is "AND".

    • The UserSpecifiedStateTransitionExecutionOrder property of the chart that contains the state is true.

    Active State Output

    Whether to create an active state data output port for the state, specified as a numeric or logical 1 (true) or 0 (false). For more information, see Monitor State Activity Through Active State Data.

    This property is read-only.

    Active state data object for the state, specified as a Stateflow.Data object. This property applies only when the HasOutputData property for the state is true.

    Name of the active state data object for the state, specified as a string scalar or character vector. This property applies only when the HasOutputData property for the state is true.

    Monitoring mode for the active state output data, specified as "SelfActivity", "ChildActivity", or "LeafStateActivity".

    Name of the enumerated data type for the active state data object for the state, specified as a string scalar or character vector. This property applies only when the OutputMonitoringMode property for the state is "ChildActivity" or "LeafStateActivity". For more information, see Enum Name.

    Whether to define the enumerated data type for the active state data output manually, specified as a numeric or logical 1 (true) or 0 (false). This property applies only when the OutputMonitoringMode property for the state is "ChildActivity" or "LeafStateActivity". For more information, see Define State Activity Enumeration Type.

    Signal Logging and Test Point Monitoring

    Signal logging properties for the state, specified as a Stateflow.SigLoggingInfo object with these properties:

    • DataLogging — Whether to enable signal logging, specified as a numeric or logical 1 (true) or 0 (false).

    • DecimateData — Whether to limit the amount of logged data, specified as a numeric or logical 1 (true) or 0 (false).

    • Decimation — Decimation interval, specified as an integer scalar. This property applies only when the DecimateData property is true.

    • LimitDataPoints — Whether to limit the number of data points to log, specified as a numeric or logical 1 (true) or 0 (false).

    • MaxPoints — Maximum number of data points to log, specified as an integer scalar. This property applies only when the LimitDataPoints property is true.

    • NameMode — Source of the signal name, specified as "SignalName" or "Custom".

    • LoggingName — Custom signal name, specified as a string scalar or character vector. This property applies only when the NameMode property is "Custom".

    Signal logging saves the self activity of the state to the MATLAB® workspace during simulation. For more information, see Log Simulation Output for States and Data.

    Example: state.LoggingInfo.DataLogging = true;

    Whether to set the state as a test point, specified as a numeric or logical 1 (true) or 0 (false). You can monitor testpoints with a floating scope during simulation. You can also log test point values to the MATLAB workspace. For more information, see Monitor Test Points in Stateflow Charts.

    Debugging

    Debugger properties for the state, specified as a Stateflow.StateDebug object with these properties:

    • OnEntry — Whether to set the On State Entry breakpoint, specified as a numeric or logical 1 (true) or 0 (false).

    • OnDuring — Whether to set the During State breakpoint, specified as a numeric or logical 1 (true) or 0 (false).

    • OnExit — Whether to set the On State Exit breakpoint, specified as a numeric or logical 1 (true) or 0 (false).

    For more information, see Set Breakpoints to Debug Charts.

    Example: state.Debug.Breakpoints.OnEntry = true;

    Example: state.Debug.Breakpoints.OnDuring = true;

    Example: state.Debug.Breakpoints.OnExit = true;

    Code Generation

    Appearance of the state functions in generated code, specified as one of these values:

    • "Auto" — An internal calculation determines the appearance of state functions in generated code.

    • "Function" — State functions are implemented as separate static functions.

    • "Inline" — Calls to state functions are replaced by code as long as the function is not part of a recursion.

    For more information, see Inline State Functions in Generated Code (Simulink Coder).

    Hierarchy

    This property is read-only.

    Chart that contains the state, specified as a Stateflow.Chart object.

    This property is read-only.

    Subviewer for the state, specified as a Stateflow.Chart, Stateflow.State, or Stateflow.Box object. The subviewer is the chart or subchart where you can graphically view the state.

    This property is read-only.

    Machine that contains the state, specified as a Stateflow.Machine object.

    This property is read-only.

    Location of the parent of the state in the model hierarchy, specified as a character vector.

    Identification

    Description for the state, specified as a string scalar or character vector.

    Document link for the state, specified as a string scalar or character vector.

    User-defined tag for the state, specified as data of any type.

    This property is read-only.

    Session-independent identifier, specified as an integer scalar. Use this property to distinguish the state from other objects in its parent chart.

    This property is read-only.

    Unique identifier, specified as an integer scalar. Unlike SSIdNumber, the value of this property is reassigned every time you start a new MATLAB session and may be recycled after an object is deleted.

    Object Functions

    findIdentify specified objects in hierarchy
    getChildrenIdentify children of object
    getParentIdentify parent of object
    defaultTransitionsIdentify default transitions in specified object
    innerTransitionsIdentify inner transitions with specified source
    outerTransitionsIdentify outgoing transitions with specified source
    sinkedTransitionsIdentify transitions with specified destination
    sourcedTransitionsIdentify transitions with specified source
    getReferencesIdentify references to symbol name
    renameReferencesRename symbol and update references to symbol name
    commentedByIdentify objects that implicitly comment out a graphical object
    dialogOpen properties dialog box
    viewDisplay object in editing environment
    highlightHighlight graphical object
    fitToViewZoom in on graphical object

    Examples

    collapse all

    Add a state in the chart ch. Set its name to A.

    state = Stateflow.State(ch);
    state.Name = "A";

    To enter a multiline label in the state state, you can:

    • Call the MATLAB function sprintf and use the escape sequence \n to insert newline characters:

      str = sprintf("A\nen: action1();\ndu: action2();\nen,du: action3();");
      sA.LabelString = str;
    • Enter a concatenated text expression that uses the function newline to create newline characters:

      str = "A" + newline + ...
          "en: action1();" + newline + ...
          "du: action2();" + newline + ...
          "en,du: action3();"
      sA.LabelString = str;

    State with entry and during actions.

    To extract the state name, entry action, and during action specified by the state label, enter:

    name = state.Name
    name =
    
        'A'
    entry = state.EntryAction
    entry =
    
        ' action1();
          action3();'
    during = state.DuringAction
    during =
    
        ' action2();
          action3();'

    For more information, see Specify Labels in States and Transitions Programmatically.

    Create a supertransition that connects a junction inside a subchart to a junction outside the subchart.

    Stateflow chart with one state. A transition connects a junction inside the state to a junction outside the state.

    Open the model and access the Stateflow.Chart object for the chart.

    open_system("sfSupertransitionAPIExample")
    ch = find(sfroot,"-isa","Stateflow.Chart");

    Access the Stateflow.State object for the subchart and the Stateflow.Junction objects for the junctions.

    st = find(ch,"-isa","Stateflow.State");
    j1 = find(st,"-isa","Stateflow.Junction");
    j2 = find(ch,"-isa","Stateflow.Junction","-depth",1);

    Save the original position of the subchart to a temporary workspace variable subchartPosition.

    subchartPosition = st.Position;

    Convert the subchart to a normal state by setting its IsSubchart and IsGrouped properties to false.

    st.IsSubchart = false;
    st.IsGrouped = false;

    When you convert a subchart to a normal state, it may change size to display its contents.

    Stateflow chart with one state. A transition connects a junction inside the state to a junction outside the state.

    Add a transition that connects junction j1 to junction j2.

    tr = Stateflow.Transition(ch);
    tr.Source = j1;
    tr.Destination = j2;

    Stateflow chart with one subchart. A supertransition connects a junction inside the subchart to a junction outside the subchart.

    Revert the state to a subchart by setting its IsSubchart property to true. Restore the subchart to its original position.

    st.IsSubchart = true;
    st.Position = subchartPosition;

    Stateflow chart with one subchart. A supertransition connects a junction inside the subchart to a junction outside the subchart.

    The transition between the junctions is now a supertransition that crosses the boundary of the subchart.

    Version History

    Introduced before R2006a

    expand all