Ξ
Δ
◄
►
¬
Ѕ
Filtro
Diretivas
Variáveis Nativas
Funções Nativas
Instruções de Fluxo de Controle
Operadores
Declarações
Comandos
Sub-commands
Built-in Methods/Properties
Ahk2Exe Compiler
Destacar palavras-chave
</head> <body> <h1>ComObjConnect() <span class="ver">[AHK_L 53+]</span></h1> <p>Connects a COM object's event sources to functions with a given prefix.</p> <pre class="Syntax"><span class="func">ComObjConnect</span>(ComObject <span class="optional">, PrefixOrSink</span>)</pre> <h2 id="Parameters">Parâmetros</h2> <dl> <dt>ComObject</dt> <dd> <p>An object which raises events.</p> <p>If the object does not support the IConnectionPointContainer interface or type information about the object's class cannot be retrieved, an error message is shown. This can be suppressed or handled with <a href="ComObjError.htm">ComObjError()</a> or <a href="Try.htm">try</a>/<a href="Catch.htm">catch</a>.</p> <p><span class="ver">[v1.1.22+]</span>: The IProvideClassInfo interface is used to retrieve type information about the object's class if the object supports it. Otherwise, ComObjConnect attempts to retrieve type information via the object's IDispatch interface, which may be unreliable.</p> </dd> <dt>PrefixOrSink</dt> <dd> <p>A string to prefix to the event name to determine which function to call when an event occurs, or <span class="ver">[in v1.1.01+]</span> an <a href="#event-sink">event sink object</a> defining a method for each event to be handled.</p> <p>If omitted, the object is "disconnected"; that is, the script will no longer receive notification of its events.</p> </dd> </dl> <h2 id="Usage">Usage</h2> <p>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:</p> <pre class="Syntax Short NoIndent"><i>Prefix</i><b>EventName</b>([<i>Params...</i>, ComObject]) { <i class="dull">... event-handling code ...</i> return <i>ReturnValue</i> }</pre> <p><i>Prefix</i> should be the same as the <em>PrefixOrSink</em> parameter if it is a string; otherwise, it should be omitted. <b>EventName</b> should be replaced with the name of whatever event the function should handle.</p> <p><i>Params</i> corresponds to whatever parameters the event has. If the event has no parameters, <i>Params</i> should be omitted entirely. <i>ComObject</i> is optional, and can only be used if the correct number of <i>Params</i> 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.</p> <p>Note that event handlers may have return values. To return a COM-specific type of value, use <a href="ComObjActive.htm#param">ComObject(type, value)</a>. For example, <code>return ComObject(0,0)</code> returns a variant of type VT_EMPTY, which is equivalent to returning <code>undefined</code> (or not returning) from a JavaScript function.</p> <p>Call <code>ComObjConnect(yourObject, "<i>Prefix</i>")</code> to enable event-handling.</p> <p>Call <code>ComObjConnect(yourObject)</code> to disconnect the object (stop handling events).</p> <p>If the number of parameters is not known, a <a href="../Functions.htm#Variadic">variadic function</a> can be used.</p> <h3 id="event-sink">Event Sink <span class="ver">[v1.1.01+]</span></h3> <p>If <em>PrefixOrSink</em> is an object, whenever an event is raised, the corresponding method of that object is called. Although the object can be constructed dynamically, it is more typical for <em>PrefixOrSink</em> to refer to a class or an instance of a class. In that case, methods are defined as shown above, but without <em>Prefix</em>.</p> <p>As with any call to a method, the method's (normally hidden) <code>this</code> parameter contains a reference to the object through which the method was called; i.e. the event sink object, not the COM object. This can be used to provide context to the event handlers, or share values between them.</p> <p>To catch all events without defining a method for each one, define a <a href="../Objects.htm#Meta_Functions">__Call meta-function</a>.</p> <p><em>ComObject</em> retains a reference to <em>PrefixOrSink</em>, so it cannot be deleted before the object is disconnected.</p> <p><span class="ver">[v1.1.36.02+]:</span> <em>ComObject</em> releases its reference to <em>PrefixOrSink</em> automatically if the COM object releases the connection. For example, Internet Explorer does this when it exits. If the script does not retain its own reference to <em>PrefixOrSink</em>, it can use <a href="../Objects.htm#Custom_NewDelete">__Delete</a> to detect when this occurs. If the object is hosted by a remote process and the process terminates unexpectedly, it may take several minutes for the system to release the connection.</p> <h2 id="Remarks">Remarks</h2> <p>The script must retain a reference to <em>ComObject</em>, otherwise it would be freed automatically and would disconnect from its COM object, preventing any further events from being detected. There is no standard way to detect when the connection is no longer required, so the script must disconnect manually by calling ComObjConnect.</p> <p>The <a href="_Persistent.htm">#Persistent</a> directive may be needed to keep the script running while it is listening for events.</p> <p>On failure, the function may throw an exception, exit the script or simply return, depending on the current <a href="ComObjError.htm">ComObjError()</a> setting and <a href="ComObjError.htm#factors">other factors</a>.</p> <h2 id="Related">Tópicos relacionados</h2> <p><a href="ComObjCreate.htm">ComObjCreate()</a>, <a href="ComObjGet.htm">ComObjGet()</a>, <a href="ComObjActive.htm">ComObjActive()</a>, <a href="ComObjError.htm">ComObjError()</a>, <a href="http://msdn.microsoft.com/en-us/library/ccxe1xe6.aspx">WScript.ConnectObject (MSDN)</a></p> <h2 id="Examples">Exemplos</h2> <div class="ex" id="ExIE"> <p><a class="ex_number" href="#ExIE"></a> Launches an instance of Internet Explorer and connects events to corresponding script functions with the prefix "IE_". For details about the COM object and DocumentComplete event used below, see <a href="http://msdn.microsoft.com/en-us/library/aa752084.aspx">InternetExplorer object (Microsoft Docs)</a>.</p> <pre>ie := ComObjCreate("InternetExplorer.Application") <em>; Connects events to corresponding script functions with the prefix "IE_".</em> ComObjConnect(ie, "IE_") ie.Visible := true <em>; This is known to work incorrectly on IE7.</em> ie.Navigate("https://www.autohotkey.com/") #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:=<a href="ComObjActive.htm#enwrap">ComObjUnwrap</a>(ieEventParam)) == (disp2:=ComObjUnwrap(ieFinalParam))) s .= "Both wrapper objects refer to the same IDispatch instance.`n" <a href="ObjAddRef.htm">ObjRelease</a>(disp1), ObjRelease(disp2) MsgBox % s . "Finished loading " ie.Document.title " @ " url ie.Quit() ExitApp } </pre> </div> </body> </html>