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 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 OnInit callback would be named simply OnInit, 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 Logic.
For example, if the prefix is MyPlugin_ then Softimage expects a handler named MyPlugin_OnInit rather than MyProperty_OnInit or just plain OnInit. Similarly, the MyPlugin_OnClicked handler will be expected rather than MyProperty_OnClicked or OnClicked only.
|
For a discussion of the differences between SPDL-based, runtime, and plug-in properties with respect to prefixes and naming conventions for their event handlers, see Using Prefixes with Custom Properties. That section also has fairly extensive examples of how to specify logic prefixes for runtime-based properties and plug-in (self-installing) properties. |
The Define callback is where you add parameters to the custom property. The Define callback gets a Context object as input, from which you can get the CustomProperty object. The CustomProperty object provides methods for adding parameters:
• AddParameter
• AddFCurveParameter
• AddGridParameter
• AddProxyParameter
• 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;
}
The DefineLayout callback defines the layout of controls on the property page for a self-installing custom property. The DefineLayout callback gets a Context object as input, from which you can get the PPGLayout object. The 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 before you define the layout. Otherwise, a new set of controls would be appended to the existing layout everytime DefineLayout was called.
C++ and C# properties use PPGEvent to handle all property page events.
PPGEvent is fired when the property page is opened, when a parameter value is changed, and when a user clicks a button or tab.
The PPGEvent callback takes the PPGEventContextobject 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.
Scripted properties use OnInit to respond when the property page loads.
The OnInit 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 OnInit, instead of in DefineLayout.
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 <property-name>_<parameter-name>_OnChanged() {
// Implement the handler here
}
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 <property-name>_<button-name>_OnClicked()
{
// Implement the handler here
}where <button-name> is the name specified in the call to AddButton, with any spaces removed.
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 <property-name>_<tab-label>_OnTab()
{
// Implement the handler here
}where <tab-label> is the label specified in the call to AddTab, with any spaces removed.
Autodesk Softimage v7.5