ModelAdvisor.Check

R2026b

Create custom Model Advisor checks

Description

Use the ModelAdvisor.Check class to define custom checks that appear in the Model Advisor tree, configure their callback functions and input parameters, and control how results are displayed.

Creation

Syntax

check_obj = ModelAdvisor.Check(check_ID)

Description

check_obj = ModelAdvisor.Check(check_ID) creates a check object, check_obj, using the identifier specified by check_ID. To display checks in the Model Advisor tree, the checks must have an associated ModelAdvisor.Task or ModelAdvisor.Root object.

You can use one ModelAdvisor.Check object in multiple ModelAdvisor.Task objects, allowing you to place the same check in multiple locations in the Model Advisor tree. For example, Check for implicit signal resolution is displayed in the By Product > Simulink folder and in the By Task > Model Referencing folder in the Model Advisor tree.

When you use checks in task definitions, the following rules apply:

• If you define the properties of the check in the check definition and the task definition functions, the Model Advisor only displays the information contained in the task definition. For example, if you define the name of the check using the ModelAdvisor.Task.DisplayName property and using the ModelAdvisor.Check.Title property, the Model Advisor displays the information provided in ModelAdvisor.Task.DisplayName.

• If you define the properties of the check in the check definition but not the task definition, the task uses the properties from the check. For example, if you define the name of the check in the check definition function using the ModelAdvisor.Check.Title property, and you register the check using a task definition, the Model Advisor displays the information provided in ModelAdvisor.Check.Title.

• If you define the properties of the check in the task definition function but not the check definition function, the Model Advisor displays the information as long as you register the task with the Model Advisor instead of the check. For example, if you define the name of the check in the task definition using the ModelAdvisor.Task.DisplayName property instead of the ModelAdvisor.Check.Title property, and you register the check using a task definition, the Model Advisor displays the information provided in ModelAdvisor.Task.DisplayName.

Input Arguments

check_ID — Check ID for the custom Model Advisor check, specified as a character vector

character vector

Unique identifier for the custom Model Advisor check.

Properties

CallbackContext — Specify when to run check

None (default) | PostCompile | PostCompileForCodeGen

Specifies the context for checking the model or subsystem.

• None — Runs the check without requiring model compilation.

• PostCompile — Runs the check after the model is compiled.

• PostCompileForCodeGen — Runs the check after the model is compiled for code generation.

CallbackHandle — Callback function handle for check

[ ] (default) | Function handle | Cell array of function handles

Specifies the handle to the check callback function.

Example: {@checkFcn1, @checkFcn2}

CallbackStyle — Callback function type

StyleOne (default) | DetailStyle | StyleTwo | StyleThree

Specifies the type of the callback function.

The DetailStyle callback function uses a detailed results collection callback function, which is the recommended approach. This style enables the default Model Advisor report format, so you do not need to use the ModelAdvisor.FormatTemplate class or other formatting APIs. It allows you to view results by block, subsystem, or recommended action. Instead of returning output arguments, the callback stores results directly in the CheckObj object using the Simulink.ModelAdvisor API. The check definition requires the DetailStyle keyword.

Argument	I/O Type	Description
system	Input	Path to the model or subsystem analyzed by the Model Advisor.
CheckObj	Input	ModelAdvisor.Check object

The StyleOne callback function uses a simple check callback function to indicate whether a model passes or fails the check, or to recommend fixes. You format results using the Model Advisor Formatting APIs. The check definition requires the StyleOne keyword.

Argument	I/O Type	Description
system	Input	Path to the model or subsystem analyzed by the Model Advisor.
result	Output	MATLAB® character vector that supports Model Advisor Formatting API calls or embedded HTML tags for text formatting object.

The StyleTwo callback function uses a detailed check callback function to return and organize results as strings in a layered, hierarchical structure. The function provides two output arguments to associate text descriptions with one or more paragraphs of detailed information. The check definition requires the StyleTwo keyword.

Argument	I/O Type	Description
system	Input	Path to the model or subsystem analyzed by the Model Advisor.
ResultDescription	Output	Cell array of MATLAB character vectors that supports Model Advisor Formatting API calls or embedded HTML tags for text formatting. The Model Advisor concatenates the ResultDescription character vector with the corresponding array of ResultDetails character vectors.
ResultDetails	Output	Cell array of cell arrays, each of which contains one or more character vectors. The ResultDetails cell array must be the same length as the ResultDescription cell array.

The StyleThree callback function uses a callback function that automatically displays hyperlinks for every object returned by the check. This style makes it easy to navigate to related model elements. The check definition requires the StyleThree keyword.

Argument	I/O Type	Description
system	Input	Path to the model or subsystem analyzed by the Model Advisor.
ResultDescription	Output	Cell array of MATLAB character vectors that supports the Model Advisor Formatting API calls or embedded HTML tags for text formatting.
ResultDetails	Output	Cell array of cell arrays, each of which contains one or more Simulink® objects such as blocks, ports, lines, and Stateflow® charts. The objects must be in the form of a handle or Simulink path. The ResultDetails cell array must be the same length as the ResultDescription cell array.

