## 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