Property Callbacks

Naming Callback Functions

Self-installed callbacks (callbacks for plug-in based properties) are named using the name of the property (for example, MyProperty_DefineLayout or MyProperty_MyButton_OnClicked, where MyProperty is the name used in the call to PluginRegistrar.RegisterProperty or PluginRegistrar::RegisterProperty).

On-the-fly properties (runtime-based properties), on the other hand, do not use the property name in the callback name, so for example the PPGEvent callback would be named simply PPGEvent , and the OnClicked callback for a button would be named MyButton_OnClicked.

For both plug-in based and runtime propertoes, you may want to use a prefix, which is a namespace that helps differentiate between multiple event handlers in a single file. In this case you can specify a prefix by setting the siUILogicPrefix layout attribute. The specified prefix will then be expected on all handlers in the PPGLayout.Logic or PPGLayout::GetLogic.

For example, if the prefix is MyPlugin_ then Softimage expects a handler named MyPlugin_PPGEvent rather than MyProperty_PPGEvent or just plain PPGEvent . Similarly, the MyPlugin_OnClicked handler will be expected rather than MyProperty_OnClicked or OnClicked only.

Define

The DefineLayout callback is where you add parameters to the custom property. The Define callback gets a Context or Context object as input, from which you can get the CustomProperty or CustomProperty object. The CustomProperty or CustomProperty object provides methods for adding parameters:

• CustomProperty.AddParameter3 or CustomProperty::AddParameter, (and for the object model only, AddParameter2 and AddParameter3)

• CustomProperty.AddFCurveParameter or CustomProperty::AddFCurveParameter

• CustomProperty.AddGridParameter or CustomProperty::AddGridParameter

• CustomProperty.AddProxyParameter or CustomProperty::AddProxyParameter

• CustomProperty.AddParameterFromDef or 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

The DefineLayout callback defines the layout of controls on the property page for a self-installing custom property. The DefineLayout callback gets a Context or Context object as input, from which you can get the PPGLayout or PPGLayout object. The PPGLayout or PPGLayout object provides methods for adding and grouping controls.

// 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;
}

Typically, the DefineLayout callback is called once per Softimage session. However, in scripting you can force Softimage to call DefineLayout again using the Refresh command, the PPG.Refresh method (or the XSIUtils.Reload method). Users can also refresh a property page by right-clicking the header bar of a property page and choosing Refresh.

For this reason, you should always call PPGLayout.Clear or PPGLayout::Clear before you define the layout. Otherwise, a new set of controls would be appended to the existing layout everytime DefineLayout was called.

PPGEvent

C++ and C# properties use OnClicked to handle all property page events.

OnClicked is fired when the property page is opened, when a parameter value is changed, and when a user clicks a button or tab.

The OnClicked callback takes the PPGEventContext or PPGEventContext object as input which allows access to the event ID (which event was fired: property page loaded, parameter change, button click, or tab selection) and the effected control, if any.

OnInit

Scripted properties use PPGEvent to respond when the property page loads.

The PPGEvent callback can contain any code you want to run to initialize the property page before loading. For example, if the values of certain parameters determine which controls are included in the layout, you can define the layout in PPGEvent, instead of in DefineLayout.

OnChanged

Scripted properties use OnChanged to handle changes to parameter values.

Each time the value of a parameter changes, the OnChanged event for that parameter is fired. You can trap those events and use them to perform a variety of tasks. For example, you may want to validate the new value.

You implement the handler code inside a callback that uses the following convention:

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

OnClicked

Scripted properties use OnClicked to handle button events.

Each Command Button has its own OnClicked callback to associate the code to the button. Therefore, you need to write your handler inside a callback that uses the following convention:

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

where <button-name> is the name specified in the call to AddButton, with any spaces removed.

OnTab

Scripted properties use OnTab to handle tab events.

The OnTab callback is fired when the user clicks a tab. Write your handler inside a callback that uses the following convention:

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

where <tab-label> is the label specified in the call to PPGLayout.AddTab or PPGLayout::AddTab, with any spaces removed.