EmitInputParametersToReport — Display check input parameters in the Model Advisor report

true (default) | false

Specifies the display of check input parameters in the Model Advisor report.

Enable — Indicate whether user can enable or disable check

true (default) | false

Specifies whether the user can enable or disable the check.

ErrorSeverity — Set severity of check failure

0 (default) | 1

An integer value that specifies whether the check is marked as a warning or failure when the check flags an issue in your model. A value of 0 marks the check as a warning; a value of 1 marks the check as a failure. This property is the programmatic equivalent of using the Check result when issues are flagged options in the Model Advisor Configuration Editor.

In this sample code for defining the properties of a custom check, the value for ErrorSeverity is 1. Therefore, if a violation of this check is flagged in a model, the check is marked as Fail in the results.

% Create ModelAdvisor.Check object and set properties.
rec = ModelAdvisor.Check('com.mathworks.sample.detailStyle');
rec.Title = 'Check whether block names appear below blocks';
rec.TitleTips = 'Check position of block names';
rec.setCallbackFcn(@DetailStyleCallback,'None','DetailStyle');
rec.ErrorSeverity = 1;

ID — Identifier for check

'' (empty character vector) (default) | character vector

The ID property specifies a permanent, unique identifier for the check. Note the following about the ID property:

• You must specify this property.

• The value of ID must remain constant.

• The Model Advisor generates an error if ID is not unique.

• Tasks and factory group definitions must refer to checks by ID.

LicenseName — Product license names required to display and run check

{} (empty cell array) (default) | cell array of product license names

Specifies a cell array of names for product licenses required to display and run the check. When the Model Advisor starts, it tests whether the product license exists. If you do not meet the license requirements, the Model Advisor does not display the check. The Model Advisor performs a checkout of the product licenses when you run the custom check. If you do not have the product licenses available, you see an error message that the required license is not available.

Tip

To find the text for license strings, type help license at the MATLAB command line.

Result — Results cell array

{} (empty cell array) (default) | cell array

Specifies the cell array for storing the results that are returned by the callback function specified in CallbackHandle.

Tip

To set the icon associated with the check, use the Simulink.ModelAdvisor setCheckResultStatus and setCheckErrorSeverity methods.

ResultDetails — Results details cell array

{} (empty cell array) (default) | cell array

Stores the ModelAdvisor.ResultDetail objects associated with the check. This property can contain multiple objects.

SupportExclusion — Enables model element exclusions

false (default) | true

Specifies whether the check supports exclusions.

The sample code specifies a check that supports exclusions.

% specify that a check supports exclusions
rec = ModelAdvisor.Check('com.mathworks.sample.Check1');
rec.SupportExclusion = true; 

SupportLibrary — Enables library model support

false (default) | true

Specifies whether the check supports library models.

The sample code specifies a check that supports library models.

% specify that a check supports library models
rec = ModelAdvisor.Check('com.mathworks.sample.Check1');
rec.SupportLibrary = true;  

Title — Name of check

'' (empty character vector) (default) | character vector

Specifies the name of the check in the Model Advisor. The Model Advisor displays each custom check in the tree using the title of the check. Specify a unique title for each check. When you specify the same title for multiple checks, the Model Advisor generates a warning.

The sample code specifies a name for a custom check.

rec = ModelAdvisor.Check('com.mathworks.sample.Check1');
rec.Title = 'Check Simulink block font';  

TitleTips — Description of check

'' (empty character vector) (default) | character vector

Specifies a description of the check. Details about the check are displayed in the right pane of the Model Advisor.

The sample code specifies a description for a custom check.

rec = ModelAdvisor.Check('com.mathworks.sample.Check1');
rec.Title = 'Check Simulink block font';
rec.TitleTips = 'Example style three callback';  

Value — Status of check

false (default) | true

Specifies the initial status of the check. When you use the Value property to specify the initial status of the check, you enable or disable Run This Check in the Model Advisor window.

If you want to specify the initial status of a check in the By Product folder, before starting Model Advisor, make sure ModelAdvisor.Preferences.DeselectByProduct is false.

The sample code specifies the initial status of a check.

% hide all checks that do not belong to Demo group
if ~(strcmp(checkCellArray{i}.Group, 'Demo'))
    checkCellArray{i}.Visible = false;
    checkCellArray{i}.Value = false;
end  

Visible — Indicate to display or hide check

true (default) | false

Specifies whether the Model Advisor displays the check.

The sample code specifies hiding all the checks in the Model Advisor that do not belong to the Demo group.

% hide all checks that do not belong to Demo group
if ~(strcmp(checkCellArray{i}.Group, 'Demo'))
    checkCellArray{i}.Visible = false;
    checkCellArray{i}.Value = false;
end  

Object Functions

getID	Return check identifier
setAction	Specify action for check
setHelp	Set custom help for custom authored Model Advisor checks
setInputParameters	Specify input parameters for check
setCallbackFcn	Specify callback function for check
setInputParametersLayoutGrid	Specify layout grid for input parameters
setResultDetails	Associates result details with a check object

Version History

Introduced in R2008a