COM events

Syntax

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

Parameters

ip - interface pointer variable.

eventfolder - where are event functions. Can be:

QM 2.4.1. "sub" or "sub.prefix". Use it if event functions are sub-functions in the same macro/function as the _setevents statement.
A folder (in the list of macros) containing event functions. Not recommended.
If eventfolder is omitted or "", disconnects events.

flags:

1	don't allow multiple connections on the same object.

Remarks

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.

Example:

Excel.Application x._create
x._setevents("sub.x")

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:

Type . after an interface pointer variable. It shows a popup list of functions that also may contain events (lightning icons ). Double click an event. It adds _setevents (if does not exist) and creates an event-function (sub-function) with correct name and parameters. Then you can add more code in the sub-function.
You also can invoke the popup list from the Dialog Editor: select an ActiveX control (eg web browser) and click Events.

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:

Declare it as the last parameter in the function statement. When the function is auto-created, the parameter is added as comments, need just to remove ";;". Example:
```
function x y Excel.Application'x
x.Function()
```
Sub-functions with attribute v can use parent's variables.
Declare the variable with thread scope (with -). Don't use this 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.

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
Excel.Worksheet x=es.ws
x._setevents("sub.x")
opt waitmsg 1
10

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

Example - dialog, web browser control

\Dialog_Editor

str controls = "3"
str ax3SHD
ax3SHD="http://www.quickmacros.com"
if(!ShowDialog("" &sub.DialogProcedure &controls)) ret

 BEGIN DIALOG
 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"
 END DIALOG
 DIALOG EDITOR: "" 0x2040104 "*" "" "" ""

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


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