Stateflow®

Using Graphical Functions to Extend Actions

What Is a Graphical Function?

A graphical function is a program that you write with flow graphs using connective junctions and transitions. You create a graphical function, fill it with a flow graph, and call it many times in the actions of states and transitions.

Back to Top

Why Use a Graphical Function?

A graphical function is easier to create, access, and manage than a textual function, such as a C or MATLAB^® function that you must define externally. Like a textual function, a graphical function can accept arguments and return values. Unlike a textual function, a graphical function is a native Stateflow^® object. You use the Stateflow Editor to create a graphical function that resides in your model along with the charts that invoke the function.

Back to Top

Where to Use a Graphical Function

A graphical function can reside anywhere in a chart, state, or subchart. The location of a function determines its scope, that is, the set of states and transitions that can call the function. In particular, graphical functions are visible to the chart, to the parent state and its parents, and to sibling transitions and states. These exceptions apply:

• If the chart containing the function exports its graphical functions, the scope of the function is the entire Stateflow machine, which encompasses all the charts in the model. See Exporting Chart-Level Graphical Functions for more information.

• A function that you define in a state or subchart overrides any functions of the same name in the parents and ancestors of that state or subchart.

Back to Top

Workflow for Defining a Graphical Function

Creating a Graphical Function

Use these steps to create a graphical function in your chart:

1. Click the graphical function icon in the Stateflow Editor toolbar:

   

2. Move your pointer to the location for the new graphical function in your chart and click to insert the function box.

3. Enter the function signature.

   The function signature specifies a name for your function and the formal names for its arguments and return values. A signature has this syntax:

   [r1, r2,..., rn] = func(a1,a2,..., an)
   

   where func is the name of your function, a₁, a₂, ..., a_n are formal names for its arguments, and r₁, r₂, ..., r_n are formal names for its return values.

   Note   You can define arguments and return values as scalars, vectors, or 2-dimensional matrices of any data type.

4. Click outside of the function box.

The following signature is for a graphical function that has the name f1, which takes three arguments (a, b, and c) and returns three values (x, y, and z).

Note   You can use the Stateflow Editor to change the signature of your graphical function at any time. After you edit the signature, the Model Explorer updates to reflect the changes.

Programming a Graphical Function

To program a graphical function, follow these steps:

1. Click the default transition icon in the Stateflow Editor toolbar:

   

2. Move your pointer inside the function box in your chart and click to insert the default transition and its terminating junction.

3. Enter transition conditions and actions for your graphical function. If necessary, add connective junctions and transitions to your function.

   Note   Connective junctions and transitions are the only graphical elements you can use in a graphical function. Because a graphical function must execute completely when you call it, you cannot use states.

This function box shows a flow graph that returns different products of its arguments.

Defining Graphical Function Data

You must define the data in your graphical function:

1. In the Stateflow Editor, select View > Model Explorer.

   The signature for your function appears as a property of its parent chart in the Contents pane of the Model Explorer.

   

2. Expand the parent object in the Model Explorer, so that you can see the return values and arguments of the function signature as data items that belong to your graphical function.

   

   The Scope column in the Model Explorer indicates the role of each argument or return value. Arguments have the scope Input, and return values have the scope Output.

3. For each function argument and return value, right-click the data row in the Model Explorer and select Properties from the context menu.

4. In the Data properties dialog for each argument and return value, specify the data properties.

   These rules apply:

   • Each argument and return value can be a scalar or matrix of values.

   • Arguments cannot have initial values.

5. Create any additional data items that your function must have to process its programming.

   Your function can access its own data or data belonging to parent states or the chart. The data items that you create for the function itself can have one of these scopes:

   • Local

     Local data persists from one function call to the next.

   • Temporary

     Temporary data initializes at the start of every function call.

   • Constant

     Constant data retains its initial value through all function calls.

   Note   You can initialize your function data (other than arguments and return values) from the MATLAB workspace. However, you can save only local items to this workspace.

Back to Top

Managing Large Graphical Functions

You can make your graphical function as large as you want, as shown below.

However, if your function grows too large, you can hide its contents by right-clicking inside the function box and selecting Make Contents > Subcharted from the context menu. This option makes your graphical function opaque.

To access the programming of your subcharted graphical function, double-click it. This action dedicates the entire chart window to programming your function.

To access your original chart, click the Back button .

Back to Top

Calling Graphical Functions in Stateflow^® Action Language

Description

To call your graphical function, use Stateflow action language. Any state or transition action in the scope of your function can perform a function call.

Syntax

Syntax for a function call is the same as that of a function signature, with actual arguments replacing the formal ones specified in a signature. If the data types of the actual and formal argument differ, a function casts the actual argument to the type of the formal argument.

See Creating a Graphical Function for information about syntax for a function signature.

Example

In this example, a state entry action calls a graphical function that returns three products.

Back to Top

Exporting Chart-Level Graphical Functions

Why Export Graphical Functions?

When you export chart-level graphical functions, you extend the scope of your functions to all other charts in your model.

Note   To export functions in library charts, you must link those charts to your main model.

How to Export Chart-Level Graphical Functions

Perform these steps to export graphical functions to your main model:

1. Open the chart where your graphical function resides.

2. In the Stateflow Editor, select File > Chart Properties.

3. In the Chart Properties dialog, select Export Chart Level Graphical Functions (Make Global).

4. If your function resides in a library chart, link that chart to your main model.

Example of Exporting Chart-Level Graphical Functions

This example describes how to export graphical functions in library charts to your main model.

1. Create these objects:

   • Add a model named main_model, with a chart named modChart.

     

   • Add a library model named lib1, with a chart named lib1Chart.

     

   • Add a library model named lib2, with a chart named lib2Chart.

     

2. Create these graphical functions:

   • For modChart, add this graphical function.

     

   • For lib1Chart, add this graphical function.

     

   • For lib2Chart, add this graphical function.

     

3. Add a default transition to modChart.

   

4. For each chart, select File > Chart Properties in the Stateflow Editor.

5. In the properties dialog for each chart, select the Export Chart Level Graphical Functions (Make Global) option.

6. Drag lib1Chart and lib2Chart into main_model from lib1 and lib2, respectively.

   

   Each chart now defines a graphical function that any chart in main_model can call.

After you export your graphical functions from the library charts, the sequence of actions in main_model is:

1. modChart calls the graphical function lib1_func, which takes two arguments, x and y.

2. lib1_func calls the graphical function lib2_func, which passes the same two arguments.

3. lib2_func calls the graphical function mod_func, which adds x and y.

4. x takes the result of the addition.

Back to Top

Specifying Graphical Function Properties

You can set general properties for your graphical function through its properties dialog:

1. Right-click your graphical function box.

2. Select Properties from the context menu.

   The properties dialog for your graphical function appears.

   

The fields in the properties dialog are:

Back to Top

Extending Transitions with Smart Behavior

Using Boxes to Extend Charts