XSICollection

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.

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)"

Add	AddItems	Expand	Filter
FindObjectsByMarkingAndCapabilities	GetAsText	Remove	RemoveAll
RemoveItems	SetAsText

XSICollection

Introduced

Description

Methods

Properties

Examples

1. VBScript Example

2. JScript Example

3. VBScript Example

See Also