Main Content

matlab.settings.loadSettingsCompatibilityResults

Results of upgrading personal settings of toolbox for specific version

Since R2019b

collapse all in page

Syntax

results = matlab.settings.loadSettingsCompatibilityResults(toolboxName,version)

Description

example

results = matlab.settings.loadSettingsCompatibilityResults(toolboxName,version) gets the results of upgrading the personal settings for the specified toolbox and version and returns them as a ReleaseCompatibilityResults object. This function is meant for debugging purposes only and should not be included in shipping toolbox code.

After running matlab.settings.loadSettingsCompatibilityResults, delete the log of results before running the function again. Deleting the log ensures the correct upgrade results are always loaded. The log is located in the preferences folder, in the toolboxname folder.

Examples

collapse all

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

Create the function createMyToolboxFactoryTree that 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 settings file upgrader 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 to determine whether any exceptions occurred during the upgrade and whether all upgrade operations were performed successfully.

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

Input Arguments

collapse all

Name of toolbox to get the upgrade results for, specified as a character vector or string.

Example: 'mytoolbox'

Toolbox version to get the upgrade results for, specified as a character vector or string.

Example: 'version2'

Version History

Introduced in R2019b

See Also

| |

Topics