Handling events of an ole object

Ole4D Methods

Events are handled using event handlers.
Event handlers were introduced to allow processing of an ole object event.
Event handlers are 4D methods that allow processing an event from 4D.

How to set an event handling method
To make a regular 4D function event handler you have to call OCSetEventHandler or OCSetAsynchHandler.Calling this method will associate(bind) the 4D method passed as parameter to the event passed as parameter. The handler method is called when it's associated event occurs.
Only one 4D method can handle an event at one time. If you call OCSetEventHandler or OCSetAsynchHandler and the event already has a handler, the existing handler(4D method that is currently set to handle the event) is first removed.
The binding of the Ole object event to the 4D method can be removed by using the OCRemoveHandler command.
The command OCRemoveHandler is used for the event handlers assigned both with OCSetEventHandler and OCSetAsynchHandler .

Example
The following call sequence:
$i := OCSetEventHandler(CONTAINER_AREA;"OnNewDocument";firstHandle) $i := OCSetEventHandler(CONTAINER_AREA;"OnNewDocument";secondHandle)

is equivalent to:
$i := OCSetEventHandler(CONTAINER_AREA;"OnNewDocument";firstHandle) $i := OCRemoveHandler(CONTAINER_AREA;"OnNewDocument") $i := OCSetEventHandler(CONTAINER_AREA;"OnNewDocument";secondHandle)

How to run VBScript code inside the 4D event handling methods
VBScript code is run in the 4D event handling methods almost the same as in the other methods, with some small exceptions.
A value used to identify the event is put in the first parameter of the 4D event handling method.
You have to pass this value to the SHost object every time when you use it.
Using this value, you can run VBScript code inside the 4D event handling method , in order to access the Ole object or the event parameters.
It is recommended that you do not create and destroy script hosts in the 4D event handling methods, this may lead to increased memory usage and slow execution.
It is better to create the script hosts before assigning the event handler, and to destroy the script host after releasing the event handler.

How to access event parameters
From within the 4D event handling method you can have access to the event parameters. You can retrieve and set the values of the event parameters.
Note : for the event handling methods set with the OCSetAsynchHandler you can only read the event parameters values, and you cannot change their value.
You can access the event parameters using both VBScript and 4D commands.
In VBScript you can accomplish that using the SHost object.
In 4D there are the following commands : OCGetParamCount , OCGetRealParam , OCGetLongParam ,OCGetTextParam , OCSetRealParam , OCSetLongParam ,OCSetTextParam .

How to access the Ole object from within the 4D event handling method
The Ole object can be accessed in VBScript either using the Sender property of the SHost object, or by using the OCDeclareObj command in case the Ole object is not already declared.
You can also use the following 4D commands: OCGetLongOfSender , OCGetRealOfSender ,OCGetTextOfSender , OCSetLongOfSender , OCSetRealOfSender ,OCSetTextOfSender .