Communicates to COM objects.

Dispatch Surrogates

Dispatch Surrogates allow classes to mimic the behaviour of their peer COM components - they ensure compilation type safety and consistent reuse.

A Dispatch Surrogate is any object that conforms to the following rules. (Think of it as an implied interface.)

A Dispatch Surrogate must have either:

  • a ctor with the signature new makeFromDispatch(Dispatch dispatch) or
  • a static factory method with the signature static MyClass fromDispatch(Dispatch dispatch)

A Dispatch Surrogate must also have either:

  • a method with the signature Dispatch toDispatch() or
  • a field with the signature Dispatch dispatch

An example surrogate would look like:

using afFancom

class SpVoice {
  internal Dispatch dispatch

  new makeFromDispatch(Dispatch dispatch) {
    this.dispatch = dispatch

  SpObjectToken? voice {
    get { dispatch.getProperty("Voice").asType(SpObjectToken#) }
    set { dispatch.setProperty("Voice", it) }

  Int speak(Str text, SpeechVoiceSpeakFlags flags := SpeechVoiceSpeakFlags.SVSFDefault) {"Speak", text, flags).asInt

The Variant.asType method will happily instantiate and return Dispatch Surrogates, such as SpObjectToken above.

COM Events

You can register any class to receive events from COM objects by passing it into the registerForEvents() method. When a COM event is received, Fancom will look for a method on your event sink with the same name as the COM event, prefixed with on.

Example: If COM fires an event called Recognition your event sink should have a method called onRecognition(). The parameters on the event handler should match those raised by COM. Parameters can be the Fantom equivalents including surrogates. A detailed error message is given should they not match.

See Variant Types for parameter mappings.


 Void onRecognition(Int streamNumber, Variant streamPosition, SpeechRecognitionType recognitionType, ISpeechRecoResult result) {

Event handlers may optionally return a Variant that will be



Variant call(Str methodName, Obj? a := null, Obj? b := null, Obj? c := null, Obj? d := null, Obj? e := null, Obj? f := null, Obj? g := null, Obj? h := null)

Convenience for callList().



Variant callList(Str methodName, Obj?[] params := [,])

Calls a method on the COM object.



Dispatch dispatch { private set }

The JACOB Dispatch this object wraps



Variant getProperty(Str propertyName)

Gets a property from the COM object.



new makeFromProgId(Str programId)



Void registerForEvents(Obj eventSink)

Registers the given event sink to receive events from this Dispatch object. Ensure your sink defines a method called onEventName() for each event you wish to receive.

Note method this will sometimes fail if this Dispatch object was not created via the makeFromProgId ctor.



Void setProperty(Str propertyName, Obj? propertyValue)

Sets a property on the COM object.