ツールボックスの出荷時設定の作成

MathWorks^® 製品と連携して機能するツールボックスを作成する場合、インストール後にユーザーがツールボックスの外観と動作をカスタマイズするための設定を、ツールボックスに追加することができます。たとえば、ユーザーがツールボックスのフォントサイズを変更できるようにする設定を追加できます。

ツールボックスに付属する、出荷時の値を含む設定を追加するには、関数 matlab.settings.FactoryGroup.createToolboxGroup を使用して出荷時の設定を作成します。ツールボックスをインストールした後、ユーザーは出荷時の値を使用するか、あるいは個人用の値や一時的な値を独自に指定できます。

ツールボックスの出荷時の設定を作成するには、以下の手順が必要です。

出荷時の設定ツリーを作成します。
出荷時の設定の JSON ファイルを作成します。
出荷時の設定ツリーをテストします。

出荷時設定ツリーの作成

ツールボックスに出荷時の設定を作成するための最初の手順は、出荷時の設定ツリーを作成することです。関数 matlab.settings.FactoryGroup.createToolboxGroup を使用して、ツールボックス用にルートの出荷時の設定グループを作成します。たとえば、ツールボックス mytoolbox にルートの出荷時グループを作成します。既定では、出荷時グループは非表示であり、つまり、親設定グループ内には表示されません。名前と値のペア 'Hidden' に false 値を指定して、コマンドウィンドウまたはタブ補完の一部として表示されるときに、グループが出荷時の設定ツリーに表示されるようにします。

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

ツールボックスのルート出荷時グループが作成されたら、出荷時の設定と出荷時の設定グループをルートに追加して、出荷時の設定ツリーを作成します。新しい出荷時の設定グループを追加するには、関数 addGroup を使用します。名前と値のペア 'Hidden' に false 値を指定して、可視の出荷時グループを作成します。たとえば、font 出荷時グループをツールボックスのフォント設定を格納する可視のグループとして追加します。

toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)

toolboxFontGroup = 
  FactoryGroup with properties:

             Name: "font"
    ValidationFcn: []
          Hidden: 0

新しい出荷時の設定を追加するには、関数 addSetting を使用します。たとえば、FontSize を可視の出荷時の設定として font 出荷時グループに追加します。設定の出荷時の値を指定します。この値はツールボックスとともに提供されます。

addSetting(toolboxFontGroup,'FontSize','FactoryValue',11,'Hidden',false)

ans = 

  FactorySetting with properties:

               Name: "FontSize"
       FactoryValue: 11
    FactoryValueFcn: []
      ValidationFcn: []
             Hidden: 0
           ReadOnly: 0

また、名前と値のペアの引数 'ReadOnly' を使用して、読み取り専用の設定を追加することもできます。読み取り専用の設定を追加することで、ツールボックスのユーザーが設定の値を変更することを防ぎます。

出荷時の設定ツリーの作成コマンドをすべて 1 つの関数に、入力なしで配置します。その関数を、ツールボックスをパッケージ化して配布する際にツールボックスコードに含めます。たとえば、関数 createMyToolboxFactoryTree.mlx はツールボックス mytoolbox 用の出荷時の設定ツリーを作成し、出荷時グループ font と 2 つの出荷時設定 MyFontSize および MyFontColor をツリーに追加します。

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

    toolboxFontGroup = addGroup(myToolboxFactoryTree,'font','Hidden',false)
    addSetting(toolboxFontGroup,'MyFontSize','FactoryValue',11,'Hidden',false)    
    addSetting(toolboxFontGroup,'MyFontColor','FactoryValue','Black', ...
        'Hidden',false);
end

関数を使用した設定の検証

設定またはグループに検証関数を指定することにより、設定値に特定の制約を課することができます。検証関数は、設定値候補を引数として受け入れ、その値が特定の要件を満たさない場合はエラーをスローします。

MATLAB^® では、検証関数をいくつか定義しています。

