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:

- 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

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