Registers a function or method to be called whenever the GUI window or control receives the specified message.
Note: On Linux and macOS, only mouse and keyboard input messages (WM_MOUSEMOVE, the left, right and middle button down, up and double-click messages, WM_MOUSEWHEEL, WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, WM_SYSKEYUP and WM_CHAR) are synthesized from the script's own GUI events; callbacks for other messages are never called. Delivery is verified on Linux X11 and Wayland; macOS delivery remains unverified.
Gui.OnMessage(MsgNumber, Callback , AddRemove) GuiCtrl.OnMessage(MsgNumber, Callback , AddRemove) ; Requires [v2.1-alpha.7+]
Type: Integer
The number of the message to monitor.
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:
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, including 0, 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. A non-numeric string replies 0. A callback whose thread ends with an error also stops the remaining callbacks, while one which calls Exit passes the message to the next.
The callback should return either an integer or an empty string, or not explicitly return.
Type: Integer
If omitted, it defaults to 1. Otherwise, specify one of the following numbers:
Any other value raises a ValueError.
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+]: On Windows, GuiCtrl.OnMessage uses window subclassing to detect or intercept messages sent directly to the control. These directly sent messages are not detected by the global OnMessage function.
On Linux and macOS, synthesized GUI input messages reach global OnMessage callbacks first, then Gui.OnMessage for a message addressed to the GUI window or GuiCtrl.OnMessage for one addressed to a control. Events not raised by the toolkit are not delivered. On Linux, GTK's single-line Edit consumes mouse-button presses before these callbacks can observe them.
Gui and GuiControl methods: OnEvent, OnNotify, OnCommand
Functions: OnMessage, PostMessage, SendMessage, Critical, DllCall
Other: List of Windows Messages, Threads