名前	意味	入力で呼び出される関数
`matlab.settings.mustBeStringScalar(A)`	`A` は string スカラーでなければならない。	`isStringScalar`
`matlab.settings.mustBeLogicalScalar(A)`	`A` は logical スカラーでなければならない。	`islogical`, `isscalar`
`matlab.settings.mustBeNumericScalar(A)`	`A` は数値スカラーでなければならない。	`isnumeric`, `isscalar`
`matlab.settings.mustBeIntegerScalar(A)`	`A` は整数スカラーでなければならない。	`isinteger`, `isscalar`
`mustBePositive(A)`	`A > 0`	`gt`, `isreal`, `isnumeric`, `islogical`
`mustBeNonpositive(A)`	`A <= 0`	`ge`, `isreal`, `isnumeric`, `islogical`
`mustBeFinite(A)`	`A` には、`NaN` 要素も `Inf` 要素もない。	`isfinite`
`mustBeNonNan(A)`	`A` には `NaN` 要素がない。	`isnan`
`mustBeNonnegative(A)`	`A >= 0`	`ge`, `isreal`, `isnumeric`, `islogical`
`mustBeNegative(A)`	`A < 0`	`lt`, `isreal`, `isnumeric`, `islogical`
`mustBeNonzero(A)`	`A ~= 0`	`eq`, `isnumeric`, `islogical`
`mustBeNonempty(A)`	`A` は空ではない。	`isempty`
`mustBeNonsparse(A)`	`A` にはスパース要素がない。	`issparse`
`mustBeNumeric(A)`	`A` は数値である。	`isnumeric`
`mustBeNumericOrLogical(A)`	`A` は数値または論理値である。	`isnumeric`, `islogical`
`mustBeReal(A)`	`A` には虚数部がない。	`isreal`
`mustBeInteger(A)`	`A == floor(A)`	`isreal`, `isfinite`, `floor`, `isnumeric`, `islogical`

出荷時の設定を作成する際に検証関数を指定するには、名前と値のペアの引数 'ValidationFcn' を使用して、関数ハンドルを指定します。たとえば、設定 MyLogicalSetting を myfactorysettings グループに追加し、その値が logical スカラーでなければならないと指定します。

addSetting(s.myfactorysettings,'MyLogicalSetting','ValidationFcn', ...
    @matlab.settings.mustBeLogicalScalar);

MyLogicalSetting の値を logical 値以外に設定するよう試みます。予想どおり、MATLAB はエラーをスローします。

s.myfactorysettings.MyLogicalSetting.PersonalValue = 10

Error setting "MyLogicalSetting" in group "myfactorysettings":
Value must be logical or convertible to logical.

検証関数を出荷時の設定グループ全体に指定することも可能です。指定した関数は、グループ内で独自の検証関数が指定されていないすべての出荷時設定の値を検証するために使用されます。サブグループまたは設定で独自の検証関数を指定しない限り、これにはサブグループ内の設定も含まれます。たとえば、設定グループ mylogicalsettings を作成し、検証関数 matlab.settings.mustBeLogicalScalar を指定します。

addGroup(s.myfactorysettings,'mylogicalsettings','ValidationFcn', ...
    @matlab.settings.mustBeLogicalScalar);

設定 MyLogicalSetting を mylogicalsettings グループ内に作成し、設定の値を logical 値以外に設定するよう試みます。予想どおり、MATLAB はエラーをスローします。

addSetting(s.myfactorysettings.mylogicalsettings,'MyLogicalSetting')
s.myfactorysettings.mylogicalsettings.PersonalValue = 10;

Error setting 'MyLogicalSetting' in group 'mysettings': 
Value must be logical or convertible to logical.

カスタム検証関数の定義

MATLAB の検証関数でカバーされないプロパティについて出荷時の設定をチェックするために、独自の検証関数を作成することもできます。検証関数は、設定の値の検証を目的として設計された通常の MATLAB 関数です。それらは以下の条件を満たさなければなりません。

設定値候補を入力引数として受け入れる。
出力引数がない。
検証に失敗した場合はエラーをスローする。

検証関数を MATLAB パスに配置して、利用できるようにします。

たとえば、設定の値が偶数かどうかを検証する関数を作成します。

function evenNumberValidationFcn(x)
    errorMsg = 'Value must be an even number.';
    iseven = isnumeric(x) && mod(x, 2) == 0;
    assert(iseven,errorMsg);
end

この検証関数を新しい設定に追加します。

addSetting(s.mysettings,'MyEvenNumberSetting','ValidationFcn',@evenNumberValidationFcn);

