/*
        This example demonstrates how to set user keywords with SetUserKeyword and 
        then how to read them back with GetUserKeyword.
*/
BuildSampleScene();
// Display X3DObjects that include the keyword "Useless"
var oUselessNulls = FindObjectsWithKeyword( "Useless" );
for ( var k=0; k<oUselessNulls.Count; k++ ) {
        Application.LogMessage( oUselessNulls(k).Name + " has keywords: " + GetKeywordsAsString( oUselessNulls(k) ) );
}
// Expected results:
//INFO : null10 has keywords: placeholder,useless
//INFO : null11 has keywords: placeholder,useless
//INFO : null13 has keywords: placeholder,useless
//INFO : null14 has keywords: placeholder,useless
//INFO : null15 has keywords: beta,useless
//INFO : null16 has keywords: beta,useless
//INFO : null17 has keywords: beta,useless
//INFO : null18 has keywords: beta,useless
//INFO : null19 has keywords: beta,useless
function BuildSampleScene()
{
        NewScene(null, false);
        var oNulls = new ActiveXObject( "XSI.Collection" );
        for ( var i=0; i<20; i++ ) {
                var oNull = ActiveSceneRoot.AddNull();
                oNulls.Add( oNull );            
        }
        // Now store some user keywords on the newly created nulls.
        // Some nulls have several keywords applied
        for ( i=0; i<10; i++ ) {             
                SetUserKeyword( oNulls(i), "important" );
        }
        for ( i=0; i<5; i++ ) {              
                AddUserKeyword( oNulls(i), "alpha" );
        }
        for ( i=15; i<20; i++ ) {            
                AddUserKeyword( oNulls(i), "beta" );
        }
        for ( i=5; i<15; i++ ) {             
                AddUserKeyword( oNulls(i), "placeholder" );
        }
        for ( i=10; i<20; i++ ) {            
                AddUserKeyword( oNulls(i), "useless" );
        }
        // Remove keywords from one of the nulls        
        ClearUserKeyword( oNulls( 12 )  );      
}
// GetUserKeyword returns a collection of strings.
// This function turns that collection into a comma separated
// string suitable for printing out.
function GetKeywordsAsString( in_obj )
{
        var oKeywords = GetUserKeyword( in_obj );               
        var aKeywords = new Array( oKeywords.Count );   
        for ( var i=0; i<oKeywords.Count; i++ ) {            
                aKeywords[i] = oKeywords(i);
        }
        return aKeywords.join( "," );   
}
// Find all X3DObjects with a certain keyword
//
// User keywords can be stored on almost 
// any Softimage object, but in this case we only search
// X3DObjects
function FindObjectsWithKeyword( in_keyword )
{
        // Set keywords to lowercase
        strSearchKeyword = in_keyword.toLowerCase();
        var oReturnCollection = new ActiveXObject( "XSI.Collection" );
        var oAllX3DObjects = ActiveSceneRoot.FindChildren();
        for ( var i=0; i<oAllX3DObjects.Count; i++ ) {
                var oKeywords = GetUserKeyword( oAllX3DObjects(i) );
                for ( var j=0; j<oKeywords.Count; j++ ) {            
                        if ( oKeywords(j) == strSearchKeyword ) {                                               
                                // Found object with this keyword
                                oReturnCollection.Add( oAllX3DObjects(i) );                             
                                break;
                        }
                }       
        }
        return oReturnCollection;
}