XSI::CValue

CValue Class Reference

The CValue object provides the convenience of a loosely typed variable inside a strictly typed language like C++. More...

#include <xsi_value.h>

List of all members.

Public Types

enum DataType {
  siEmpty = 0,
  siInt2 = 2,
  siInt4 = 3,
  siFloat = 4,
  siDouble = 5,
  siString = 8,
  siIDispatch = 9,
  siBool = 11,
  siIUnknown = 13,
  siInt1 = 16,
  siUInt1 = 17,
  siUInt2 = 18,
  siUInt4 = 19,
  siWStr = 31,
  siRef = 666,
  siArray = 667,
  siPtr = 668,
  siRefArray = 669,
  siVector3 = 670
}

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 (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 MATH::CVector3 &valSrc)

CValue (siPtrType valSrc)

CValue (const wchar_t *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= (float valSrc)

CValue & operator= (double valSrc)

CValue & operator= (bool valSrc)

CValue & operator= (const CString &valSrc)

CValue & operator= (const wchar_t *valSrc)

CValue & operator= (const CRef &valSrc)

CValue & operator= (const CRefArray &valSrc)

CValue & operator= (const MATH::CVector3 &valSrc)

CValue & operator= (unsigned char valSrc)

CValue & operator= (signed char valSrc)

CValue & operator= (const CValueArray &valSrc)

CValue & operator= (siPtrType valSrc)

operator short () const

operator unsigned short () const

operator LONG () const

operator int () const

operator ULONG () 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 MATH::CVector3 () const

operator siPtrType () 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== (float) const

bool operator== (double) const

bool operator== (bool) const

bool operator== (const CString &) const

bool operator== (const wchar_t *) 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 siPtrType) const

bool operator== (const MATH::CVector3 &) const

bool operator!= (const CValue &valSrc) 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

Public Attributes

XSI::CValue::ValueField m_u

Classes

union ValueField

Detailed Description

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.

Example:

Demonstrates CValue usage

        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() ) ;

Example:

Demonstrates using CValue with the GetValue command

        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() );

Member Enumeration Documentation

enum DataType

DataType enumerator.

Enumerator:

siEmpty	empty type
siInt2	2 bytes signed integer number type (-32768..32767)
siInt4	4 bytes signed integer number type (-2147483648..2147483647)
siFloat	float type
siDouble	double type
siString	A normal XSI 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 XSI objects in the scripting Object Model while siRef is the normal representation of XSI objects in the C++ API. See CComAPIHandler and XSI::ConvertObject for more information about handling objects of this type in the C++ API. The value is stored in m_u.pval; however you should never access it directly from this structure member, because the result may be undefined. Use CValue::operator siPtrType() instead to access the IDispatch pointer.
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 m_u.pval; however you should never access it directly from this structure member, because the result may be undefined. Use CValue::operator siPtrType() instead to access the IUnknown pointer.
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)
siWStr	Null-terminated wide character string. This data type is rarely encountered because siString is the recommended representation of all XSI strings.
siRef	CRef object type
siArray	Array of type CValue
siPtr	Pointer type
siRefArray	CRefArray object type
siVector3	CVector3 object type

Constructor & Destructor Documentation

CValue ( )

Default constructor.

virtual ~CValue ( ) [virtual]

Default destructor.

CValue ( const CValue & valSrc )

Constructor.

Parameters:

valSrc

CValue object

CValue ( short valSrc )

Constructor.

Parameters:

valSrc

short value

CValue ( unsigned short valSrc )

Constructor.

Parameters:

valSrc

unsigned short value

CValue ( LONG valSrc )

Constructor.

Parameters:

valSrc

LONG value

CValue ( int valSrc )

Constructor. Has the same results as using the LONG constructor.

Parameters:

valSrc

int value

CValue ( ULONG valSrc )

Constructor.

Parameters:

valSrc

ULONG value

CValue ( float valSrc )

Constructor.

Parameters:

valSrc

float value

CValue ( double valSrc )

Constructor.

Parameters:

valSrc

double value

CValue ( bool valSrc )

Constructor.

Parameters:

valSrc

bool value

CValue ( const CString & valSrc )

Constructor.

Parameters:

valSrc

CString value

CValue ( const CRef & valSrc )

Constructor.

Parameters:

valSrc

CRef value

CValue ( const CRefArray & valSrc )

Constructor.

Parameters:

valSrc

CRefArray value

Since:: 4.0

CValue ( unsigned char valSrc )

Constructor.

Parameters:

valSrc

unsigned char value

CValue ( signed char valSrc )

Constructor.

Parameters:

valSrc

signed char value

CValue ( const CValueArray & valSrc )

