ArgumentArray Class Reference
 
 
 
ArgumentArray Class Reference

#include <xsi_argument.h>


Class 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
Inheritance diagram for ArgumentArray:
CBase

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

Default constructor.

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
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_index 0-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_strArgName Name 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: