Reuse Logic Patterns by Defining Graphical Functions
A graphical function in a Stateflow® chart is a graphical element that helps you reuse control-flow logic and iterative loops. You create graphical functions with flow charts that use connective junctions and transitions. You can call a graphical function in the actions of states and transitions. With graphical functions, you can:
Create modular, reusable logic that you can call anywhere in your chart.
Track simulation behavior visually during chart animation.
A graphical function can reside anywhere in a chart, state, or subchart. The location of the function determines the set of states and transitions that can call the function.
If you want to call the function only within one state or subchart and its substates, put your graphical function in that state or subchart. That function overrides any other functions of the same name in the parents and ancestors of that state or subchart.
If you want to call the function anywhere in that chart, put your graphical function at the chart level.
If you want to call the function from any chart in your model, put your graphical function at the chart level and enable exporting of chart-level functions. For more information, see Export Stateflow Functions for Reuse.
For example, this graphical function has the name f1. It takes
three arguments (a, b, and c)
and returns three output values (x, y, and
z). The function contains a flow chart that computes three
different products of the arguments.
Define a Graphical Function
In the object palette, click the graphical function icon
. Move your pointer to the location for the new
graphical function in your chart.Enter the signature label for the function, as described in Declare Function Arguments and Return Values.
To program the function, construct a flow chart inside the function box, as described in Flow Charts in Stateflow.
Because a graphical function must execute completely when you call it, you cannot use states. Connective junctions and transitions are the only graphical elements that you can use in a graphical function.
In the Model Explorer, expand the chart object and select the graphical function. The arguments and return values of the function signature appear as data items that belong to your function. Arguments have the scope
Input. Return values have the scopeOutput.In the Data properties dialog box for each argument and return value, specify the data properties, as described in Set Data Properties.
Create any additional data items required by your function. For more information, see Add Data Through the Model Explorer.
Your function can access its own data or data belonging to parent states or the chart. The data items in the function can have one of these scopes:
Local— Local data persists from one function call to the next function call. Valid for C charts only.Constant— Constant data retains its initial value through all function calls.Parameter— Parameter data retains its initial value through all function calls.Temporary— Temporary data initializes at the start of every function call. Valid for C charts only.
Initialize Function Data
You can initialize your function data (other than arguments and return values) from the MATLAB® workspace. For more information, see Initialize Data from the MATLAB Base Workspace.
Define Temporary Data
In charts that use C as the action language, define temporary data when you
want to use data that is only valid while a function executes. For example, you
can designate a loop counter to have Temporary scope if the counter value does not need to persist
after the function completes.
In charts that use MATLAB as the action language, you do not need to define temporary function data. If you use an undefined variable, Stateflow creates a temporary variable. The variable is available to the rest of the function.
Declare Function Arguments and Return Values
The function signature label specifies a name for your function and the formal names for its arguments and return values. A signature label has this syntax:
[return_val1,return_val2,...] = function_name(arg1,arg2,...)
You can use the same variable name for both arguments and return values. For
example, a function with this signature label uses the variables
y1 and y2 as both inputs and
outputs:
[y1,y2,y3] = f(y1,u,y2)
y1 and y2
are passed by reference (as pointers), and u is passed by value.
Passing inputs by reference reduces the number of times that the generated code
copies intermediate data, resulting in more optimal code.Call Graphical Functions in States and Transitions
You can call graphical functions from the actions of any state or transition. You can also call graphical functions from other functions. If you export a graphical function, you can call it from any chart in the model.
The syntax for a call to a graphical function is the same as the function signature, with actual arguments replacing the formal ones specified in a signature. If the data types of an actual and formal argument differ, a function casts the actual argument to the type of the formal argument.
Tip
If the formal arguments of a function signature are scalars, verify that inputs and outputs of function calls follow the rules of scalar expansion. For more information, see Assign Values to All Elements of a Matrix.
Specify Graphical Function Properties
You can set general properties for your graphical function through its properties dialog box. To open the function properties dialog box, right-click the graphical function box and select Properties from the context menu.
Name
Function name. Click the function name link to bring your function to the foreground in its native chart.
Function Inline Option
Controls the inlining of your function in generated code:
Auto— Determines whether to inline your function based on an internal calculation.Inline— Inlines your function if you do not export it to other charts and it is not part of a recursion. (A recursion exists if your function calls itself directly or indirectly through another function call.)Function— Does not inline your function.
Label
Signature label for your function. For more information, see Declare Function Arguments and Return Values.
Description
Function description. You can enter brief descriptions of functions in the hierarchy.
Document Link
Link to online documentation for the function. You can enter a web URL address or a MATLAB command that displays documentation in a suitable online format, such as an HTML file or text in the MATLAB Command Window. When you click the Document link hyperlink, Stateflow displays the documentation.
Manage Large Graphical Functions
You can choose to make your graphical function as large as you want. If your function grows too large, you can hide its contents by right-clicking inside the function box and selecting Group & Subchart > Subchart from the context menu.
To make the graphical function box opaque, right-click the function and clear the Content Preview property from the context menu.
To dedicate the entire chart window to programming your function, access the flow chart in your subcharted graphical function by double-clicking the function box.
Event Broadcasts in Graphical Functions
In a graphical function, do not broadcast events that can cause the active state to change. In a graphical function, the behavior of an event broadcast that causes an exit from the active state is unpredictable.