Unique (XSICollection)

Description

Returns or sets a Boolean value indicating whether or not this collection is unique. A collection is unique if it contains only one copy of an object (ie., no duplicates). However, you can have several different objects in a unique collection.

Note: XSICollection is non-unique by default: you have to explicitly set the Unique flag to True in order to get a unique collection. Once a collection is unique, all duplicates are removed and you cannot add any more duplicates.

C# Syntax

    // get accessor
    Boolean rtn = XSICollection.Unique;

    // set accessor
    XSICollection.Unique = Boolean;

Examples

1. VBScript Example

    Dim oColl ' object pointer for collection

    ' Create a non-unique collection as an ActiveX object
    Set oColl = CreateObject("XSI.Collection")

    ' Add a bunch of duplicates
    oColl.Add ActiveSceneRoot
    oColl.Add ActiveSceneRoot
    oColl.Add ActiveSceneRoot
    oColl.Add ActiveSceneRoot
    oColl.Add ActiveSceneRoot

    ' How many members are in this collection?
    countMembers oColl

    ' Explicitly set
    oColl.Unique = True

    ' Now how many members are in this collection?
    countMembers oColl

    '--------------------------------------------------
    function countMembers( in_coll )
       ' How many members are in this collection
       LogMessage "This collection contains " & in_coll.Count & " members."
    end function

    '--------------------------------------------------
    ' Output of above script:
    'INFO : "This collection contains 5 members."
    'INFO : "This collection contains 1 members."

2. JScript Example

    /*
       This example demonstrates how you can remove all instances
       of an object using either the Unique property or using the
       RemoveItems method iteratively
    */

    NewScene( null, false );

    // Add multiple instances of the Scene_Root to two collections
    var oQuints1 = new ActiveXObject( "XSI.Collection" );
    var oQuints2 = new ActiveXObject( "XSI.Collection" );

    for ( i=0; i<5; i++)
    {
       oQuints1.Add( ActiveSceneRoot );
       oQuints2.Add( ActiveSceneRoot );
    }

    LogMessage( "-------------------------------" );
    LogMessage( "oQuints1 before removing: " + oQuints1.GetAsText() );
    LogMessage( "oQuints2 before removing: " + oQuints2.GetAsText() );

    // Reduce the first collection to one scene root using the Unique property
    oQuints1.Unique = true;
    LogMessage( "-------------------------------" );
    LogMessage( "oQuints2 after Unique: " + oQuints2.GetAsText() );

    // Now create an XSICollection with a single scene root so we can remove
    // a single instance of the root one at a time
    var oRemoveMe = new ActiveXObject( "XSI.Collection" );
    oRemoveMe.Add( ActiveProject.ActiveScene.Root );

    // One a time, remove all instances of the root
    LogMessage( "-------------------------------" );
    while ( oQuints2.RemoveItems( oRemoveMe ).Count != 0 )
    {
       LogMessage( "Another one bites the dust (" + oQuints2.Count + " items now remain in the collection)." );
    }

    LogMessage( "-------------------------------" );
    LogMessage( "oQuints2 after RemoveItems: " + oQuints2.GetAsText() );

    //--------------------------------------------------
    // Output of above script:
    //INFO : "-------------------------------"
    //INFO : "oQuints1 before removing: Scene_Root,Scene_Root,Scene_Root,Scene_Root,Scene_Root"
    //INFO : "oQuints2 before removing: Scene_Root,Scene_Root,Scene_Root,Scene_Root,Scene_Root"
    //INFO : "-------------------------------"
    //INFO : "oQuints2 after Unique: Scene_Root,Scene_Root,Scene_Root,Scene_Root,Scene_Root"
    //INFO : "-------------------------------"
    //INFO : "Another one bites the dust (4 items now remain in the collection)."
    //INFO : "Another one bites the dust (3 items now remain in the collection)."
    //INFO : "Another one bites the dust (2 items now remain in the collection)."
    //INFO : "Another one bites the dust (1 items now remain in the collection)."
    //INFO : "Another one bites the dust (0 items now remain in the collection)."
    //INFO : "-------------------------------"
    //INFO : "oQuints2 after RemoveItems: "

See Also

XSICollection.RemoveItems

Autodesk Softimage v7.5