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