最新のリリースでは、このページがまだ翻訳されていません。 このページの最新版は英語でご覧になれます。

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

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

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

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

  1. 出荷時の設定ツリーを作成します。

  2. 出荷時の設定の JSON ファイルを作成します。

  3. 出荷時の設定ツリーをテストします。

出荷時設定ツリーの作成

ツールボックスに出荷時の設定を作成するための最初の手順は、出荷時の設定ツリーを作成することです。関数 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 用の出荷時の設定ツリーを作成します。

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

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

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

MATLAB® ではいくつかの便利な検証関数が定義されています。

名前

意味

入力で呼び出される関数

matlab.settings.mustBeStringScalar(A)

A は 1 要素の string 配列である。

isStringScalar

matlab.settings.mustBeLogicalScalar(A)

A は 1 要素の logical である。

islogical, isscalar

matlab.settings.mustBeNumericScalar(A)

A は 1 要素の数値である。

isnumeric, isscalar

matlab.settings.mustBeIntegerScalar(A)

A は 1 要素の整数である。

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' を使用して、関数ハンドルを指定します。たとえば、設定 MyLogicalSettingmyfactorysettings グループに追加し、その値が 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);

設定 MyLogicalSettingmylogicalsettings グループ内に作成し、設定の値を 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 numericValidationFcn(x)
    errorMsg = 'Value must be numeric.'; 
    assert(isnumeric(x),errorMsg);
end

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

addSetting(s.mysettings,'MyNumericSetting','ValidationFcn',@numericValidationFcn);

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

s.mysettings.MyNumericSetting.PersonalValue = 'Hello';
Unable to validate settings data. Error using myvalidationFcn (line 3)
Value must be numeric.

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

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

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

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

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

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

メモ

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

{
"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]"
}

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

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

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

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

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

メモ

予期しない結果を避けるため、設定ツリー作成関数を含むツールボックス フォルダーとツールボックス リソース フォルダーを 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>
      FactoryValue: 11

メモ

  • 関数 matlab.settings.reloadFactoryFile はデバッグ専用であり、発送されるツールボックスのコードに含めてはならない。

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

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

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

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

  1. 出荷時の設定ツリーを変更します。

  2. ツリーへの変更をログに記録します。

  3. 出荷時の設定の JSON ファイルを変更します。

  4. 個人用設定ツリーのアップグレード結果を確認します。

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

警告

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

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

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

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

メモ

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

たとえば、Version 2mytoolbox で、設定 MyFontSize および MyFontColorFontSize および 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 2mytoolbox での MyFontSizeMyFontColor に対する変更を記録します。

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

end

メモ

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

たとえば、次のコードは Version 2 と Version 3 での mytoolbox の変更を記録します。

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

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

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

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

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

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

メモ

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

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

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

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

  1. mytoolbox の出荷時の設定ツリーを再度読み込みます。

    matlab.settings.reloadFactoryFile('mytoolbox');
  2. 関数 settings を使用して設定ツリーのルートにアクセスし、FontSize 設定の個人用の値が MyFontSize 設定から正しく移されていることを確認します。ツールボックス設定にアクセスすると、個人用設定のアップグレード プロセスがトリガーされます。

    s = settings;
    s.mytoolbox.font.FontSize
    ans = 
      Setting 'mytoolbox.font.FontSize' with properties:
           ActiveValue: 15
        TemporaryValue: <no value>
         PersonalValue: 15
          FactoryValue: 11
  3. 関数 matlab.settings.loadSettingsCompatibilityResults を実行して、Version 2mytoolbox のアップグレード結果を取得します。事前検証での例外がないことを確認します。

    matlab.settings.loadSettingsCompatibilityResults('mytoolbox','Version2')
    ans = 
      ReleaseCompatibilityResults with properties:
                   VersionLabel: "Version2"
        PreValidationExceptions: [0×0 matlab.settings.ReleaseCompatibilityException]
                        Results: [1×1 matlab.settings.VersionResults]
  4. Results プロパティにアクセスして、実行されたアップグレード操作の数を判定します。

    upgradeResults.Results
    ans = 
      VersionResults with properties:
          VersionLabel: "Version2"
        VersionChanges: [1×2 matlab.settings.OperationResult]
  5. 各アップグレード操作のステータスをチェックして、それらが正常に実行されたことを確認します。

    upgradeResults.Results.VersionChanges.Status
    ans = 
        "Succeeded"
    
    ans = 
        "Succeeded"
    

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

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

  1. 関数 settings を使用して設定ツリーのルートとツールボックス設定にアクセスします。ツールボックス設定にアクセスすると、個人用設定のアップグレード プロセスがトリガーされます。

    s = settings;
    s.mytoolbox
    ans = 
      SettingsGroup 'mytoolbox' with properties:
        font: [1×1 SettingsGroup]

  2. 関数 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 はデバッグ専用であり、発送されるツールボックスのコードに含めてはなりません。

参考

| |

関連するトピック