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 --- TODO -> DateTime 8 VT_BSTR String Str 9 VT_DISPATCH Dispatch Dispatch 10 VT_ERROR int --- TODO -> throw Err 11 VT_BOOL boolean Bool 12 VT_VARIANT Variant --- TODO -> Variant 14 VT_DECIMAL BigDecimal --- TODO -> Decimal 17 VT_UI1 byte Int 20 VT_I8 long Int
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.- 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.- 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.- make
new make()
Make a
null
Variant- makeFromBool
new makeFromBool(Bool value)
Make a Variant representing a
Bool
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