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