</head> <body> <h1>OnMessage()</h1> <p>Specifies a <a href="../Functions.htm">function</a> or <a href="../objects/Functor.htm">function object</a> to call automatically when the script receives the specified message.</p> <pre class="Syntax"><span class="func">OnMessage</span>(MsgNumber <span class="optional">, Function, MaxThreads</span>)</pre> <h2 id="Parameters">Parâmetros</h2> <dl> <dt>MsgNumber</dt> <dd><p>The number of the message to monitor or query, which should be between 0 and 4294967295 (0xFFFFFFFF). If you do not wish to monitor a <a href="../misc/SendMessageList.htm">system message</a> (that is, one below 0x0400), it is best to choose a number greater than 4096 (0x1000) to the extent you have a choice. This reduces the chance of interfering with messages used internally by current and future versions of AutoHotkey.</p></dd> <dt>Function</dt> <dd><p>A <a href="../Functions.htm">function</a>'s name or, in <span class="ver">[v1.1.20+]</span>, a <a href="../objects/Functor.htm">function object</a>. To pass a literal function name, it must be enclosed in quotes.</p> <p>How the function is registered and the return value of OnMessage depend on whether this parameter is a string or a function object. See <a href="#Name_v_Object">Function Name vs Object</a> for details.</p> </dd> <dt id="MaxThreads">MaxThreads <span class="ver">[v1.0.47+]</span></dt> <dd><p>This integer is normally omitted, in which case the monitor function is limited to one <a href="../misc/Threads.htm">thread</a> at a time. This is usually best because otherwise, the script would process messages out of chronological order whenever the monitor function interrupts itself. Therefore, as an alternative to <em>MaxThreads</em>, consider using <em>Critical</em> as described <a href="#Critical">below</a>.</p> <p>If the monitor function directly or indirectly causes the message to be sent again while the function is still running, it is necessary to specify a <em>MaxThreads</em> value greater than 1 or less than -1 to allow the monitor function to be called for the new message (if desired). Messages sent (not posted) by the script's own process to itself cannot be delayed or buffered.</p> <p><span class="ver">[v1.1.20+]:</span> Specify 0 to unregister a previously registered function. If <em>Function</em> is a string, the "legacy" monitor is removed. Otherwise, only the given function object is unregistered.</p> <p><span class="ver">[v1.1.20+]:</span> By default, when multiple functions are registered for a single <em>MsgNumber</em>, they are called in the order that they were registered. To register a function to be called before any previously registered functions, specify a negative value for <em>MaxThreads</em>. For example, <code>OnMessage(Msg, Fn, -2)</code> registers <code>Fn</code> to be called before any other functions previously registered for <em>Msg</em>, and allows <em>Fn</em> a maximum of 2 threads. However, if the function is already registered, the order will not change unless it is unregistered and then re-registered.</p></dd> </dl> <h2 id="Name_v_Object">Function Name vs Object</h2> <p>OnMessage's return value and behavior depends on whether the <em>Function</em> parameter is a function name or an object.</p> <h3 id="Function_Name">Function Name</h3> <p>For backward compatibility, at most one function can be registered by name to monitor each unique <em>MsgNumber</em> -- this is referred to as the "legacy" monitor.</p> <p>When the legacy monitor is first registered, whether it is called before or after previously registered monitors depends on the <em>MaxThreads</em> parameter. Updating the monitor to call a different function does not affect the order unless the monitor is unregistered first.</p> <p>This registers or updates the current legacy monitor for <em>MsgNumber</em> (omit the quote marks if passing a variable):</p> <pre class="Syntax">Name := <span class="func">OnMessage</span>(MsgNumber, "FunctionName")</pre> <p>The return value is one of the following:</p> <ul> <li>An empty string on <a href="#Failure">failure</a>.</li> <li>The name of the previous function, if there was one.</li> <li>Otherwise, the name of the new function.</li> </ul> <p>This unregisters the current legacy monitor for <em>MsgNumber</em> (if any) and returns its name (blank if none):</p> <pre class="Syntax">Name := <span class="func">OnMessage</span>(MsgNumber, "")</pre> <p>This returns the name of the current legacy monitor for <em>MsgNumber</em> (blank if none):</p> <pre class="Syntax">Name := <span class="func">OnMessage</span>(MsgNumber)</pre> <h3 id="Function_Object">Function Object</h3> <p>Any number of <a href="../objects/Functor.htm">function objects</a> (including <a href="../objects/Func.htm">normal functions</a>) can monitor a given <em>MsgNumber</em>.</p> <p>Either of these two lines registers a function object to be called <strong>after</strong> any previously registered functions:</p> <pre class="Syntax"> <span class="func">OnMessage</span>(MsgNumber, FuncObj) <em>; Option 1</em> <span class="func">OnMessage</span>(MsgNumber, FuncObj, 1) <em>; Option 2 (MaxThreads = 1)</em></pre> <p>This registers a function object to be called <strong>before</strong> any previously registered functions:</p> <pre class="Syntax"><span class="func">OnMessage</span>(MsgNumber, FuncObj, -1)</pre> <p>To unregister a function object, specify 0 for <em>MaxThreads</em>:</p> <pre class="Syntax"><span class="func">OnMessage</span>(MsgNumber, FuncObj, 0)</pre> <h2 id="Failure">Failure</h2> <p>Failure occurs when <em>Function</em>:</p> <ol> <li>is not an object, the name of a user-defined function, or an empty string;</li> <li>is known to require more than four parameters; or</li> <li>in <span class="ver">[v1.0.48.05]</span> or older, has any <a href="../Functions.htm#ByRef">ByRef</a> or <a href="../Functions.htm#optional">optional</a> parameters.</li> </ol> <p>In <span class="ver">[v1.1.19.03]</span> or older, failure also occurs if the script attempts to monitor a new message when there are already 500 messages being monitored.</p> <p>If <em>Function</em> is an object, an exception is thrown on failure. Otherwise, an empty string is returned.</p> <h2 id="The_Functions_Parameters">The Function's Parameters</h2> <p>A <a href="../Functions.htm">function</a> assigned to monitor one or more messages can accept up to four parameters:</p> <pre>MyMessageMonitor(wParam, lParam, msg, hwnd) { ... body of function... }</pre> <p>Although the names you give the parameters do not matter, the following information is sequentially assigned to them:</p> <ul> <li>Parameter #1: The message's WPARAM value.</li> <li>Parameter #2: The message's LPARAM value.</li> <li>Parameter #3: The message number, which is useful in cases where a function monitors more than one message.</li> <li>Parameter #4: The HWND (unique ID) of the window or control to which the message was sent. The HWND can be used with <a href="../misc/WinTitle.htm#ahk_id">ahk_id</a>.</li> </ul> <p>WPARAM and LPARAM are unsigned 32-bit integers (from 0 to 2<sup>32</sup>-1) or signed 64-bit integers (from -2<sup>63</sup> to 2<sup>63</sup>-1) depending on whether the exe running the script is 32-bit or 64-bit. For 32-bit scripts, if an incoming parameter is intended to be a signed integer, any negative numbers can be revealed by following this example:</p> <pre>if (A_PtrSize = 4 &amp;&amp; wParam &gt; 0x7FFFFFFF) <em>; Checking <a href="../Variables.htm#PtrSize">A_PtrSize</a> ensures the script is 32-bit.</em> wParam := -(~wParam) - 1</pre> <p>You can omit one or more parameters from the end of the list if the corresponding information is not needed. For example, a function defined as <code>MyMsgMonitor(wParam, lParam)</code> would receive only the first two parameters, and one defined as <code>MyMsgMonitor()</code> would receive none of them.</p> <h2 id="Additional_Information_Available_to_the_Function">Additional Information Available to the Function</h2> <p>In addition to the parameters received above, the function may also consult the values in the following built-in variables:</p> <ul> <li><a href="../Variables.htm#Gui">A_Gui</a>: Blank unless the message was sent to a GUI window or control, in which case A_Gui is the <a href="Gui.htm#MultiWin">Gui Window number</a> (this window is also set as the function's <a href="Gui.htm#DefaultWin">default GUI window</a>).</li> <li><a href="../Variables.htm#GuiControl">A_GuiControl</a>: Blank unless the message was sent to a GUI control, in which case it contains the control's variable name or other value as described at <a href="../Variables.htm#GuiControl">A_GuiControl</a>. Some controls never receive certain types of messages. For example, when the user clicks a <a href="GuiControls.htm#Text">text control</a>, the operating system sends WM_LBUTTONDOWN to the parent window rather than the control; consequently, A_GuiControl is blank.</li> <li><a href="../Variables.htm#GuiX">A_GuiX</a> and <a href="../Variables.htm#GuiY">A_GuiY</a>: Both contain -2147483648 if the incoming message was sent via <a href="PostMessage.htm">SendMessage</a>. If it was sent via <a href="PostMessage.htm">PostMessage</a>, they contain the mouse cursor's coordinates (relative to the screen) at the time the message was posted.</li> <li><a href="../Variables.htm#EventInfo">A_EventInfo</a>: Contains 0 if the message was sent via SendMessage. If sent via PostMessage, it contains the <a href="../Variables.htm#TickCount">tick-count time</a> the message was posted.</li> </ul> <p>A monitor function's <a href="../misc/WinTitle.htm#LastFoundWindow">last found window</a> starts off as the parent window to which the message was sent (even if it was sent to a control). If the window is hidden but not a GUI window (such as the script's main window), turn on <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> before using it. Por exemplo:</p> <pre>DetectHiddenWindows On MsgParentWindow := WinExist() <em>; This stores the unique ID of the window to which the message was sent.</em></pre> <h2 id="What_the_Function_Should_Return">What the Function Should <em>Return</em></h2> <p>If a monitor function uses <a href="Return.htm">Return</a> without any parameters, or it specifies a blank value such as "" (or it never uses Return at all), the incoming message goes on to be processed normally when the function finishes. The same thing happens if the function <a href="Exit.htm">Exits</a> or causes a runtime error such as <a href="Run.htm">running</a> a nonexistent file. By contrast, returning an integer causes it to be sent immediately as a reply; that is, the program does not process the message any further. For example, a function monitoring WM_LBUTTONDOWN (0x0201) may return an integer to prevent the target window from being notified that a mouse click has occurred. In many cases (such as a message arriving via <a href="PostMessage.htm">PostMessage</a>), it does not matter which integer is returned; but if in doubt, 0 is usually safest.</p> <p>The range of valid return values depends on whether the exe running the script is 32-bit or 64-bit. Non-empty return values must be between -2<sup>31</sup> and 2<sup>32</sup>-1 for 32-bit scripts (<code><a href="../Variables.htm#PtrSize">A_PtrSize</a> = 4</code>) and between -2<sup>63</sup> and 2<sup>63</sup>-1 for 64-bit scripts (<code><a href="../Variables.htm#PtrSize">A_PtrSize</a> = 8</code>).</p> <p><span class="ver">[v1.1.20+]:</span> If there are multiple functions monitoring a given message number, they are called one by one until one returns a non-empty value.</p> <h2 id="Remarks">Observações Gerais</h2> <p>Unlike a normal function-call, the arrival of a monitored message calls the function as a new <a href="../misc/Threads.htm">thread</a>. Because of this, the function starts off fresh with the default values for settings such as <a href="SendMode.htm">SendMode</a> and <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a>. These defaults can be changed in the <a href="../Scripts.htm#auto">auto-execute section</a>.</p> <p>Messages sent to a control (rather than being posted) are not monitored because the system routes them directly to the control behind the scenes. This is seldom an issue for system-generated messages because most of them are posted.</p> <p>Any script that calls OnMessage anywhere is automatically <a href="_Persistent.htm">persistent</a>. It is also single-instance unless <a href="_SingleInstance.htm">#SingleInstance</a> has been used to override that.</p> <p><p id="Critical">If a message arrives while its function is still running due to a previous arrival of the same message, by default the function will not be called again; instead, the message will be treated as unmonitored. If this is undesirable, there are multiple ways it can be avoided:</p> <ul> <li>If the message is posted rather than sent and has a number greater than 0x0311, it can be buffered until its function completes by specifying <a href="Critical.htm">Critical</a> as the first line of the function. Alternatively, <a href="Thread.htm">Thread Interrupt</a> can achieve the same effect as long as it lasts long enough for the function to finish.</li> <li><span class="ver">[v1.0.46+]:</span> Using <a href="Critical.htm">Critical</a> to increase the <a href="Critical.htm#Interval">message check interval</a> gives the function more time to complete before any messages are dispatched. An interval greater than 16 may be needed for reliability. Due to the granularity of the system timer (usually 15.6 milliseconds), the default interval of 5 milliseconds (for non-Critical threads) or 15 milliseconds (for Critical threads) might appear to pass the instant after the function starts.</li> <li>Ensuring that the monitor function returns quickly reduces the risk that messages will be missed due to <em>MaxThreads</em>. One way to do this is to have it queue up a future thread by <a href="PostMessage.htm">posting</a> to its own script a monitored message number greater than 0x0311. That message's function should use <a href="Critical.htm">Critical</a> as its first line to ensure that its messages are buffered. Alternatively, a <a href="SetTimer.htm">timer</a> can be used to queue up a future thread.</li> <li>Specifying a higher value for the <a href="#MaxThreads">MaxThreads</a> parameter allows the function to be interrupted to process the newly-received message.</li> </ul> <p id="buffering">If a monitored message that is numerically greater than 0x0311 is posted while the script is <a href="../misc/Threads.htm#Interrupt">uninterruptible</a>, the message is buffered; that is, its function is not called until the script becomes interruptible. However, messages which are sent rather than posted cannot be buffered as they must provide a return value. Posted messages also might not be buffered when a modal message loop is running, such as for a system dialog, ListView drag-drop operation or menu.</p> <p>When a monitored message arrives, if it is not buffered and the script is uninterruptible merely due to the settings of <a href="Thread.htm">Thread Interrupt</a> or <a href="Critical.htm">Critical</a>, the current thread will be interrupted so that the function can be called. However, if the script is absolutely uninterruptible -- such as while a <a href="Menu.htm">menu</a> is displayed, a <a href="SetKeyDelay.htm">KeyDelay</a>/<a href="SetMouseDelay.htm">MouseDelay</a> is in progress, or the clipboard is being <a href="_ClipboardTimeout.htm">opened</a> -- the message's function will not be called and the message will be treated as unmonitored.</p> <p>The <a href="../misc/Threads.htm">priority</a> of OnMessage threads is always 0. Consequently, no messages are monitored or buffered when the current thread's priority is higher than 0.</p> <p>Caution should be used when monitoring system messages (those below 0x0400). For example, if a monitor function does not finish quickly, the response to the message might take longer than the system expects, which might cause side-effects. Unwanted behavior may also occur if a monitor function returns an integer to suppress further processing of a message, but the system expected different processing or a different response.</p> <p>When the script is displaying a system dialog such as <a href="MsgBox.htm">MsgBox</a>, any message posted to a control is not monitored. For example, if the script is displaying a message box and the user clicks a button in a GUI window, the WM_LBUTTONDOWN message is sent directly to the button without calling the monitor function.</p> <p>Although an external program may post messages directly to a script's thread via PostThreadMessage() or other API call, this is not recommended because the messages would be lost if the script is displaying a system window such as a <a href="MsgBox.htm">message box</a>. Instead, it is usually best to post or send the messages to the script's main window or one of its GUI windows.</p> <h2 id="Related">Tópicos relacionados</h2> <p><a href="RegisterCallback.htm">RegisterCallback()</a>, <a href="OnExit.htm#function">OnExit()</a>, <a href="OnExit.htm#command">OnExit</a>, <a href="OnClipboardChange.htm#function">OnClipboardChange()</a>, <a href="OnClipboardChange.htm#label">OnClipboardChange Label</a>, <a href="PostMessage.htm">Post/SendMessage</a>, <a href="../Functions.htm">Functions</a>, <a href="../misc/SendMessageList.htm">List of Windows Messages</a>, <a href="../misc/Threads.htm">Threads</a>, <a href="Critical.htm">Critical</a>, <a href="DllCall.htm">DllCall()</a></p> <h2 id="Examples">Exemplos</h2> <div class="ex" id="ExLButtonDown"> <p><a class="ex_number" href="#ExLButtonDown"></a> Monitors mouse clicks in a GUI window. Related topic: <a href="Gui.htm#GuiContextMenu">GuiContextMenu</a></p> <pre>Gui, Add, Text,, Click anywhere in this window. Gui, Add, Edit, w200 vMyEdit Gui, Show OnMessage(0x0201, "WM_LBUTTONDOWN") return WM_LBUTTONDOWN(wParam, lParam) { X := lParam &amp; 0xFFFF Y := lParam &gt;&gt; 16 if A_GuiControl Ctrl := "`n(in control " . A_GuiControl . ")" ToolTip You left-clicked in Gui window #%A_Gui% at client coordinates %X%x%Y%.%Ctrl% } GuiClose: ExitApp</pre> </div> <div class="ex" id="shutdown"> <p><a class="ex_number" href="#shutdown"></a> Detects system shutdown/logoff and allows the user to abort it. On Windows Vista and later, the system displays a user interface showing which program is blocking shutdown/logoff and allowing the user to force shutdown/logoff. On older OSes, the script displays a confirmation prompt. Related topic: <a href="OnExit.htm">OnExit</a></p> <pre><em>; The following DllCall is optional: it tells the OS to shut down this script first (prior to all other applications).</em> DllCall("kernel32.dll\SetProcessShutdownParameters", "UInt", 0x4FF, "UInt", 0) OnMessage(0x0011, "WM_QUERYENDSESSION") return WM_QUERYENDSESSION(wParam, lParam) { ENDSESSION_LOGOFF := 0x80000000 if (lParam &amp; ENDSESSION_LOGOFF) <em>; User is logging off.</em> EventType := "Logoff" else <em>; System is either shutting down or restarting.</em> EventType := "Shutdown" try { <em>; Set a prompt for the OS shutdown UI to display. We do not display ; our own confirmation prompt because we have only 5 seconds before ; the OS displays the shutdown UI anyway. Also, a program without ; a visible window cannot block shutdown without providing a reason.</em> BlockShutdown("Example script attempting to prevent " EventType ".") return false } catch { <em>; ShutdownBlockReasonCreate is not available, so this is probably ; Windows XP, 2003 or 2000, where we can actually prevent shutdown.</em> MsgBox, 4,, %EventType% in progress. Allow it? IfMsgBox Yes return true <em>; Tell the OS to allow the shutdown/logoff to continue.</em> else return false <em>; Tell the OS to abort the shutdown/logoff.</em> } } BlockShutdown(Reason) { <em>; If your script has a visible GUI, use it instead of A_ScriptHwnd.</em> DllCall("ShutdownBlockReasonCreate", "ptr", A_ScriptHwnd, "wstr", Reason) OnExit("StopBlockingShutdown") } StopBlockingShutdown() { OnExit(A_ThisFunc, 0) DllCall("ShutdownBlockReasonDestroy", "ptr", A_ScriptHwnd) }</pre> </div> <div class="ex" id="ExCustom"> <p><a class="ex_number" href="#ExCustom"></a> Receives a custom message and up to two numbers from some other script or program (to send strings rather than numbers, see the example after this one).</p> <pre>OnMessage(0x5555, "MsgMonitor") OnMessage(0x5556, "MsgMonitor") MsgMonitor(wParam, lParam, msg) { <em>; Since returning quickly is often important, it is better to use ToolTip than</em> <em>; something like MsgBox that would prevent the function from finishing:</em> ToolTip Message %msg% arrived:`nWPARAM: %wParam%`nLPARAM: %lParam% } <em>; The following could be used inside some other script to run the function inside the above script:</em> SetTitleMatchMode 2 DetectHiddenWindows On if WinExist("Name of Receiving Script.ahk ahk_class AutoHotkey") PostMessage, 0x5555, 11, 22 <em>; The message is sent to the "<a href="../misc/WinTitle.htm#LastFoundWindow">last found window</a>" due to WinExist() above.</em> DetectHiddenWindows Off <em>; Must not be turned off until after PostMessage.</em></pre> </div> <div class="ex" id="SendString"> <p><a class="ex_number" href="#SendString"></a> Sends a string of any length from one script to another. To use this, save and run both of the following scripts then press <kbd>Win</kbd>+<kbd>Space</kbd> to show an input box that will prompt you to type in a string. Both scripts must use the same <a href="../Concepts.htm#native-encoding">native encoding</a>.</p> <p>Save the following script as <strong>Receiver.ahk</strong> then launch it.</p> <pre filename="Receiver.ahk">#SingleInstance OnMessage(0x004A, "Receive_WM_COPYDATA") <em>; 0x004A is WM_COPYDATA</em> return Receive_WM_COPYDATA(wParam, lParam) { StringAddress := NumGet(lParam + 2*A_PtrSize) <em>; Retrieves the CopyDataStruct's lpData member.</em> CopyOfData := StrGet(StringAddress) <em>; Copy the string out of the structure.</em> <em>; Show it with ToolTip vs. MsgBox so we can return in a timely fashion:</em> ToolTip %A_ScriptName%`nReceived the following string:`n%CopyOfData% return true <em>; Returning 1 (true) is the traditional way to acknowledge this message.</em> }</pre> <p>Save the following script as <strong>Sender.ahk</strong> then launch it. After that, press the <kbd>Win</kbd>+<kbd>Space</kbd> hotkey.</p> <pre filename="Sender.ahk">TargetScriptTitle := "Receiver.ahk ahk_class AutoHotkey" #space:: <em>; Win+Space hotkey. Press it to show an input box for entry of a message string.</em> InputBox, StringToSend, Send text via WM_COPYDATA, Enter some text to Send: if ErrorLevel <em>; User pressed the Cancel button.</em> return result := Send_WM_COPYDATA(StringToSend, TargetScriptTitle) if (result = "FAIL") MsgBox SendMessage failed. Does the following WinTitle exist?:`n%TargetScriptTitle% else if (result = 0) MsgBox Message sent but the target window responded with 0, which may mean it ignored it. return Send_WM_COPYDATA(ByRef StringToSend, ByRef TargetScriptTitle) <em>; ByRef saves a little memory in this case. ; This function sends the specified string to the specified window and returns the reply. ; The reply is 1 if the target window processed the message, or 0 if it ignored it.</em> { VarSetCapacity(CopyDataStruct, 3*A_PtrSize, 0) <em>; Set up the structure's memory area.</em> <em>; First set the structure's cbData member to the size of the string, including its zero terminator:</em> SizeInBytes := (StrLen(StringToSend) + 1) * (A_IsUnicode ? 2 : 1) NumPut(SizeInBytes, CopyDataStruct, A_PtrSize) <em>; OS requires that this be done.</em> NumPut(&amp;StringToSend, CopyDataStruct, 2*A_PtrSize) <em>; Set lpData to point to the string itself.</em> Prev_DetectHiddenWindows := A_DetectHiddenWindows Prev_TitleMatchMode := A_TitleMatchMode DetectHiddenWindows On SetTitleMatchMode 2 TimeOutTime := 4000 <em>; Optional. Milliseconds to wait for response from receiver.ahk. Default is 5000</em> <em>; Must use SendMessage not PostMessage.</em> SendMessage, 0x004A, 0, &amp;CopyDataStruct,, %TargetScriptTitle%,,,, %TimeOutTime% <em>; 0x004A is WM_COPYDATA.</em> DetectHiddenWindows %Prev_DetectHiddenWindows% <em>; Restore original setting for the caller.</em> SetTitleMatchMode %Prev_TitleMatchMode% <em>; Same.</em> return ErrorLevel <em>; Return SendMessage's reply back to our caller.</em> }</pre> </div> <p>See the <a href="../scripts/index.htm#WinLIRC">WinLIRC client script</a> for a demonstration of how to use OnMessage() to receive notification when data has arrived on a network connection.</p> </body> </html>