| Simulink® | |
| On this page… |
|---|
Creating Model Callback Functions |
You can define MATLAB® expressions that execute when the block diagram or a block is acted upon in a particular way. These expressions, called callback functions, are specified by block, port, or model parameters. For example, the function specified by a block's NameChangeFcn parameter is executed when you double-click that block's name or its path changes.
Note Do not call the run command from within model or block callbacks. Doing so can result in unexpected behavior (such as errors or incorrect results) if a Simulink® model is loaded, compiled, or simulated from inside an M-function. |
Callback tracing allows you to determine the callbacks the Simulink software invokes and in what order the it invokes them when you open or simulate a model. To enable callback tracing, select the Callback tracing option on the Preferences dialog box (see ) or execute set_param(0, 'CallbackTracing', 'on'). This option causes the callbacks to be listed in the MATLAB Command Window as they are invoked. This option applies to all Simulink models, not just models that are open when the preference is enabled.
You can create model callback functions interactively or programmatically. Use the Callbacks pane of the model's Model Properties dialog box (see Callbacks Pane) to create model callbacks interactively. To create a callback programmatically, use the set_param command to assign a MATLAB expression that implements the function to the model parameter corresponding to the callback (see Model Callback Functions).
For example, this command evaluates the variable testvar when the user double-clicks the Test block in mymodel:
set_param('mymodel/Test', 'OpenFcn', testvar)
You can examine the clutch system (sldemo_clutch.mdl) for routines associated with many model callbacks. This model defines the following callbacks:
PreLoadFcn
PostLoadFcn
StartFcn
StopFcn
CloseFcn
The following table describes callback functions associated with models.
| Parameter | When Executed | |
|---|---|---|
Before the block diagram is closed. Any ModelCloseFcn and DeleteFcn callbacks set on blocks in the model are called prior to the model's CloseFcn. The DestroyFcn callback of any blocks in the model is called after the model's CloseFcn. | ||
After the model is loaded. Defining a callback routine for this parameter might be useful for generating an interface that requires that the model has already been loaded. | ||
Called at start of model simulation. | ||
After the model is saved. | ||
Before the model is loaded. Defining a callback routine for this parameter might be useful for loading variables used by the model.
| ||
Before the model is saved. | ||
Before the simulation starts. | ||
After the simulation stops. Output is written to workspace variables and files before the StopFcn is executed. |
Note Beware of adverse interactions between callback functions of models referenced by other models. (See Referencing a Model.) For example, suppose that model A references model B and that model A's OpenFcn creates variables in the MATLAB workspace and model B's CloseFcn clears the MATLAB workspace. Now suppose that simulating model A requires rebuilding model B. Rebuilding B entails opening and closing model B and hence invoking model B's CloseFcn, which clears the MATLAB workspace, including the variables created by A's OpenFcn. |
You can create block callback functions interactively or programmatically. Use the Callbacks pane of the block's Block Properties dialog box (see Callbacks Pane) to create block callbacks interactively. To create a callback programmatically, use the set_param command to assign a MATLAB expression that implements the function to the block parameter corresponding to the callback (see Block Callback Parameters).
Note A callback for a masked subsystem cannot directly reference the parameters of the masked subsystem (see About Masks). The Simulink software evaluates block callbacks in the MATLAB base workspace whereas the mask parameters reside in the masked subsystem's private workspace. A block callback, however, can use get_param to obtain the value of a mask parameter, e.g., get_param(gcb, 'gain'), where gain is the name of a mask parameter of the current block. |
This table lists the parameters for which you can define block callback routines, and indicates when those callback routines are executed. Routines that are executed before or after actions take place occur immediately before or after the action.
| Parameter | When Executed |
|---|---|
When the block is copied or cut to the system clipboard. | |
When the block is closed using the close_system command. The CloseFcn is not called when you interactively close the block, when you interactively close the subsystem or model containing the block, or when you close the subsystem or model containing the block using close_system. | |
After a block is copied. The callback is recursive for Subsystem blocks (that is, if you copy a Subsystem block that contains a block for which the CopyFcn parameter is defined, the routine is also executed). The routine is also executed if an add_block command is used to copy the block. | |
After a block or line is deleted in a subsystem. If the block has a DeleteFcn or DestroyFcn, those functions are executed prior to the DeleteChildFcn. Only Subsystem blocks have a DeleteChildFcn callback. | |
After a block is graphically deleted, e.g., when you graphically delete the block, invoke delete_block on the block, or close the model containing the block. When the DeleteFcn is called, the block handle is still valid and can be accessed using get_param. The DeleteFcn callback is recursive for Subsystem blocks. If the block is graphically deleted by invoking delete_block or by closing the model, after deletion the block is destroyed from memory and the block's DestroyFcn is called. | |
When the block has been destroyed from memory, e.g., when you invoke delete_block on either the block or a subsystem containing the block or close the model containing the block. If the block was not previously graphically deleted, the block's DeleteFcn is called prior to the DestroyFcn. When the DestroyFcn is called, the block handle is no longer valid. | |
Before the block diagram is compiled and before block parameters are evaluated. | |
When an error has occurred in a subsystem. Only Subsystem blocks have a ErrorFcn callback. The callback function should have the following form: errorMsg = errorHandler(subsys, errorType) where errorHandler is the name of the callback function, subsys is a handle to the subsystem in which the error occurred, errorType is a Simulink string indicating the type of error that occurred, and errorMsg is a string specifying the error message to be displayed to the user. The following command sets the ErrorFcn of the subsystem subsys to call the errorHandler callback function set_param(subsys,'ErrorFcn','errorHandler') Do not include the callback function's input arguments in the call to set_param. The Simulink software displays the error message errorMsg returned by the callback function. | |
After the block diagram is loaded. This callback is recursive for Subsystem blocks. | |
Before the block diagram is closed. When the model is closed, the block's ModelCloseFcn is called prior to its DeleteFcn. This callback is recursive for Subsystem blocks. | |
When the block is moved or resized. | |
After a block's name and/or path changes. When a Subsystem block's path is changed, it recursively calls this function for all blocks it contains after calling its own NameChangeFcn routine. | |
When the block is opened. This parameter is generally used with Subsystem blocks. The routine is executed when you double-click the block or when an open_system command is called with the block as an argument. The OpenFcn parameter overrides the normal behavior associated with opening a block, which is to display the block's dialog box or to open the subsystem. | |
Before closing a subsystem containing the block or when the block is made part of a new subsystem using the new_system command (see new_system in the online Simulink software reference) or the Create Subsystem item in model editor's Edit menu. The ParentCloseFcn of blocks at the root model level is not called when the model is closed. | |
After the block diagram is saved. This callback is recursive for Subsystem blocks. | |
| PreCopyFcn | Before a block is copied. The callback is recursive for Subsystem blocks (that is, if you copy a Subsystem block that contains a block for which the PreCopyFcn parameter is defined, that routine is also executed). The block's CopyFcn is called after all PreCopyFcn callbacks are executed, unless the PreCopyFcn invokes the error command either explicitly or via a command used in any PreCopyFcn. The PreCopyFcn is also executed if an add_block command is used to copy the block. |
| PreDeleteFcn | Before a block is graphically deleted, e.g., when the user graphically deletes the block or invokes delete_block on the block. The PreDeleteFcn is not called when the model containing the block is closed. The block's DeleteFcn is called after the PreDeleteFcn unless the PreDeleteFcn invokes the error command either explicitly or via a command used in the PreDeleteFcn. |
Before the block diagram is saved. This callback is recursive for Subsystem blocks. | |
After the block diagram is compiled and before the simulation starts. In the case of an S-Function block, StartFcn executes immediately before the first execution of the block's mdlProcessParameters function. See S-Function Callback Methods for more information. | |
At any termination of the simulation. In the case of an S-Function block, StopFcn executes after the block's mdlTerminate function executes. See S-Function Callback Methods for more information. | |
When a block deletion is undone. |
Block input and output ports have a single callback function parameter, ConnectionCallback. This parameter allows you to set callbacks on ports that are triggered every time the connectivity of these ports changes. Examples of connectivity changes include adding a connection from the port to a block, deleting a block connected to the port, and deleting, disconnecting, or connecting branches or lines to the port.
Use get_param to get the port handle of a port and set_param to set the callback on the port. The callback function must have one input argument that represents the port handle, but the input argument is not included in the call to set_param. For example, suppose the currently selected block has a single input port. The following code fragment sets foo as the connection callback on the input port.
phs = get_param(gcb, 'PortHandles'); set_param(phs.Inport, 'ConnectionCallback', 'foo');
where, foo is defined as:
function foo(portHandle)
| Modeling Control Flow Logic | Using Model Workspaces | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |