Defining a Custom Property

To create an underlying property set

1. Depending on how you are creating the custom property, you start with getting a pointer to the CustomProperty or CustomProperty object:

   • For creating properties on-the-fly, use SceneItem.AddCustomProperty or SceneItem::AddCustomProperty to create an empty custom property set. You can use any scene node that supports properties as an owner (such as clusters, 3D objects, models, etc.).

   • For self-installing properties, you can get a pointer to the CustomProperty object from the Context.Source or Context::GetSource property inside the Define callback:

   // JScript
   function MyCPSet_Define( in_context ) {
   	var oCusProp = in_context.Source;
   	// ...
   }
   
   // C++
   CStatus MyCPSet_Define( CRef& in_context ) {
   	Context ctxt(in_context);
   	CustomProperty cus_prop(ctxt.GetSource());
   }
   

2. Use CustomProperty.AddParameter3 or CustomProperty::AddParameter for each simple control you want to define or hidden parameter you want to create.

   Color controls are more complex: for each channel (RGB/RGBA), you need to create one parameter.

   For fcurve widgets, use CustomProperty.AddFCurveParameter or CustomProperty::AddFCurveParameter.

   for grid data widgets, use CustomProperty.AddGridParameter or CustomProperty::AddGridParameter.

   Tip

   For C# or scripting, CustomProperty.AddParameter3 is the recommended version for creating property sets because it is JScript-compliant (like CustomProperty.AddParameter2) and has been simplied from the original (CustomProperty.AddParameter). However, you should use one of these two versions if the parameter needs a UI range, specific classification flags, or a user name.

   For the C++ API, there are two flavours of the CustomProperty::AddParameter function, one simplified and another that allows you to specify UI ranges. Both provide arguments to specify classification flags and user names.

3. Define the layout for the property set by getting the PPGLayout or PPGLayout object from the PPG.PPGLayout or ProjectItem::GetPPGLayout, which you can then use to:

   • Add controls to your property page—Property Page Controls.

   • Add the logic to drive the property page controls and process the data on your property set—Property Callbacks.

   • Assign help files to your property page—Providing Help Files.

4. If you want to make this CustomProperty a self-installing plug-in (so you can reuse it), you also need to specify certain callbacks. For more information, see Property Callbacks.

   Important

   It is possible to create and register a SPDL (and optionally, a preset) from a scripted CustomProperty definition in the scene using XSIUtils.WriteSPDL and then XSIUtils.RegisterSPDL. However, this is not recommended, since using these methods are low-level and can potentially damage your Softimage installation.

   In addition, there is no advantage to creating extra SPDL files when the self-installing CustomProperty performs the same function.