プロパティコールバック

コールバック関数の名前付け

自己インストールされるコールバック(プラグインベースのプロパティのコールバック)は、プロパティの名前を使用して名前が付けられます。たとえば、MyProperty_DefineLayout や MyProperty_MyButton_OnClicked の場合、MyProperty が PluginRegistrar.RegisterProperty や PluginRegistrar::RegisterProperty の呼び出しで使用される名前になります。

一方、処理中のプロパティ(ランタイムベースのプロパティ)はコールバック名にプロパティ名を使用しないため、たとえば PPGEvent コールバックは単純に PPGEvent と命名され、ボタンの OnClicked コールバックは MyButton_OnClicked という名前になります。

プラグインベースのプロパティとランタイムベースのプロパティの両方で、プリフィックスを使用することができます。プリフィックスは、単一のファイル内で複数のイベントハンドラを区別するためのネームスペースです。この場合、siUILogicPrefix レイアウト属性を設定することによってプリフィックスを指定できます。指定したプリフィックスは PPGLayout.Logic または PPGLayout::GetLogic のすべてのハンドラで必要になります。

たとえば、プリフィックスが MyPlugin_ の場合、Softimage では MyPlugin_PPGEvent という名前のハンドラが必要になります(MyProperty_PPGEvent や、単純に PPGEvent ではなく)。同様に、MyProperty_OnClicked や OnClicked のみでなく、MyPlugin_OnClicked ハンドラが必要になります。

注:

プリフィックスやイベントハンドラの命名規則に関する SPDL ベースのプロパティ、ランタイムのプロパティ、プラグインのプロパティについては、「カスタムプロパティとともにプリフィックスを使用する」を参照してください。このセクションには、ランタイムベースのプロパティおよびプラグイン(自己インストール)プロパティのロジックプリフィックスの指定方法に関する例が記載されています。

Define

DefineLayout コールバックでは、カスタムプロパティにパラメータを追加します。Define コールバックは、Context または Context オブジェクトを入力として取得します。この入力から、CustomProperty または CustomProperty オブジェクトを取得することができます。CustomProperty または CustomProperty オブジェクトは、次のパラメータを追加するメソッドを提供します。

CustomProperty.AddParameter3 または CustomProperty::AddParameter、(オブジェクトモデルのみの場合、AddParameter2 および AddParameter3)
CustomProperty.AddFCurveParameter または CustomProperty::AddFCurveParameter
CustomProperty.AddGridParameter または CustomProperty::AddGridParameter
CustomProperty.AddProxyParameter または CustomProperty::AddProxyParameter
CustomProperty.AddParameterFromDef または CustomProperty::AddParameterFromDef

// JScript code generated by the wizard
function MyJsProperty_Define( ctxt )
{
	var oCustomProperty;
	oCustomProperty = ctxt.Source;
	oCustomProperty.AddParameter2("Param",siInt4,0,0,100,0,100,0,siPersistable);

	return true;
}

// C++ code generated by the wizard
XSIPLUGINCALLBACK CStatus MyCppProperty_Define( CRef& in_ctxt )
{
	Context ctxt( in_ctxt );
	CustomProperty oCustomProperty;
	Parameter oParam;
	oCustomProperty = ctxt.GetSource();

	oCustomProperty.AddParameter(L"Param",CValue::siInt4,siPersistable,L"",L"",0l,0l,100l,0l,100l,oParam);
	return CStatus::OK;
}

DefineLayout

DefineLayout コールバックは、自己インストールカスタムプロパティ用のプロパティページにおけるコントロールのレイアウトを定義します。DefineLayout コールバックは、Context または Context オブジェクトを入力として取得します。この入力から、PPGLayout または PPGLayout オブジェクトを取得することができます。PPGLayout または PPGLayout オブジェクトは、コントロールを追加およびグループ化するメソッドを提供します。

