ReleaseCompatibilityResults

Results of upgrading toolbox with specific version number

expand all in page

Description

A ReleaseCompatibilityResults object represents the results of upgrading the personal settings of a toolbox for a specific version number.

Creation

Create a ReleaseCompatibilityResults object for a specific toolbox version number by using the matlab.settings.loadSettingsCompatibilityResults function. For example, this command gets the ReleaseCompatibilityResults object for version 2 of the toolbox mytoolbox.

myCompatibilityResults = matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2')

ans = 
  ReleaseCompatibilityResults with properties:
               VersionLabel: "Version2"
    PreValidationExceptions: [0×0 matlab.settings.ReleaseCompatibilityException]
                    Results: [1×1 matlab.settings.VersionResults]

Properties

expand all

Version toolbox is being upgraded to, specified as a string scalar.

Example: 'Version2'

First prevalidation exception, specified as a ReleaseCompatibilityException object. PreValidationExceptions is the first exception that occurs while validating the personal and factory settings trees before upgrading the personal settings. If no exception occurs, PreValidationExceptions is a 0-by-0 array of ReleaseCompatibilityException objects.

Upgrade results, specified as an array of VersionResults objects.

Examples

collapse all

Create functions to create and then upgrade a toolbox factory tree and then test that the upgrade completes successfully.

The function createMyToolboxFactoryTree creates the factory settings tree for the toolbox mytoolbox.

function myToolboxFactoryTree = createMyToolboxFactoryTree()
    myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup('mytoolbox', ...
        'Hidden',false);

    toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)
    addSetting(toolboxFontGroup,'MyFontSize','FactoryValue',11,'Hidden',false, ...
        'ValidationFcn',@matlab.settings.mustBeNumericScalar)    
    addSetting(toolboxFontGroup,'MyFontColor','FactoryValue','Black', ...
        'Hidden',false,'ValidationFcn',@matlab.settings.mustBeStringScalar);
end

Create the function createMyToolboxSettingsFileUpgraders with an empty matlab.settings.SettingsFileUpgrader object.

function upgraders = createMyToolboxSettingsFileUpgraders()
    upgraders = matlab.settings.SettingsFileUpgrader.empty;
end

Create the settingsInfo.json file for the toolbox. Specify mytoolbox as the root settings group name, createMyToolboxFactoryTree as the settings tree creation function, and createMyToolboxSettingsFileUpgraders as the settings tree upgrade function. Place settingsInfo.json in the toolbox resources folder.

{
"ToolboxGroupName" : "mytoolbox",
"Hidden" : false,
"CreateTreeFcn" : "createMyToolboxFactoryTree",
"CreateUpgradersFcn" : "createMyToolboxSettingsFileUpgraders"
}

Add the folder that contains the settings tree creation function and the toolbox resources folder to the MATLAB® path. Then, load the factory settings tree for mytoolbox.

matlab.settings.reloadFactoryFile('mytoolbox');

Use the settings function to access the root of the settings tree and set the personal value for the MyFontSize setting.

s = settings;
s.mytoolbox.font.MyFontSize.PersonalValue = 15;

Change the settings names in createMyToolboxFactoryTree from MyFontSize and MyFontColor to FontSize and FontColor.

function myToolboxFactoryTree = createMyToolboxFactoryTree()
    myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup('mytoolbox', ...
        'Hidden',false);

    toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)
    addSetting(toolboxFontGroup,'FontSize','FactoryValue',11,'Hidden',false, ...
        'ValidationFcn',@matlab.settings.mustBeNumericScalar)    
    addSetting(toolboxFontGroup,'FontColor','FactoryValue','Black', ...
        'Hidden',false,'ValidationFcn',@matlab.settings.mustBeStringScalar);
end

Record the rename of the two settings in the createMyToolboxSettingsFileUpgraders function as changes to the settings tree for version 2 of mytoolbox.

function upgraders = createMyToolboxSettingsFileUpgraders()
    upgraders = matlab.settings.SettingsFileUpgrader('Version2'); 
    move(upgraders,'mytoolbox.font.MyFontSize','mytoolbox.font.FontSize'); 
    move(upgraders,'mytoolbox.font.MyFontColor','mytoolbox.font.FontColor');
end

Reload the factory settings tree for mytoolbox.

matlab.settings.reloadFactoryFile('mytoolbox');

Use the settings function to access the root of the settings tree and verify that the personal value for the FontSize setting was correctly moved from the MyFontSize setting.

s = settings;
s.mytoolbox.font.FontSize
ans = 
  Setting 'mytoolbox.font.FontSize' with properties:
       ActiveValue: 15
    TemporaryValue: <no value>
     PersonalValue: 15
      FactoryValue: 11

Get the upgrade results for version 2 of mytoolbox.

matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2')
ans = 
  ReleaseCompatibilityResults with properties:
               VersionLabel: "Version2"
    PreValidationExceptions: [0×0 matlab.settings.ReleaseCompatibilityException]
                    Results: [1×1 matlab.settings.VersionResults]

Version History

Introduced in R2019b

See Also

| |

Topics