RegisterFilter (PluginRegistrar)

Introduced

4.0

Description

Registers a custom filter in Softimage.

Scripting Syntax

PluginRegistrar.RegisterFilter( Name, Type )

C# Syntax

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

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.

Return Value

PluginItem

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

Autodesk Softimage v7.5