プロパティ コールバック

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

自己インストール コールバック(プラグイン ベースのプロパティのコールバック)に名前を付ける場合は、プロパティの名前(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 ハンドラが必要になります。

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 を呼び出す必要があります。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
}

OnClicked

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

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

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

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

OnTab

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

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

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

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