プロパティ コールバック

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

自己インストール コールバック(プラグイン ベースのプロパティのコールバック)は、プロパティの名前(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 ではない)。 同様に、MyPlugin_OnClicked ハンドラが必要になります(MyProperty_OnClicked や 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;
}

通常、DefineLayout コールバックは、各 Softimage セッションで 1 回呼び出されます。 ただし、スクリプトでは、Softimage で DefineLayout を再度呼び出すことができます。その際、Refresh コマンド、PPG.Refresh メソッド(または XSIUtils.Reload メソッド)を使用します。 また、プロパティ ページのヘッダ バーを右クリックし、[更新](Refresh)を選択して、プロパティ ページを更新することもできます。

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

PPGEvent

C++ および C# のプロパティは、OnClicked を使用して、すべてのプロパティ ページ イベントを処理します。

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

OnClicked コールバックは、PPGEventContext または PPGEventContext オブジェクトを入力として取ります。このオブジェクトを使用することにより、イベント ID(発生したイベント: プロパティ ページのロード、パラメータの変更、ボタンのクリック、またはタブの選択)、および影響を受けるコントロール(存在する場合)にアクセスすることができます。

OnInit

スクリプト プロパティは、PPGEvent を使用して、プロパティ ページのロード時に応答します。

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

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 の呼び出しで指定されたラベルです。このラベルに含まれるスペースは除去されます。