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