Meandering Through the Maze of MFC Message and Command Routing

So let me guide you through the labyrinth of message and command routing, show you how MFC handles commands differently from other window messages, why menu items sometimes appear mysteriously grayed, how and when user interface objects get updated and how to solve all the problems I just mentioned. And more. Want to punt the document/view architecture in favor of something else? I‘ll show you how. I‘ll even show you some tricks to impress your friends. So grab your compass and golden thread, here we go.

Message Madness Made Merry 
I have a friend who‘s fond of saying, when confronted with any daunting task, "How do you eat an elephant? One bite at a time." Frankly, I can‘t for the life of me figure why anyone would attempt to eat an elephant, but I suspect the overall experience may not be unlike trying to digest MFC source code. To explain the intricacies of message and command handling, I‘ll break it into bite-sized pieces. At its simplest level, there are two steps:

1. Get a message. 
   
2. Process it.

1. Get a message. 
   
   • Maybe translate it.
2. Process it.
   
   • Process ordinary messages.
   • Process command messages.
3. Handle user interface objects

Pump It Up 
In the days of yore, when a hacker was anyone who spent most waking hours writing programs and C++ was confined to research halls, everyone wrote a function called WinMain with a loop that went like this:

 MSG msg;
 while (GetMessage(&msg, NULL, 0, 0)) {
    TranslateMessage(&msg);
    DispatchMessage(&msg);  // send to window proc
 }

 MSG msg;
 HWND hwnd =       // your main window
 HACCEL hAccel =   // load from resource file

 while (GetMessage(&msg, NULL, 0, 0)) {
    if (!TranslateAccelerator(hwnd, hAccel, &msg)) {
       // Not an accelerator, so dispatch as normal.
       TranslateMessage(&msg);
       DispatchMessage(&msg);
    }
 }

 int CWinApp::Run()
 {
 •
 •
 •
    for (;;) {
       while (!::PeekMessage(&m_msgCur,...)) {
          if (!OnIdle(...))    // do some idle work
             break;
       }
       // I have a message, or else no idle work to do: // pump it
       if (!PumpMessage())
          break;
    }
    return ExitInstance();
 }

 BOOL CWinApp::PumpMessage()
 {
 •
 •
 •
    if (!::GetMessage(&m_msgCur,...)) {
       return FALSE;
    }
    if (!PreTranslateMessage(&m_msgCur)) {
       ::TranslateMessage(&m_msgCur);
       ::DispatchMessage(&m_msgCur);
    }
    return TRUE;
 }

 BOOL CWinApp::PreTranslateMessage(MSG* pMsg)
 {
    for (pWnd = /* window that sent msg */; pWnd; pWnd=pWnd->getParent())
       if (pWnd->PreTranslateMessage(pMsg))
          return TRUE;

    if (pMainWnd = /* main frame and it‘s not one of the parents */)
       if (pMainWnd->PreTranslateMessage(pMsg))
          return TRUE;

    return FALSE;  // not handled
 }

 BOOL CDialog::PreTranslateMessage(MSG* pMsg)
 {
  if (pMsg->message >= WM_KEYFIRST && // for performance
      pMsg->message <= WM_KEYLAST)

    // maybe translate dialog key
    return ::IsDialogMessage(m_hWnd, pMsg);

  return FALSE;
 }

It makes a lot more sense to translate dialog messages in the dialog class instead of CWinApp, don‘t you think? CWinApp doesn‘t know a dialog from a hole in the wall. Of course, ::IsDialogMessage is technically only required for modeless dialogs, but PreTranslateMessage doesn‘t get called for modal dialogs because when you call DoModal, Windows starts another message loop and control doesn‘t return until the dialog is over. But the really wonderful thing is you never have to worry about ::IsDialogMessage again! In fact, you can just forget it exists: any dialog you write inherits the goodness from CDialog, even if you add it in a flurry of haste at the last minute. If you‘ve never programmed without MFC, you‘ve probably never even heard of IsDialogMessage. And a good thing, too! 
Likewise, since the frame window owns the menus, it makes sense for it to handle accelerators. And so it does. When you create the frame in your app‘s InitInstance function, it loads the accelerator table with whatever ID you used to define the document template, usually IDR_ MAINFRAME or IDR_MYDOCTYPE. CFrameWnd stores the table in m_hAccel, which CFrameWnd::PreTranslateMessage passes to ::TranslateAccelerator, magically translating your accelerators without you having to lift so much as a finger. (Well, you have to lift your finger to press the key, but that‘s all.) One interesting tidbit I discovered writing this article is that CFrameWnd first tries to get the accelerator table from CDocument::GetDefaultAccelerator. In other words, if you want document-specific accelerators, all you have to do is override this virtual function. (In older versions of MFC it‘s called GetDefaultAccel.) It‘s amazing the things you discover when you start poking around.
 Figure 3 shows how various MFC classes implement PreTranslateMessage. MFC handles about 99.9 percent of the situations you‘re likely to run into, so you can mostly forget about PreTranslateMessage. This month‘s C/C++ Q&A gives an example of the other 0.1 percent.
