full-featured support for processing COM events
Scriptom lets you subscribe to COM events on an ActiveXObject using the .events metaproperty. The event handler is a Closure. The arguments in the Closure are passed through an instance of ActiveXObject.EventSupport.EventArguments. Don't worry ... it works like an array.
In this example, we're subscribing to the Change event of an Excel Worksheet. The Change event passes one argument - an Excel Range. In the context of this code, we're assuming that the Range object contains just one cell. In the general case, that would be a bad assumption. Once the event handler is defined this way, every change to a cell in the worksheet is going to print a line to standard out with the column, row, and new value.
As with other COM method types, events support passing values by reference. This is particularly important in light of the fact that events don't return a value. If you want to be able to send data back to whoever raised the event, you have to pass values back to the sender using byref arguments. Fortunately, this is easy to do using the EventArguments instance.
Take, for example, the following class written in Visual Basic 2005. When you call RaisePassBooleanByref, it will raise the OnPassBooleanByref event, by reference. This gives us an opportunity to change the value of the boolean in the event handler!
In the following Groovy code, note how the return value changes after we define the event handler, which simply inverts the value of the first argument.
Note that you may only change a value if it has been passed by reference. Otherwise you get an exception.
Back in the first example, I defined and event handler for an Excel Worksheet. There is another piece of information you need to make that example actually work. For many COM objects (and all true ActiveX objects), the underlying COM event handler is defined in a standard way that's easy to find and work with. However, for some COM objects, like those in Microsoft Office and Internet Explorer, there isn't enough information available for Scriptom to find the associated event interface. When this happens, you must manually define the prog-id of the object before you define any event handler. To help you out as much as possible, these are available as constants in the Scriptom library for the Office suite and for Internet Explorer. Here is how you define a prog-id for an ActiveXObject.
Additionally, there are some objects in Office and other applications where the event interface exists, but it cannot be discovered, and the object does not have an associated prog-id. The Excel Workbook object is one example of this. We're hoping to address this limitation in a future version of Scriptom.