PluginRegistrar.RegisterProperty

Description

Registers a new type of CustomProperty. To create instances of this CustomProperty, use SceneItem.AddProperty.

C# Syntax

PluginItem PluginRegistrar.RegisterProperty( String in_name );

Scripting Syntax

oReturn = PluginRegistrar.RegisterProperty( Name );

Return Value

PluginItem

Parameters

Parameter Type Description
Name String The name of the property (actually, the name of the PluginItem object created for this property). Instances of the property have this name as their SIObject.Type. It should begin with a letter and contain only letters, numbers and the underscore character. It is recommended to use a prefix based on your company or plug-in name.

If a property name contains spaces (for example, "My Custom Property"), the callback function names must omit the spaces (for example, "MyCustomProperty_DefineLayout").

Property names must be unique. To avoid naming conflicts, it is recommended to use a prefix based on your company name or the plug-in name (for example, "ACME_TornadoKit_Configuration").

Examples

JScript Example

/*
	"SimpleProp"
	Example of a script-based Custom Property plug-in
	To try out this example, use the Plug-in Tree to create an empty plug-in, 
	replace the generated code with the example code, and save the file. Softimage
	will automatically load the plug-in, and you can create an instance of the
	property by right-clicking the property in the Plug-in Tree and choosing
	Create Property.
	(You can also load the plug-in without restarting Softimage - see
	XSIApplication.LoadPlugin)
*/
function XSILoadPlugin( in_reg )
{
	// Called on startup of Softimage to defined
	// what is contained in the script.  (We could potentially
	// implement many PluginItems in the same script)
	in_reg.Author = "Softimage SDK Team" ;
	in_reg.Name = "SDK Example - Simple Custom Property" ;
	in_reg.Major = 1 ;
	in_reg.Minor = 1 ;
	in_reg.RegisterProperty( "SimpleProp" ) ;
	return true ;
}
function SimpleProp_Define( io_Context )
{
	//Called when a new instance of the Custom Property is created
	//Define is not called when the plug-in is updated or reloaded.
	var oCustomProperty = io_Context.Source
	oCustomProperty.AddParameter3( "U", siDouble, 0.3, 0.0, 1.0  ) ;
	oCustomProperty.AddParameter3( "V", siDouble, 0.75, 0.0, 1.0  ) ;	
	oCustomProperty.AddParameter3( "LockUV",siBool,false,null,null,false ) ;		
	oCustomProperty.AddParameter3( "ShowInfo",siBool,false,null,null,false ) ;
	// Some static text that we will dynamically show and hide
	strInfo = "This is an sdk example showing a Custom\r\n" +
			  "Property that is defined inside a script-based\r\n" +
			  "plug-in." ;
	var oParameter = oCustomProperty.AddParameter3( "InfoStatic", siString ) ;		
	oParameter.Show( false ) ;
	oParameter.Value = strInfo ;
}
function SimpleProp_DefineLayout( io_Context )
{
	// Called once per Softimage session, or after
	// a call to XSIUtils.Reload
	var oPPGLayout = io_Context.Source
	//Important first step is to erase any existing contents
	oPPGLayout.Clear() ;
	oPPGLayout.AddGroup( "Data" ) ;
	oPPGLayout.AddRow() ;
	var oItem =	oPPGLayout.AddItem( "U" ) ;
	oItem.SetAttribute( siUIThumbWheel, true ) ;
	oItem.LabelMinPixels = 20 ;
	oItem.LabelPercentage = 1 ;	
	oItem =	oPPGLayout.AddItem( "V" ) ;
	oItem.SetAttribute( siUITreadmill, true ) ;
	oItem.LabelMinPixels = 20 ;
	oItem.LabelPercentage = 1  ;
	oPPGLayout.EndRow() ;
	oPPGLayout.AddItem( "LockUV", "Lock UV" ) ;	
	oPPGLayout.EndGroup() ;
	oPPGLayout.AddGroup() ;	
	// The InfoStatic is always in the layout,
	// but it will not appear if siNotInspected 
	// capability has been set by calling Parameter.Show(false)
	oItem = oPPGLayout.AddItem( "InfoStatic", "", siControlStatic ) ;
	oItem.SetAttribute( siUIValueOnly, true ) ;
	oPPGLayout.AddItem( "ShowInfo", "Show Info" ) ;	
	oPPGLayout.EndGroup() ;
	oPPGLayout.AddButton( "Done" ) ;
}
//
// Logic Code - these callbacks are called when
// events happen in the user interface
//
// The syntax is basically the same as SPDL logic
// but notice how each function uses a prefix based on the
// Custom Property that we registered, i.e. 
// "SimpleProp_"
//
function SimpleProp_OnInit()
{
	//Called when the UI first appears.
	Application.LogMessage( "Someone is inspecting " + 
		PPG.Inspected(0).FullName ) ;
}
function SimpleProp_Done_OnClicked()
{
	// See the documentation for
	// PPG.Close for more info about this
	// technique.
	// Self destruct the property page
	DeleteObj( PPG.Inspected(0) ) ;
	// Close the property page
	PPG.Close() ;
}
function SimpleProp_ShowInfo_OnChanged()
{
	// Toggle the visibility of the static text
	PPG.InfoStatic.Show( PPG.ShowInfo.Value ) ;
	// It isn't strictly necessary to call this for
	// simple cases of hiding and showing controls,
	// but it ensures that the property page is fully
	// redrawn and resized.
	PPG.Refresh() ;
}
// The following three logic routines force both 
// parameters to have the same value
function SimpleProp_U_OnChanged()
{
	if ( PPG.LockUV.Value )
	{	
		// Note: Changing the value from
		// within the logic code will not 
		// result in SimpleProp_V_OnChanged
		// being called.  So there is
		// minimal risk of infinite loops.
		PPG.V.Value = PPG.U.Value ;
	}
}
function SimpleProp_V_OnChanged()
{
	if ( PPG.LockUV.Value )
	{	
		PPG.U.Value = PPG.V.Value ;
	}
}
function SimpleProp_LockUV_OnChanged()
{
	if ( PPG.LockUV.Value )
	{
		// When locking is enabled make sure
		// that the two values snap to the same,
		// value.		
		avg = ( PPG.U.Value + PPG.V.Value	 ) / 2 ;
		PPG.U.Value = avg ;
		PPG.V.Value = avg ;
	}
}

See Also

Plugin.Items SceneItem.AddProperty CustomProperty PPGLayout PPG Definition Callbacks for Properties