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