Object Model: Command.Code

Command.Code

Introduced

v4.0

Description

Sets and returns the implementation of the Command as a String value. Use this property as an alternative to storing the Command implementation in a file. This is a convenient way to implement small, simple script-based custom commands. The code is stored as part of the Command definition.

Any script language can be represented as a string, but the "toString()" method in JScript is particularly convenient for turning a function into its string representation.

The string must include a function with the name specified in the Command.Handler property, and it can also contain helper functions or global variables.

Note: Global variables will potentially be re-initialized each time the command is executed.

C# Syntax

// get accessor
String rtn = Command.Code;
// set accessor
Command.Code = String;

Examples

1. JScript Example

/*
        Example of an embedded command
*/
// These are the two different implementations of
// the command that we will use
function FuncImpl1( arg )
{
        Application.LogMessage( arg ) ;
}
function FuncImpl2( arg )
{
        XSIUIToolkit.MsgBox( arg ) ;
}
Application.RemoveCommand( "EmbeddedJScript" ) ;
var cmd = Application.CreateCommand( "EmbeddedJScript" ) ;
cmd.ScriptingName = "EmbeddedJScript" ;
cmd.Language = "JScript" ;
cmd.Handler = "FuncImpl1" 
cmd.Code = FuncImpl1.toString(); // Embed the code directly in the definition
cmd.Arguments.Add( "arg1") ;
cmd.ReturnValue = false   // Optional, but makes it explicit that this is
                                                  // is a subroutine
Application.AddCommand( cmd ) ;
//Tip: uncomment this line to see the command
//that has just been defined
//EditCommand( "EmbeddedJScript" ) ;
//Execute the command
//This will log:
//INFO : "56"
EmbeddedJScript( 56 ) ;
//Change the code by updating the command with
//a new function
var cmd = Application.Commands( "EmbeddedJScript" ) ;
cmd.Code = FuncImpl2.toString() ;
cmd.Handler = "FuncImpl2" ;
cmd.Update() ;
//Execute the command
//This will pop up a message box
EmbeddedJScript( 56 ) ;
//Cleanup 
Application.RemoveCommand( "EmbeddedJScript" ) ;

2. VBScript Example

'
'       VBScript example of an embedded command
'
'The implementation of the command is stored in this string
'Clearly it would be awkward to write a huge command
'like that.  For large custom commands we recommend that
'you store the command in a file
'and set the Command.FileName property.
dim strCommandImpl 
strCommandImp = _
        "sub FuncImpl( arg )" & vbCrLf & _
        "       logmessage arg" & vbCrLf & _
        "end sub"
Application.RemoveCommand "EmbeddedVBScript" 
set cmd = Application.CreateCommand( "EmbeddedVBScript" )
cmd.ScriptingName = "EmbeddedVBScript" 
cmd.Language = "VBScript" 
cmd.Handler = "FuncImpl" 
cmd.Code = strCommandImp  ' Embed the code directly in the definition
cmd.Arguments.Add "arg1"
cmd.ReturnValue = false   ' Optional, but makes it explicit that this is
                                                  'is a subroutine
Application.AddCommand( cmd )
'Tip: uncomment this line to see the command
'that has just been defined
'EditCommand "EmbeddedVBScript"
'Execute the command
'This will log:
'INFO : "56"
EmbeddedVBScript 56
'Change the code by updating the command with
'a new function
strCommandImp = _
        "sub FuncImpl( arg )" & vbCrLf & _
        "       MsgBox arg" & vbCrLf & _
        "end sub"
set cmd = Application.Commands( "EmbeddedVBScript" )
cmd.Code = strCommandImp
cmd.Update
'Execute the command
'This will pop up a message box
EmbeddedVBScript 56
'Cleanup 
Application.RemoveCommand "EmbeddedVBScript"

3. Python Example

#g_EmbeddedCmd is some simple python code that we will
#use as the implementation of a custom command
g_EmbeddedCmd = """
#This routine expects in_obj to be a light
def FuncWithLightAsArgCmdImp( in_obj ):
        Application.LogMessage( in_obj.Shaders.Count ) 
        Application.LogMessage( in_obj.Name ) 
"""
#
# Function that creates custom command, provides g_EmbeddedCmd
# as the implementation and then calls it
#
def DemoObjectArgument():
        oDefaultLight = Application.ActiveSceneRoot.Children( "light" )         
        Application.RemoveCommand( "pythontestcmd" )
        cmd = Application.CreateCommand( "pythontestcmd" )
        cmd.ScriptingName = "pythontestcmd"
        cmd.Code = g_EmbeddedCmd
        cmd.Language = "Python"
        cmd.Handler = "FuncWithLightAsArgCmdImp"
        cmd.Arguments.AddObjectArgument( "in_obj" )
        Application.AddCommand( cmd )
        Application.pythontestcmd( oDefaultLight )
        #Because of argument handler we can also call it 
        #with a string and it will automatically be converted
        #into the object equivalent
        Application.pythontestcmd( "light" )
        Application.RemoveCommand( "pythontestcmd" )
DemoObjectArgument()
#Expected output
#INFO : 2
#INFO : light
#INFO : 2
#INFO : light