ArgumentCollection

Related C++ Class: ArgumentArray

Introduced

v2.0

Description

This object is owned by a Command object and holds a collection of Argument objects.

Each Argument has a unique name, which is useful for documentation purposes and to faciliate the ArgumentCollection.Item method. However it is the order of the arguments in the collection which determines how they are passed to the command implementation. For script-based implementations the number of arguments must exactly match the number of arguments expected by the function (or subroutine) that implements the command. (For commands implemented with the C++ API all the arguments are passed together in a CValueArray).

Even though the number of arguments defined must exactly match those expected by the implementation, it is not always necessary to specify each argument when invoking a command. In that case a default value is passed, based on the definition or the action of an ArgumentHandler.

This object can be used in two different ways - to define the arguments of a new custom command and to specify specific argument values when a command is executed. The definition of the arguments is normally done on a command after XSIApplication.CreateCommand has been called and before XSIApplication.AddCommand is called. Alternatively an existing custom command can be changed by changing the argument collection and then calling Command.Update.

Note: You access a specific argument using the ArgumentCollection.Item method, for example, oCommand.Arguments.Item("strArgument"). Usually the argument returns the value assigned; however, if the argument is not available, "Nothing" in VBScript or "NULL" in COM-based C++ is returned.

Methods

Add AddCopy AddObjectArgument AddWithHandler
Remove RemoveAll    
       

Properties

Count operator Item operator    
       

Examples

1. JScript Example

/*
        This example finds the Argument names for the SICreateImageClip command. 
        When working with the ISIVTCollection returned by SICreateImageClip, you
        need to know the exact names of the output arguments.
*/
var e = new Enumerator( Application.Commands ); 
for ( ; ! e.atEnd(); e.moveNext() ) {
        if ( e.item().ScriptingName == "SICreateImageClip" ) {
                var cmd = e.item();
                for ( var i=0; i<cmd.Arguments.Count; i++ ) {
                        // the pipe '|' characters allow you to see 
                        // any spaces before or after the name
                        Application.LogMessage( "|" + cmd.Arguments(i).Name + "|" );
                }
        }
}
// Logs the following results:
//INFO : |FileName|
//INFO : |Name|
//INFO : |Clip|

2. VBScript Example

set args = Application.Commands("Twist").Arguments
LogMessage "arguments count: " & args.count

See Also

Command.Arguments Command.Execute XSIApplication.CreateCommand