OnMessage (GUI) [v2.1-alpha.1+]

Registers a function or method to be called whenever the GUI window or control receives the specified message.

Note: Window messages exist only on Windows. On Linux and macOS the registration is accepted, so a cross-platform script still loads, but the callback is never called.

Gui.OnMessage(MsgNumber, Callback , AddRemove)
GuiCtrl.OnMessage(MsgNumber, Callback , AddRemove) ; Requires [v2.1-alpha.7+]

Parameters

MsgNumber

Type: Integer

The number of the message to monitor.

Callback

Type: String or Function Object

The function, method or object to call when the message is received.

If the GUI has an event sink (that is, if Gui()'s EventObj parameter was specified), this parameter may be the name of a method belonging to the event sink. Otherwise, this parameter must be a function object.

The callback accepts four parameters and can be defined as follows:

MyCallback(GuiOrCtrlObj, wParam, lParam, msg) { ...

Although the names you give the parameters do not matter, the following values are sequentially assigned to them:

  1. The Gui or GuiControl object of the GUI window or control which received the message.
  2. The message's WPARAM value.
  3. The message's LPARAM value.
  4. The message number, which is useful in cases where a callback monitors more than one message.

You can omit one or more parameters from the end of the callback's parameter list if the corresponding information is not needed, but in this case an asterisk must be specified as the final parameter, e.g. MyCallback(Param1, *).

However, refer to the notes for OnEvent, especially regarding this and the GuiOrCtrlObj parameter.

If the callback returns a non-empty value, it is used as the message's reply, any remaining callbacks are not called, and the GUI window's default processing of the message is suppressed.

The callback should return either an integer or an empty string, or not explicitly return.

AddRemove

Type: Integer

If omitted, it defaults to 1. Otherwise, specify one of the following numbers:

Any other value raises a ValueError: a GUI event runs only one thread at a time, so this parameter is an ordering and removal switch rather than a thread count.

Remarks

These notes for OnEvent also apply to OnMessage: Threads, Destroying the GUI.

[v2.1-alpha.7+]: When the callback is called, A_EventInfo and the last found window are set as per Additional Information Available to the Callback.

Gui-specific message callbacks are called after global message callbacks (registered with the OnMessage function), but before the GUI window's own default processing takes place.

The callback function may be called recursively if the message is received while the callback is already running. The number of threads that can be started is limited only by #MaxThreads.

[v2.1-alpha.7+]: For GuiCtrl.OnMessage, window subclassing is used to detect or intercept messages sent directly to the control. These messages are not detected by the global OnMessage function.

Gui and GuiControl methods: OnEvent, OnNotify, OnCommand

Functions: OnMessage, PostMessage, SendMessage, Critical, DllCall

Other: List of Windows Messages, Threads