ツールボックスの出荷時設定の作成- MATLAB和Sim金宝appulink MathWorks日本

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

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

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

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

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

出荷時設定ツリーの作成

ツールボックスに出荷時の設定を作成するための最初の手順は,出荷時の設定ツリーを作成することです。関数matlab.settings.FactoryGroup.createToolboxGroupを使用して,ツールボックス用にルートの出荷時の設定グループを作成します。たとえば,ツールボックスmytoolboxにルートの出荷時グループを作成します。既定では,出荷時グループは非表示であり,つまり,親設定グループ内には表示されません。名前と値のペア“隐藏”に假値を指定して,グループが出荷時の設定ツリーに必ず表示されるようにします。

myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup (“mytoolbox”，“隐藏”、假);

ツールボックスのルート出荷時グループが作成されたら,出荷時の設定と出荷時の設定グループをルートに追加して,出荷時の設定ツリーを作成します。

新しい出荷時の設定グループを追加するには,関数addGroupを使用します。名前と値のペア“隐藏”に假値を指定して,可視の出荷時グループを作成します。たとえば,字体出荷時グループを可視のグループとして追加します。

toolboxFontGroup = addGroup (myToolboxFactoryTree,“字体”，“隐藏”假)

ValidationFcn:[]隐藏:0

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

addSetting (toolboxFontGroup“字形大小”，“FactoryValue”11“隐藏”假)

ans = FactorySetting with properties: Name: "FontSize" FactoryValue: 11 FactoryValueFcn: [] ValidationFcn: [] Hidden: 0 ReadOnly: 0

また,名前と値のペアの引数“只读”を使用して,読み取り専用の設定を追加することもできます。読み取り専用の設定を追加することで,ツールボックスのユーザーが設定に一時的な値や個人用の値を指定して設定の値を変更することを防ぎます。

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

函数myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup()“mytoolbox”，．..“隐藏”、假);toolboxFontGroup = addGroup (myToolboxFactoryTree,“字体”，“隐藏”假)addSetting (toolboxFontGroup“MyFontSize”，“FactoryValue”11“隐藏”假的,．..“ValidationFcn”@matlab.settings.mustBeNumericScalar) addSetting (toolboxFontGroup“MyFontColor”，“FactoryValue”，“黑”，．..“隐藏”假的,“ValidationFcn”, @matlab.settings.mustBeStringScalar);结束

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

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

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

名前	意味	入力で呼び出される関数
`matlab.settings.mustBeStringScalar(一)`	`一个`は1要素の字符串配列である。	`isStringScalar`
`matlab.settings.mustBeLogicalScalar(一)`	`一个`は1要素の逻辑である。	`islogical`，`isscalar`
`matlab.settings.mustBeNumericScalar(一)`	`一个`は1要素の数値である。	`isnumeric`，`isscalar`
`matlab.settings.mustBeIntegerScalar(一)`	`一个`は1要素の整数である。	`isinteger`，`isscalar`
`mustBePositive(一)`	`> 0`	`gt`，`伊斯雷尔`，`isnumeric`，`islogical`
`mustBeNonpositive(一)`	`< = 0`	`通用电气`，`伊斯雷尔`，`isnumeric`，`islogical`
`mustBeFinite(一)`	`一个`には,`南`要素も`正`要素もない。	`isfinite`
`mustBeNonNan(一)`	`一个`には`南`要素がない。	`isnan`
`mustBeNonnegative(一)`	`> = 0`	`通用电气`，`伊斯雷尔`，`isnumeric`，`islogical`
`mustBeNegative(一)`	`< 0`	`lt`，`伊斯雷尔`，`isnumeric`，`islogical`
`mustBeNonzero(一)`	`~ = 0`	`情商`，`isnumeric`，`islogical`
`mustBeNonempty(一)`	`一个`は空ではない。	`isempty`
`mustBeNonsparse(一)`	`一个`にはスパース要素がない。	`issparse`
`mustBeNumeric(一)`	`一个`は数値である。	`isnumeric`
`mustBeNumericOrLogical(一)`	`一个`は数値または論理値である。	`isnumeric`，`islogical`
`mustBeReal(一)`	`一个`には虚数部がない。	`伊斯雷尔`
`mustBeInteger(一)`	`= =地板(A)`	`伊斯雷尔`，`isfinite`，`地板上`，`isnumeric`，`islogical`

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

addSetting (s.myfactorysettings“MyLogicalSetting”，“ValidationFcn”，．..@matlab.settings.mustBeLogicalScalar);

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

s.myfactorysettings.MyLogicalSetting.PersonalValue = 10

在组“myfactorysettings”中设置“MyLogicalSetting”时出错:Value必须是逻辑的或可转换为逻辑的。

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

addGroup (s.myfactorysettings“mylogicalsettings”，“ValidationFcn”，．..@matlab.settings.mustBeLogicalScalar);

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

addSetting (s.myfactorysettings.mylogicalsettings“MyLogicalSetting”) .myfactorysettings.mylogicalsettings. personalvalue = 10;

在组“mysettings”中设置“MyLogicalSetting”时出错:值必须是逻辑的或可转换为逻辑的。

カスタム検証関数の定義

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

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

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

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

函数numericValidationFcn (x) errorMsg =“值必须是数字。”；断言(isnumeric (x), errorMsg);结束

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

