Windows 95 Subclassing and Superclassing

Windows supplies a number of ready-to-use window classes, including listboxes, comboboxes, and scrollbars. While these controls are intended to be feature laden and general enough for use in any application, there may be times when you require slightly different behavior from controls. Although you could design your own control from scratch, both window subclassing and superclassing let you inherit features and styles from one or more windows. However, the form you use is dictated by your particular requirements. For example, if you're creating a single control that inherits from a Windows control, then you'll likely use subclassing to create your new control. If, on the other hand, you plan to create several controls that inherit similar features from a common class, you may want to use superclassing. In this case, superclassing reduces your programming effort while producing smaller code in your application.

When registering a window class, you fill in the members of the WNDCLASSEX structure and pass the address of the structure to the RegisterClassEx function. Of course, before calling RegisterClassEx, you must initialize the lpfnWndProc member of the WNDCLASSEX structure to point to the address of the class's window procedure. This procedure processes messages pertaining to all windows of this class. Before RegisterClassEx returns, the system allocates an internal block of memory that contains information about the window class. The class's window procedure address is part of this block.

Whenever a new window is created, the system allocates another internal block of memory containing information specific to the new window. When the system allocates and initializes the block of memory for this window, the system copies the class's window procedure address from the class's internal memory block into the window's internal memory block. When a message is dispatched to a window procedure, the system examines the value of the window procedure in the window's memory block and calls the function whose address is stored there. The system does not use the window procedure address stored in the window class's memory block when dispatching a message to a window. The window procedure address stored in the class's memory block is there only so that it can be copied when a window is created--the system does not use this address for any other purpose.

To subclass a window, you change the window procedure address in the window's memory block to point to a new window procedure. Because the address is changed in one window's memory block, it does not affect any other windows created from the same class. If the system did not give each window instance its own copy of the window procedure address, changing the class's address would alter the behavior of all windows in the class. If this were the case, subclassing a single edit control so that it would no longer accept digits also would cause all edit controls used within a single process to stop accepting digits. This certainly is not desirable.

Once you have changed the window procedure address in the window's memory block, all messages destined for the window are sent to the function at this new address. This function must look exactly like a standard window procedure. In other words, its prototype must have an identical prototype.

Once the message destined for the original window procedure has been sent to your procedure, you can:

• Pass it to the original procedure. This option is used for most messages. The reason for subclassing is usually to alter the behavior of a window only slightly. For this reason, most messages are passed to the original procedure so that the default behavior for this window class can be performed.
• Stop the message from being passed to the original procedure. For example, if you want an edit control to stop accepting digits, you examine WM_CHAR messages, check to see if the character (wParam parameter) is between 0 and 9, and, if it is, immediately return from the SubClassWndProc function. If the character is not a digit, you pass the message to the original window procedure for edit controls.
• Alter the message before sending it. If you want a combobox to accept only uppercase characters, examine each WM_CHAR message and convert the key (contained in wParam) to uppercase (using the CharUpper function) before passing the message to the original procedure.

When you subclass a window, you often want to define some new window messages that can be sent to the window. Let's say that you create an edit window that accepts only numbers (using the new ES_NUMBER window style). Then, you subclass this edit window to alter its behavior slightly. For example, you might want to define a new window message, EM_ADDNUM, that you can send to your subclassed window to make adding a value to the number shown in the subclassed edit window very easy. How should you define this EM_ADDNUM message? Normally, if you were implementing a window class entirely by yourself, you would define your class-specific window messages starting with WM_USER. For example, the EM_ADDNUM message might be defined as #define EM_ADDNUM (WM_USER + 0).

But, when you are subclassing a window that was originally created from a class that you did not implement yourself, you cannot simply create new window messages starting at WM_USER. All the new common controls, like trackbars, have their class-specific messages starting at WM_USER. For example, the trackbar class's TBM_GETPOS message is defined as #define TBM_GETPOS (WM_USER).