MyEvenNumberSetting の値を奇数に設定します。予想どおり、MATLAB はエラーをスローします。

s.mysettings.MyEvenNumberSetting.PersonalValue = 1;

Unable to validate settings data. Error using evenNumberValidationFcn (line 4)
Value must be an even number.

また、mustBeGreaterThan、mustBeLessThan、mustBeGreaterThanOrEqual、mustBeLessThanOrEqual、mustBeMember など、複数の入力を必要とする MATLAB 検証関数を利用したカスタム検証関数を作成することもできます。たとえば、次の関数は、設定の値が 4 つの色のいずれかであることを検証します。

function colorValidationFcn(val) 
    mustBeMember(val, ['Black' 'Blue' 'Yellow' 'Green']); 
end

出荷時の設定または出荷時の設定グループへの検証関数の追加の詳細については、addSetting および addGroup を参照してください。

出荷時設定の JSON ファイルの作成

出荷時の設定ツリーを作成するために使用する関数を MATLAB が認識するために、settingsInfo.json という JSON ファイルを作成します。ツールボックスをパッケージ化して配布するときに、ツールボックスの resources フォルダーにこのファイルを含めます。

settingsInfo.json は次のテンプレートに従わなければなりません。要素 ToolboxGroupName および CreateTreeFcn は必須です。

{
"ToolboxGroupName" : "toolbox root factory group name",
"Hidden" : "hidden state of toolbox root factory group",
"CreateTreeFcn" : "toolbox factory tree creation function", 
"CreateUpgradersFcn" : "toolbox factory tree upgrade function"
}

メモ

ToolboxGroupName と Hidden の値は、ツールボックスのルート出荷時グループ名および非表示状態と一致しなければなりません。

たとえば、mytoolbox 用に settingsInfo.json ファイルを作成します。mytoolbox をルート設定グループ名として、false を非表示状態として、createMyToolboxFactoryTree を設定ツリー作成関数として指定します。

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

出荷時の設定ツリーのテスト

ツールボックスの設定ツリー作成関数と settingsInfo.json ファイルを作成した後、ツールボックスをパッケージ化して配布する前に、設定ツリーをテストして設定が想定どおりに機能することを確認できます。

ツリーをテストするには、設定ツリー作成関数を含むツールボックスフォルダーとツールボックスリソースフォルダーを MATLAB パスに追加します。次に、関数 matlab.settings.reloadFactoryFile を使用してツールボックスの出荷時の設定と関数 settings を読み込みます。これにより、MATLAB が設定ツリーのルートと、その下にあるツールボックス出荷時の設定ツリーにアクセスできるようになります。

メモ

予期しない結果を避けるため、設定ツリー作成関数を含むツールボックスフォルダーとツールボックスリソースフォルダーを MATLAB に追加しなければなりません。

たとえば、mytoolbox の出荷時の設定ツリーをテストする場合は次のようになります。

matlab.settings.reloadFactoryFile('mytoolbox');
s = settings;
s.mytoolbox.font.MyFontSize

ans = 
  Setting 'mytoolbox.font.MyFontSize' with properties:
       ActiveValue: 11
    TemporaryValue: <no value>
     PersonalValue: <no value>
  InstallationValue: <no value>
      FactoryValue: 11

メモ

関数 matlab.settings.reloadFactoryFile はデバッグ専用であり、発送されるツールボックスのコードに含めてはならない。
matlab.settings.reloadFactoryFile を呼び出した後、指定のツールボックスを参照する変数があれば再作成しなければならない。たとえば、変数 a = s.mytoolbox を作成してから matlab.settings.reloadFactoryFile を呼び出す場合、mytoolbox の更新後の設定にアクセスするには a を再作成しなければなりません。

複数のツールボックスバージョンにわたる下位互換性の確保

出荷時の設定ツリーに変更がある新バージョンのツールボックスを作成するために、以前インストールしたバージョンのツールボックスで構成された個人用設定が、アップグレードされた出荷時の設定ツリーに正しく移されていることを確認するよう対処することができます。

出荷時の設定ツリーに変更を加える際に下位互換性を確保するには、以下の手順に従います。

出荷時の設定ツリーを変更します。
ツリーへの変更をログに記録します。
出荷時の設定の JSON ファイルを変更します。
個人用設定ツリーのアップグレード結果を確認します。

