EVENT SOURCE statement

Purpose

Declare an event interface within a Class definition

Syntax

EVENT SOURCE InterfaceName

Remarks

With objects, normally a client module calls a server module to perform specific operations as they are needed.  However, in many situations, it's convenient and efficient for a server to notify its client of a condition or event immediately, without forcing the client to inquire about the status.  At the appropriate time, the server calls back to a client method, passing information via the method parameters.  This is the exact opposite of normal communication, because the server module is now calling the client module.  In effect, the client is acting as a server for the purpose of handling these events.  In the world of objects, a server which can call such "Event Methods" is said to offer a "Connection Point".  A Connection Point can be used with COM objects or internal objects.  Further, it may use either a direct interface or the DISPATCH interface.  Event methods may take parameters, but may not return a result.

Each server class created by PowerBASIC may offer up to four event interfaces.  A client module may subscribe to any or all of these event interfaces.  When it's time for the server object to notify the client of an event, the RAISEEVENT statement is used.  For the Dispatch interface, OBJECT RAISEEVENT is used instead.  RAISEEVENT may only appear within a class which declares the Event Source interface.

The client must initiate a connection to the server with EVENTS FROM statement, and disconnect when done with EVENTS END statement.

A Connection Point may be attached to one Event Method, multiple Event Methods, or no Event Method at all.  Whenever a RAISEEVENT statement or OBJECT RAISEEVENT statement is executed, all Event Methods attached to the source object are called, one after another.  There is no guarantee of the sequence of the calls, and you must consider the possibility that RAISEEVENT with a ByRef parameter could change the value of a parameter variable before any particular Event Method is executed.

InterfaceName

Specifies the "Event Source" Interface name. If InterfaceName is DISPATCH, you can reference it with the OBJECT RAISEEVENT statement -- otherwise, regular Method references are used.

See also

EVENTS, INTERFACE (Direct), INTERFACE (IDBind),  Just what is COM?, METHOD, OBJECT RAISEEVENT, RAISEEVENT, What are Connection Points?

Example

' Direct Interface Example

#COMPILE EXE

#DIM ALL

CLASS EvClass AS EVENT

  INTERFACE IStatus AS EVENT

    INHERIT IUNKNOWN

    METHOD Done

      ? "Done!"

    END METHOD

  END INTERFACE

END CLASS

CLASS MyClass

  INTERFACE IMath

    INHERIT IUNKNOWN

    METHOD DoMath

      ? "Calculating..."   ' Do some math calculations here

      RAISEEVENT IStatus.Done()

    END METHOD

  END INTERFACE

  EVENT SOURCE IStatus

END CLASS

FUNCTION PBMAIN()

  LOCAL oMath   AS IMath

  LOCAL oStatus AS IStatus

  oMath   = CLASS "MyClass"

  oStatus = CLASS "EvClass"

  EVENTS FROM oMath CALL oStatus

  oMath.DoMath

  EVENTS END oStatus

END FUNCTION

' Dispatch Interface Example

#COMPILE EXE

#DIM ALL

CLASS EvClass AS EVENT

  INTERFACE IStatus AS EVENT

    INHERIT IDISPATCH

    METHOD Done

      ? "Done!"

    END METHOD

  END INTERFACE

END CLASS

CLASS MyClass

  INTERFACE IMath

    INHERIT IDISPATCH

    METHOD DoMath

      ? "Calculating..."   ' Do some math calculations here

      OBJECT RAISEEVENT IStatus.Done()

    END METHOD

  END INTERFACE

  EVENT SOURCE DISPATCH

END CLASS

FUNCTION PBMAIN()

  LOCAL oMath   AS IMath

  LOCAL oStatus AS DISPATCH

  oMath   = CLASS "MyClass"

  oStatus = CLASS "EvClass"

  EVENTS FROM oMath CALL oStatus

  oMath.DoMath

  EVENTS END oStatus

END FUNCTION