If you subclass a trackbar window and define your own message with a value of WM_USER + 0, your subclass procedure intercepts the message and processes the message your way. Any code that is expecting to send the TBM_GETPOS message in order to retrieve size information will be in for a big surprise!

So, you can start defining your messages at WM_USER + 500. But, this isn't really a safe approach because you don't know if Microsoft has created any undocumented (WM_USER + x) messages specific for the control. If you add your own user message starting at WM_USER + 500, it could conflict with an undocumented message recognized by the trackbar class. Actually, choosing any value would be tempting fate.

Fortunately, there are two ways to solve this problem. The first is to use the RegisterWindowMessage function, which creates a new message that is unique as long as the string we pass to it is also unique. Whenever you call RegisterWindowMessage, you know that the integer value returned identifies a message that is ignored by any and all window procedures that have not also requested to register the same string message.

The second way to solve the problem is much easier. Starting with Windows 95, Microsoft has declared that all third-party window-class procedures must ignore messages that range from WM_APP to 0xBFFF, inclusive where WM_APP is defined in WinUser.H as #define WM_APP 0x8000.

This means Microsoft guarantees that all system-global window classes and all new common controls will ignore messages in this range. It also means other companies that produce controls also should ignore messages in this range. You should definitely check with the vendor of any controls you use to make sure that they do not process any messages above WM_APP.

Because these classes ignore messages in this range, you can safely define your EM_ADDNUM message for our subclassed edit window as #define EM_ADDNUM (WM_APP + 0). Now, when you send this message to a subclassed edit window, it will know, beyond a shadow of a doubt, that you want it to add a number to the value shown in the edit control.

Another problem with subclassing windows is that associating additional data with the window is difficult. For example, you might like to associate a valid numeric range with our subclassed edit window. Because you did not register the edit window class, you have no way to add additional class and/or window extra bytes. In addition, because subclassing requires that a window instance already exists before you can subclass it, increasing the number of class or window extra bytes is also impossible.

The best way to associate data with a subclassed window is to use window properties. You also could use the GWL_USERDATA bytes to store an address of a data structure that contains some additional data, but this is not a good idea. The GWL_USERDATA bytes are supposed to be available for the application that creates and manipulates the window. Since your subclass procedure doesn't create the window, but acts very much like a window procedure, you should not touch the GWL_USERDATA bytes. Window properties are the only robust solution.

Of course, if you know that the users of your subclassed window will not touch the GWL_USERDATA bytes, you can use them, but you sacrifice some flexibility that you may desire in the future.

Window superclassing is similar to window subclassing. Again, you are associating a different window procedure address with a window to alter a single window's behavior slightly. With window superclassing, however, you create a new window class that has altered behavior. Superclassing is most useful if you intend to create several windows, all with slightly altered behavior. (There are some other differences between subclassing and superclassing that will be discussed later.) Creating a superclass is accomplished by registering a new window class. For example, let's say that your application needs to create several edit windows where each of the windows can accept only letters. You could create all the windows and then subclass each individually in order to get the desired effect, or you could use window superclassing.

For window superclassing, you must create a superclass window procedure that is almost identical to a window subclass procedure. The prototype is the same, and the way that you intercept messages is the same. In fact, the only difference is how you call the original window procedure.

In our book Windows 95: A Developer's Guide, we present the Arcade application which demonstrates how to create an animated button class (AniBtn) by superclassing the standard button class. AniBtn works almost identically to the standard button class except that it takes advantage of the new image list controls to create buttons that have animated icon images instead of boring, old text. Due to space constraints, we can't present a discussion here. However, we have provided the Arcade application electronically (see "Availability," on page 3) and a complete discussion can be found in our book. With the techniques presented here, you should be able to create your own controls that inherit from standard Windows controls.

