What is the `uIdSubclass` in the third `SetWindowSubclass` Parameter? - c++

Question

According to: http://msdn.microsoft.com/en-us/library/windows/desktop/bb762102(v=vs.85).aspx
the SetWindowSubclass prototype is:
BOOL SetWindowSubclass(
__in HWND hWnd,
__in SUBCLASSPROC pfnSubclass,
__in UINT_PTR uIdSubclass,
__in DWORD_PTR dwRefData
);
Ok, I understand hWnd, pfnSubclass, and dwRefData.
What I can not find good information on is, what do I set uIdSubclass to?
MSDN says:
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.
Ok, understood, but still, where do I get this ID? Is it something I create or do I get it someplace? If it something I create, what should it look like?
I am doing this in C++ and Win32 API, nothing else.
Thanks.

Answer 1

Karl E. Peterson writes about the purpose of the uIdSubclass parameter in Visual Studio Magazine 07/16/2009 Subclassing the XP Way and provides an example named HookXP
Topics discussed in Karl E. Peterson's article:
Use uIdSubclass to store a this pointer [or HWND].
Use dwRefData to pass optional data, e.g. pointer to create data.
It is important to handle WM_NCDESTROY in pfnSubclass and call
RemoveWindowSubclass() passing uIdSubclass used in call to SetWindowSubclass().
Quotes from Karl E. Peterson's article
Each subclass is identified two pieces of data along with the window's hWnd -- those being a pointer to the new message-handling procedure and a unique ID that's up to you to generate. You may also select to pass one Long value along as an extra parameter to each callback, for whatever purpose you may desire. The thought that immediately struck me was to use an ObjPtr() as the unique ID for each subclass. What object? The one that will be handling the callback!
About the only undocumented caveat I've run into is that you must be sure to unhook your subclass before a window is destroyed. If you use my technique of embedding the handler in a form or class that's destroyed during the Form_Unload method, this should never be a problem. If you really don't want to take any chances, you can insert a simple branch in your handling routine:
Select Case uiMsg
Case WM_THIS
'
Case WM_THAT
'
Case WM_NCDESTROY
Call Unhook ' !!!
End Select
The Explorer Browser Search Sample also has a example of using uIdSubclass to store a pointer to this.
void CExplorerBrowserSearchApp::_OnInitializeDialog()
{
...
// Register the searchbox icon to receive hover and mouseclick events
SetWindowSubclass(GetDlgItem(_hdlg, IDC_SEARCHIMG), s_SearchIconProc, (UINT_PTR)this, 0);
...
}
Raymond Chen's blog "The Old New Thing" article Safer subclassing also mentions the importance handling WM_NCDESTROY in pfnSubclass for the purpose of calling RemoveWindowSubclass().
Quote from Raymond Chen's article
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(...);
As a side note the Microsoft SetWindowSubclass documentation has the caveat of SetWindowSubclass() being limited to a per thread basis.
Warning You cannot use the subclassing helper functions to subclass a window across threads.