Constructor.

Parameters:

valSrc

CValueArray value

CValue ( const MATH::CVector3 & valSrc )

Constructor.

Parameters:

valSrc

MATH::CVector3 value

Since:: 5.1

CValue ( siPtrType valSrc )

Constructor.

Parameters:

valSrc

pointer value

CValue ( const wchar_t * valSrc )

Constructor.

Parameters:

valSrc

string value

Member Function Documentation

CValue& operator= ( const CValue & valSrc )

Assignment

Parameters:

valSrc

CValue value

CValue& operator= ( short valSrc )

Assignment

Parameters:

valSrc

short value

CValue& operator= ( unsigned short valSrc )

Assignment

Parameters:

valSrc

unsigned short value

CValue& operator= ( LONG valSrc )

Assignment

Parameters:

valSrc

LONG value

CValue& operator= ( int valSrc )

Assignment

Parameters:

valSrc

int value

CValue& operator= ( ULONG valSrc )

Assignment

Parameters:

valSrc

ULONG value

CValue& operator= ( float valSrc )

Assignment

Parameters:

valSrc

float value

CValue& operator= ( double valSrc )

Assignment

Parameters:

valSrc

double value

CValue& operator= ( bool valSrc )

Assignment

Parameters:

valSrc

bool value

CValue& operator= ( const CString & valSrc )

Assignment

Parameters:

valSrc

CString value

CValue& operator= ( const wchar_t * valSrc )

Assignment

Parameters:

valSrc

Wide Character String

CValue& operator= ( const CRef & valSrc )

Assignment

Parameters:

valSrc

CRef value

CValue& operator= ( const CRefArray & valSrc )

Assignment

Parameters:

valSrc

CRefArray value

Since:: 4.0

CValue& operator= ( const MATH::CVector3 & valSrc )

Assignment

Parameters:

valSrc

MATH::CVector3 value

Since:: 5.1

CValue& operator= ( unsigned char valSrc )

Assignment

Parameters:

valSrc

unsigned char value

CValue& operator= ( signed char valSrc )

Assignment

Parameters:

valSrc

signed char value

CValue& operator= ( const CValueArray & valSrc )

Assignment

Parameters:

valSrc

CValueArray value

CValue& operator= ( siPtrType valSrc )

Assignment

Parameters:

valSrc

pointer value

operator short ( ) const

short extractor

operator unsigned short ( ) const

unsigned short extractor

operator LONG ( ) const

LONG extractor

operator int ( ) const

int extractor

Since:: 5.1

operator ULONG ( ) const

ULONG extractor

Since:: 5.0

operator float ( ) const

float extractor

operator double ( ) const

double extractor

operator bool ( ) const

bool extractor

operator CString ( ) const

CString extractor

operator CRef ( ) const

CRef extractor

operator CRefArray ( ) const

The CRefArray extractor returns a CRefArray if the source is a siRefArray type. If the source is a siRef type, the extractor returns a one element CRefArray containing the source object. The function returns an empty array if the source is invalid.

operator unsigned char ( ) const

unsigned byte extractor

operator signed char ( ) const

byte extractor

operator CValueArray & ( ) const

CValueArray& extractor

operator MATH::CVector3 ( ) const

CVector3 extractor

Since:: 5.1

operator siPtrType ( ) const

CValue::siPtrType extractor. The data returned by this function depends on the type of this CValue:

type: siIDispatch, pointer type returned: IDispatch*
type: siIUnknown, pointer type returned: IUnknown*
type: siPtr, pointer type returned: void*

Warning:: Always use this function to access the pointer stored in m_u.pval, do not access m_u.pval directly otherwise the result may be undefined.

Note:: Returned pointers to IDispatch and IUnknown are reference counted.

Example:

        using namespace XSI;

        CComAPIHandler uitoolkit;
        uitoolkit.CreateInstance( L"XSI.UIToolkit");

        // retrieves the IDispatch pointer of the XSI UI toolkit object
        CValue dispVal = uitoolkit.GetRef();
        IDispatch* pDisp = (IDispatch*)(CValue::siPtrType)dispVal;

bool operator== ( const CValue & valSrc ) const

Comparison

Parameters:

valSrc

CValue value

bool operator== ( short ) const [inline]

short equality operator

bool operator== ( unsigned short ) const [inline]

unsigned short equality operator

bool operator== ( LONG ) const [inline]

LONG equality operator

bool operator== ( int ) const [inline]

int equality operator

bool operator== ( ULONG ) const [inline]

ULONG equality operator

bool operator== ( float ) const [inline]

float equality operator

bool operator== ( double ) const [inline]

