## SetUserKeyword

### Introduced

v4.0

### Description

Sets the user keyword(s) on each object in the specified list.
Note: Calling this command will erase any existing keywords. To set a user keyword while preserving any existing list, use the AddUserKeyword command instead.

### Scripting Syntax

    SetUserKeyword( [InputObjs], [Keywords] );

### Parameters

Parameter | Type | Description
--- | --- | ---
InputObjs | String | List of objects on which to set keywords. Default Value: Current selection
Keywords | String | Keywords to set, as a comma separated list. Default Value: ""

### Examples

#### JScript Example

    /*
            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;
    }

### See Also

AddUserTab RemoveUserTab ClearUserTab GetUserTab SetUserTab AddUserKeyword RemoveUserKeyword ClearUserKeyword GetUserKeyword