v1.0
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
StringParameter 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.
| Add | AddItems | Expand | FindObjectsByMarkingAndCapabilities |
| GetAsText | Remove | RemoveAll | RemoveItems |
| SetAsText | |||
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"
|
// 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
|
'===========================================================
' 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)"
|