ip._setevents(["eventfolder"] [flags])
ip - interface pointer variable.
eventfolder - QM folder with event procedures (user-defined functions). Default: "" (disconnect).
flags - combination of the following values:
| 1 | don't allow multiple connections on the same object. |
Usually you call COM object's functions ("methods" and "properties"). Some COM objects also support "events", that is, can call your functions. But at first you must connect object's events to your functions.
This function connects or disconnects object's events. It is similar to the WithEvents keyword in Visual Basic. Events can be used only with coclasses that are defined in a type library and have an event-source interface.
Example:
Excel.Application a._create a._setevents("a_Events")
When object (in the example - a) triggers an event, the corresponding function from eventfolder (in the example - a_Events folder) is called. Names of functions must end with names of events, and include underscore before name of event. For example, function for event "Event", may be "my_Event", or "_Event", etc. Arguments must match event's arguments. Event functions don't return a value. If your function returns some nonzero value, it is interpreted as error code.
When you type . after a variable of a coclass type, you can see a popup list of functions. The list consists of methods and properties of the default interface as well as events (lightning icons) of the event-source interface. If you double click an event, new event-function is added. The function is properly named and declared. The folder also is created if does not exist, and the function is placed there. The _setevents("folder") also is added.
In the example, type a. in the second line, and double click an event in the popup list. This adds _setevents("a_Events"), creates a_Events folder, creates the event function, and opens the function. Then you can add code there.
You can have more than one event folder with same name. _setevents uses one that is nearest in the list of macros. At first it searches in the same folder (where function that calls _setevents is) and subfolders, then in its parent folder and its subfolders, then in other ancestors, and finally in whole list of macros. This feature added in QM 2.1.8.5.
Usually, COM objects work only in single thread (running macro). To receive events, thread where the object is created must stay running. If the macro ends immediately, events have no sense. For example, you can use a dialog. If you decide to use the wait function, insert opt waitmsg 1 before, or events will be blocked.
To access the event-source object variable from an event function, one additional argument can be added at the end of the argument list. When the function is auto-created, the argument is added, but it is commented, so if you want to use it, delete ";;". Example:
function arg1 arg2 Excel.Application'a a.Function()
Alternatively, you can declare the variable with thread scope (with -). In QM, thread variables must be declared in each function where they are used, so you also have to place declaration in event functions that want to access the variable. Don't use thread variables with ActiveX controls in dialogs.
By default, multiple calls to _setevents create multiple connections. For example, you can connect two folders simultaneously. If flag 1 is set, previous connection is deleted before making new.
To disconnect, call _setevents without arguments. Usually it is not necessary because it happens automatically when the object is deleted.