PluginRegistrar.RegisterFilter

Introduced

v4.0

Description

Registers a custom filter in Softimage.

C# Syntax

PluginItem PluginRegistrar.RegisterFilter( String in_name, siFilterType in_Type );

Scripting Syntax

oReturn = PluginRegistrar.RegisterFilter( Name, Type );

Return Value

PluginItem

Parameters

Parameter Type Description
Name String The name of the custom filter to register. It should begin with a letter and contain only letters, numbers and the underscore character.

The filter name is used to name the filter callback functions such as Match and Subset. For example, the Match callback for a filter named "My3DObjectFilter" is "My3DObjectFilter_Match". If a filter name contains spaces (for example, "My 3D Object Filter"), the callback function names must omit the spaces (for example, "My3DObjectFilter_Match").

The filter name also appears in the Softimage user interface, and is the name you use to reference the filter in scripting or C++ code. If the filter name contains spaces, you must replace the spaces with underscores to use the filter with scripting commands or the object model. For example, if you register a filter with the name "My Custom Filter", then to get the filter from the FiltersCollection, you need to replace the spaces with underscores:

var oFilter = Application.Filters.Item( "My_Custom_Filter" );
Type siFilterType Type of filter to register.

Examples

JScript Example

/*-------------------------------------------------------------------
	This example shows how to register, implement and use a 
	custom filter.
	README: Copy and paste the example into the script editor 
	and run (F5).
	The filter will now be listed in the Scene Explorer 
	filter list when the "Source/Clips" view context  is
	selected.
-------------------------------------------------------------------*/
function  XSILoadPlugin( in_reg )
{
	in_reg.Author = "Softimage Co." 
	in_reg.Name = "PluginRegistrar.RegisterFilter Example" 
	// register the cone filter plug-in item
	in_reg.RegisterFilter( "ExRegisterFilter_ConePrimitive", siFilterObject );
	// register a command to illustrate usage
	in_reg.RegisterCommand( "ExRegisterFilterDemo", "ExRegisterFilterDemo" );
	return true;
} 
function  ExRegisterFilter_ConePrimitive_Match( in_context )
{
	var obj = in_context.GetAttribute("Input");
	return obj.IsKindOf( siConePrimType );
}
// This command shows how to use the ConePrimitive filter 
function  ExRegisterFilterDemo_Execute()
{
	Application.LogMessage("Running ExRegisterFilterDemo");
	var filter = Application.Filters( "ExRegisterFilter_ConePrimitive" );
	Application.LogMessage( "Filter: " + filter.Name + " type=" + filter.Type );
	var sphere = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface", "sphere" );
	var cone = ActiveSceneRoot.AddGeometry( "Cone", "MeshSurface", "cone" );
	// log all objects that match the filter
	var eChildren = new Enumerator(ActiveSceneRoot.Children);
	for (;!eChildren.atEnd();eChildren.moveNext())
	{
		var child = eChildren.item();
		Application.LogMessage( child.name + " is a cone: " + filter.Match( child ) );
	}
}
//--------------------------------------------------------------------
// Code to bootstrap example into system
//--------------------------------------------------------------------
function ExampleSourceCode()
{
	return "//XSISDK Doc Example\n" +
		ExRegisterFilter_ConePrimitive_Match.toString() + "\n" + 
		ExRegisterFilterDemo_Execute.toString() + "\n" + 
		XSILoadPlugin.toString();
}
// if we are running from script editor save code to 
// examples addon folder in the user's directory.
if (GetUserPref("ScriptingSessionActive"))
{
	var ex_name 		= "ExPluginRegistrarRegisterFilter";
	var ex_subfolder 	= "Plugins";
	var ex_folder 		= "XSISDKDocExamples";
	var ex_langsuffix	= ".js";
	CreateAddonDirectories( InstallationPath(siUserPath), ex_folder );
	var fso = XSIFactory.CreateActiveXObject("Scripting.FileSystemObject");
	var filename = XSIUtils.BuildPath( 
		InstallationPath(siUserAddonPath), 
		ex_folder,
		"Application",
		ex_subfolder,
		ex_name+ex_langsuffix );
	if (!fso.FileExists(filename))
	{
		var f = fso.CreateTextFile ( filename );
		f.write( ExampleSourceCode() );
		f.close();
		Application.LoadPlugin(filename);	
	}
	// run demo
	ExRegisterFilterDemo();
}

See Also

Plugin.Items Definition Callbacks for Filters