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 properties, you might 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. You can also refresh a property page by right-clicking the header bar of a property page and choosing Refresh.

You should always call PPGLayout.Clear or PPGLayout::Clear before you define the layout. Otherwise, a new set of controls is appended to the existing layout each time DefineLayout is called.

PPGEvent

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

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

The PPGEvent callback takes the PPGEventContext or PPGEventContext object as input, which allows access to the event ID (event such as, 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 might want to validate a new value.

You can 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
}

Here, <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
}

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

GridData Events

The following events are for the GridData object.

• OnBeginValueChange – Fired before applying modifications to a grid data parameter. Write your handler inside a callback that uses the following convention:

  function <property_name>_<parameter_name>_OnBeginValueChange()
  { 
   // Implement the handler here
  }

• OnEndValueChange – Fired after modifications have been applied to a grid data parameter. Write your handler inside a callback that uses the following convention:

  function <property_name>_<parameter_name>_OnEndValueChange()
  { 
   // Implement the handler here 
  }
  

• OnBeginSelectionChange – Fired before applying a selection change to a grid widget that is associated with a grid data parameter. Write your handler inside a callback that uses the following convention:

  function <property_name>_<parameter_name>_OnBeginSelectionChange()
  {
   // Implement the handler here
  }
  

• OnEndSelectionChange – Fired after a selection change is applied to a grid widget that is associated with a grid data parameter. Write your handler inside a callback that uses the following convention:

  function <property_name>_<parameter_name>_OnEndSelectionChange()
  {
   // Implement the handler here
  }
  

• OnButtonClicked – Fired when a button gets clicked in a grid widget associated with a grid data parameter. Write your handler inside a callback that uses the following convention:

  function <property_name>_<parameter_name>_OnButtonClicked()
  {
   // Implement the handler here
  }
  

• OnHeaderDoubleClick – Fired when a header gets double-clicked in a grid widget associated with a grid data parameter. Write your handler inside a callback that uses the following convention:

  function <property_name>_<parameter_name>_OnHeaderDoubleClick()
  {
   // Implement the handler here
  }
  

• OnContextMenuInit – Fired when a mouse is right-clicked over a grid widget that is associated with a grid data parameter. The callback must return the contextual menu definition as String/Long pairs in a return value. Write your handler inside a callback that uses the following convention:

  function <property_name>_<parameter_name>_OnContextMenuInit()
  {
   // Implement the handler here
  }
  

• OnContextMenuSelected – Fired when a contextual menu item is selected over a grid widget that is associated with a grid data parameter. Write your handler inside a callback that uses the following convention:

  function <property_name>_<parameter_name>_OnContextMenuSelected()
  {
   // Implement the handler here
  }
  

See the GridData example for more information. This example is located in the examples folder of the Softimage SDK installation directory.