classafFancom::Variant
sys::Obj afFancom::Variant
A multi-format data type used for all COM communications.
A Variant's type may be queried using the isXXX()
methods and returned with the asXXX()
methods. Variants have the notion of being null, the equivalent of VB Nothing. Whereas Variant objects themselves are never null, their asXXX()
methods may return null.
The asType() method can be used to return any Fantom literal (Bool
, Int
, Emum
, etc...) and also Fancom Surrogates. Surrogates are user defined classes which wrap either a Dispatch or a Variant object. Surrogates make it easy to write boiler plate Fantom classes that mimic the behaviour of COM components.
Variant Surrogates
A Variant Surrogate is any object that conforms to the following rules. (Think of it as an implied interface.)
A Variant Surrogate must have either:
- a ctor with the signature
new makeFromVariant(Variant variant)
or - a static factory method with the signature
static MyClass fromVariant(Variant variant)
A Variant Surrogate must also have either:
- a method with the signature
Variant toVariant()
or - a field with the signature
Variant variant
This allows Variant Surrogates to be passed in as parameters to a Dispatch object, and to be instantiated from the asType() method.
Enums are good candidates for converting into surrogates. Also see Flag as another example.
Note: Fancom Surrogate methods and fields may be of any visibility - which is useful if don't wish to expose them.
Note: Fancom Surrogates don't require you to implement any Mixins, reflection is used to find your wrapper methods.
Variant Types
The conversion of types between the various underlying systems is given below:
Automation Type | JACOB Type | Fancom Type | Remarks --------------------------------------------------------------------- 0 VT_EMPTY null null Equivalent to VB Nothing 1 VT_NULL null null Equivalent to VB Null 2 VT_I2 short Int 3 VT_I4 int Int / Enum A Long in VC 4 VT_R4 float Float 5 VT_R8 double Float 6 VT_CY Currency --- 7 VT_DATE Date DateTime 8 VT_BSTR String Str 9 VT_DISPATCH Dispatch Dispatch 10 VT_ERROR int throws Err 11 VT_BOOL boolean Bool 12 VT_VARIANT Object --- 14 VT_DECIMAL BigDecimal Decimal 16 VT_I1 --- Int 17 VT_UI1 byte Int 18 VT_UI2 --- Int 19 VT_UI4 --- Int 20 VT_I8 long Int 21 VT_UI8 --- Int Unsigned 64 bit - will throw err if out of range 22 VT_INT --- Int Signed 32 / 64 bit (dependent on OS) 23 VT_UINT --- Int Unsigned 32 / 64 bit - will throw err if out of range 25 VT_HRESULT --- throws Err 30 VT_LPSTR --- Str 31 VT_LPWSTR --- Str
All other value types are unsupported by JACOB and hence unsupported by Fancom. For more information on Automation Types see VARENUM enumeration (Automation) on MSDN.
- asBool
Bool? asBool()
Returns the Variant value as a
Bool
ornull
if the Variant representsnull
. Throws FancomErr if the Variant is not aBool
type.- asDateTime
DateTime? asDateTime()
Returns the Variant value as a
DateTime
ornull
if the Variant representsnull
. Throws FancomErr if the Variant is not aDateTime
type.- asDecimal
Decimal? asDecimal()
Returns the Variant value as a
Decimal
ornull
if the Variant representsnull
. Throws FancomErr if the Variant is not aDecimal
type.- asDispatch
Dispatch? asDispatch()
- asEnum
Returns the Variant value as an instance of the supplied
Enum
type ornull
if the Variant representsnull
.Throws
ArgErr
if the given type is not a subclass ofEnum
. Throws FancomErr if the Variant is not anEnum
(Int
) type or if theInt
value is not a valid ordinal for the enum.- asFloat
Float? asFloat()
Returns the Variant value as a
Float
ornull
if the Variant representsnull
. Throws FancomErr if the Variant is not aFloat
type.- asInt
Int? asInt()
Returns the Variant value as an
Int
ornull
if the Variant representsnull
. Throws FancomErr if the Variant is not anInt
type.- asStr
Str? asStr()
Returns the Variant value as a
Str
ornull
if the Variant representsnull
. Throws FancomErr if the Variant is not aStr
type.- asType
A Swiss Army knife this method is; attempts to convert the Variant value into the given Type, be it a
Bool
,Enum
or a Fancom wrapper. Throws FancomErr if unsuccessful.- isArray
Bool isArray()
Returns
true
if this Variant represents an array.- isBool
Bool isBool()
Returns
true
if this Variant represents aBool
value. Will returnfalse
if the Variant representsnull
as the type cannot be determined.- isByRef
Bool isByRef()
Returns
true
if this Variant is aByRef
value.- isDateTime
Bool isDateTime()
Returns
true
if this Variant represents a DateTime object. Will returnfalse
if the Variant representsnull
as the type cannot be determined.- isDecimal
Bool isDecimal()
Returns
true
if this Variant represents a Decimal object. Will returnfalse
if the Variant representsnull
as the type cannot be determined.- isDispatch
Bool isDispatch()
Returns
true
if this Variant represents a Dispatch object. Will returnfalse
if the Variant representsnull
as the type cannot be determined.- isEnum
Returns
true
if this Variant can be converted into the givenEnum
type, checking that the Variant value is a valid ordinal for the type. ThrowsArgErr
if the given type is not a subclass ofEnum
.- isFloat
Bool isFloat()
Returns
true
if this Variant represents aFloat
value. Will returnfalse
if the Variant representsnull
as the type cannot be determined.- isInt
Bool isInt()
Returns
true
if this Variant represents aInt
value. Will returnfalse
if the Variant representsnull
as the type cannot be determined.- isNull
Bool isNull()
Returns
true
if this Variant represents anull
value- isStr
Bool isStr()
Returns
true
if this Variant represents aStr
value. Will returnfalse
if the Variant representsnull
as the type cannot be determined.- isVector
Bool isVector()
Returns
true
if this Variant is aVector
value.- make
new make()
Make a
null
Variant- makeFromBool
new makeFromBool(Bool value)
Make a Variant representing a
Bool
value- makeFromDateTime
new makeFromDateTime(DateTime value)
Make a Variant representing a
DateTime
value- makeFromDecimal
new makeFromDecimal(Decimal value)
Make a Variant representing a
Decimal
value- makeFromFloat
new makeFromFloat(Float value)
Make a Variant representing a
Float
value- makeFromInt
new makeFromInt(Int value)
Make a Variant representing an
Int
value- makeFromStr
new makeFromStr(Str value)
Make a Variant representing a
Str
value- toStr
virtual override Str toStr()
Returns details of the underlying COM value.
- variant
Variant variant { private set }
The JACOB Variant this object wraps