Oh, one more thing. In 32-bit versions of MFC, you can replace CWinApp with CWinThread everywhere in the preceding discussion. There‘s CWinThread::Run, CWinThread::OnIdle, CWinThread::PumpMessage, and CWinThread::PreTranslateMessage. I‘d have mentioned it straight away, but I didn‘t want to give you a heart attack so early in the story. In multitaskingland, each thread has its own message pump, and an app is just a specialization of a thread. So most MFC functions that were in CWinApp have migrated to CWinThread, from which CWinApp is now derived.

One Framework, One Window Proc 
Most messages are never translated. PreTranslateMessage returns FALSE all the way up the line and CWinApp::PumpMessage calls ::DispatchMessage, which is a kind of Windows wormhole. Your message disappears inside, then magically reappears in your window procedure (seeFigure 4). 

 LRESULT
 AfxWndProc(HWND hWnd, UINT nMsg, WPARAM wParam, LPARAM lParam)
 {
 •
 • // minor details omitted
 •
    CWnd* pWnd = CWnd::FromHandlePermanent(hWnd);
    return AfxCallWndProc(pWnd, hWnd, nMsg, wParam,
                          lParam);
 }

 LRESULT AFXAPI
 AfxCallWndProc(CWnd* pWnd,HWND hWnd,
               UINT nMsg,
               WPARAM wParam,
               LPARAM lParam)
 {
 •
 • // Save message params in a
 •//  state variable
   LRESULT lResult = pWnd->
WindowProc(nMsg, wParam, lParam);

 •
 •
 •
    return lResult;
 }

AfxCallWndProc calls WindowProc. Instead of passing an HWND to a C window procedure, MFC calls a CWnd virtual WindowProc function. So all that‘s been accomplished is to convert C into C++-. But oh, what an accomplishment that is! Because WindowProc is virtual!
CWnd::WindowProc is, as its name implies, the C++ equivalent of the window procedure. It‘s where messages are handled. Because it‘s virtual, different window classes can implement WindowProc differently. C++ virtual functions (aka polymorphism) are what make AfxWndProc work for all windows. 
You all know CWnd::WindowProc is not the place where you normally handle messages, but you should understand that you can handle messages here if you need to. WindowProc is the first stop on the message highway, the first CWnd function to see a message when it arrives. If you‘re porting a C program, you can more or less copy your entire window-proc-with-the-giant-switch-statement to CMainFrame::WindowProc, change "hwnd" to "m_hWnd," clean up a few details, and everything should work. Just don‘t tell anyone. And definitely don‘t tell them you learned it from me!

