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