static LPCSTR g_szSubclassWndProcOrig = "SubclassWndProcOrig";
int WINAPI WinMain (HINSTANCE hinstExe, HINSTANCE hinstPrev,
   LPSTR lpszCmdLine, int nCmdShow) {
   HWND hwndEdit = CreateWindowEx(0, "EDIT", "", WS_CHILD, 10, 20,
      100, 16, hWndParent, NULL, hInstance, 0L);
   //Change the window procedure address associated with this one edit
   //control
   pfnWndProcOrig = SubclassWindow(hwndEdit, Edit_SubclassWndProc);
   // Associate the original window procedure address with the window
   SetProp(hwndEdit, g_szSubclassWndProcOrig, (HANDLE) (DWORD)
          pfnWndProcOrig);
   // Messages destined for hwndEdit are sent to Edit_SubclassWndProc
   // instead
}
   .
   .
   .
LRESULT WINAPI Edit_SubclassWndProc (HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam) {
   LRESULT lResult = 0;
   BOOL fCallOrigWndProc = TRUE;
   switch (uMsg) {
      // Some cases set fCallOrigWndProc to FALSE.
      .
      .
      .
   }
   if (fCallOrigWndProc)
      lResult = CallWindow(
         (WNDPROC) (DWORD) GetProp(hwnd, g_szSubclassWndProcOrig),
         hwnd, uMsg, wParam, lParam);
   return(lResult);
}

#define SubclassWindow(hwnd, lpfn) \     
    ((WNDPROC)SetWindowLong((hwnd), GWL_WNDPROC, \
    (LPARAM)(WNDPROC)(lpfn)))

// Store the address of the original window procedure.
WNDPROC g_pfnWndProcOrig;
    .
    .
    .
int WINAPI WinMain (HINSTANCE hinstExe, HINSTANCE hinstPrev,  
    LPSTR lpszCmdLine, int nCmdShow) {  
    WNDCLASSEX wc;  
    adgINITSTRUCT(wc, TRUE);  
    // Get all the information about the original window class  
    GetClassInfoEx(NULL, "EDIT", &wc);  
    // Save the original window procedure address so that the  
    // Edit_SuperClassWndProc can use it.  
    g_pfnWndProcOrig = wc.lpfnWndProc;  
    // Our new class must have a new class name.  
    wc.lpszClassName = "NoDigits";  
    // Our new class is registered by our module.  
    wc.hInstance = hinstExe;  
    // Our new class has a different window procedure address.  
    wc.lpfnWndProc = NoDigitsClass_SuperClassWndProc;  
    // Register our new window class.  
    RegisterClassEx(&wc);  
    // At this point we can create windows of the NoDigits window class.
    // All messages that go to these windows are sent to the  
    // NoDigitsClass_SuperClassWndProc first where we can decide if we  
    // want to pass them on to g_pfnWndProcOrig.  
        .  
        .  
        .
}
LRESULT WINAPI NoDigitsClass_SuperClassWndProc (HWND hwnd, UINT uMsg,  
    WPARAM wParam, LPARAM lParam) {  
    LRESULT lResult = 0;  
    BOOL fCallOrigWndProc = TRUE;  
    switch (uMsg) {     
        .     
        .     
        .  
    }  
    if (fCallOrigWndProc)     
      lResult = CallWindowProc(g_pfnWndProcOrig,hwnd,uMsg,wParam,lParam);
       return(lResult);
}

// Global variables to save the number of class extra bytes, the window
// extra bytes, and the window procedure address of listbox base class
int g_cbClsExtraOrig, g_cbWndExtraOrig;
WNDPROC g_pfnWndProcOrig;
// Index into window extra bytes where our edit data can be found.
// These data follow the data required by the base class.
#define GWL_NODIGITSDATA      (g_cbWndExtraOrig + 0)
    .
    .
    .
