OnNotify

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

GuiControl.OnNotify(NotifyCode, Callback , AddRemove := 1)

Parameters

GuiControl

The GuiControl object of the control to monitor.

NotifyCode

The control-defined notification code to monitor.

Callback

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

If this parameter is a string, its meaning depends on whether the GUI has an event sink (that is, whether GuiCreate's EventObj parameter was specified). If the GUI has an event sink, the string must be the name of a method belonging to the event sink; otherwise, it must be the name of a function.

To register a function regardless of whether the GUI has an event sink, pass a function reference.

AddRemove

One of the following values:
1 (the default): Call the callback after any previously registered callbacks.
-1: Call the callback before any previously registered callbacks.
0: Do not call the callback.

WM_NOTIFY

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).

Related

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.