## XSICollection

Object Hierarchy

### Introduced

v1.0

### Description

A Collection is an object that stores a "list" or "grouping" of multiple objects. The XSICollection is normally used to create, and subsequently process, a temporary list of objects from within the scene. A typical use of XSICollection is demonstrated in one of the examples for the Shader object.
Instances of the XSICollection are not persisted and, unlike the Group object, are not part of the Scene. One way to persist the contents of an XSICollection is to store the return value of XSICollection.GetAsText inside a String Parameter in a CustomProperty.
The Object Model also contains many other collection objects, for example, the PropertyCollection and the ParameterCollection. Enumerating through all these objects is identical (using the Item and Count properties). However these other collections only contain objects of one single type and the script writer cannot add or remove objects in these collections. For this reason XSICollection is the most suitable choice for most scripts.
Each script language also provides its own Array support which can be similar to the XSICollection object. This "native" collection support can be useful inside the implementation of a script but cannot be easily understood by C++ or other scripting languages. For example, custom Commands cannot receive JScript arrays as arguments. These collection objects also do not have the same convenient capability that the XSICollection has for converting between the string representation of an object and the Object Model representation (see XSICollection.SetAsText).
The equivalent object in the C++ API is the CRefArray.

### Methods

Add | AddItems | Expand | Filter
FindObjectsByMarkingAndCapabilities | GetAsText | Remove | RemoveAll
RemoveItems | SetAsText |  |

### Properties

Count | Item | Type | Unique

### Examples

#### 1. VBScript Example

    Dim oColl			' object pointer for collection

    Dim oItem			' for enumerating the collection

    Dim iCounter		' for looping through the collection

    ' Create the collection as an ActiveX object

    Set oColl = CreateObject("XSI.Collection")

    ' Add some items to it

    oColl.Add "Camera"

    oColl.Add "Light"

    ' You can enumerate the collection...

    For Each oItem In oColl

    	Application.LogMessage oItem

    Next

    ' ... or loop through it...

    For iCounter = 0 To oColl.Count - 1

    	Application.LogMessage oColl(iCounter)

    Next

    ' ... or convert it to a string expression

    Application.LogMessage oColl.GetAsText

    ' You can also find out if the collection is unique

    Application.LogMessage "Is the collection unique? -- " & oColl.Unique

    '--------------------------------------------------

    ' Output of above script:

    'INFO : "Camera"

    'INFO : "light"

    'INFO : "Camera"

    'INFO : "light"

    'INFO : "Camera,light"

    'INFO : "Is the collection unique? -- False"

#### 2. JScript Example

    // Create the collection as an ActiveX object

    var oColl = new ActiveXObject("XSI.Collection") ;

    // Add the default camera by name

    oColl.Add( "Camera" ) ;

    // Add an item by its Object Model reference

    var oNull = ActiveSceneRoot.AddNull() ;

    oColl.Add( oNull ) ;

    // You can enumerate the collection...

    var eCollItems = new Enumerator( oColl );

    eCollItems.moveFirst();

    for (; !eCollItems.atEnd(); eCollItems.moveNext() )

    {

    	var oItem = eCollItems.item();

    	Application.LogMessage( oItem ) ;

    }

    // ... or loop through it...

    for (var iCounter = 0 ; iCounter < oColl.Count ; iCounter++ )

    {

    	Application.LogMessage( oColl(iCounter) ) ;

    }

    // ... or convert it to a string expression

    Application.LogMessage( oColl.GetAsText() ) ;

    // By default collections are not set to Unique

    Application.LogMessage( "Is the collection unique? -- " + oColl.Unique ) ;

    //--------------------------------------------------

    // Output of above script:

    //INFO : Camera

    //INFO : null

    //INFO : Camera

    //INFO : null

    //INFO : Camera,null

    //INFO : Is the collection unique? -- false

#### 3. VBScript Example

    '===========================================================

    ' This example demonstrates how to create an XSICollection,

    ' how to work with collection items, and how to set the

    ' get its family information

    ' Create the collection and the main object to go in it

    Set oXSIColl = CreateObject( "XSI.Collection" )

    Set oStuff = CreatePrim( "Torus", "MeshSurface" )

    ' Add the object to the new collection and print out

    ' the family info

    getMembers oStuff

    ' Apply an operator to make the Families seach more

    ' interesting on the construction history

    ApplyOp "Twist"

    ' Add each operator to the collection, etc.

    Set oThingey = oStuff.ActivePrimitive.ConstructionHistory

    For Each s in oThingey

    	getMembers s

    Next

    ' Finally, what is in the XSICollection?

    LogMessage "This collection contains these members:"

    For Each c in oXSIColl

    	LogMessage vbTab & c & " (" & typename( c ) & ")"

    Next

    '========================================================

    function getMembers( in_object )

    	' Make an empty collection item and assign an

    	' object to it.

    	Set oCache = CreateObject( "XSI.CollectionItem" )

    	oCache.Value = in_object

    	' Print out the family information on the new item

    	aMembership = oCache.Families

    	LogMessage in_object & " is a member of these families: "

    	LogMessage vbTab & aMembership & vbLf

    	' Assign the new collection item to the collection

    	oXSIColl.Add oCache

    end function

    '========================================================

    'OUTPUT:

    'INFO : "torus is a member of these families: "

    'INFO : "	3D Objects

    '"

    'INFO : "torus.polymsh.twistop is a member of these families: "

    'INFO : "	Operators,DeformOperators

    '"

    'INFO : "torus.polymsh.geom is a member of these families: "

    'INFO : "	Operators,Converters

    '"

    'INFO : "This collection contains these members:"

    'INFO : "	torus (X3DObject)"

    'INFO : "	torus.polymsh.twistop (Operator)"

    'INFO : "	torus.polymsh.geom (Operator)"

### See Also

CollectionItem siBranchFlag ArgumentHandler Shader Group.AddMember Array