The CValue object provides the convenience of a loosely typed variable inside a strictly typed language like C++.
In C++ all variables are strictly typed. For example "x" may be declared as an INT and "y" as a double. However scripting languages are often loosely typed, so a variable named x may contain a string or an integer or even a pointer to an object. The exact type of x is only determined when it is assigned a value, and the type of x can be changed at runtime by re-assigning its value.
For example, consider FCurve::AddKey. Because FCurves can be based on double, integer or boolean key values, there could be three versions of the function:
%FCurve::AddKey( ...double in_value... ) %FCurve::AddKey( ...integer in_value... ) %FCurve::AddKey( ...bool in_value... )
However, with the availability of a class like CValue, all three functions can be replaced by a single one:
FCurve::AddKey( ...const CValue& in_value... )
A CValue can store basic types like longs, floats and CString. By storing a CRef it can also contain a reference to any object in the scene. It can contain an entire array of values via CValueArray. It can also be used to hold a raw pointer to your own data or objects. Exceptionnaly, CVector3 objects can be contained in a CValue but other math objects are not automatically supported since they are not based on CBase.
The CValue::ChangeType and CValue::GetAsText methods are very useful for data conversion, for example to turn the value 55.5 to the string "55.5".
CValue is very similar to the VARIANT structure used in Win32. It is possible to convert between the two types using XSIVariantFromCValue and XSIVariantToCValue. However normally conversion is automatic, for example when using CComAPIHandler or when a custom C++ command is called from scripting. As a result it is possible to use this object without any knowledge of difficult COM datatypes like BSTR and SAFEARRAY. Because CValue provides operator overloads and various constructors it is much easier to use than a VARIANT and code using CValue will look very similar to the equivalent script code.
using namespace XSI; Application app; // x has type "empty" and no value CValue x ; // Give x a value of type siInt4 x = 5 ; // Change the type to siFloat by assigning a new value x = 6.0f; // Change the value 6.0 to the string "6.0" x.ChangeType( CValue::siString ) ; // Copy the value CValue y = x ; // It is possible to test exactly what type // of data a CValue contains if ( y.m_t == CValue::siString ) { app.LogMessage( L"y has the value " + (CString)y ) ; } // CValueArray containing 3 CValue objects CValueArray a(3) ; a[0] = CValue( 125 ); // Explicit construction a[1] = 135 ; // Implicit call to CValue( int ) a[2] = L"String" ; // Implicit call to CValue( const wchar_t* ) // Now copy the entire CValueArray into a CValue. // b will have type siArray CValue b( a ) ; // Use the cast operator to access the Array inside b LONG size = ((CValueArray&)b).GetCount() ; //Will print: 'INFO : "Array contents: (125,135,String)" app.LogMessage( L"Array contents: " + b.GetAsText() ) ; // Copy the first array item CValue item1 = ((CValueArray&)b)[1] ; // Will print: 'INFO : "Item1 contains 135 and has type 3" // Notice how using a temporary CValue can be a // convenient way to convert a number (m_t) to text. app.LogMessage( L"Item1 contains " + item1.GetAsText() + L" and has type " + CValue( (LONG)item1.m_t ).GetAsText() ) ;
using namespace XSI; Application app; Model root = app.GetActiveSceneRoot(); X3DObject myCube; root.AddGeometry( L"Cube", L"MeshSurface", CString(L"MyCube"), myCube ); // change the cube's position x parameter value Parameter posx( myCube.GetParameter(L"posx") ); CValue posxVal( posx.GetValue() ); posx.PutValue( ((double)posxVal + 5.75) * 2.0 ); app.LogMessage( posx.GetValue().GetAsText() );
#include <xsi_value.h>
Classes | |
union | ValueField |
Public Types | |
enum | DataType { siEmpty = 0, siInt2 = 2, siInt4 = 3, siInt8 = 10, siFloat = 4, siDouble = 5, siString = 8, siIDispatch = 9, siBool = 11, siIUnknown = 13, siInt1 = 16, siUInt1 = 17, siUInt2 = 18, siUInt4 = 19, siUInt8 = 20, siWStr = 31, siRef = 666, siArray, siPtr, siRefArray, siVector3, siLongArray, siFloatArray, siVector2f = 800, siVector3f, siVector4f, siQuaternionf, siRotationf, siMatrix3f, siMatrix4f, siColor4f, siShape, siBlob } |
DataType enumerator. More... | |
Public Member Functions | |
CValue () | |
virtual | ~CValue () |
CValue (const CValue &valSrc) | |
CValue (short valSrc) | |
CValue (unsigned short valSrc) | |
CValue (LONG valSrc) | |
CValue (int valSrc) | |
CValue (ULONG valSrc) | |
CValue (LLONG valSrc) | |
CValue (ULLONG valSrc) | |
CValue (float valSrc) | |
CValue (double valSrc) | |
CValue (bool valSrc) | |
CValue (const CString &valSrc) | |
CValue (const CRef &valSrc) | |
CValue (const CRefArray &valSrc) | |
CValue (unsigned char valSrc) | |
CValue (signed char valSrc) | |
CValue (const CValueArray &valSrc) | |
CValue (const CLongArray &valSrc) | |
CValue (const CFloatArray &valSrc) | |
CValue (const MATH::CVector3 &valSrc) | |
CValue (const MATH::CVector2f &valSrc) | |
CValue (const MATH::CVector3f &valSrc) | |
CValue (const MATH::CVector4f &val) | |
CValue (const MATH::CQuaternionf &val) | |
CValue (const MATH::CRotationf &val) | |
CValue (const MATH::CMatrix3f &val) | |
CValue (const MATH::CMatrix4f &val) | |
CValue (const MATH::CColor4f &val) | |
CValue (const MATH::CShape &val) | |
CValue (siPtrType valSrc) | |
CValue (const siBlobType &valSrc) | |
CValue (const wchar_t *valSrc) | |
CValue (const char *valSrc) | |
CValue & | operator= (const CValue &valSrc) |
CValue & | operator= (short valSrc) |
CValue & | operator= (unsigned short valSrc) |
CValue & | operator= (LONG valSrc) |
CValue & | operator= (int valSrc) |
CValue & | operator= (ULONG valSrc) |
CValue & | operator= (LLONG valSrc) |
CValue & | operator= (ULLONG valSrc) |
CValue & | operator= (float valSrc) |
CValue & | operator= (double valSrc) |
CValue & | operator= (bool valSrc) |
CValue & | operator= (const CString &valSrc) |
CValue & | operator= (const wchar_t *valSrc) |
CValue & | operator= (const char *valSrc) |
CValue & | operator= (const CRef &valSrc) |
CValue & | operator= (const CRefArray &valSrc) |
CValue & | operator= (const MATH::CVector3 &valSrc) |
CValue & | operator= (const MATH::CVector2f &valSrc) |
CValue & | operator= (const MATH::CVector3f &valSrc) |
CValue & | operator= (const MATH::CVector4f &valSrc) |
CValue & | operator= (const MATH::CMatrix3f &valSrc) |
CValue & | operator= (const MATH::CMatrix4f &valSrc) |
CValue & | operator= (const MATH::CRotationf &valSrc) |
CValue & | operator= (const MATH::CQuaternionf &valSrc) |
CValue & | operator= (const MATH::CColor4f &valSrc) |
CValue & | operator= (const MATH::CShape &valSrc) |
CValue & | operator= (unsigned char valSrc) |
CValue & | operator= (signed char valSrc) |
CValue & | operator= (const CValueArray &valSrc) |
CValue & | operator= (const CLongArray &valSrc) |
CValue & | operator= (const CFloatArray &valSrc) |
CValue & | operator= (siPtrType valSrc) |
CValue & | operator= (const siBlobType &valSrc) |
operator short () const | |
operator unsigned short () const | |
operator LONG () const | |
operator int () const | |
operator ULONG () const | |
operator LLONG () const | |
operator ULLONG () const | |
operator float () const | |
operator double () const | |
operator bool () const | |
operator CString () const | |
operator CRef () const | |
operator CRefArray () const | |
operator unsigned char () const | |
operator signed char () const | |
operator CValueArray & () const | |
operator CLongArray & () const | |
operator CFloatArray & () const | |
operator MATH::CVector3 () const | |
operator MATH::CVector2f () const | |
operator MATH::CVector3f () const | |
operator MATH::CVector4f () const | |
operator MATH::CMatrix3f () const | |
operator MATH::CMatrix4f () const | |
operator MATH::CRotationf () const | |
operator MATH::CQuaternionf () const | |
operator MATH::CColor4f () const | |
operator MATH::CShape () const | |
operator siPtrType () const | |
operator siBlobType & () const | |
bool | operator== (const CValue &valSrc) const |
bool | operator== (short) const |
bool | operator== (unsigned short) const |
bool | operator== (LONG) const |
bool | operator== (int) const |
bool | operator== (ULONG) const |
bool | operator== (LLONG) const |
bool | operator== (ULLONG) const |
bool | operator== (float) const |
bool | operator== (double) const |
bool | operator== (bool) const |
bool | operator== (const CString &) const |
bool | operator== (const wchar_t *) const |
bool | operator== (const char *) const |
bool | operator== (const CRef &) const |
bool | operator== (const CRefArray &) const |
bool | operator== (unsigned char) const |
bool | operator== (signed char) const |
bool | operator== (const CValueArray &) const |
bool | operator== (const CLongArray &) const |
bool | operator== (const CFloatArray &) const |
bool | operator== (const siPtrType) const |
bool | operator== (const siBlobType &) const |
bool | operator== (const MATH::CVector3 &) const |
bool | operator== (const MATH::CVector2f &) const |
bool | operator== (const MATH::CVector3f &) const |
bool | operator== (const MATH::CVector4f &) const |
bool | operator== (const MATH::CMatrix3f &) const |
bool | operator== (const MATH::CMatrix4f &) const |
bool | operator== (const MATH::CRotationf &) const |
bool | operator== (const MATH::CQuaternionf &) const |
bool | operator== (const MATH::CColor4f &) const |
bool | operator== (const MATH::CShape &) const |
bool | operator!= (const CValue &valSrc) const |
bool | operator> (const CValue &val) const |
bool | operator< (const CValue &val) const |
bool | operator>= (const CValue &val) const |
bool | operator<= (const CValue &val) const |
void | ChangeType (CValue::DataType in_type, const CValue *in_pSrc=NULL) |
void | Clear () |
void | Attach (CValue &in_valSrc) |
CValue | Detach () |
CString | GetAsText () const |
bool | IsEmpty () const |
enum DataType |
DataType enumerator.
siEmpty |
empty type |
siInt2 |
2 bytes signed integer number type (-32768..32767) |
siInt4 |
4 bytes signed integer number type (-2147483648..2147483647) |
siInt8 |
8 bytes signed integer number type (-9223372036854775808..9223372036854775807) |
siFloat |
float type |
siDouble |
double type |
siString |
A normal Softimage string. In the C++ API this corresponds to the CString object. |
siIDispatch |
IDispatch pointer type. This is the data type for the COM objects that expose methods and properties to scripting in addition to all Softimage objects in the scripting Object Model while |
siBool |
boolean type |
siIUnknown |
IUnknown pointer type. This represents a COM object. Normally such objects are not accessible to the C++ API or to scripting. The value is stored in |
siInt1 |
byte type (-128..127) |
siUInt1 |
unsigned byte type (0..255) |
siUInt2 |
2 bytes unsigned integer number type (0..65535) |
siUInt4 |
4 bytes unsigned integer number type (0..4294967295) |
siUInt8 |
8 bytes unsigned integer number type (0..18446744073709551615) |
siWStr |
Null-terminated wide character string. This data type is rarely encountered because |
siRef |
CRef object type |
siArray |
Array of type CValue |
siPtr |
Pointer type |
siRefArray |
CRefArray object type |
siVector3 |
CVector3 object type |
siLongArray |
CLongArray object type |
siFloatArray |
CFloatArray object type |
siVector2f |
CVector2f object type |
siVector3f |
CVector3f object type |
siVector4f |
CVector4f object type |
siQuaternionf |
CQuaternionf object type |
siRotationf |
CRotationf object type |
siMatrix3f |
CMatrix3f object type |
siMatrix4f |
CMatrix4f object type |
siColor4f |
CColor4f object type |
siShape |
CShape object type |
siBlob |
Blob object type |
CValue | ( | ) |
Default constructor.
virtual ~CValue | ( | ) | [virtual] |
Default destructor.
CValue | ( | short | valSrc | ) |
Constructor.
valSrc | short value |
CValue | ( | unsigned short | valSrc | ) |
Constructor.
valSrc | unsigned short value |
CValue | ( | LONG | valSrc | ) |
Constructor.
valSrc | LONG value |
CValue | ( | int | valSrc | ) |
Constructor. Has the same results as using the LONG constructor.
valSrc | int value |
CValue | ( | ULONG | valSrc | ) |
Constructor.
valSrc | ULONG value |
CValue | ( | LLONG | valSrc | ) |
Constructor.
valSrc | LLONG value |
CValue | ( | ULLONG | valSrc | ) |
Constructor.
valSrc | ULLONG value |
CValue | ( | float | valSrc | ) |
Constructor.
valSrc | float value |
CValue | ( | double | valSrc | ) |
Constructor.
valSrc | double value |
CValue | ( | bool | valSrc | ) |
Constructor.
valSrc | bool value |
CValue | ( | unsigned char | valSrc | ) |
Constructor.
valSrc | unsigned char value |
CValue | ( | signed char | valSrc | ) |
Constructor.
valSrc | signed char value |
CValue | ( | const CValueArray & | valSrc | ) |
Constructor.
valSrc | CValueArray value |
CValue | ( | const CLongArray & | valSrc | ) |
CValue | ( | const CFloatArray & | valSrc | ) |
CValue | ( | const MATH::CVector3 & | valSrc | ) |
CValue | ( | const MATH::CVector2f & | valSrc | ) |
CValue | ( | const MATH::CVector3f & | valSrc | ) |
CValue | ( | const MATH::CVector4f & | val | ) |
CValue | ( | const MATH::CQuaternionf & | val | ) |
CValue | ( | const MATH::CRotationf & | val | ) |
CValue | ( | const MATH::CMatrix3f & | val | ) |
CValue | ( | const MATH::CMatrix4f & | val | ) |
CValue | ( | const MATH::CColor4f & | val | ) |
CValue | ( | const MATH::CShape & | val | ) |
CValue | ( | siPtrType | valSrc | ) |
Constructor.
valSrc | pointer value |
CValue | ( | const siBlobType & | valSrc | ) |
Constructor.
valSrc | siBlobType value |
CValue | ( | const wchar_t * | valSrc | ) |
Constructor.
valSrc | string value |
CValue | ( | const char * | valSrc | ) |
Constructor.
valSrc | Ascii string value |
CValue& operator= | ( | short | valSrc | ) |
Assignment
valSrc | short value |
CValue& operator= | ( | unsigned short | valSrc | ) |
Assignment
valSrc | unsigned short value |
CValue& operator= | ( | LONG | valSrc | ) |
Assignment
valSrc | LONG value |
CValue& operator= | ( | int | valSrc | ) |
Assignment
valSrc | int value |
CValue& operator= | ( | ULONG | valSrc | ) |
Assignment
valSrc | ULONG value |
CValue& operator= | ( | LLONG | valSrc | ) |
Assignment
valSrc | LLONG value |
CValue& operator= | ( | ULLONG | valSrc | ) |
Assignment
valSrc | ULLONG value |
CValue& operator= | ( | float | valSrc | ) |
Assignment
valSrc | float value |
CValue& operator= | ( | double | valSrc | ) |
Assignment
valSrc | double value |
CValue& operator= | ( | bool | valSrc | ) |
Assignment
valSrc | bool value |
CValue& operator= | ( | const wchar_t * | valSrc | ) |
Assignment
valSrc | Wide Character String |
CValue& operator= | ( | const char * | valSrc | ) |
Assignment
valSrc | Ascii string value. |
CValue& operator= | ( | const MATH::CVector3 & | valSrc | ) |
CValue& operator= | ( | const MATH::CVector2f & | valSrc | ) |
CValue& operator= | ( | const MATH::CVector3f & | valSrc | ) |
CValue& operator= | ( | const MATH::CVector4f & | valSrc | ) |
CValue& operator= | ( | const MATH::CMatrix3f & | valSrc | ) |
CValue& operator= | ( | const MATH::CMatrix4f & | valSrc | ) |
CValue& operator= | ( | const MATH::CRotationf & | valSrc | ) |
CValue& operator= | ( | const MATH::CQuaternionf & | valSrc | ) |
CValue& operator= | ( | const MATH::CColor4f & | valSrc | ) |
CValue& operator= | ( | const MATH::CShape & | valSrc | ) |
CValue& operator= | ( | unsigned char | valSrc | ) |
Assignment
valSrc | unsigned char value |
CValue& operator= | ( | signed char | valSrc | ) |
Assignment
valSrc | signed char value |
CValue& operator= | ( | const CValueArray & | valSrc | ) |
Assignment
valSrc | CValueArray value |
CValue& operator= | ( | const CLongArray & | valSrc | ) |
Assignment
valSrc | CLongArray value |
CValue& operator= | ( | const CFloatArray & | valSrc | ) |
Assignment
valSrc | CFloatArray value |
CValue& operator= | ( | siPtrType | valSrc | ) |
Assignment
valSrc | pointer value |
CValue& operator= | ( | const siBlobType & | valSrc | ) |
Assignment
valSrc | siBlobType value |
operator short | ( | ) | const |
short extractor
operator unsigned short | ( | ) | const |
unsigned short extractor
operator LONG | ( | ) | const |
LONG extractor
operator int | ( | ) | const |
int extractor
operator ULONG | ( | ) | const |
ULONG extractor
operator LLONG | ( | ) | const |
LLONG extractor
operator ULLONG | ( | ) | const |
ULLONG extractor
operator float | ( | ) | const |
float extractor
operator double | ( | ) | const |
double extractor
operator bool | ( | ) | const |
bool extractor
operator CRefArray | ( | ) | const |
operator unsigned char | ( | ) | const |
unsigned byte extractor
operator signed char | ( | ) | const |
byte extractor
operator CValueArray & | ( | ) | const |
CValueArray& extractor
operator CLongArray & | ( | ) | const |
CLongArray& extractor
operator CFloatArray & | ( | ) | const |
CFloatArray& extractor
operator MATH::CVector3 | ( | ) | const |
CVector3 extractor
operator MATH::CVector2f | ( | ) | const |
CVector2f extractor
operator MATH::CVector3f | ( | ) | const |
CVector3f extractor
operator MATH::CVector4f | ( | ) | const |
CVector4f extractor
operator MATH::CMatrix3f | ( | ) | const |
CMatrix3f extractor
operator MATH::CMatrix4f | ( | ) | const |
CMatrix4f extractor
operator MATH::CRotationf | ( | ) | const |
CRotationf extractor
operator MATH::CQuaternionf | ( | ) | const |
CQuaternionf extractor
operator MATH::CColor4f | ( | ) | const |
CColor4f extractor
operator MATH::CShape | ( | ) | const |
CShape extractor
operator siPtrType | ( | ) | const |
CValue::siPtrType extractor. The data returned by this function depends on the type of this CValue:
siIDispatch
, pointer type returned: IDispatch*
siIUnknown
, pointer type returned: IUnknown*
siPtr
, pointer type returned: void*
m_u.pval
, do not access m_u.pval
directly otherwise the result may be undefined.using namespace XSI; CComAPIHandler uitoolkit; uitoolkit.CreateInstance( L"XSI.UIToolkit"); // retrieves the IDispatch pointer of the Softimage UI toolkit object CValue dispVal = uitoolkit.GetRef(); IDispatch* pDisp = (IDispatch*)(CValue::siPtrType)dispVal;
operator siBlobType & | ( | ) | const |
siBlobType extractor
bool operator== | ( | short | val | ) | const [inline] |
short equality operator
bool operator== | ( | unsigned short | val | ) | const [inline] |
unsigned short equality operator
bool operator== | ( | LONG | val | ) | const [inline] |
LONG equality operator
bool operator== | ( | int | val | ) | const [inline] |
int equality operator
bool operator== | ( | ULONG | val | ) | const [inline] |
ULONG equality operator
bool operator== | ( | LLONG | val | ) | const [inline] |
LLONG equality operator
bool operator== | ( | ULLONG | val | ) | const [inline] |
ULLONG equality operator
bool operator== | ( | float | val | ) | const [inline] |
float equality operator
bool operator== | ( | double | val | ) | const [inline] |
double equality operator
bool operator== | ( | bool | val | ) | const [inline] |
bool equality operator
bool operator== | ( | const wchar_t * | val | ) | const [inline] |
wchar_t * equality operator
bool operator== | ( | const char * | val | ) | const [inline] |
char * equality operator
bool operator== | ( | unsigned char | val | ) | const [inline] |
unsigned byte equality operator
bool operator== | ( | signed char | val | ) | const [inline] |
byte equality operator
bool operator== | ( | const CValueArray & | ) | const |
CValueArray& equality operator
bool operator== | ( | const CLongArray & | ) | const |
CLongArray& equality operator
bool operator== | ( | const CFloatArray & | ) | const |
CFloatArray& equality operator
bool operator== | ( | const siPtrType | val | ) | const [inline] |
siPtrType equality operator
bool operator== | ( | const siBlobType & | val | ) | const [inline] |
siBlobType equality operator
bool operator== | ( | const MATH::CVector3 & | val | ) | const [inline] |
CVector3 equality operator
bool operator== | ( | const MATH::CVector2f & | val | ) | const [inline] |
CVector2f equality operator
bool operator== | ( | const MATH::CVector3f & | val | ) | const [inline] |
CVector3f equality operator
bool operator== | ( | const MATH::CVector4f & | val | ) | const [inline] |
CVector4f equality operator
bool operator== | ( | const MATH::CMatrix3f & | val | ) | const [inline] |
CMatrix3f equality operator
bool operator== | ( | const MATH::CMatrix4f & | val | ) | const [inline] |
CMatrix4f equality operator
bool operator== | ( | const MATH::CRotationf & | val | ) | const [inline] |
CRotationf equality operator
bool operator== | ( | const MATH::CQuaternionf & | val | ) | const [inline] |
CQuaternionf equality operator
bool operator== | ( | const MATH::CColor4f & | val | ) | const [inline] |
CColor4f equality operator
bool operator== | ( | const MATH::CShape & | val | ) | const [inline] |
CShape equality operator
bool operator> | ( | const CValue & | val | ) | const |
Greater than operator. Return true if this value is greater than val, false otherwise. Return false if types don't match.
val | Value to test. |
bool operator< | ( | const CValue & | val | ) | const |
Less than operator. Return true if this value is less than val, false otherwise. Return false if types don't match.
val | Value to test. |
bool operator>= | ( | const CValue & | val | ) | const |
Greater than or equal to operator. Return true if this value is greater or equal to val, false otherwise. Return false if types don't match.
val | Value to test. |
bool operator<= | ( | const CValue & | val | ) | const |
Less than or equal to operator. Return true if this value is less or equal to val, false otherwise. Return false if types don't match.
val | Value to test. |
void ChangeType | ( | CValue::DataType | in_type, |
const CValue * | in_pSrc = NULL |
||
) |
Converts the object into a given type. If in_pSrc is NULL, the conversion is done in place, otherwise the object is copied from in_pSrc and then converted. This function can also be used to create a CValue object of type siIDispatch or siIUnknown, see example below.
in_type | Type to convert into. |
in_pSrc | Pointer to the CValue to convert |
using namespace XSI; Application app; CValue val((LONG)55); app.LogMessage( L"Value = " + val.GetAsText() ); val.ChangeType( CValue::siDouble ); app.LogMessage( L"Value = " + val.GetAsText() );
using namespace XSI; Application app; CComAPIHandler uitoolkit; uitoolkit.CreateInstance( L"XSI.UIToolkit"); // retrieves a IDispatch pointer from the Softimage UI toolkit object CValue dispVal = uitoolkit.GetRef(); IDispatch* pDisp = (IDispatch*)(CValue::siPtrType)dispVal; // create a CValue of type IUnknown IUnknown* pUnk = NULL; pDisp->QueryInterface( IID_IUnknown, (void**)&pUnk ); CValue valUnk((CValue::siPtrType)pUnk); valUnk.ChangeType( CValue::siIUnknown ); pDisp->Release(); pUnk->Release();
void Clear | ( | ) |
Clear this CValue object
void Attach | ( | CValue & | in_valSrc | ) |
CValue Detach | ( | ) |
CString GetAsText | ( | ) | const |
Returns the CValue content into a text string.
bool IsEmpty | ( | ) | const [inline] |
Convenient method to know if the object is set with a value or not.