## 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