Public Member Functions
ArgumentArray Class Reference

Detailed 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 ArgumentArray::GetItem function. However it is the order of the arguments in the collection which determines how they are passed to the command implementation. 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:

Warning:
This specialized array is returned by Command::GetArguments, it is not meant to be created and modified in user-defined functions. If you want to add and remove arbitrary items to a collection, you must use a CRefArray instead.
Since:
4.0

#include <xsi_argument.h>

Inheritance diagram for ArgumentArray:
Inheritance graph
[legend]

List of all members.

Public Member Functions

 ArgumentArray ()
 ~ArgumentArray ()
 ArgumentArray (const CRef &in_ref)
 ArgumentArray (const ArgumentArray &in_obj)
bool IsA (siClassID in_ClassID) const
siClassID GetClassID () const
ArgumentArrayoperator= (const ArgumentArray &in_obj)
ArgumentArrayoperator= (const CRef &in_ref)
Argument GetItem (LONG in_index) const
Argument GetItem (const CString &in_name) const
Argument operator[] (LONG in_index)
const Argument operator[] (LONG in_index) const
LONG GetCount () const
Argument Add (const CString &in_strName, const CValue &in_dftValue=CValue())
Argument AddObjectArgument (const CString &in_strName)
Argument AddWithHandler (const CString &in_strName, const CString &in_strHandlerName, const CString &in_Default=CString())
Argument AddWithHandler (const CString &in_strName, ArgumentHandler &in_Handler, const CString &in_Default=CString())
Argument AddCopy (const Argument &in_src)
CStatus RemoveAll ()
CStatus Remove (LONG in_index)
CStatus Remove (const CString &in_strArgName)

Constructor & Destructor Documentation

Default constructor.

Default destructor.

ArgumentArray ( const CRef in_ref)

Constructor.

Parameters:
in_refconstant reference object.
ArgumentArray ( const ArgumentArray in_obj)

Copy constructor.

Parameters:
in_objconstant class object.

Member Function Documentation

bool IsA ( siClassID  in_ClassID) const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:
in_ClassIDclass type.
Returns:
True if the class is compatible, false otherwise.

Reimplemented from CBase.

siClassID GetClassID ( ) const [virtual]

Returns the type of the API class.

Returns:
The class type.

Implements CBase.

ArgumentArray& operator= ( const ArgumentArray in_obj)

Creates an object from another object.

Parameters:
in_objconstant class object.
Returns:
The new ArgumentArray object.
ArgumentArray& operator= ( const CRef in_ref)

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:
in_refconstant class object.
Returns:
The new ArgumentArray object.
Argument GetItem ( LONG  in_index) const

Returns an Argument object at a specified index in the array.

Parameters:
in_indexThe index of the argument.
Returns:
The specified Argument object.
Since:
4.0
Argument GetItem ( const CString in_name) const

Returns an Argument object based on its name.

Parameters:
in_nameThe name of the argument.
Returns:
The specified Argument object.
Since:
4.0
Argument operator[] ( LONG  in_index)

Accessor to elements at a given index.

Parameters:
in_indexThe index of the argument
Returns:
The specified Argument object.
Since:
4.0
const Argument operator[] ( LONG  in_index) const

Accessor to elements at a given index. This function can only be called by constant objects, the returned value is read-only.

Parameters:
in_indexThe index of the argument
Returns:
The read-only Argument object.
Since:
4.0
LONG GetCount ( ) const

Returns the number of Argument objects in the array.

Returns:
The number of Argument objects.
Argument Add ( const CString in_strName,
const CValue in_dftValue = CValue() 
)

Adds an argument to the Command definition. To add an argument that receives an object call, use ArgumentArray::AddObjectArgument instead. To use an ArgumentHandler use ArgumentArray::AddWithHandler instead.

This function is only available on custom commands. Normally this is called during the definition of a command (for example during the commandname_Init callback of a self-installed plug-in).

Parameters:
in_strNameA name for the argument. The name chosen is not particularly important as long as it is unique in the ArgumentArray. However having a good argument name helps users understand how to use the Command.
in_dftValueThe argument default value (optional). Specifying a default value also serves the purpose of specifying the specific CValue type that is expected (See CValue::DataType). For example if the default value is a double then XSI 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.
Returns:
The new Argument object.
Since:
4.0
Argument AddObjectArgument ( const CString in_strName)

Adds an Argument to the Command definition which will receive an XSI object as its value when the Command is invoked. Because the argument uses the ::siArgHandlerSingleObj ArgumentHandler it automatically handles conversion of strings that represent objects in the scene. It also automatically converts from a scripting (COM-based) object to a CRef-based C++ object. See the example in the documentation for the Command object.

To receive a CValueArray containing multiple objects, use ArgumentArray::AddWithHandler with ::siArgHandlerCollection, or ::siArgHandlerMarkedParameters.

Parameters:
in_strNameA name for the argument. The name chosen is not particularly important as long as it is unique in the ArgumentArray. However having a good argument name helps users understand how to use the Command.
Returns:
The new Argument object.
Since:
4.0
Argument AddWithHandler ( const CString in_strName,
const CString in_strHandlerName,
const CString in_Default = CString() 
)

Adds an argument to the command definition that uses an ArgumentHandler.

Parameters:
in_strNameName of the new argument
in_strHandlerNameName of the ArgumentHandler, see the ::siArgumentHandler enum for a complete list of supported handlers.
in_DefaultNormally Argument Handlers do not require a default value, but some adjust their behavior if a string is provided. For example if the string * is provided in conjunction with the Collection Argument Handler then all the objects in the scene are sent to the command rather than the current selection. This behavior is documented with the ::siArgumentHandler enum.
Returns:
The new Argument object.
See also:
Argument, ArgumentHandler
Since:
4.0
Argument AddWithHandler ( const CString in_strName,
ArgumentHandler in_Handler,
const CString in_Default = CString() 
)

Alternative version of ArgumentArray::AddWithHandler that takes an existing ArgumentHandler object rather than the string name of the ArgumentHandler.

Parameters:
in_strNameName of the new argument
in_HandlerArgumentHandler object.
in_DefaultNormally Argument Handlers do not require a default value, but some adjust their behavior if a string is provided. For example if the string * is provided in conjunction with the Collection Argument Handler then all the objects in the scene are sent to the command rather than the current selection. This behavior is documented with the ::siArgumentHandler enum.
Returns:
The new Argument object.
See also:
Argument, ArgumentHandler
Since:
4.0
Argument AddCopy ( const Argument in_src)

Appends a copy of an argument. Because the name must be unique for each ArgumentArray, the Argument that is being copied must belong to a different command than the one that it is being added to. This function would normally not be used for custom commands implemented as self-installed plug-ins.

Parameters:
in_srcArgument to copy
Returns:
The new Argument object.
Since:
4.0
CStatus RemoveAll ( )

Removes all arguments from the collection. This function would normally not be used for custom commands implemented as self-installed plug-ins.

Returns:
CStatus::OK
CStatus::Fail
See also:
Command::Update
Since:
4.0
CStatus Remove ( LONG  in_index)

Removes a single argument from the collection. This function would normally not be used for custom commands implemented as self-installed plug-ins.

Parameters:
in_index0-based index
Returns:
CStatus::OK
CStatus::Fail
See also:
Command::Update
Since:
4.0
CStatus Remove ( const CString in_strArgName)

Removes a single argument from the collection. This function would normally not be used for custom commands implemented as self-installed plug-ins.

Parameters:
in_strArgNameName of the Argument
Returns:
CStatus::OK
CStatus::Fail
See also:
Command::Update
Since:
4.0

The documentation for this class was generated from the following file: