# ArgumentArray Class Reference

Related Scripting Object: ArgumentCollection

`#include <xsi_argument.h>`

Inheritance diagram for ArgumentArray:

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)

## 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

## 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

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:

- xsi_argument.h