Main Content

ModelAdvisor.ResultDetail class

Package: ModelAdvisor

Define check result details

Description

Use objects of the ModelAdvisor.ResultDetail class in your custom check authoring algorithm to provide details about check results. For checks that run only in the Model Advisor, use the setResultDetails method to associate these results with the ModelAdvisor.Check object and specify 'DetailStyle' as the callback style in the ModelAdvisor.Check.setCallbackFcn function.

Properties

expand all

Simulink identifier (SID) for each block or signal handle for each signal that violates your custom check, specified as a string.

Data Types: char

Data type, specified as the ModelAdvisor.ResultDetailType enumeration type that indicates the location of the check violation:

  • SID – Check violation is on a block

  • Signal – Check violation is on a signal

Data Types: enum

Whether check results do not have violations, specified as true or false. If IsInformer = true, then IsViolation = false.

Data Types: logical

Whether check results have violations, specified as true or false. If IsViolation = true, then IsInformer = false.

Data Types: logical

Description of check results, specified as a string.

Data Types: char

Title of check results, specified as a string.

Data Types: char

Additional information about the check results, specified as a string.

Data Types: char

Status message that appears in the Model Advisor, specified as a string.

Data Types: char

Recommended action for fixing the check, specified as a string.

Data Types: char

Severity of check results specified as "pass", "fail", or "warn".

Data Types: char

Methods

setDataAssociate block identifier or signal handle with ModelAdvisor.ResultDetail object

Examples

collapse all

Create a custom Model Advisor check that checks whether block names appear below blocks.

To register the custom edit-time check, create an sl_customization function. The sl_customization function accepts one argument, a customization manager object. To register the custom check, use the addModelAdvisorCheckFcn method. The input to this method is a handle to the check definition function. For this example, defineDetailStyleCheck is the check definition function. Create the sl_customization function and save it to your working folder.

function sl_customization(cm)
cm.addModelAdvisorCheckFcn(@defineDetailStyleCheck);

Create the check definition function. For this example, create the defineDetailStyleCheck function and copy the code below into it. Save the function to your working folder. The check definition function contains ModelAdvisor.Check and ModelAdvisor.Action objects that define the check actions and a fix. For more details on these aspects of the code, see Fix a Model to Comply with Conditions that You Specify with the Model Advisor.

The defineDetailStyleCheck function contains a DetailStyleCallback callback function. To return blocks whose name does not appear below the block, violationBlks, the DetailStyleCallback function uses the find_system function.

When violationBlks is empty, the code creates one ModelAdvisor.ResultDetail object, ElementResults. ElementResults specifies information about the passing check that appears in the Model Advisor.

When the find_system function returns a list of blocks that violate the check, ElementResults is an array of ModelAdvisor.Results objects. The array contains one object for each block that violates the check. Each object contains information about the violation block that appears in the Model Advisor.

function defineDetailStyleCheck

% 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');

% Create ModelAdvisor.Action object for setting fix operation.
myAction = ModelAdvisor.Action;
myAction.setCallbackFcn(@ActionCB);
myAction.Name='Make block names appear below blocks';
myAction.Description='Click the button to place block names below blocks';
rec.setAction(myAction);

% publish check into Demo group.
mdladvRoot = ModelAdvisor.Root;
mdladvRoot.publish(rec, 'Demo'); 

end

% -----------------------------
% This callback function uses the DetailStyle CallbackStyle type. 
% -----------------------------
function DetailStyleCallback(system, CheckObj)
% get Model Advisor object
mdladvObj = Simulink.ModelAdvisor.getModelAdvisor(system); 

% Find all blocks whose name does not appear below blocks
violationBlks = find_system(system, 'Type','block',...
    'NamePlacement','alternate',...
    'ShowName', 'on');
if isempty(violationBlks)
    ElementResults = ModelAdvisor.ResultDetail;
    ElementResults.IsInformer = true;
    ElementResults.Description = 'Identify blocks where the name is not displayed below the block.';
    ElementResults.Status = 'All blocks have names displayed below the block.';
else
    for i=1:numel(violationBlks)
	 ElementResults(1,i) = ModelAdvisor.ResultDetail;
    end
    for i=1:numel(ElementResults)
        ModelAdvisor.ResultDetail.setData(ElementResults(i), 'SID',violationBlks{i});
        ElementResults(i).Description = 'Identify blocks where the name is not displayed below the block.';
        ElementResults(i).Status = 'The following blocks have names that do not display below the blocks:';
        ElementResults(i).RecAction =  'Change the location such that the block name is below the block.';
        ElementResults(i).ViolationType = 'warn';
    end
    mdladvObj.setActionEnable(true);
end
CheckObj.setResultDetails(ElementResults);
end

% -----------------------------
% This action callback function changes the location of block names. 
% -----------------------------
function result = ActionCB(taskObj)
mdladvObj = taskObj.MAObj;
checkObj = taskObj.Check;
resultDetailObjs = checkObj.ResultDetails;
for i=1:numel(resultDetailObjs)
    % take some action for each of them
    block=Simulink.ID.getHandle(resultDetailObjs(i).Data);
    set_param(block,'NamePlacement','normal');
end

result = ModelAdvisor.Text('Changed the location such that the block name is below the block.');
mdladvObj.setActionEnable(false);
end

Refresh the Model Advisor to update the cache with the new check on the path.

Advisor.Manager.refresh_customizations

To use the check, copy the AdvisorCustomizationExample.slx model to your current working folder. Open the model.

copyfile(fullfile(matlabroot,'examples','slcheck','main',...
'AdvisorCustomizationExample.slx'),'AdvisorCustomizationExample.slx','f');

Model to check for check violations

Open the Model Advisor by clicking the Modeling tab and selecting Model Advisor.

In the left pane, select By Product > Demo > Check whether block names appear below and click Run Checks.

To address the warning, click Fix.

Create a custom edit-time check that checks whether signals that connect to Outport blocks have labels.

To register the custom edit-time check, create an sl_customization function and save it to your working folder.

function sl_customization(cm)
cm.addModelAdvisorCheckFcn(@defineCheck);

Create the check definition function. Inside the function, create a ModelAdvisor.Check object and specify the check ID as the input argument. Then, specify the ModelAdvisor.Check Title and CallbackHandle properties. The CallbackHandle property is the name of the class that you create to define the edit-time check. For this example, MyEditTimeChecks is the package name and SignalLabel is the class names. Then, publish the check to a new folder in the Model Advisor. For this example, the folder name is DEMO: Edit Time Checks. For this example, create a defineCheck function and include the code below in it. Save the defineCheck function to your working folder.

function defineCheck
rec = ModelAdvisor.Check("advisor.edittimecheck.SignalLabel");
rec.Title = 'Check that signals have labels if they are to propagate those labels';
rec.CallbackHandle = 'MyEditTimeChecks.SignalLabels';
mdladvRoot = ModelAdvisor.Root;
mdladvRoot.publish(rec,'DEMO: Edit Time Checks');

Create a class that derives from the ModelAdvisor.EdittimeCheck abstract base class. For this example, create a class file named SignalLabel.m. Copy the code below into the SignalLabel.m file and save it to the +MyEditTimeChecks folder. For more information on the code in the ModelAdvisor.EdittimeCheck class, see Define Edit-Time Checks to Comply with Conditions that You Specify with the Model Advisor.

The blockDiscovered method contains an algorithm that defines check violations. Notice that, unlike custom checks that appear only in the Model Advisor, this algorithm does not contain the find_system function. The blockDiscovered method takes block handles as inputs and traverses the model, so you do not need the find_system function for custom edit-time checks.

For each model element that violates the check, the code creates a ModelAdvisor.ResultDetail object. For this example, because the violations are on signals, the check must use parameters on the line handles of blocks, LineHandles to find signals with violations. Specifically, for signals that connect to Outport blocks, this algorithm checks whether the Name signal parameter has a value. Then, because the violation is on a signal, the algorithm highlights the signal by creating a violation object with the Type property value set to Signal.

classdef SignalLabels < ModelAdvisor.EdittimeCheck
    methods
        function obj=SignalLabels(checkId)
            obj=obj@ModelAdvisor.EdittimeCheck(checkId);
            obj.traversalType = edittimecheck.TraversalTypes.BLKITER;                       
        end

        function violation = blockDiscovered(obj, blk)
            violation = [];
            ports    = get_param(blk,'Ports');
            lh = get_param(blk, 'LineHandles');
            if strcmp(get_param(blk,'BlockType'),'Outport')
                for j = 1 : ports(1)
                    if lh.Inport(j) ~= -1 % failure case: no connection
                        allsources = get_param(lh.Inport(j),'SrcPortHandle');
                        hiliteHandle = get_param(lh.Inport(j), 'DstPortHandle');
                        if (isempty(allsources) ~= 0) || (isempty(find(allsources==-1,1)) ~= 0)
                            lh_obj = get_param(lh.Inport(j),'Object');
                            if isempty(lh_obj.Name)
                                if strcmp(lh_obj.signalPropagation,'off') == 1
                                   allsources_parent = get_param(allsources,'Parent');
                                   if strcmp(get_param(allsources_parent,'BlockType'),'Inport')
                                        buscreator_outputs = get_param(allsources_parent,'IsBusElementPort');
                                    else
                                        buscreator_outputs = 'off';
                                    end
                                    if ~strcmp(buscreator_outputs,'on')
                                        violation = ModelAdvisor.ResultDetail;
                                        ModelAdvisor.ResultDetail.setData(violation, 'Signal',hiliteHandle);
                                        violation.Description ='This signal should have a label.';
                                        violation.CheckID = obj.checkId;
                                        violation.Title = 'Signal Label Missing';                               
                                    end
                                end
                            end
                        end
                    end
                end
            end
        end
    end       
end

To use the checks, copy the AdvisorCustomizationExample.slx model to your current working folder and open the model.

copyfile(fullfile(matlabroot,'examples','slcheck','main',...
'AdvisorCustomizationExample.slx'),'AdvisorCustomizationExample.slx','f');

Refresh the Model Advisor to update the cache with the new checks on the path.

Advisor.Manager.refresh_customizations

Open the Model Advisor Configuration Editor by clicking the Modeling tab and selecting Model Advisor > Configuration Editor.

Create a custom configuration that consists of the custom edit-time check by deleting every folder except the DEMO: Edit Time Checks folder.

Save the configuration as my_config.json. When prompted to set this configuration as the default, click No.

Close the Model Advisor Configuration Editor.

Set the custom configuration to the my_config.json file by clicking the Modeling tab and selecting Model Advisor > Edit-Time Checks. In the Configuration Parameters dialog box, specify the path to the configuration file in the Model Advisor configuration file parameter.

Turn on edit-time checking by selecting the Edit-Time Checks parameter. Close the Model Configuration Parameters dialog box.

To view the edit-time warning, click the signal highlighted in yellow. The signal connecting to the Outport block produces a warning because it does not have a label.

Version History

Introduced in R2018b