Scripting: AddUserKeyword

AddUserKeyword

Introduced

v8.0 (2010)

Description

Preserves the existing keywords and adds the new keyword to the end of the list. If the object already has the specified keyword set, nothing happens.

To completely replace the existing keywords with new keyword(s), use the SetUserKeyword command instead.

Scripting Syntax

AddUserKeyword( [InputObjs], Keywords );

Parameters

Parameter	Type	Description
InputObjs	SelectionList or Selection	Default Value: If not specified, the current selection is used.
Keywords	String

Examples

Python Example

#
# This example demonstrates how to set, get, and add user keywords
#
def BuildSampleScene() :
        app = Application
        app.NewScene("", False)
        oNulls = XSIFactory.CreateActiveXObject( "XSI.Collection" )
        i=0
        while i<20 :
                oNulls.Add( app.ActiveSceneRoot.AddNull() )
                i = i + 1
        # Now store some user keywords on the newly created nulls.
        # Some nulls have several keywords applied
        for i in [0,1,2,3,4,5,6,7,8,9] :
                app.SetUserKeyword( oNulls(i), "important" )
        for i in [0,1,2,3,4] :          
                app.AddUserKeyword( oNulls(i), "alpha" )
        for i in [15,16,17,18,19] :             
                app.AddUserKeyword( oNulls(i), "beta" )
        for i in [5,6,7,8,9,10,11,12,13,14] :
                app.AddUserKeyword( oNulls(i), "placeholder" )
        for i in [10,11,12,13,14,15,16,17,18,19] :              
                app.AddUserKeyword( oNulls(i), "useless" )
        # Remove keywords from one of the nulls 
        app.ClearUserKeyword( oNulls(12)  )
# GetUserKeyword returns a collection of strings.
# This function turns that collection into a comma separated
# string suitable for printing out.
def GetKeywordsAsString( in_obj ) :
        oKeywords = Application.GetUserKeyword( in_obj )                
        return ",".join( oKeywords )
# 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
def FindObjectsWithKeyword( in_keyword ) :
        app = Application
        # Set keywords to lowercase
        strSearchKeyword = in_keyword.lower()
        oReturnCollection = XSIFactory.CreateActiveXObject( "XSI.Collection" )
        oAllX3DObjects = app.ActiveSceneRoot.FindChildren()
        for oX3DObject in oAllX3DObjects :
                oKeywords = app.GetUserKeyword( oX3DObject )
                for sKey in oKeywords:          
                        if sKey == strSearchKeyword :
                                # Found object with this keyword
                                oReturnCollection.Add( oX3DObject )
                                break
        return oReturnCollection
BuildSampleScene()
# Display X3DObjects that include the keyword "Useless"
oUselessNulls = FindObjectsWithKeyword( "Useless" )
for oUseless in oUselessNulls :
        Application.LogMessage( oUseless.Name + " has keywords: " + GetKeywordsAsString( oUseless ) )
# 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