Using Prefixes with Custom Properties

The naming conventions for property page event handlers differ slightly for SPDL-based, runtime and plug-in properties:

By default, plug-in based (self-installing) properties use the name of the property as a prefix. For example, the MyProp property's OnInit callback would be MyProp_OnInit.
By default, SPDL- and runtime-based properties use no prefix at all. For example, the MyProp property's OnInit callback would be simply OnInit whether it's defined in a SPDL file or on the fly.

However, when a prefix is specified, it is used across the board for all event handler callbacks, regardless of the name of the property or how it was implemented. For example, for the MyProp property with a prefix defined as FooBar, the OnInit callback would be FooBar_OnInit for SPDL-based, runtime-based, and plug-in based custom properties alike.

Defining a Prefix

For runtime and plug-in properties you can explicitly specify a prefix via scripting, by setting the siUILogicPrefix via PPGLayout.SetAttribute or PPGLayout::PutAttribute. SPDL-based properties, on the other hand, can either define a prefix via scripting in the Logic block of the SPDL file or via the LogicPrefix setting.

Example: Simple Runtime Property

This example creates a very simple custom property on the fly using the prefix FooBar, which must appear on the event handlers for this page's logic.

// Define an on-the-fly property with a single boolean parameter
var root = Application.ActiveSceneRoot;
var prop = root.AddCustomProperty( "RuntimePropertyDemo" );
prop.AddParameter3( "BooParam", siBool );


// Access the logic via the layout and simply add the handlers 
// specified below via the JScript toString() function
var ppglay = prop.PPGLayout;
ppglay.Logic = FooBar_OnInit.toString() + FooBar_BooParam_OnChanged.toString();

// Specify the new prefix and set the language to JScript
ppglay.Language = "JScript";
ppglay.SetAttribute( siUILogicPrefix, "FooBar_" ); // explicitly specify the underscore 


//
// Event handlers: for demo, these just log their names when called
//
// INFO : OnInit handler called
function FooBar_OnInit() // specify the prefix before 'OnInit'

{
	Application.LogMessage( "OnInit handler called" );
}

// INFO : Parameter_OnChanged handler called
function FooBar_BooParam_OnChanged() // specify the prefix before 'Parameter_OnChanged'
{
	Application.LogMessage( "Parameter_OnChanged handler called" );
}

Example: Simple Plug-in Based Property

This example is very similar to its runtime counterpart except that it is a scripted plug-in. To test it, follow these instructions:

Copy and paste the example text below into a file under the Applications/Plugins folder of your user directory (call it PluginPropertyDemoPlugin.js).
Apply the property to the scene root by running the following in the script editor:
```
Application.ActiveSceneRoot.AddProperty( "PluginPropertyDemo" );
```
Inspect the new property (the OnInit event handler will log a message).

You can toggle the BooParam check box to see its event handler log messages to the screen.

In this example, notice that not only do the OnInit and OnChanged callbacks use the prefix, but also the Define and DefineLayout callbacks.

// Define a plug-in based property with a single boolean parameter
//
// Notice that the Define and DefineLayout callbacks use the 
// property name; only the event handlers use the prefix
function XSILoadPlugin( in_reg )
{
	in_reg.Name = "PluginPropertyDemoPlugin";
	in_reg.RegisterProperty( "PluginPropertyDemo" );
	return true;
}

// Add parameters in this callback
function PluginPropertyDemo_Define( in_ctxt )
{
	var prop = in_ctxt.Source; // Get the CustomProperty
	prop.AddParameter3( "BooParam", siBool );
	return true;
}

// Set the language and prefix in this callback (the logic is automatically 
// provided by the event handler callbacks specified at the bottom of the file)
function PluginPropertyDemo_DefineLayout( in_ctxt )
{
	var ppglay = in_ctxt.Source; // Get the PPGLayout
	
	// Set the language to JScript and specify the new prefix 
	ppglay.Language = "JScript";
	ppglay.SetAttribute( siUILogicPrefix, "FooBar_" ); // explicitly specify the underscore 
	return true;
}


//
// Event handlers: for demo, these just log their names when called
//
// INFO : OnInit handler called
function FooBar_OnInit() // specify the prefix before 'OnInit'
{
	Application.LogMessage( "OnInit handler called" );
}

// INFO : Parameter_OnChanged handler called
function FooBar_BooParam_OnChanged() // specify the prefix before 'Parameter_OnChanged'
{
	Application.LogMessage( "Parameter_OnChanged handler called" );
}

Example: Simple SPDL Shader Property

This example demonstrates how to set the prefix using the LogicPrefix setting. It is a fully functional SPDL file although as a shader it will obviously fail without some kind of library file. To test it, follow these instructions:

Copy and paste the text below into a file under the Applications/spdl folder of your user directory (call it SPDLPropertyDemo.spdl).
From the Plug-in Tree in Softimage, right-click the new spdl file (click Update All if you don't see it) and choose Regenerate Preset.

Apply the shader to a cube in Softimage scene by running the following in the script editor:

var obj = Application.ActiveSceneRoot.AddGeometry( "Cube", "NurbsSurface" );
var shaderpreset = XSIUtils.BuildPath( 
   Application.InstallationPath( siUserPath ),
   "Data", "DSPresets", "Shaders", "Texture", "SPDLPropertyDemo.Preset" );
CreateShaderFromPreset( shaderpreset, "Sources.Materials.DefaultLib.Material" );
SIConnectShaderToCnxPoint( "Sources.Materials.DefaultLib.Material.SPDLPropertyDemo", 
	"Sources.Materials.DefaultLib.Scene_Material.Phong.ambient", false );

Inspect the new shader property (the OnInit event handler will log a message).

You can toggle the BooParam check box to see its event handler log messages to the screen.

Notice that, in this SPDL snippet, the prefix is specified exactly as in the runtime and plug-in based examples, and the event handlers are identical.

SPDL
Version = "2.0.0.0";
Reference = "{0DEC8359-4327-42E4-AE1B-A9504FF4047C}";
PropertySet "SPDLPropertyDemo_pset"
{
	Parameter "out" output
	{
		GUID = "{248FCEFE-DBA6-412A-9A8F-17A96D97F1E3}";
		Type = color;
	}
	Parameter "BooParam" input
	{
		GUID = "{4F5EE6C2-D219-4986-B455-EFAA6C538FC7}";
		Type = boolean;
		Value = off;
	}
}

MetaShader "SPDLPropertyDemo_meta"
{
	Name = "SPDL Property Demo Shader";
	Type = texture;
	Renderer "mental ray"
	{
		Name = "SPDLPropertyDemo";
		FileName = "SPDLPropertyDemo";
		Options
		{
			"version" = 1;
		}
	}
}

Layout "Default"
{
	BooParam;
}

Language = "JScript";
LogicPrefix = "FooBar_";
# Alternatively you could copy the code between the BeginScript and EndScript
# keywords and save them in the following file (and uncomment the next line):
#LogicFile = "$XSI_USERHOME/Application/spdl/lib/SPDLPropertyDemo.js";

BeginScript
	//
	// Event handlers: for demo, these just log their names when called
	//
	// INFO : OnInit handler called
	function FooBar_OnInit() // specify the prefix before 'OnInit'
	{
		Application.LogMessage( "OnInit handler called" );
	}
	
	// INFO : Parameter_OnChanged handler called
	function FooBar_BooParam_OnChanged()					// specify the prefix before 'Parameter_OnChanged'
	{
		Application.LogMessage( "Parameter_OnChanged handler called" );
	}
EndScript

Plugin = Shader
{
	FileName = "SPDLPropertyDemo";
}

Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License