ComObjConnect() [AHK_L 53+]

Connects the object's event sources to functions with a given prefix.

ComObjConnect(ComObject [, Prefix])

Parameters

ComObject The object which raises events.
Prefix A string to prefix to the event name to determine which function to call when an event occurs.
If omitted entirely, the object is "disconnected"; that is, the script will no longer receive notification of its events.

Usage

To make effective use of ComObjConnect, you must first write functions in the script to handle any events of interest. Such functions, or "event-handlers," have the following structure:

PrefixEventName([Params..., ComObject])
{
    ... event-handling code ...
    return returnValue
}

Prefix is a prefix of your choosing, while EventName is the name of whatever event the function should handle.

Params corresponds to whatever parameters the event has. If the event has no parameters, Params should be omitted entirely. ComObject is optional, and can only be used if the correct number of Params are defined; it contains a reference to the original wrapper object which was passed to ComObjConnect. "ComObject" should be replaced with a name more meaningful in the context of your script.

Note that event handlers may have return values. To return a COM-specific type of value, use ComObjParameter, which may also be written as ComObjRetVal(type, value) or simply ComObj(type, value).

Call ComObjConnect(yourObject, "Prefix") to enable event-handling.

Call ComObjConnect(yourObject) to disconnect the object (stop handling events).

If the number of parameters is not known, a variadic function can be used.

Related

ComObjCreate, ComObjGet, ComObjActive, ComObjConnect, ComObjError, WScript.ConnectObject (MSDN)

Examples

ie := ComObjCreate("InternetExplorer.Application")

; Connects events to corresponding script functions with the prefix "IE_".
ComObjConnect(ie, "IE_")

ie.Visible := true  ; This is known to work incorrectly on IE7.
ie.Navigate("http://www.autohotkey.net/~Lexikos/AutoHotkey_L/")
#Persistent

IE_DocumentComplete(ieEventParam, url, ieFinalParam) {
    global ie
    if (ie != ieEventParam)
        s .= "First parameter is a new wrapper object.`n"
    if (ie == ieFinalParam)
        s .= "Final parameter is the original wrapper object.`n"
    if ((disp1:=ComObjUnwrap(ieEventParam)) == (disp2:=ComObjUnwrap(ieFinalParam)))
        s .= "Both wrapper objects refer to the same IDispatch instance.`n"
    ObjRelease(disp1), ObjRelease(disp2)
    MsgBox % s . "Finished loading " ie.Document.title " @ " url
    ie.Quit()
    ExitApp
}