addSetting (s.mysettings“MyNumericSetting”，“ValidationFcn”, @numericValidationFcn);

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

s.mysettings.MyNumericSetting.PersonalValue =“你好”；

无法验证设置数据。错误使用myvalidationFcn(第3行)值必须是数字。

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

函数colorValidationFcn (val) mustBeMember (val, (“黑”“蓝”“黄色”“绿色”]）;结束

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

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

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

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

メモ

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

{"ToolboxGroupName": "[工具箱根工厂组名称]"，"Hidden": "[工具箱根工厂组隐藏状态]"，"CreateTreeFcn": "[工具箱工厂树创建函数]"，"CreateUpgradersFcn": "[工具箱工厂树升级函数]"}

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

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

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

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

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

メモ

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

たとえば,mytoolboxの出荷時の設定ツリーをテストするには,次のコードを実行できます。

matlab.settings.reloadFactoryFile (“mytoolbox”）;s =设置;s.mytoolbox.font.MyFontSize

设置mytoolbox.font。MyFontSize' with properties: ActiveValue: 11 TemporaryValue:  PersonalValue:  FactoryValue: 11

メモ

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

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

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

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

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

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

警告

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

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

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

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

メモ

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

たとえば,版本2のmytoolboxで,設定MyFontSizeおよびMyFontColorを字形大小およびFontColorに名称変更するものとします。設定名をcreateMyToolboxFactoryTree.mlxで変更します。

函数myToolboxFactoryTree = matlab.settings.FactoryGroup.createToolboxGroup()“mytoolbox”，．..“隐藏”、假);toolboxFontGroup = addGroup (myToolboxFactoryTree,“字体”，“隐藏”假)addSetting (toolboxFontGroup“字形大小”，“FactoryValue”11“隐藏”假的,．..“ValidationFcn”@matlab.settings.mustBeNumericScalar) addSetting (toolboxFontGroup“FontColor”，“FactoryValue”，“黑”，．..“隐藏”假的,“ValidationFcn”, @matlab.settings.mustBeStringScalar);结束

ツリーへの変更のログ

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

この関数で,出荷時の設定ツリーに対する変更を含む各バージョンのツールボックス用に,設定ファイルの升级程序オブジェクトを追加します。関数移动と関数删除を使用して,個々の変更を記録します。たとえば,関数createMyToolboxSettingsFileUpgraders.mlxは,版本2のmytoolboxでのMyFontSizeとMyFontColorに対する変更を記録します。

函数updater = matlab.settings.SettingsFileUpgrader()“Version2”）;移动(升级,“mytoolbox.font.MyFontSize”，“mytoolbox.font.FontSize”）;移动(升级,“mytoolbox.font.MyFontColor”，“mytoolbox.font.FontColor”）;结束

メモ

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

たとえば,次のコードは版本2と版本3.でのmytoolboxの変更を記録します。

函数updater = matlab.settings.SettingsFileUpgrader()“Version2”）;移动(升级,“mytoolbox.font.MyFontSize”，“mytoolbox.font.FontSize”）;移动(升级,“mytoolbox.font.MyFontColor”，“mytoolbox.font.FontColor”）;升级(2)= matlab.settings.SettingsFileUpgrader (“Version3”）;remove(升级(2),“mytoolbox.font.FontName”）;结束

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

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

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

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

メモ

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

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

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

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

mytoolboxの出荷時の設定ツリーを再度読み込みます。
```
matlab.settings.reloadFactoryFile (“mytoolbox”）;
```
関数设置を使用して設定ツリーのルートにアクセスし,字形大小設定の個人用の値がMyFontSize設定から正しく移されていることを確認します。ツールボックス設定にアクセスすると,個人用設定のアップグレードプロセスがトリガーされます。
```
s =设置;s.mytoolbox.font.FontSize
```
```
设置mytoolbox.font。字形大小' with properties: ActiveValue: 15 TemporaryValue:  PersonalValue: 15 FactoryValue: 11
```
関数matlab.settings.loadSettingsCompatibilityResultsを実行して,版本2のmytoolboxのアップグレード結果を取得します。事前検証での例外がないことを確認します。
```
matlab.settings.loadSettingsCompatibilityResults (“mytoolbox”，“Version2”）
```
```
ans = ReleaseCompatibilityResults with properties:结果:[1×1 matlab.settings.VersionResults]
```
结果プロパティにアクセスして,実行されたアップグレード操作の数を判定します。
```
upgradeResults。结果
```
```
ans = VersionResults with properties: VersionLabel: "Version2"
```
各アップグレード操作のステータスをチェックして,それらが正常に実行されたことを確認します。
```
upgradeResults.Results.VersionChanges.Status
```
```
ans = "成功" ans = "成功"
```

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

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

関数设置を使用して設定ツリーのルートとツールボックス設定にアクセスします。ツールボックス設定にアクセスすると,個人用設定のアップグレードプロセスがトリガーされます。
```
s =设置;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 = "成功" ans = "成功"
```

メモ

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

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

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

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

s =设置;settingListener = addlistener (s.mytoolbox.font,“字形大小”，“PostSet”，．..@ (src, evnt) disp (的字体大小改变））;

字形大小設定の値を12に設定します。この値を設定すると,設定に関するPostSetイベントがトリガーされます。

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

字体大小改变

参考

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