<     > 

SetUserKeyword

Introduced

5.0

Description

Sets the user keyword(s) on each object in the specified list. Keywords are persisted in lowercase.

Note: Calling this command will erase any existing keywords. The example below includes an AddUserKeyword function that demonstrates how to preserve existing keywords.

Scripting Syntax

SetUserKeyword( [InputObjs], [Keywords] )

Parameters

Examples

JScript Example

/*
   Example of setting users keywords with SetUserKeyword and 
   reading 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 )  ); 
       }

// Add a user keyword to an object
//
// Calling the SetUserKeyword command will replace any existing
// keywords.  This function preserves the existing keywords
// and adds the new keyword to the end of the list.  It does
// nothing if the object already has the specified keyword set
function AddUserKeyword( in_obj, in_newkeyword )
{
   // Keywords are always stored in lower case
   strNewKeyword = in_newkeyword.toLowerCase() ;

   var oExistingKeywords = GetUserKeyword( in_obj ) ;
   var strNewKeywordString = "" ;

   for ( var i = 0 ; i < oExistingKeywords.Count ; i++ )
   {
       if ( oExistingKeywords(i) == strNewKeyword )
       {
          // Already set, nothing to do
          return ;
       }

       strNewKeywordString += oExistingKeywords(i) + "," ; 
   }

   strNewKeywordString += strNewKeyword ;
   SetUserKeyword( in_obj, strNewKeywordString ) ;
}

// 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 XSI object, but in this case we only search
// X3DObjects
function FindObjectsWithKeyword( in_keyword )
{
   // keywords are always stored in 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 ;
}

See Also

SOFTIMAGE|XSI v6.01     <     >