double equality operator

bool operator== ( bool ) const [inline]

bool equality operator

bool operator== ( const CString & ) const [inline]

CString equality operator

bool operator== ( const wchar_t * ) const [inline]

wchar_t * equality operator

bool operator== ( const CRef & ) const [inline]

CRef equality operator

bool operator== ( const CRefArray & ) const [inline]

CRefArray equality operator

Since:: 4.0

bool operator== ( unsigned char ) const [inline]

unsigned byte equality operator

bool operator== ( signed char ) const [inline]

byte equality operator

bool operator== ( const CValueArray & ) const

CValueArray& equality operator

bool operator== ( const siPtrType ) const [inline]

siPtrType equality operator

bool operator== ( const MATH::CVector3 & ) const [inline]

CVector3 equality operator

Since:: 5.1

bool operator!= ( const CValue & valSrc ) const

Inequality

Parameters:

valSrc

CValue value

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.

Parameters:

	in_type	Type to convert into.
	in_pSrc	Pointer to the CValue to convert

Example:

Converting a LONG to double value

        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() );

Example:

Setting a CValue as a IUnknown pointer

        using namespace XSI;
        Application app;

        CComAPIHandler uitoolkit;
        uitoolkit.CreateInstance( L"XSI.UIToolkit");

        // retrieves a IDispatch pointer from the XSI 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 )

Attaches a CValue into this object. The object takes ownership of a CValue by encapsulating it. This function releases any existing encapsulated CValue, then copies the input CValue.

Parameters:

in_valSrc

CValue object to encapsulate.

CValue Detach ( )

Detaches the encapsulated CValue object from this CValue object. Extracts and returns the encapsulated CValue, then clears this CValue object without destroying it.

Returns:: The encapsulated CValue.

CString GetAsText ( ) const

Returns the CValue content into a text string.

Returns:: The value in text format.

bool IsEmpty ( ) const [inline]

Convenient method to know if the object is set with a value or not.

Returns:: true if the CValue is empty or false otherwise.

Member Data Documentation

union XSI::CValue::ValueField m_u

This union is used for storing the value described by the CValue::m_t data member. Instead of accessing the value stored in CValue::m_u directly, it is strongly recommended to use the extractor methods defined by CValue.

Example:

Demonstrates the CValue extractor methods

        CValue val((short)255);

        // good but not recommended
        short wrong = val.sval;

        // right way to do it
        short good = (short)val;

        CComAPIHandler uitoolkit;
        uitoolkit.CreateInstance( L"XSI.UIToolkit");

        CValue dispVal = uitoolkit.GetRef();

        // wrong way of accessing a COM object from a CValue, could return
        // an invalid pointer
        IDispatch* pDisp = dispVal.pval;

        // this is the right way to do it
        IDispatch* pDisp = (IDispatch*)(CValue::siPtrType)dispVal;

The documentation for this class was generated from the following file:

xsi_value.h

Return to Softimage XSI Index

Your Ad Here


Public Types
enum	DataType { siEmpty = 0, siInt2 = 2, siInt4 = 3, siFloat = 4, siDouble = 5, siString = 8, siIDispatch = 9, siBool = 11, siIUnknown = 13, siInt1 = 16, siUInt1 = 17, siUInt2 = 18, siUInt4 = 19, siWStr = 31, siRef = 666, siArray = 667, siPtr = 668, siRefArray = 669, siVector3 = 670 }
	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 (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 MATH::CVector3 &valSrc)
	CValue (siPtrType valSrc)
	CValue (const wchar_t *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= (float valSrc)
CValue &	operator= (double valSrc)
CValue &	operator= (bool valSrc)
CValue &	operator= (const CString &valSrc)
CValue &	operator= (const wchar_t *valSrc)
CValue &	operator= (const CRef &valSrc)
CValue &	operator= (const CRefArray &valSrc)
CValue &	operator= (const MATH::CVector3 &valSrc)
CValue &	operator= (unsigned char valSrc)
CValue &	operator= (signed char valSrc)
CValue &	operator= (const CValueArray &valSrc)
CValue &	operator= (siPtrType valSrc)
	operator short () const
	operator unsigned short () const
	operator LONG () const
	operator int () const
	operator ULONG () 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 MATH::CVector3 () const
	operator siPtrType () 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== (float) const
bool	operator== (double) const
bool	operator== (bool) const
bool	operator== (const CString &) const
bool	operator== (const wchar_t *) 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 siPtrType) const
bool	operator== (const MATH::CVector3 &) const
bool	operator!= (const CValue &valSrc) 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
Public Attributes
XSI::CValue::ValueField	m_u
Classes
union	ValueField