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

Source

Bool? asBool()

Returns the Variant value as a Bool or null if the Variant represents null. Throws FancomErr if the Variant is not a Bool type.

asDateTime

Source

DateTime? asDateTime()

Returns the Variant value as a DateTime or null if the Variant represents null. Throws FancomErr if the Variant is not a DateTime type.

asDecimal

Source

Decimal? asDecimal()

Returns the Variant value as a Decimal or null if the Variant represents null. Throws FancomErr if the Variant is not a Decimal type.

asDispatch

Source

Dispatch? asDispatch()

Returns the Variant value as a Dispatch object or null if the Variant represents null. Throws FancomErr if the Variant is not a Dispatch type.

asEnum

Source

Enum? asEnum(Type enumType)

Returns the Variant value as an instance of the supplied Enum type or null if the Variant represents null.

Throws ArgErr if the given type is not a subclass of Enum. Throws FancomErr if the Variant is not an Enum (Int) type or if the Int value is not a valid ordinal for the enum.

asFloat

Source

Float? asFloat()

Returns the Variant value as a Float or null if the Variant represents null. Throws FancomErr if the Variant is not a Float type.

asInt

Source

Int? asInt()

Returns the Variant value as an Int or null if the Variant represents null. Throws FancomErr if the Variant is not an Int type.

asStr

Source

Str? asStr()

Returns the Variant value as a Str or null if the Variant represents null. Throws FancomErr if the Variant is not a Str type.

asType

Source

Obj? asType(Type type)

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

Source

Bool isArray()

Returns true if this Variant represents an array.

isBool

Source

Bool isBool()

Returns true if this Variant represents a Bool value. Will return false if the Variant represents null as the type cannot be determined.

isByRef

Source

Bool isByRef()

Returns true if this Variant is a ByRef value.

isDateTime

Source

Bool isDateTime()

Returns true if this Variant represents a DateTime object. Will return false if the Variant represents null as the type cannot be determined.

isDecimal

Source

Bool isDecimal()

Returns true if this Variant represents a Decimal object. Will return false if the Variant represents null as the type cannot be determined.

isDispatch

Source

Bool isDispatch()

Returns true if this Variant represents a Dispatch object. Will return false if the Variant represents null as the type cannot be determined.

isEnum

Source

Bool isEnum(Type enumType)

Returns true if this Variant can be converted into the given Enum type, checking that the Variant value is a valid ordinal for the type. Throws ArgErr if the given type is not a subclass of Enum.

isFloat

Source

Bool isFloat()

Returns true if this Variant represents a Float value. Will return false if the Variant represents null as the type cannot be determined.

isInt

Source

Bool isInt()

Returns true if this Variant represents a Int value. Will return false if the Variant represents null as the type cannot be determined.

isNull

Source

Bool isNull()

Returns true if this Variant represents a null value

isStr

Source

Bool isStr()

Returns true if this Variant represents a Str value. Will return false if the Variant represents null as the type cannot be determined.

isVector

Source

Bool isVector()

Returns true if this Variant is a Vector value.

make

Source

new make()

Make a null Variant

makeFromBool

Source

new makeFromBool(Bool value)

Make a Variant representing a Bool value

makeFromDateTime

Source

new makeFromDateTime(DateTime value)

Make a Variant representing a DateTime value

makeFromDecimal

Source

new makeFromDecimal(Decimal value)

Make a Variant representing a Decimal value

makeFromFloat

Source

new makeFromFloat(Float value)

Make a Variant representing a Float value

makeFromInt

Source

new makeFromInt(Int value)

Make a Variant representing an Int value

makeFromStr

Source

new makeFromStr(Str value)

Make a Variant representing a Str value

toStr

Source

virtual override Str toStr()

Returns details of the underlying COM value.

variant

Source

Variant variant { private set }

The JACOB Variant this object wraps