EVENTS statement

Purpose | Attach or detach an event handler to/from an event source.

Syntax

DIM oSource AS InterfaceName

DIM oEvent AS EventInterface

LET oSource = NEWCOM CLSID $ClassId

LET oEvent = CLASS "EventClass"

EVENTS FROM oSource CALL oEvent

[statements]

EVENTS END oEvent

Remarks

In the above source code sample, oEvent is an object variable which references an event handler object, and oSource is an object variable which references an event source object which generates events.

The EVENTS FROM statement attaches event handler code to an event source object variable. The object variable oEvent must be declared as a supported event interface, while EventClass" specifies the class which implements the event handler code. The object variable oSource specifies the event source. EVENTS END detaches the event handler from the event source.

Generally speaking, a server object "sources" events, and a client object "handles" events by supplying a METHOD which is called by the server to perform a user-defined notification. This event handler is code in the client object, which is sometimes referred to as an "event sink" (analogous to the electrical engineering terms source/sink).

One or more clients may choose to "subscribe" to events from a server object by executing the EVENTS FROM statement. The subscription is terminated by execution of the EVENTS END statement. When the server executes RAISEEVENT or OBJECT RAISEEVENT, all clients which have unsubscribed to these events are called. PowerBASIC servers support up to 32 concurrent client subscribers per server object.

Event sources and event handlers may be used within a single module, or through COM services supplied by the Windows operating system.

See also | CLASS, EVENT SOURCE, INTERFACE (Direct), INTERFACE (IDBind), Just what is COM?, OBJECT RAISEEVENT, RAISEEVENT, What is an object, anyway?, What are Connection Points?

Example

#COMPILE EXE

CLASS EvClass AS EVENT

INTERFACE EvStatus AS EVENT

INHERIT IUNKNOWN

METHOD Done

MSGBOX "Done!"

END METHOD

END INTERFACE

END CLASS

CLASS MyClass

INTERFACE MyMath

INHERIT IUNKNOWN

METHOD DoMath

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

RAISEEVENT EvStatus.Done()

END METHOD

END INTERFACE

EVENT SOURCE EvStatus

END CLASS

FUNCTION PBMAIN()

DIM oMath AS MyMath

DIM oStatus AS EvStatus

LET oMath = CLASS "MyClass"

LET oStatus = CLASS "EvClass"

EVENTS FROM oMath CALL oStatus

oMath.DoMath

EVENTS END oStatus

END FUNCTION