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