v11.0 (2013)
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.
CXSICollection XSICollection.Filter( String in_filter, Object in_famArray, String in_path ); |
oReturn = XSICollection.Filter( [Type], [Families], [Path] ); |
XSICollection (subset of original collection).
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 |
// 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) |