Events

Events generated by OLE objects are provided via an event sink which is simply an interface that defines a collection of events that may be generated by the object. Objects may support more than one event sink and may or may not define them in a type library.

By default, events generated by COM objects are processed like all other events in Dyalog APL.

This means that if you attach a callback function to an event in an instance of an OCXClass object, the events are queued up when they are received and then processed one-by-one, by ⎕DQ, from the internal queue. This is the mechanism used to process all events in Dyalog APL and it has many advantages:

• Events are handled in an orderly manner
• An event cannot interrupt a callback that is processing a previous event
• Incoming events are held up so that you can trace a callback function

The disadvantage of this approach is that, for internal reasons, your APL callback function is unable to return a result to the ActiveX control, or to modify any of the arguments supplied by the event. This is a severe problem if the COM object relies on callbacks to control certain aspects of its functionality.

The QueueEvents property allows you to change the normal behaviour so that it is possible for a callback function to return a result to a COM object.

If QueueEvents is 1, which is the default, the result (if any) of your callback function is not passed back to the COM object but is discarded. Thus you cannot, for example, inhibit or modify the default processing of the event by the COM object.

If instead you set QueueEvents to 0, the callback function attached to the event is executed immediately, even if there are other APL events before it in the internal event queue. The result of your callback function is then passed back to the COM object which may use it to inhibit or modify its normal event processing.

See QueueEvents for further details.