// JScript code generated by the wizard
function MyProperty_DefineLayout( ctxt )
{
	var oLayout,oItem;
	oLayout = ctxt.Source;
	oLayout.Clear();
	oLayout.AddTab(" Plug-in Info");
	oLayout.AddGroup(" ");
	oLayout.AddItem("Property_Name", "Property Name");
	oLayout.AddItem("Author");
	oLayout.AddItem("Script_Language");
	oLayout.AddItem("Add_to_Menu");
	oLayout.EndGroup();
	oLayout.AddTab("Add Parameter");
	oLayout.AddItem("ParamType");
	return true;
}

通常は、Softimage セッションごとに一度ずつ DefineLayout コールバックが呼び出されます。ただし、PPG.Refresh メソッドまたは XSIUtils.Reload メソッドの Refresh コマンドを使用して、強制的に DefineLayout を再び呼び出すこともできます。また、プロパティページのヘッダバーを右クリックし、[更新]を選択して、プロパティページを更新することもできます。

レイアウトを定義する前には常に PPGLayout.Clear または PPGLayout::Clear を呼び出す必要があります。呼び出さない場合、DefineLayout が呼び出されるたびに既存のレイアウトに新しいコントロールのセットが追加されます。

PPGEvent

C++ プロパティおよび C# プロパティは、あらゆるプロパティページイベントを、OnClicked を使用して扱います。

OnClicked が起動されるのは、プロパティページが開いたとき、パラメータ値が変更されたとき、またはユーザがボタンまたはタブをクリックしたときです。

OnClicked コールバックは、PPGEventContext または PPGEventContext オブジェクトを入力値として取得します。これにより、イベント ID (プロパティページのロード、パラメータの変更、ボタンのクリック、タブの選択などのうち、どのイベントが起動されたかを判別する)およびエフェクトコントロール(存在する場合)へのアクセスが可能になります。

OnInit

スクリプトプロパティは、プロパティページがロードされたときに、PPGEvent を使用して応答します。

PPGEvent コールバックには、ロードを行う前にプロパティページを初期化するために実行するコードを含めることができます。たとえば、特定のパラメータの値によってレイアウトに含まれるコントロールが決定する場合、DefineLayout ではなく PPGEvent でレイアウトを定義しておきます。

OnChanged

スクリプトプロパティは、OnChanged を使用してパラメータ値への変更を処理します。

パラメータの値を変更するたびに、そのパラメータ用の OnChanged イベントが起動されます。これらのイベントをトラップして使用すれば、さまざまなタスクを実行できます。たとえば、新しい値を有効にする場合もあります。

次の規則を使用するコールバックの内部に、ハンドラコードを実装できます。

function <prefix-name>_<parameter-name>_OnChanged() {
	// Implement the handler here
}

注:既定では、プラグインベースのカスタムプロパティはカスタムプロパティの名前をプリフィックスとして使用します。一方、ランタイムおよび SPDL ベースのカスタムプロパティは既定でプリフィックスを使用しません。詳細については、「カスタムプロパティとともにプリフィックスを使用する」を参照してください。

OnClicked

スクリプトプロパティは、OnClicked を使用してボタンイベントを処理します。

各コマンドボタンは、独自の OnClicked コールバックでボタンにコードを関連付けます。次の規則を使用するコールバックの内部に、ハンドラを記述する必要があります。

function <prefix-name>_<button-name>_OnClicked()
{
	// Implement the handler here
}

ここで、<button-name>は AddButton の呼び出しで指定された名前です。この名前に含まれるスペースは削除されます。

注:

既定では、プラグインベースのカスタムプロパティはカスタムプロパティの名前をプリフィックスとして使用します。一方、ランタイムおよび SPDL ベースのカスタムプロパティは既定でプリフィックスを使用しません。詳細については、「カスタムプロパティとともにプリフィックスを使用する」を参照してください。

OnTab

スクリプトプロパティは、OnTab を使用してタブイベントを処理します。