下位非互換性の問題を引き起こす可能性がある変更には、ツールボックスの出荷時の設定や設定グループに対する名前変更、あるいはその移動や削除などが含まれます。新たな設定を出荷時の設定ツリーに追加する場合は、これらの手順に従う必要はありません。

警告

出荷時の設定ツリー作成関数に変更を加えると、対象とするツールボックスの設定の保存された個人用の値や一時的な値に影響することがあります。データ損失を避けるために、変更を加える前に、あるいはツールボックスをアップグレードする前にツールボックス設定ファイルをバックアップしてください。ツールボックス設定ファイル toolboxname.mlsettings は、基本設定フォルダー内にあります。基本設定フォルダーの絶対パスを確認するには、MATLAB コマンドウィンドウに prefdir と入力します。

アップグレードの後にツールボックス設定ツリーに予期しない変化が見られる場合は、ツールボックス設定ファイルを、作成したバックアップに置き換えることでツリーを復元できます。

出荷時の設定ツリーの変更

出荷時の設定ツリー作成関数は、最新バージョンのツールボックスの設定ツリーを作成します。最新バージョンのツールボックスに対する出荷時の設定ツリーを更新するには、出荷時の設定ツリー作成コマンドを変更します。

メモ

出荷時の設定ツリー作成関数にあるコマンドは、最新バージョンのツールボックスの設定ツリーを表します。

たとえば、Version 2 の mytoolbox で、設定 MyFontSize および MyFontColor を FontSize および FontColor に名称変更するものとします。設定名を createMyToolboxFactoryTree.mlx で変更します。

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

ツリーへの変更のログ

以前のバージョンのツールボックスから個人用の設定をアップグレードするための手順を保存するために、入力のない関数を作成します。ツールボックスをパッケージ化して配布する際に、ツールボックスのコードをもつファイルを含めます。出荷時の設定ツリーへの変更を記録することで、新しいバージョンにアップグレードするツールボックスユーザーには、既存のツールボックス設定との下位非互換性の問題がなくなります。下位非互換性の問題を引き起こす可能性がある変更には、ツールボックスの出荷時の設定や設定グループに対する名前変更、あるいはその移動や削除などが含まれます。出荷時の設定ツリーに追加する新たな設定は記録する必要はありません。

この関数で、出荷時の設定ツリーに対する変更を含む各バージョンのツールボックス用に、設定ファイルの upgrader オブジェクトを追加します。関数 move と関数 remove を使用して、個々の変更を記録します。たとえば、関数 createMyToolboxSettingsFileUpgraders.mlx は、Version 2 の mytoolbox での MyFontSize と MyFontColor に対する変更を記録します。

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

ユーザー向けにツールボックスのパッケージ化と配布を行った後に、設定ツリーアップグレード関数で記録済みのアップグレード手順を変更しないでください。手順を変更すると、予期しない結果となる可能性があります。設定ツリーに追加の変更を加える場合は、その変更を既存の手順に追加するか、または新たなアップグレーダーインスタンスを作成することでそれを記録します。

たとえば、次のコードは Version 2 と Version 3 での 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"); 

    upgraders(2) = matlab.settings.SettingsFileUpgrader('Version3');
    remove(upgraders(2),"mytoolbox.font.FontName"); 
end

出荷時設定の JSON ファイルの変更

ツールボックスの出荷時設定ツリーのアップグレードに使用する関数を MATLAB に認識させるには、出荷時設定ファイル (settingsInfo.json) で設定ツリーアップグレード関数を指定します。たとえば、mytoolbox の settingsInfo.json で、createMyToolboxSettingsFileUpgrader を設定ツリーアップグレード関数として指定します。

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

mytoolbox をパッケージ化して配布する際に、createMyToolboxFactoryTree.mlx、createMyToolboxSettingsFileUpgraders.mlx、settingsInfo.json の各ファイルを含めます。settingsInfo.json をツールボックスの resources フォルダーに配置します。

メモ

settingsInfo.json ファイルを変更した後で MATLAB を再起動しなければなりません。

個人用設定ツリーのアップグレード結果の確認

ツールボックスの個人用設定をアップグレードした後、結果を調べて、アップグレードが正しく行われたことを確かめることができます。アップグレードの結果を調べるには、関数 matlab.settings.loadSettingsCompatibilityResults を使用します。

