ArgumentArray Class
Reference
#include <xsi_argument.h>
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:
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) |
| ArgumentArray | ( | ) |
Default constructor.
| ~ArgumentArray | ( | ) |
Default destructor.
| ArgumentArray | ( | const CRef & | in_ref | ) |
Constructor.
| in_ref | constant reference object. |
| ArgumentArray | ( | const ArgumentArray & | in_obj | ) |
Copy constructor.
| in_obj | constant class object. |
| bool IsA | ( | siClassID | in_ClassID | ) | const [virtual] |
Returns true if a given class type is compatible with this API class.
| in_ClassID | class type. |
Reimplemented from CBase.
| siClassID GetClassID | ( | ) | const [virtual] |
| ArgumentArray& operator= | ( | const ArgumentArray & | in_obj | ) |
Creates an object from another object.
| in_obj | constant class 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.
| in_ref | constant class object. |
| Argument GetItem | ( | LONG | in_index | ) | const |
| Argument operator[] | ( | LONG | in_index | ) |
Accessor to elements at a given index.
| in_index | The index of the argument |
| 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.
| in_index | The index of the argument |
| LONG GetCount | ( | ) | const |
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).
| 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. |
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.
| 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. |
| 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.
| 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. |
| 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.
| 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. |
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.
| in_src | Argument to copy |
| CStatus RemoveAll | ( | ) |
Removes all arguments from the collection. This function would normally not be used for custom commands implemented as self-installed plug-ins.
| 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.
| in_index | 0-based index |
Removes a single argument from the collection. This function would normally not be used for custom commands implemented as self-installed plug-ins.
| in_strArgName | Name of the Argument |