ATOM WINAPI NoDigitsClass_RegisterClass (void) {  
    WNDCLASSEX wc;  
    GetClassInfoEx(NULL, "Edit", &wc);     
    // Save the information we need later in global variables.  
    g_cbClsExtraOrig = wc.cbClsExtra;  
    g_cbWndExtraOrig = wc.cbWndExtra;  
    g_pfnWndProcOrig = wc.lpfnWndProc;  
    // Add four window extra bytes to account for additional edit data.
    wc.cbWndExtra += sizeof(LONG);  
    // Change lpfnWndProc, lpszClassName, and hInstance members, too.
        .  
        .  
        .  
    // Register the new window class.  
    return(RegisterClassEx(&wc));
}
LRESULT WINAPI NoDigitsClass_SuperClassWndProc (HWND hwnd, UINT uMsg,  
    WPARAM wParam, LPARAM lParam) {  
    int nNoDigitsData;  
        .  
        .  
        .  
    // Retrieve our data from the added window extra bytes.  
    nNoDigitsData = GetWindowLong(hwnd, GWL_NODIGITSDATA);  
        .  
        .  
        .  
    // Call base class window procedure for remainder of processing. return(CallWindowProc(g_pfnWndProcOrig,  hwnd, uMsg, wParam, lParam));
}

/******************************************************************************
Module name: NoDigits.c
Written by: Jeffrey Richter
Notices: Copyright (c) 1995 Jeffrey Richter
Purpose: Demonstrates how to subclass a window
******************************************************************************/
#include "..\Win95ADG.h"          /* See Appendix A for details */
#include <Windows.h>
#include <WindowsX.h>
#pragma warning(disable: 4001)    /* Single-line comment */
#include "resource.h"
///////////////////////////////////////////////////////////////////////////////
// Function that converts an edit window to a NoDigitsClass window
// by subclassing the edit window
BOOL WINAPI NoDigitsClass_ConvertEdit (HWND hwnd, BOOL fSubclass);
///////////////////////////////////////////////////////////////////////////////
BOOL NoDigits_OnInitDialog (HWND hwnd, HWND hwndFocus, LPARAM lParam) {
   adgSETDLGICONS(hwnd, IDI_SUBCLASS, IDI_SUBCLASS);
   // Turn the regular edit windows into NoDigits windows by subclassing them.
   NoDigitsClass_ConvertEdit(GetDlgItem(hwnd, IDC_NODIGITS1), TRUE);
   NoDigitsClass_ConvertEdit(GetDlgItem(hwnd, IDC_NODIGITS2), TRUE);
   return(TRUE);  // Accepts default focus window.
}
///////////////////////////////////////////////////////////////////////////////
void NoDigits_OnCommand (HWND hwnd, int id, HWND hwndCtl, UINT codeNotify) {
   switch (id) {
      case IDCANCEL:              // Allows dialog box to close.
         // Turn the NoDigits windows back into regular Edit windows.
         NoDigitsClass_ConvertEdit(GetDlgItem(hwnd, IDC_NODIGITS1), FALSE);
         NoDigitsClass_ConvertEdit(GetDlgItem(hwnd, IDC_NODIGITS2), FALSE);
         EndDialog(hwnd, id);
         break;
   }   
}
///////////////////////////////////////////////////////////////////////////////
BOOL WINAPI NoDigits_DlgProc (HWND hwnd, UINT uMsg, 
   WPARAM wParam, LPARAM lParam) {
   switch (uMsg) {
      // Standard Window's messages
      adgHANDLE_DLGMSG(hwnd, WM_INITDIALOG, NoDigits_OnInitDialog);
      adgHANDLE_DLGMSG(hwnd, WM_COMMAND,    NoDigits_OnCommand);
   }
   return(FALSE);                 // We didn't process the message.
}
///////////////////////////////////////////////////////////////////////////////
int WINAPI WinMain (HINSTANCE hinstExe, HINSTANCE hinstPrev, 
   LPSTR lpszCmdLine, int nCmdShow) {
   adgWARNIFUNICODEUNDERWIN95();
   adgVERIFY(-1 != DialogBox(hinstExe, MAKEINTRESOURCE(IDD_NODIGITS),
      NULL, NoDigits_DlgProc));
   return(0);
}
//////////////////////////////// End of File //////////////////////////////////