Object Model: XSICollection.Filter

XSICollection.Filter

Introduced

v11.0 (2013)

Description

Returns a subset of this collection as a new collection of objects matching the filter criteria. If no items are found, Filter returns "Nothing", which allows you to trap errors.

You can set up the filter criteria by using the 'Type', 'Families', and/or 'Path' parameters which roughly correspond to searching by type as outlined in the siType constant, searching by family as outlined in the siFamily constant, or searching by name of the object (see Object Name for more about valid syntax for the Path parameter).

Note: If you combine these parameters, they will narrow the scope of your search, not broaden it. For example, if you specify 'Nurbs Surface Mesh Geometries' (siNurbsSurfaceMeshFamily) for the Families parameter and 'Cone*' for the Path parameter, the return collection will contain any Nurbs cone that was in the original collection, but no Polygon Mesh cones and no Nurbs cubes, spheres, etc.

C# Syntax

CXSICollection XSICollection.Filter( String in_filter, Object in_famArray, String in_path );

Scripting Syntax

oReturn = XSICollection.Filter( [Type], [Families], [Path] );

Return Value

XSICollection (subset of original collection).

Parameters

Parameter	Type	Description
Type	String	siType (for example, "Model", "cube", "torus", etc.). Providing a type argument is equivalent to testing each object with the ProjectItem.IsKindOf method. Default Value: Empty string
Families	siFamily or Array of siFamily values	Specifies the families that objects must belong to. To match the filter, an object must belong to at least one of the specified families. Default Value: Empty Variant
Path	String	An Object Name. This can be a partial name using wildcards. For example, "a*" returns all matches that begin with the character "a". Default Value: Empty string

Examples

JScript Example

// Build a new scene with lots of objects to filter and return the scene root
var child_coll = CreateCollection();
// Using this criterion will match either nulls or srfmesh elements
families2find = new Array( "Nurbs Surface Mesh Geometries", "Nulls" )
WriteCollection( child_coll.Filter( "", "","*Cone" ), "filter( , ,'*Cone' )", "any item with a name ending in 'Cone'" );
WriteCollection( child_coll.Filter( "", "","MyAwesome*" ), "filter( '', '', '*Awesome*' )", "any item with a name starting with 'MyAwesome'" );
WriteCollection( child_coll.Filter( "Cone", families2find,"MyAwesome*" ), "filter( 'Cone', new Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ), 'MyAwesome*' )", "any cone with a name starting with 'MyAwesome' that is either a surfmsh or a null" );
WriteCollection( child_coll.Filter( "Cone", families2find ), "filter( 'Cone', new Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ) )","any cone that is either a surfmsh or a null" );
WriteCollection( child_coll.Filter( "", families2find ), "filter( '', Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ) )", "any item that is either a surfmsh or a null"  );
WriteCollection( child_coll.Filter( "Cone", "Nurbs Surface Mesh Geometries" ),  "filter( 'Cone', 'Nurbs Surface Mesh Geometries' )", "any surfmsh cone"  );
WriteCollection( child_coll.Filter( "Cone" ), "filter( 'Cone' )", "any cone"  );
WriteCollection( child_coll.Filter( "Torus", "","*Super*" ), "filter( 'Torus', '', '*Super*' )", "any torus with a name containing 'Super'"  );
WriteCollection( child_coll.Filter( "", "Nurbs Surface Mesh Geometries" ), "filter( '', 'Nurbs Surface Mesh Geometries' )", "any surfmsh" );
WriteCollection( child_coll.Filter( "", "Mesh Geometries" ), "filter( '', Mesh Geometries )", "any polymsh"   );
WriteCollection( child_coll.Filter( "", "Mesh Geometries","*Cone" ), "filter( '', 'Mesh Geometries', '*Cone' )", "any polymsh item with a name ending in 'Cone'" );
/* --------------------------------------------------------------
This function adds the following items to the scene root:
Name                Primitive Type      Geometry Type
---------------     --------------      -------------
MySuperCone         polymsh             Cone
MySuperCylinder     polymsh             Cylinder
MyAwesomeCone       surfmsh             Cone
MyAwesomeTorus      polymsh             Torus
MySuperTorus        surfmsh             Torus
MyImplicitCube      cube                Cube
MyAwesomeNull       --                  Null
CameraRoot          --                  CameraRig
camera1             --                  Camera
CameraInterest      --                  Null
*/
function CreateCollection( )
{
        NewScene( null, false );
        var root = ActiveProject.ActiveScene.Root;
        root.AddGeometry( "cone", "meshsurface", "MySuperCone" ); 
        root.AddGeometry( "Cylinder", "meshsurface", "MySuperCylinder" ); 
        root.AddGeometry( "cone", "nurbssurface", "MyAwesomeCone" ); 
        root.AddGeometry( "Torus", "nurbssurface", "MySuperTorus"  ); 
        root.AddGeometry( "Torus", "meshsurface", "MyAwesomeTorus" ); 
        root.AddPrimitive( "cube", "MyImplicitCube" ); 
        root.AddNull( "MyAwesomeNull" ); 
        root.AddCameraRig( "Camera" ); 
        var coll = new ActiveXObject( "XSI.Collection" );        
        var children = root.Children
        for (var i=0; i<children.count; i++)
        {                       
                coll.Add( children(i) );
        }
        return coll;
        }
