Defining a Custom Property

In order to build your property page you first need to create a custom property set with a set of parameters that can correpond to the controls you want to use. For example, if you want to create a dialog that presents the user with one (RGB) color control and two text boxes, you must create five parameters in all: three double floating-point parameters and two string parameters.

Note

You can create extra parameters on your custom property set without displaying them on the final property page. Hidden parameters can be useful for storing information not available to the user and that do not have to be persisted in the scene.

Tip

You can also change the parameters on your custom property dynamically. For more information, see Dynamically Changing Custom Properties.

To create an underlying property set

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());
}
```
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.
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.
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.