Plugin SDK Variant Reference
From Real Software Documentation
About Variants
In REALbasic, Variants are immutable objects much like Strings are. To create a Variant, you call one of the REALNewVariant* methods to instantiate a wrapper around a value. Once the Variant has been created, it's value can be retrieved by calling REALGetPropValue@Type@ and asking for the appropriate value. The same variant conversion rules apply to a plugin as they do in REALbasic code itself. However, instead of firing an exception, the REALGetPropValue call will return false.
REALNewVariantPtr
Creates a new REALbasic Variant object from the given Ptr. This API is available in REALbasic 2008 Release 1 and later.
REALobject REALNewVariantPtr( void *value );
- value: the pointer the variant encapsulates
Return Value a new variant object wrapping the Ptr
REALNewVariantCString
Creates a new REALbasic Variant object from the given C string data. This API is available in REALbasic 2008 Release 1 and later.
REALobject REALNewVariantCString( const char *value );
- value: the null terminated C string data to be encapsulated by the variant
Return Value a new variant object wrapping the null terminated string
REALNewVariantWString
Creates a new REALbasic Variant object from the given UTF-16 string data. This API is available in REALbasic 2008 Release 1 and later.
REALobject REALNewVariantWString( const wchar_t *value );
- value: the null terminated UTF-16 string data to be encapsulated by the variant
Return Value a new variant object wrapping the null terminated string
REALNewVariantPString
Creates a new REALbasic Variant object from the given Pascal string data. This API is available in REALbasic 2008 Release 1 and later.
REALobject REALNewVariantPString( const unsigned char *value );
- value: the Pascal string data to be encapsulated by the variant. Note that strings longer than 255 characters are illegal.
Return Value a new variant object wrapping the Pascal string
REALNewVariantCFStringRef
Creates a new REALbasic Variant object from the given CFStringRef string data. This API is available in REALbasic 2008 Release 1 and later, and only on Macintosh platforms.
REALobject REALNewVariantCFStringRef( CFStringRef value );
- value: the CFStringRef string data to be encapsulated by the variant
Return Value a new variant object wrapping the CFStringRef data
REALNewVariantOSType
Creates a new REALbasic Variant object from the given OSType (four-char code). This API is available in REALbasic 2008 Release 1 and later.
REALobject REALNewVariantOSType( unsigned long value );
- value: the OSType, or four-char code, data to encapsulate
Return Value a new variant object wrapping the OSType
REALGetVariantStructure
Retrieves the structure data from a variant object. This API is available in REALbasic 2008 Release 1 and later. Note that if you want to retrieve the data from a variant, you usually would use REALGetPropValue@Type@ and pass in the type you are attempting to retrieve (such as "ColorValue" or "StringValue"). However, structures cannot use this mechanism due to the variable-sized nature of their data.
Boolean REALGetVariantStructure( REALobject variant, void *buffer, unsigned long length );
- variant: the variant object to interrogate
- buffer: a buffer to hold the data. Note that the data is copied into this buffer from the variant instead of retrieving a pointer directly to the data.
- length: the number of bytes valid in the buffer. This API will never copy more than length bytes from the variant object.
Return Value If the data is copied from the variant, the return value will be true. If the data could not be copied, then the return value will be false.
The easiest way to retrieve a structure from a variant is:
if (REALGetVariantStructure( someVariant, (void *)&s, sizeof( s ) )) {
...
}
REALNewVariantStructure
Creates a new REALbasic Variant object from the given structure data. This API is available in REALbasic 2008 Release 1 and later.
REALobject REALNewVariantStructure( const void *data, unsigned long len );
- data: the structure data to be encapsulated by the variant
- len: the number of bytes valid to be copied from the data pointer
Return Value a new variant object wrapping the structure
The easiest way to create a variant wrapping a structure would be like so:
REALobject someVariant = REALNewVariantStructure( (const void *)&someStruct, sizeof( someStruct ) );
If you find yourself doing this frequently, it may make more sense to use a macro to handle creation:
REALobject someVariant = REALCreateVariantFromStructure( someStruct );
REALNewVariantString
Creates a new REALbasic Variant object from the given string value.
REALobject REALNewVariantString(REALstring value);
- value: the string data to be encapsulated by the variant
Return Value a new variant object wrapping the string
REALNewVariantInteger
Creates a new REALbasic Variant object from the given integer value. This value can be any signed integer under 64 bits wide (Int32, Int16, Int8). REALbasic variants do not distinguish between the size of integers aside from 64-bit and not-64-bit.
REALobject REALNewVariantInteger(long value);
- value: the integer data to be encapsulated by the variant
Return Value a new variant object wrapping the signed integer
REALNewVariantUInt32
Creates a new REALbasic Variant object from the given unsigned integer value. This value can be any unsigned integer under 64 bits wide (UInt32, UInt16, UInt8). REALbasic variants do not distinguish between the size of integers aside from 64-bit and not-64-bit.
REALobject REALNewVariantUInt32(unsigned long value);
- value: the integer data to be encapsulated by the variant
Return Value a new variant object wrapping the unsigned integer
REALNewVariantInt64
Creates a new REALbasic Variant object from the given integer value. This value can be any signed integer 64 bits wide or less (Int64, Int32, Int16, Int8). REALbasic variants do not distinguish between the size of integers aside from 64-bit and not-64-bit, so the variant you create with this function will report the variant's type as 64-bits. Note that it is feasible to store a Currency datatype into a variant using this function. However, that should be avoided as the REALNewVariantCurrency function is better suited for that purpose.
REALobject REALNewVariantInt64(RBInt64 value);
- value: the integer data to be encapsulated by the variant
Return Value a new variant object wrapping the 64-bit integer
REALNewVariantUInt64
Creates a new REALbasic Variant object from the given integer value. This value can be any unsigned integer 64 bits wide or less (UInt64, UInt32, UInt16, UInt8). REALbasic variants do not distinguish between the size of integers aside from 64-bit and not-64-bit, so the variant you create with this function will report the variant's type as 64-bits. Note that it is feasible to store a Currency datatype into a variant using this function. However, that should be avoided as the REALNewVariantCurrency function is better suited for that purpose.
REALobject REALNewVariantUInt64(unsigned RBInt64 value);
- value: the integer data to be encapsulated by the variant
Return Value a new variant object wrapping the unsigned 64-bit integer
REALNewVariantCurrency
Creates a new REALbasic Variant object from the given currency value. This value should be a signed 64-bit integer, that is expressed in mils. This means that if you would like to convert from a currency value into a regular Int64 value, you would simply divide by 10000. To convert an Int64 into a currency value, you would multiply by 10000. When dealing with currency datatypes, this function is preferred over the U/Int64 variant functions as it will properly reflect the format of the data in the variant's VarType property.
REALobject REALNewVariantCurrency(REALcurrency value);
- value: the currency data to be encapsulated by the variant
Return Value a new variant object wrapping the currency data
REALNewVariantDouble
Creates a new REALbasic Variant object from the given 64-bit floating-point value.
REALobject REALNewVariantDouble(double value);
- value: the 64-bit floating-point data to be encapsulated by the variant
Return Value a new variant object wrapping the double
REALNewVariantSingle
Creates a new REALbasic Variant object from the given 32-bit floating-point value.
REALobject REALNewVariantSingle(float value);
- value: the 32-bit floating-point data to be encapsulated by the variant
Return Value a new variant object wrapping the single
REALNewVariantBoolean
Creates a new REALbasic Variant object from the given boolean value. Note that this function should be preferred over the Integer variant functions as it will properly reflect the format of the data in the variant's VarType property.
REALobject REALNewVariantBoolean(Boolean value);
- value: the boolean data to be encapsulated by the variant
Return Value a new variant object wrapping the boolean
REALNewVariantColor
Creates a new REALbasic Variant object from the given color value. Color values are expressed as a 32-bit integer in the form 0x00RRGGBB on all platforms. Note that this function should be preferred over the Integer variant functions as it will properly reflect the format of the data in the variant's VarType property.
REALobject REALNewVariantColor(long value);
- value: the 32-bit color data to be encapsulated by the variant
Return Value a new variant object wrapping the color
