COM events


ip._setevents(["eventfolder"] [flags])



ip - interface pointer variable.

eventfolder - where are event functions. Can be:


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 (event functions). But at first need to connect object's events to your functions.


_setevents connects or disconnects object's events.




Excel.Application x._create


When object (in the example - variable x) fires an event, the corresponding function from eventfolder (in the example - a sub-function) is called.


Creating a new event function:

Names of event functions must consist of some prefix, underscore ( _ ) and event name. If eventfolder is like "sub.prefix", names must have that prefix, else can have any prefix. For example, if eventfolder is "sub.x", will be connected sub-functions like "x_Event1", "x_Event2" etc. Other sub-functions can be used for other purposes, for example with other _setevents statements.


Event function parameters must match event's parameters. Event functions don't return a value. If your function returns some nonzero value, it is interpreted as an error code.


When using a QM folder for event functions, if there are several folders 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. To avoid all this confusion, use sub-functions instead.


Usually COM objects work only in single thread (running macro). To receive events, thread where the object is created must be running. If it ends immediately, events have no sense. For example, you can use a dialog. Also you can use wait, but then need to insert opt waitmsg 1 before, or events will be blocked. See example.


To access the event-source object variable from an event function, use one of:


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.


Events can be used only with coclasses (icon ) from type libraries.


_setevents must be used directly with a variable. Code like var.Function._setevents(...) will not work.


Example - Excel, wait

ExcelSheet es.Init
opt waitmsg 1

#sub x_SelectionChange
function Excel.Range'Target ;;Excel._Worksheet'x
out 1


Example - dialog, web browser control


str controls = "3"
str ax3SHD
if(!ShowDialog("" &sub.DialogProcedure &controls)) ret

 0 "" 0x90C80AC8 0x0 0 0 224 136 "Dialog"
 3 ActiveX 0x54030000 0x0 0 0 224 114 "SHDocVw.WebBrowser"
 1 Button 0x54030001 0x4 116 116 48 14 "OK"
 2 Button 0x54030000 0x4 168 116 48 14 "Cancel"
 DIALOG EDITOR: "" 0x2040104 "*" "" "" ""

#sub DialogProcedure
function# hDlg message wParam lParam
sel message
	SHDocVw.WebBrowser we3
	we3._getcontrol(id(3 hDlg))
	case WM_COMMAND goto messages2
sel wParam
	case IDOK
ret 1

#sub we3_DocumentComplete
function IDispatch'pDisp `&URL ;;SHDocVw.IWebBrowser2'we3
out URL