/* --------------------------------------------------------------
This function prints the collection information
*/
function WriteCollection( in_collection, in_filter_text, in_plain_text )
{
        // Make sure the script doesn't break
        try 
        {
                LogMessage( "-----" );
                LogMessage( "TEST: " + in_filter_text );
                LogMessage( "      [" + in_plain_text + "]" );
                LogMessage( "Size of collection: " + in_collection.Count );
                for ( var i=0; i<in_collection.Count; i++ ) {
                        LogMessage( "\titem #" + (i+1) + ": " + in_collection(i).Name + " (type = " + in_collection(i).Type + ")" );
                }
                return 1;
        } 
        catch(e) 
        {
                LogMessage( "Encountered a problem with the input collection. Quitting..." );
                return 0;
        }
}
/* --------------------------------------------------------------
        Output of the above script:
*/
//INFO : -----
//INFO : TEST: filter( , ,'*Cone' )
//INFO :       [any item with a name ending in 'Cone']
//INFO : Size of collection: 2
//INFO :        item #1: MySuperCone (type = polymsh)
//INFO :        item #2: MyAwesomeCone (type = surfmsh)
//INFO : -----
//INFO : TEST: filter( '', '', '*Awesome*' )
//INFO :       [any item with a name starting with 'MyAwesome']
//INFO : Size of collection: 3
//INFO :        item #1: MyAwesomeCone (type = surfmsh)
//INFO :        item #2: MyAwesomeTorus (type = polymsh)
//INFO :        item #3: MyAwesomeNull (type = null)
//INFO : -----
//INFO : TEST: filter( 'Cone', new Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ), 'MyAwesome*' )
//INFO :       [any cone with a name starting with 'MyAwesome' that is either a surfmsh or a null]
//INFO : Size of collection: 1
//INFO :        item #1: MyAwesomeCone (type = surfmsh)
//INFO : -----
//INFO : TEST: filter( 'Cone', new Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ) )
//INFO :       [any cone that is either a surfmsh or a null]
//INFO : Size of collection: 1
//INFO :        item #1: MyAwesomeCone (type = surfmsh)
//INFO : -----
//INFO : TEST: filter( '', Array( 'Nurbs Surface Mesh Geometries', 'Nulls' ) )
//INFO :       [any item that is either a surfmsh or a null]
//INFO : Size of collection: 5
//INFO :        item #1: Camera_Root (type = CameraRoot)
//INFO :        item #2: MyAwesomeCone (type = surfmsh)
//INFO :        item #3: MySuperTorus (type = surfmsh)
//INFO :        item #4: MyAwesomeNull (type = null)
//INFO :        item #5: CameraRoot (type = CameraRoot)
//INFO : -----
//INFO : TEST: filter( 'Cone', 'Nurbs Surface Mesh Geometries' )
//INFO :       [any surfmsh cone]
//INFO : Size of collection: 1
//INFO :        item #1: MyAwesomeCone (type = surfmsh)
//INFO : -----
//INFO : TEST: filter( 'Cone' )
//INFO :       [any cone]
//INFO : Size of collection: 2
//INFO :        item #1: MySuperCone (type = polymsh)
//INFO :        item #2: MyAwesomeCone (type = surfmsh)
//INFO : -----
//INFO : TEST: filter( 'Torus', '', '*Super*' )
//INFO :       [any torus with a name containing 'Super']
//INFO : Size of collection: 1
//INFO :        item #1: MySuperTorus (type = surfmsh)
//INFO : -----
//INFO : TEST: filter( '', 'Nurbs Surface Mesh Geometries' )
//INFO :       [any surfmsh]
//INFO : Size of collection: 2
//INFO :        item #1: MyAwesomeCone (type = surfmsh)
//INFO :        item #2: MySuperTorus (type = surfmsh)
//INFO : -----
//INFO : TEST: filter( '', Mesh Geometries )
//INFO :       [any polymsh]
//INFO : Size of collection: 3
//INFO :        item #1: MySuperCone (type = polymsh)
//INFO :        item #2: MySuperCylinder (type = polymsh)
//INFO :        item #3: MyAwesomeTorus (type = polymsh)
//INFO : -----
//INFO : TEST: filter( '', 'Mesh Geometries', '*Cone' )
//INFO :       [any polymsh item with a name ending in 'Cone']
//INFO : Size of collection: 1
//INFO :        item #1: MySuperCone (type = polymsh)