classafFancom::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.