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:

To define the arguments of a new custom command. The definition of the arguments is normally done in the commandname_Init callback of a self-installed plug-in, as shown in the example in the Command object documentation.

To specify specific argument values when a command is executed (see Command::Execute).

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:

[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
ArgumentArray &	operator= (const ArgumentArray &in_obj)
ArgumentArray &	operator= (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

ArgumentArray ( )

Default constructor.

~ArgumentArray ( )

Default destructor.

ArgumentArray ( const CRef & in_ref )

Constructor.

Parameters:

in_ref constant reference object.

ArgumentArray ( const ArgumentArray & in_obj )

Copy constructor.

Parameters:

in_obj constant 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_ClassID class 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_obj constant 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_ref constant 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_index The 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_name The 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_index The 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_index The 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_strName	A 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_dftValue	The 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_strName A 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_strName	Name of the new argument
in_strHandlerName	Name of the ArgumentHandler, see the ::siArgumentHandler enum for a complete list of supported handlers.
in_Default	Normally 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_strName	Name of the new argument
in_Handler	ArgumentHandler object.
in_Default	Normally 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_src Argument to copy