Registers a function or method to be called when a control notification is received via the WM_NOTIFY message.

GuiCtrl.OnNotify(NotifyCode, Callback , AddRemove)



Type: Integer

The control-defined notification code to monitor.


Type: String or Function Object

The function, method or object to call when the event is raised.

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.


Type: Integer

If omitted, it defaults to 1 (call the callback after any previously registered callbacks). Otherwise, specify one of the following numbers:


Certain types of controls send a WM_NOTIFY message whenever an interesting event occurs or the control requires information from the program. The lParam parameter of this message contains a pointer to a structure containing information about the notification. The type of structure depends on the notification code and the type of control which raised the notification, but is always based on NMHDR.

To determine which notifications are available (if any), what type of structure they provide and how they interpret the return value, refer to the control's documentation. Control Library (MSDN) contains links to each of the the Windows common controls. The notification codes (numbers) can be found in the Windows SDK, or by searching the Internet.

AutoHotkey uses the idFrom and hwndFrom fields to identify which control sent the notification, in order to dispatch it to the appropriate object. The code field contains the notification code. Since these must match up to the GuiControl and NotifyCode used to register the callback, they are rarely useful to the script.

Callback Parameters

The notes for OnEvent regarding this and bound functions also apply to OnNotify.

The callback receives two parameters:

Callback(GuiControl, lParam)

As noted above, lParam is the address of a notification structure derived from NMHDR. Its exact type depends on the type of control and notification code. If the structure contains additional information about the notification, the callback can retrieve it with NumGet and/or StrGet.

Callback Return Value

If multiple callbacks have been registered for an event, a callback may return a non-empty value to prevent any remaining callbacks from being called.

The return value may have additional meaning, depending on the notification. For example, the ListView notification LVN_BEGINLABELEDIT (-175 or -105) prevents the user from editing the label if the callback returns TRUE (1).

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

OnCommand can be used for notifications which are sent as a WM_COMMAND message.