Home Library Learn Downloads Support Community
Sign in | United States - English | |
0 out of 1 rated this helpful - Rate this topic

SetWindowSubclass function

Applies to: desktop apps only

Installs or updates a window subclass callback.

Syntax

Copy 
BOOL SetWindowSubclass(
  __in  HWND hWnd,
  __in  SUBCLASSPROC pfnSubclass,
  __in  UINT_PTR uIdSubclass,
  __in  DWORD_PTR dwRefData
);

Parameters

hWnd [in]

Type: HWND

The handle of the window being subclassed.

pfnSubclass [in]

Type: SUBCLASSPROC

A pointer to a window procedure. This pointer and the subclass ID uniquely identify this subclass callback. For the callback function prototype, see SUBCLASSPROC.

uIdSubclass [in]

Type: UINT_PTR

The subclass ID. This ID together with the subclass procedure uniquely identify a subclass. To remove a subclass, pass the subclass procedure and this value to the RemoveWindowSubclass function. This value is passed to the subclass procedure in the uIdSubclass parameter.

dwRefData [in]

Type: DWORD_PTR

DWORD_PTR to reference data. The meaning of this value is determined by the calling application. This value is passed to the subclass procedure in the dwRefData parameter. A different dwRefData is associated with each combination of window handle, subclass procedure and uIdSubclass.

Return value

Type: BOOL

TRUE if the subclass callback was successfully installed; otherwise, FALSE.

Remarks

Subclass callbacks are identified by the combination of the callback address and the caller-defined subclass ID. If the callback address and ID pair have not yet been installed, then this function installs the subclass. If the pair has already been installed, then this function just updates the reference data.

Each callback can store a single DWORD of reference data, which is passed to the callback function when it is called to filter messages. No reference counting is performed for the callback; it may repeatedly call SetWindowSubclass to alter the value of its reference data element.

Warning  You cannot use the subclassing helper functions to subclass a window across threads.

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

Header
Commctrl.h

Library
Comctl32.lib

DLL
Comctl32.dll (version 5.8 or later)

See also

GetWindowSubclass
DefSubclassProc
RemoveWindowSubclass

 

 

Send comments about this topic to Microsoft

Build date: 3/7/2012

Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ
works with Windows 2000 (Service Pack 4) too
I have no problems with Windows 2000 and comctl32.dll version: 5.81.4968.2500.

you need for sure:

#define _WIN32_WINNT 0x0501
#define WINVER 0x0501
#define _WIN32_WINDOWS 0x0501
History
subclass ID
Same window procedure, same ID:

SetWindowSubclass(hwnd, pfnSubclass1, 0, 1);
SetWindowSubclass(hwnd, pfnSubclass1, 0, 2);

-> pfnSubclass1 is called only once with dwRefData=2

Same window procedure, different ID:

SetWindowSubclass(hwnd, pfnSubclass1, 0, 1);
SetWindowSubclass(hwnd, pfnSubclass1, 1, 2);

-> pfnSubclass1 is called twice with dwRefData=1 and dwRefData=2

Different window procedures:

ID don´t matter.
History
Subclass must be removed before the window is destroyed.

An important detail about this API, quoted from Raymond Chen's blog:


One gotcha that isn't explained clearly in the documentation is that you must remove your window subclass before the window being subclassed is destroyed. This is typically done either by removing the subclass once your temporary need has passed, or if you are installing a permanent subclass, by inserting a call to RemoveWindowSubclass inside the subclass procedure itself: 

...
case WM_NCDESTROY:
  RemoveWindowSubclass(hwnd, thisfunctionname, uIdSubclass);
  return DefSubclassProc(...);


Original: http://blogs.msdn.com/oldnewthing/archive/2003/11/11/55653.aspx


History