## ArgumentCollection.Add

### Description

Adds an argument to the Command definition.
To add an argument that receives an object call, use ArgumentCollection.AddObjectArgument instead. To use an ArgumentHandler use ArgumentCollection.AddWithHandler instead. This method is only available on custom commands. Normally this is called during the definition of a command (before XSIApplication.AddCommand is called). However it is also possible to add an argument and call Command.Update to change an existing command.

### C# Syntax

    Argument ArgumentCollection.Add( String Name, siArgumentFlags argflags, Object defval, siVariantType in_vtValType );

### Scripting Syntax

    ArgumentCollection.Add( Name, [Flags], [Value], [ArgType] );

### Parameters

Parameter | Type | Description
--- | --- | ---
Name | String | A name for the argument. The particular name chosen is not particularly important as long as it is unique in the ArgumentCollection. However having a good Argument name helps users understand how to use the Command. In the case of script-based custom commmands the names of the equivalent argument in the implementation does not need to match.
Flags | siArgumentFlags | Currently siArgumentInput is the only supported value for custom commands Default Value: siArgumentInput
Value | Variant | The argument default value (defaults to empty). Specifying a default value also serves the purpose of specifying the specific VARIANT type that is expected (See siVariantType). For example if the default value is a double then Softimage will attempt to convert any input argument to double before invoking the command. When not specified the argument will be passed in directly without conversion.
ArgType | siVariantType | The argument value type, by default the argument is set to siEmpty. This argument is optional for arguments which are normal Variant values, for example strings, ints, doubles and arrays. However to specify that the argument is a pointer to a Softimage object you must set this argument to siDispatch and the Value argument must be 0. (An easier approach is to use ArgumentCollection.AddObjectArgument instead.) If the argument is meant to receive a JScript object or JScript Array then siDispatch must be specified, as shown in the example below. Default Value: siEmpty

### Examples

#### JScript Example

    /*

    	This is an advanced JScript example showing how to use the powerful jscript

    	class and array features in conjunction with Softimage Custom Commands.

    	When a jscript plugin becomes very large it can be necessary to split the

    	code into multiple self-installed plugin script files and to organize the

    	code into classes.  This example shows how you can pass JScript objects and

    	arrays back and forth between these files via Softimage Custom Commands.

    */

    var strCmdName = "TestJScriptArgs"

    var oCmd = Application.CreateCommand( strCmdName  )

    oCmd.ScriptingName = strCmdName  ;

    // For demonstration purposes this is an embedded command.

    //

    // We need to copy the implementation of JScriptClass as well as the implementation

    // of the command so that JSCmdImpl can instantiate this class as the return value

    oCmd.Code = JSCmdImpl.toString()

    		+ JScriptClass.toString()

    		+ JScriptClass_Foo.toString() ;

    oCmd.Handler = "JSCmdImpl" ;

    oCmd.Language = "JScript" ;

    // You cannot print out a jscript object or a jscript array.  This is ok because

    // printing out large arrays would slow down execution of your script.

    oCmd.SetFlag(siNoLogging) ;

    // It is critical to specify siDispatch, otherwise Softimage will attempt

    // to convert the jscript object into a SAFEARRAY

    oCmd.Arguments.Add( "JSObjArg", siArgumentInput, 0, siDispatch ) ;

    // For normal custom command development this is the way to specify an array

    // argument.  But this means the array will be converted to a SAFEARRAY

    // (also called vbarray). This is important if you want your custom command

    // to be available to all other scripting languages and C++ API

    oCmd.Arguments.Add( "JSArrayToVBArray", siArgumentInput ) ;

    // If you only want your custom command to be available from other jscript

    // code then you can get better speed by passing the JScript array

    // untouched by specifying siDispatch

    oCmd.Arguments.Add( "JSArrayUnconverted", siArgumentInput, 0, siDispatch ) ;

    Application.AddCommand( oCmd ) ;

    // Create some data to pass to the command

    var oObj = new JScriptClass( 12 ) ;

    var jsarray = new Array( "A", 89, 2.5, "banana" ) ;

    // Invoke the command (which calls JSCmdImpl)

    var oRetVal = TestJScriptArgs(oObj,jsarray,jsarray) ;

    // Demonstrate that calling the command actually changed

    // MemberVar from 12 to 13

    logmessage( "oObj.MemberVar = " + oObj.MemberVar ) ;

    // Demonstrate that the command returned a jscript object

    logmessage( "oRetVal.MemberVar = " + oRetVal.MemberVar ) ;

    Application.RemoveCommand( strCmdName  ) ;

    // Simple jscript class

    function JScriptClass( in_x )

    {

    	// Remember the constructor argument

    	// as a member variable

    	this.MemberVar = in_x ;

    	// function

    	this.Foo = 	JScriptClass_Foo ;

    }

    // Function used as a method of JScriptClass

    function JScriptClass_Foo()

    {

    	return "Foo called" ;

    }

    // Custom command Implementation

    function JSCmdImpl(in_jscriptObj, in_vbarg, in_jsarg)

    {

    	logmessage( "JSCmdImpl called" );

    	// Demonstrate that we really have an instance of JScriptClass

    	logmessage( "in_jscriptObj.MemberVar = " + in_jscriptObj.MemberVar ) ;

    	logmessage( "in_jscriptObj.Foo function = " + in_jscriptObj.Foo() ) ;

    	// We can also change the content of the object passed to us

    	// and the caller will see the change.  This is an excellent

    	// way to share data between different script files

    	in_jscriptObj.MemberVar = 13 ;

    	// For a safearray we need to convert it (back) to

    	// a JScript array.  This is our only choice

    	// if we want the command to be called from vbscript

    	backAsJS = new VBArray( in_vbarg ).toArray();

    	logmessage( "in_vbarg[2] = " + backAsJS[2] ) ;

    	// Demonstrate that we really have a JScript array

    	logmessage( "in_jsarg[3] = " + in_jsarg[3] ) ;

    	// You can also return a JScript object

    	return new JScriptClass( 1000 ) ;

    }

    //Expected output:

    //INFO : JSCmdImpl called

    //INFO : in_jscriptObj.MemberVar = 12

    //INFO : in_jscriptObj.Foo function = Foo called

    //INFO : in_vbarg[2] = 2.5

    //INFO : in_jsarg[3] = banana

    //INFO : oObj.MemberVar = 13

    //INFO : oRetVal.MemberVar = 1000

### See Also

XSIApplication.CreateCommand Command ArgumentCollection ArgumentCollection.AddObjectArgument ArgumentCollection.AddWithHandler Argument