One Ringie-Dingie, Two Ringie-Dingie 
As everyone knows, the proper way to handle messages is through message maps. Where do message maps come in? CWnd::WindowProc does it. First, it checks to see if the message is WM_COMMAND or WM_NOTIFY. If so, the message takes a fork that I‘ll describe later. All other messages stay on the main road and get dispatched via your window‘s message map. CWnd::WindowProc acts like a central switchboard, directing messages right and left to the proper handler functions.

 class CMyFrame : public CFrameWnd {
    DECLARE_MESSAGE_MAP()
 };

 BEGIN_MESSAGE_MAP(CMyFrame, CFrameWnd)

 •
 • // entries
 •
 END_MESSAGE_MAP()

 class CMyFrame : public CFrameWnd {
 private:
    static const AFX_MSGMAP_ENTRY _messageEntries[];
 protected:
    static AFX_DATA const AFX_MSGMAP messageMap;
    virtual const AFX_MSGMAP* GetMessageMap() const;
 };

 // BEGIN_MESSAGE_MAP
 const AFX_MSGMAP* CMyFrame::GetMessageMap() const
 { return &CMyFrame::messageMap; }

 const AFX_MSGMAP CMyFrame::messageMap = {
    &CFrameWnd::messageMap,   // base class‘s message map
    &CMyFrame::_messageEntries[0] // this class‘s entries
 };

 const AFX_MSGMAP_ENTRY CMyFrame::_messageEntries[] = {
 •
 • // entries
 •

 // END_MESSAGE_MAP:
    {0, 0, 0, 0, 0, 0 }
 };

 struct AFX_MSGMAP {
    const AFX_MSGMAP* pBaseMap;
    const AFX_MSGMAP_ENTRY* lpEntries;
 };

 struct AFX_MSGMAP_ENTRY {
    UINT nMessage;   // windows message
    UINT nCode;      // control code or WM_NOTIFY code
    UINT nID;        // control ID (or 0 for windows
                     // messages)
    UINT nLastID;    // used for entries specifying a
                     // range of control id‘s
    UINT nSig;       // signature type (action) or
                     // pointer to message #
    AFX_PMSG pfn;    // routine to call (or special
                     // value)
 };

 { WM_CREATE, 0, 0, 0, AfxSig_is,
    (AFX_PMSG)(AFX_PMSGW)(int (CWnd::*)(LPCREATESTRUCT))OnCreate },

 { msg, 0, 0, 0, AfxSig_lwl,
    (AFX_PMSG)(AFX_PMSGW)(LRESULT (CWnd::*)(WPARAM, LPARAM))mbrfn },

 typedef void (CCmdTarget::*AFX_PMSG)(void);

 LRESULT CWnd::WindowProc(UINT nMsg, WPARAM wParam, LPARAM lParam)
 {
 •
 •
 •

 const AFX_MSGMAP_ENTRY* lpEntry = // (entry for this
                                   //  message)

 union MessageMapFunctions mmf; // described below ptr
 mmf.pfn = lpEntry->pfn;        // to your virtual function

 switch (lpEntry->nSig) {
 case AfxSig_is:
   return (this->*mmf.pfn_is)((LPTSTR)lParam);

 case AfxSig_lwl:
   return (this->*mmf.pfn_lwl)(wParam, lParam);
 •
 • // etc
 •
 }

 enum AfxSig {
    AfxSig_end = 0, // [marks end of message map]

    AfxSig_bD,      // BOOL (CDC*)
    AfxSig_bb,      // BOOL (BOOL)
    AfxSig_bWww,    // BOOL (CWnd*, UINT, UINT)
    AfxSig_hDWw,    // HBRUSH (CDC*, CWnd*, UINT)
    AfxSig_iwWw,    // int (UINT, CWnd*, UINT)
    AfxSig_iWww,    // int (CWnd*, UINT, UINT)
    AfxSig_is,      // int (LPTSTR)
    AfxSig_lwl,     // LRESULT (WPARAM, LPARAM)
 •
 •
 •
 };

 union MessageMapFunctions
 {
    AFX_PMSG pfn;   // generic member function pointer

    // specific type safe variants
    BOOL    (CWnd::*pfn_bD)(CDC*);
    BOOL    (CWnd::*pfn_bb)(BOOL);
    BOOL    (CWnd::*pfn_bWww)(CWnd*, UINT, UINT);
    HBRUSH  (CWnd::*pfn_hDWw)(CDC*, CWnd*, UINT);
    int     (CWnd::*pfn_iwWw)(UINT, CWnd*, UINT);
    int     (CWnd::*pfn_iWww)(CWnd*, UINT, UINT);
    int     (CWnd::*pfn_is)(LPTSTR);
    LRESULT (CWnd::*pfn_lwl)(WPARAM, LPARAM);
    •
    • // etc, for each AfxSig code
    •
 };

 BEGN_MESSAGE_MAP(...)
    ON_MESSAGE(WM_RUN_FOR_CONGRESS, OnRunForCongress)

 •
 •
 •
 END_MESSAGE_MAP()

 LRESULT OnRunForCongress(WPARAM wp, LPARAM, lp)
 {
    CCongressionalDistrict* pCd = (CCongressionalDistrict*)lp;
 •
 •
 •
 }

 #define ON_WM_RUN_FOR_CONGRESS()     { WM_RUN_FOR_CONGRESS, 0, 0, 0, AfxSig_is, (AFX_PMSG)(AFX_PMSGW)        (int (CWnd::*)(CCongressionalDistrict*))OnRunForCongress },

 BEGIN_MESSAGE_MAP(...)
    ON_WM_RUN_FOR_CONGRESS()
 •
 •
 •
 END_MESSAGE_MAP()

 // Returns int to agree with AfxSig_is.
 int OnRunForCongress(CCongressionalDistrict* pCd)
 {
    pCd->RunForHouse();
    pCd->RunForSenate();
    return 0;   // mission accomplished
 }

If you want other parameters, chances are you can find a suitable AfxSig_xxx code. But like I said, for most purposes there‘s no need to go to such extremes; ON_MESSAGE works just fine.

What, No Handler? 
If there‘s no entry in the message map, WindowProc calls CWnd::DefWindowProc, which as you‘d expect is the C++ analogue of ::DefWindowProc, the Windows default message procedure. The CWnd version passes the message to the original window proc, the one the window had before MFC subclassed it, which in fact might very well be ::DefWindowProc! Or it might be the default proc for an edit control or MDI child window. The point is, that‘s it. That‘s the end of this message, it‘s been processed, control returns all the way back, back, back out of AfxWndProc, pops through the wormhole, and ::DispatchMessage returns. Done. Finis. The End. Next, please.
The other way control can end up in CWnd::DefWindowProc is via one of the default CWnd::OnFooMumbleBletch implementations. When you handle a message, you frequently do something special, then call the base class.

 CMyWnd::OnFooMumbleBletch()
 {
 •
 •
 •
    CWnd::OnFooMumbleBletch();
 }

 // (From AFXWIN2.INL)
 inline void CWnd::OnSize(UINT, int, int) { Default(); }
 inline void CWnd::OnSetFocus(CWnd*)      { Default(); }
 inline BOOL CWnd::OnNcActivate(BOOL)
  // return (BOOL)Default(); }
 •
 • // etc
 •

Default() does the same thing as DefWindowProc, the only difference being that Default requires no arguments (msg, wParam, lParam) because it gets them from the state structure where AfxCallWndProc saved them. Remember?
In case you‘re wondering, you‘ve eaten about half the elephant now. You may want to eat some TUMS.

The Evil WM_COMMAND 
I mentioned that CWnd::WindowProc sends WM_COMMAND messages down a different fork along the message routing interstate. It‘s time to explore that path.
WM_COMMAND is an unfortunately overloaded message. Windows sends it whenever the user invokes a command, either through the menu or an accelerator key. WPARAM tells which. But controls also use WM_ COMMAND to send notifications, for example when a button sends BN_CLICKED or an edit control sends EN_ CHANGED. When this happens, the control‘s HWND, notification code, and ID are packed like sardines into WPARAM and LPARAM, leaving no room for additional information. How they‘re packed depends on whether you‘re using 16-bit Windows or Win32.
Overloading WM_COMMAND like this has one nice benefit: pressing a button looks to your app much like invoking a menu command. But conceptually, they‘re entirely different events. A command means "do something," whereas a control notification means "something happened." Newer versions of Windows, such as Windows® for Workgroups 3.11 and versions of Win32 that use the new common controls, introduce a new message, WM_NOTIFY, that attempts to separate these events. WM_NOTIFY is a generalized control notification. Instead of packing WPARAM and LPARAM up the wazoo, LPARAM contains a pointer to a struct.

 struct NMHDR {
    HWND hwndFrom;     // control that sent notification
    UINT idFrom;       // ID of control
    UINT code;         // notification code
 };

 struct TOOLTIPTEXT {  // In C++, you can derive from NMHDR
     NMHDR hdr;        // standard header
     LPSTR lpszText;   // tip text or LPSTR_CALLBACK
     char szText[80];  // tip text
     HINSTANCE hinst;
     UINT uFlags;
 };