ユーザがタブをクリックすると、OnTab コールバックが起動します。次の規則を使用するコールバックの内部に、ハンドラを記述する必要があります。

function <prefix-name>_<tab-label>_OnTab()
{
	// Implement the handler here
}

ここで、<tab-label>は PPGLayout.AddTab または PPGLayout::AddTab の呼び出しで指定されたラベルです。このラベルに含まれるスペースは削除されます。

注:

既定では、プラグインベースのカスタムプロパティはカスタムプロパティの名前をプリフィックスとして使用します。一方、ランタイムおよび SPDL ベースのカスタムプロパティは既定でプリフィックスを使用しません。詳細については、「カスタムプロパティとともにプリフィックスを使用する」を参照してください。

GridData イベント

次のイベントは GridData オブジェクト用です。

OnBeginValueChange – 修正をグリッドデータパラメータに適用する前に発生します。次の規則を使用するコールバックの内部に、ハンドラを記述する必要があります。
```
function <property_name>_<parameter_name>_OnBeginValueChange()
{ 
 // Implement the handler here
}
```
OnEndValueChange – 修正をグリッドデータパラメータに適用した後に発生します。次の規則を使用するコールバックの内部に、ハンドラを記述する必要があります。
```
function <property_name>_<parameter_name>_OnEndValueChange()
{ 
 // Implement the handler here 
}
```
OnBeginSelectionChange – グリッドデータパラメータに関連付けられたグリッドウィジェットに対する選択の変更を適用する前に発生します。次の規則を使用するコールバックの内部に、ハンドラを記述する必要があります。
```
function <property_name>_<parameter_name>_OnBeginSelectionChange()
{
 // Implement the handler here
}
```
OnEndSelectionChange – グリッドデータパラメータに関連付けられたグリッドウィジェットに対する選択の変更を適用した後に発生します。次の規則を使用するコールバックの内部に、ハンドラを記述する必要があります。
```
function <property_name>_<parameter_name>_OnEndSelectionChange()
{
 // Implement the handler here
}
```
OnButtonClicked – グリッドデータパラメータに関連付けられたグリッドウィジェットでボタンがクリックされたときに発生します。次の規則を使用するコールバックの内部に、ハンドラを記述する必要があります。
```
function <property_name>_<parameter_name>_OnButtonClicked()
{
 // Implement the handler here
}
```
OnHeaderDoubleClick – グリッドデータパラメータに関連付けられたグリッドウィジェットでヘッダがダブルクリックされたときに発生します。次の規則を使用するコールバックの内部に、ハンドラを記述する必要があります。
```
function <property_name>_<parameter_name>_OnHeaderDoubleClick()
{
 // Implement the handler here
}
```
OnContextMenuInit – グリッドデータパラメータに関連付けられたグリッドウィジェット上でマウスが右クリックされたときに発生します。コールバックがコンテキストメニューの定義を戻り値の文字列/Long ペアとして返す必要があります。次の規則を使用するコールバックの内部に、ハンドラを記述する必要があります。
```
function <property_name>_<parameter_name>_OnContextMenuInit()
{
 // Implement the handler here
}
```
OnContextMenuSelected – グリッドデータパラメータに関連付けられたグリッドウィジェットでコンテキストメニュー項目が選択されたときに発生します。次の規則を使用するコールバックの内部に、ハンドラを記述する必要があります。
```
function <property_name>_<parameter_name>_OnContextMenuSelected()
{
 // Implement the handler here
}
```

注:

これらすべての GridData イベントで、

<property_name>は、 PluginRegistrar.RegisterProperty の呼び出しで指定されている名前です。名前にスペースが含まれていればアンダースコアに置き換えられます。
<parameter_name>は、 CustomProperty.AddGridParameter の呼び出しで指定されている名前です。名前にスペースが含まれていればアンダースコアに置き換えられます。

詳細については、GridData のサンプルを参照してください。このサンプルは、Softimage SDK のインストールフォルダにある examples フォルダにあります。

プロパティ コールバック