アップグレードが正しく行われることを確認するには、ツールボックスの配布前にアップグレードの結果を調べます。たとえば、Version 2 の mytoolbox のアップグレード結果を、このツールボックスの配布前に調べます。

mytoolbox の出荷時の設定ツリーを再度読み込みます。
```
matlab.settings.reloadFactoryFile('mytoolbox');
```
関数 settings を使用して設定ツリーのルートにアクセスし、FontSize 設定の個人用の値が MyFontSize 設定から正しく移されていることを確認します。ツールボックス設定にアクセスすると、個人用設定のアップグレードプロセスがトリガーされます。
```
s = settings;
s.mytoolbox.font.FontSize
```
```
ans = 
  Setting 'mytoolbox.font.FontSize' with properties:
       ActiveValue: 15
    TemporaryValue: <no value>
     PersonalValue: 15
 InstallationValue: <no value>
      FactoryValue: 11
```

関数 matlab.settings.loadSettingsCompatibilityResults を実行して、Version 2 の mytoolbox のアップグレード結果を取得します。事前検証での例外がないことを確認します。

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

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

Results プロパティにアクセスして、実行されたアップグレード操作の数を判定します。

upgradeResults.Results

ans = 
  VersionResults with properties:
      VersionLabel: "Version2"
    VersionChanges: [1×2 matlab.settings.OperationResult]

各アップグレード操作のステータスをチェックして、それらが正常に実行されたことを確認します。
```
upgradeResults.Results.VersionChanges.Status
```
```
ans = 
    "Succeeded"

ans = 
    "Succeeded"
```

新バージョンのツールボックスをインストールした後に、アップグレード結果を調べることもできます。この方法は、たとえば、アップグレード後にツールボックス設定をトラブルシューティングするツールボックスユーザーに対しサポートを行っている場合に便利です。

たとえば、Version 1 の mytoolbox がインストールされていて、いくつかの設定に個人用の値が設定されているとします。Version 2 の mytoolbox をインストールした後に、アップグレード結果を調べて、個人設定が正しく移動したことを確認します。

関数 settings を使用して設定ツリーのルートとツールボックス設定にアクセスします。ツールボックス設定にアクセスすると、個人用設定のアップグレードプロセスがトリガーされます。
```
s = settings;
s.mytoolbox
```
```
ans = 
  SettingsGroup 'mytoolbox' with properties:
    font: [1×1 SettingsGroup]
```
関数 matlab.settings.loadSettingsCompatibilityResults を実行して、アップグレード結果を取得します。実行された各アップグレード操作のステータスをチェックして、正常に実行されたことを確認します。
```
upgradeResults = matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2');
upgradeResults.Results.VersionChanges.Status
```
```
ans = 
    "Succeeded"

ans = 
    "Succeeded"
```

メモ

関数 matlab.settings.reloadFactoryFile と関数 matlab.settings.loadSettingsCompatibilityResults の実行後、これらの関数を再度実行する前に、結果のログを削除します。ログを削除することで、正しいアップグレード結果が常に読み込まれるようになります。ログは基本設定フォルダーの toolboxname フォルダー内にあります。
関数 matlab.settings.reloadFactoryFile と関数 matlab.settings.loadSettingsCompatibilityResults はデバッグ専用であり、発送されるツールボックスのコードに含めてはなりません。

ツールボックスの設定変更のリスニング

ツールボックスのユーザーによって変更される設定をツールボックスに追加する場合、ツールボックスがその変更に反応できるように、設定値が変化したときに検出する設定リスナーを作成できます。設定リスナーを作成するには、関数 addlistener を使用します。

たとえば、mytoolbox.font.FontSize 設定の設定リスナーを作成します。

s = settings;
settingListener = addlistener(s.mytoolbox.font,'FontSize','PostSet', ...
    @(src,evnt)disp('Font size changed'));

FontSize 設定の値を 12 に設定します。この値を設定すると、設定に関する PostSet イベントがトリガーされます。

s.mytoolbox.font.FontSize.PersonalValue = 12;

Font size changed

参考

matlab.settings.reloadFactoryFile | matlab.settings.loadSettingsCompatibilityResults | matlab.settings.FactoryGroup.createToolboxGroup