Meandering Through the Maze of MFC Message and Command Routing MFC消息路由机制分析

Meandering Through the Maze of MFC Message and Command Routing

 

Paul DiLascia

                                                                                       

Paul DiLascia is a freelance software consultant specializing in developing C++ applications for Windows. He is the author of Windows++: Writing Reusable Code in C++ (Addison-Wesley, 1992).

 

If you've ever written even a simple program using Visual C++™ and MFC, you're familiar with messages and commands. You know that MFC uses something called "message maps" to route Windows®messages to your virtual functions. But being familiar with something is not the same as understanding it. How does it all work? And what if you ever want to do something unusual? 
It goes something like this. You run AppWizard to create a fledgling app. You fill in the blanks, write some code to handle OnFileNew and OnFileOpen. You write your view's OnDraw function. You add more menu commands and maybe some toolbar buttons for them. With ClassWizard, hooking everything up is a breeze. You add some message handlers: WM_CLOSE to clean up as your main frame is dying and WM_SIZE to shuffle the child windows when your view changes size. You're really flying now. Your app is growing by leaps and bounds. Serialization works, your view manages several windows, they all paint themselves correctly. You've got a half dozen dialog boxes and a cute bitmap in your About box. Hey, this is fun. Aren't you glad you switched to C++? 
Then it happens. 
Something unusual comes up. Maybe it's a modeless dialog or a specialized control bar and you figured you could use ON_UPDATE_COMMAND_UI to enable and disable the buttons. But it doesn't work. Or maybe you want to handle a command, but the ID is stored in a variable, not a #define symbol. Or maybe you have a specialized child window with ON_COMMAND entries in its message map. But, funny, the menu item shows up grayed. So you crank up the debugger, pick the Fooble command, and watch closely as control flows through the twisty maze. Mumble calls Fumble calls Bumble calls Bletch. Where oh where will your message go next? Poof! Into a black hole.
And what if you want to route commands to new objects? Where do you begin? Which of the seemingly gazillions of virtual functions do you override to change MFC's behavior? If you unplug that wire, will the whole thing fizzle? How do you reroute a few cortical pathways without lobotomizing your program? 
MFC's command routing paths are bogglesome even to supposed experts like me. The first time I traced the flow of a simple command like ID_APP_EXIT, I came away with a mental picture of MFC's message routing system that resembled something like Figure 1. Judging from the scores of questions I get, I'm not alone. 

 

Figure 1 Where's the Minotaur?

 

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.

Simple, right? The first involves not only getting the message, but also possibly translating it. As for step two, MFC devotes so much effort to processing WM_COMMAND messages that it makes sense to consider commands separately from other Windows messages. MFC also adds a new concept that doesn't exist in Windows: user interface objects. You know, those little CCmdUI doodads that come your way when it's time to enable menu items and toolbar buttons? The ones in the UPDATE_COMMMAND_UI handlers? So the revised elephant dissection looks something like this:

1. Get a message. 

• Maybe translate it.

1. Process it.

• Process ordinary messages.
• Process command messages.

1. Handle user interface objects

In the sections that follow, I'll discuss these topics in detail. I'll describe the vanilla way things work, then how MFC implements specific behavior for various classes, and finally ways you might want to override MFC's default behavior. Then I'll attempt to synthesize everything at the end with a sample program. In a display of amazing editorial synchronicity, this month's C/C++ Q&A column also answers a number of questions related to command and message handling. 

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:

以前，黑客花费了几个小时的时间写程序，此时c++还局限于科研大厅。每个人都要写一个winmain如下

 

 

 MSG msg;

 while (GetMessage(&msg, NULL, 0, 0)) {

    TranslateMessage(&msg);

    DispatchMessage(&msg);  // send to window proc

 }

 

This message pump is the heart of every Windows-based program. MSG is a struct that holds the HWND, message ID, WPARAM, and LPARAM, plus a couple of other things. You get one, then dispatch it. Pretty straightforward. Except for that TranslateMessage in the middle—what's that? Oh, never mind, it's just a function to translate WM_ KEYDOWN and WM_KEYUP messages into WM_CHAR. Just do it. What's that you say? You want accelerator keys? You want Ctrl-X and Ctrl-V to do Cut and Paste? Well, then, you need TranslateAccelerator.

这个消息泵是每个windows函数的核心。MSG结构包含HWND, message ID, WPARAM, and LPARAM，和一些别的东西。你拿到一个，在分发它，非常直接，除了中间的TranslateMessage，这是什么？别介意，他只是一个函数，用来把WM_ KEYDOWN and WM_KEYUP 消息转换成WM_CHAR。你还要做什么？加速键？想把Ctrl-X and Ctrl-V 转换到 Cut and Paste？好的，那你需要TranslateAccelerator

 

 

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

    }

 }

 

TranslateAccelerator is a voodoo function you must call to do accelerators. TranslateAccelerator sees Ctrl-X go by, looks in your accelerator table, and translates it into a WM_ COMMAND. Unlike TranslateMessage, it dispatches a WM_COMMAND message with ID of ID_EDIT_CUT to your window proc. To your program, it looks just like the user picked Edit Cut from the menu. TranslateMessage returns TRUE indicating the message was translated and dispatched, so you know not to dispatch it again. 

TranslateAccelerator是一个voodoo函数，你必须调用来完成加速键。TranslateAccelerator查看你的加速键表，把他转换成WM_ COMMAND消息。不想TranslateMessage，它分发WM_COMMAND消息+ ID_EDIT_CUT ID到你的程序过程。对你程序来讲，他就像看到用户从菜单式选了Edit Cut菜单。TranslateMessage返回TRUE表示消息已经翻译了以及分发了，所以不需要在分发了

Windows has all sorts of voodoo functions to translate messages: you don't really understand the rhyme or reason, you just do what they tell you. You use IsDialogMessage for modeless dialogs, so Tab keys and Ctrl mnemonics work. You might expect them to work on their own—after all, they do for modal dialogs—but no. There's TranslateMDISysAccel for MDI accelerators, like Ctrl-F6 for Next Window and Shift-F5 for Cascade. Oh, and I almost forgot—if you want to do idle processing, better call PeekMessage, not GetMessage.

Windows有很多这样的woodoo函数用来转换消息，你不需要明白原因，只需要按照他们告诉你的来做。你用IsDialogMessage处理modeless dialog，

以便tab，ctrl能工作。你可能希望他们自己搞定-毕竟，他们为model dialog处理了-但是现实不是。你需要有TranslateMDISysAccel处理MDI加速键，像Ctrl-F6 for Next Window and Shift-F5 for Cascade。哦，我忘了，你如果想做idle处理，你要用PeekMessage而不是GetMessage

 

By the time you're finished with all the voodoo, your message pump is even more complicated than the Windows version of "Hello, world"! 

当你完成所有voodoo后，你的消息泵会比windows版本的helloworld更加复杂
Not to worry. A few years pass, Bjarne Stroustrup is a household name, your mother-in-law is writing Windows-based apps, and even Microsoft has a C++ compiler. Life is so easy all you have to do is press a button to generate apps by the score. Message pumps go the way of the passenger pigeon. 

不要担心，几年过去了，Bjarne Stroustrup， 一个家庭主妇的名字。正在写windows程序，甚至MS有一个c++编译器了。生命如此简单，你所有需要做的就是按一下按钮来生成apps，不想要搞什么消息泵了

 

But underneath all the object glitz, your Wizard-generated app still trudges through the same old muck. You just don't see it, that's all. Buried inside a function called CWinApp::Run is the mother-of-all-message-pumps. MFC hides the voodoo, or at least repackages it in more palatable ways. 

但是在所有东西下面，你的wizard geberator的程序仍旧做同样的old muck。你只是看不到而已，隐藏在了函数CWinApp::Run之下，作为所有消息泵的母亲。MFC隐藏了voodoo，至少重新打包成了可口的方式
To understand how it works, stop a moment to consider a hypothetical old-world situation. You just finished your Acme App, complete with central loop in WinMain. It's all debugged, shining brightly, waiting for shrink wrap. Suddenly orders come from on high: you need an XYZ feature, which calls for a modeless dialog box. You race to the keyboard. Tap-tappity-tap-tap and . . . the dialog is running. Except the Tab key doesn't work. Shoot. After beating your head a while, you realize you forgot your voodoo: you're supposed to call IsDialogMessage from your main message loop in WinMain! 

为了明白他是如何工作的，听一下，想一想古老的世界的情形。你刚写完你的Acme程序，完成了WinMain里面的中心loop。都已经debug完了，闪闪发光，等待着你来压缩。突然高层命令来了。
你需要xyz功能，它需要调用一个modeless dialog。你冲向键盘开始敲起来。。。程序跑起来了，但是tab还不工作。nnd，你意识到你忘记了你的voodoo，你需要支持IsDialogMessage！

If you think there's something wrong with this picture, you win the grand prize. This is not the way life should be, folks! Objects should implement their own behavior! It's bad enough you have to call some weirdo function, but puh-lease, don't make WinMain do it! That's like operating on your shoulder to fix your kidneys. 

如果你觉得这样是有问题的，那你赢了。生命不应该这样。object应该完成他们自己的行为，不应该要做一些很奇怪的函数，不要让winmain做他！那就像搞你的肩膀来治疗你的肾病

MFC corrects this situation by letting windows do their own message translation. In MFC, the dialog, not WinMain, calls IsDialogMessage. How does it work? To understand, let's start with MFC's version of the message pump. It starts in CWinApp::Run.

Mfc纠正了这个问题，他通过让窗口完成他们自己的消息转换。在mfc里，dialog，而不是winmain，调用IsDialogMessage。他是怎么做的呢？为了理解，我们看看mfc的消息泵

 

 

 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();

 }

 

If there are no messages waiting, MFC calls OnIdle, which you can override to do something useful like calculate twin primes in your spare time. Just make sure you call CWinApp::OnIdle at the end or you'll be in deep doodoo. If there are no messages, or no more idle work to do, CWinApp calls PumpMessage, which does the Get/Translate/Dispatch schtick, just like in the old days:

如果没有消息，mfc调用onidle，你可以重载来做有用的事情比如计算twin primes。只需要保证在最后面要调用CWinApp::OnIdle，否则你会在deep doodo里面。如果没有消息或者没有idle work，cwinapp调用pumpMessage，这个函数Get/Translate/Dispatch的事情

 

 

 BOOL CWinApp::PumpMessage()

 {

 •

 •

 •

    if (!::GetMessage(&m_msgCur,...)) {

       return FALSE;

    }

    if (!PreTranslateMessage(&m_msgCur)) {

       ::TranslateMessage(&m_msgCur);

       ::DispatchMessage(&m_msgCur);

    }

    return TRUE;

 }

 

Look familiar? Except for PreTranslateMessage. That's a new virtual function. The default implementation for CWinApp walks the window hierarchy starting with the window that sent the message, up through its parent and grandparents, all the way up to the topmost window, calling CWnd::PreTranslateMessage for each one.

看起来很熟悉？除了PreTranslateMessage。那是一个新的虚函数。默认的实现是遍历window hierarchy，从发送消息的窗口开始，直到他的parent和grandparents，直到最上层窗口。对每个窗口调用CWnd::PreTranslateMessage

 

 

 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

 }

 

That's right, there's PreTranslateMessage for CWinApp and PreTranslateMessage for CWnd. Now windows can translate messages. When one does, it returns TRUE all the way up the stack. Message received. Next, please. The flow is illustrated in Figure 2.
就是这样，CWinApp和cwnd各自有PreTranslateMessage

现在窗口可以转换消息了，当一个做了之后他返回true一路网上

 

Figure 2 The Message Pump

 

It may make your head spin, but this translation tango is actually pretty slick because now that dialog problem is tidily dispatched (ahem). Take a look at how MFC implements PreTranslateMessage for dialogs:

这可能让你头都大了，但是这个转换非常漂亮因为现在dialog问题解决了

看看mfc如何为dialog实现PreTranslateMessage

 

 

 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! 

这样在dialog而不是cwinapp里面转换dialog明显合理多了。你觉得呢？cwinapp根本不知道dialog。当然，IsDialogMessage技术上只适用于modeless dialog，但是对于model dialog，PreTranslateMessage不会调用到，因为当你调用domodel的时候，windows开始了另个message loop，控制权直到dialog关掉之后才会返回。但是真正伟大的事情是你再也不用担心IsDialogMessage了。事实上，你可以忘了他的存在，任何从cdialog集成的dialog，即使你匆忙的在最后一分钟添加。如果你一直用mfc，你可能从未听说过IsDialogMessage

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.

类似的，由于frame窗口拥有菜单，理所当然他要处理加速键。事实上也是这样。当你在Init Instance函数里面创建frame时候，他会架子啊加速键表，改表定义了document template，如IDR_ MAINFRAME or IDR_MYDOCTYPE。CFrameWnd吧这个表奥存在m_hAccel。CFrameWnd::PreTranslateMessag把他传给TranslateAccelerator，很魔术师的。另一个有趣的事情是我发现CFrameWnd首先会试图用CDocument::GetDefaultAccelerator火的加速剪标。换句话说，如果你想要文档相关的加速剪标，你只需要重载这个虚函数！

 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.

 

图3显示各种各样的mfc class如何实现PreTranslateMessage的， mfc处理了99%的情形，所以你完全可以忘了他。这个月的c qa举例子另外的1%
另外一件事情是，32位的mfc，你可以认为cwinapp、和wcinthread一样。比如有CWinThread::Run, CWinThread::OnIdle, CWinThread::PumpMessage, and CWinThread::PreTranslateMessage。

我直接讲出来先，但我不想这么快讲（？？）。在多task的情况下，每个线程有自己的消息泵，一个程序只是一个线程的特化。因此大多数cwinapp的mfc函数迁移到了cwinthread，而cwinapp从他继承

 

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). 
大多数消息从未被翻译。PreTranslateMessage会返回false，从而::DispatchMessage会被调用，这是windows的黑洞。你的消息从中消失，然后魔术般的重新再你的windoiws过程中出现

 

Figure 4 Window Message Routing

 

You know the window proc. It's that big function you wrote in the old days, the one with the giant switch statement that fills pages and pages, defying even the most determined compiler's efforts at optimization. A lot fewer people do that stuff these days. In MFC, window procs are gone. Well, not really gone, but hidden. Replaced by MFC's universal window procedure, AfxWndProc. How can one window proc work for all windows? Easy. It does nothing application-specific.

你知道windows过程，他是在以前你需要写的一个大函数，有着巨大的switch语句。现在很少人这样做了。mfc里面，windows过程消失了。好吧，不是真的消失了。而是被mfc的统一的过程AfxWndProc代替了。一个windows 过程怎样为所有窗口工作呢？很简单，他没有做任何appl specific的事事情

 

 

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

 }

 

CWnd::FromHandlePermanent looks up the HWND in map and retrieves the CWnd associated with it. With CWnd in hand, action flows to AfxCallWndProc, the MFC analog of ::CallWindowProc.

CWnd::FromHandlePermanent查找hwnd map，找到对应的cwnd。利用cwnd，流程跑向AfxCallWndProc

 

 

 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!

AfxCallWndProc调用wndowsproc。mfc调用了cwnd的虚函数WindowProc，而不是传递hwnd到c的windows过程。所以所有的完成的就是从c编导c++。但是，这是多大的进步啊，因为windowproc是虚函数！

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!
CWnd::WindowProc顾名思义，c++的windows 过程。他就是消息处理的地方。因为他是虚函数。不同的window clsss可以用不同的方式实现。

你知道CWnd::WindowProc不是我们一般处理消息的地方，但你应该明白如果需要，你可以在这里处理消息。WindowProc是消息高速路上的第一站。如果你在移植c程序，你可以或多或少的把整个windows proc拷贝到CMainFrame::WindowProc。

 

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.

每个人都知道，正确的处理消息的方法是通过消息map。消息map从哪里来？CWnd::WindowProc。首先，他检查消息是否WM_COMMAND or WM_NOTIFY.如果是。。。否则，所有其他消息继续呗你的windows map分发。CWnd::WindowProc作为中央交换机，把消息分发到不同的处理函数

 

Figure 5 Message Maps

 

Message maps are tables that associate WM_XXX message IDs with C++ virtual functions (see Figure 5). WM_SIZE goes to OnSize. WM_CLOSE goes to OnClose. And so on. The details are hidden behind the familiar macros DECLARE_MESSAGE_MAP, BEGIN_MESSAGE_MAP, END_MESSAGE_MAP, and all those ON_WM_WHOZAMACALLIT macros. If you peek under the covers, you won't find anything magical, just some disgusting code. DECLARE_MESSAGE_MAP declares a few variables, and, most importantly, the function GetMessageMap. Here, let me put on my preprocessor hat and show you. This is what I see:

消息map是一些表格，吧WM_XXX消息和C++ virtual functions联系起来。WM_SIZE goes to OnSize. WM_CLOSE goes to OnClose等等。细节隐藏在DECLARE_MESSAGE_MAP, BEGIN_MESSAGE_MAP, END_MESSAGE_MAP, and all those ON_WM_WHOZAMACALLIT之类的macro中。这些东西都很直接，DECLARE_MESSAGE_MAP声明了一变量，更重要的是函数GetMessageMap

 

 

 class CMyFrame : public CFrameWnd {

    DECLARE_MESSAGE_MAP()

 };

 

 BEGIN_MESSAGE_MAP(CMyFrame, CFrameWnd)

 

 •

 • // entries

 •

 END_MESSAGE_MAP()

 

And this is what I spit out:

 

 

 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 }

 };

 

AFX_MSGMAP contains just two members: a pointer to the base class's message map and one to the actual entries.

AFX_MSGMAP包含两个成语，一个指针指向基类的消息map，一个指向真正的map

 

 

 struct AFX_MSGMAP {

    const AFX_MSGMAP* pBaseMap;

    const AFX_MSGMAP_ENTRY* lpEntries;

 };

 

The base map pointer provides a way to walk the inheritance chain, effectively implementing inheritance for message maps. Derived classes automatically inherit any messages handled by their base. If you link with the DLL version of MFC (_AFXDLL defined), pBaseMap is actually a pointer to a function that returns the base map, not the base map itself, but that's an implementation detail. The entries themselves look like this:

Base map指针提供了一种方式来遍历继承链，从而有效的实现了消息map的继承。派生类自动继承了基类处理的消息。如果你连接dll版本的mfc，pBaseMap其实是一个指针函数，它返回的事base map，而不是base map自身

 

 

 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)

 };

 

Each entry maps a particular Windows message, including control ID and notification code (such as EN_CHANGED or CBN_DROPDOWN) if any, to a CmdTarget-derived member function (AFX_PMSG). The nCode and nID fields are new in 32-bit MFC. They support ON_NOTIFY and ON_COMMAND_RANGE. Each ON_WM_WHATEVER macro initializes an entry for the WM_WHATEVER message. For example, ON_WM_CREATE expands like this:

每一项map到一个特别的windows消息，包括空间id，通知码，一个CmdTarget继承的成员函数，ncode和nid是32位mfc新加的，他们支持ON_NOTIFY and ON_COMMAND_RANGE

比如ON_WM_CREATE展开如下

 

 

 { WM_CREATE, 0, 0, 0, AfxSig_is,

    (AFX_PMSG)(AFX_PMSGW)(int (CWnd::*)(LPCREATESTRUCT))OnCreate },

 

At first glance, it looks like something off the Rosetta Stone. WM_CREATE is obvious: that's the message ID, that's how CWnd::WindowProc knows to use this entry when WM_CREATE happens. The zeroes are there because child notification and command IDs don't apply. The three ugly casts make sure your OnCreate function has the right signature. In other words, they make the macro type-safe. Not all macros have the function name hardwired. ON_MESSAGE(msg, mbrfn) expands like this:

第一眼，看起来像走下神坛。WM_CREATE很直接，消息id，CWnd::WindowProc直到如何使用这个entry。0是因为通知码和消息id没用，三个很丑的cast用来确保oncreate有正确的签名。换句话，他使macro类型安全。不是所有macro都对应硬编码的函数。ON_MESSAGE(msg, mbrfn)展开如下

 

 

 { msg, 0, 0, 0, AfxSig_lwl,

    (AFX_PMSG)(AFX_PMSGW)(LRESULT (CWnd::*)(WPARAM, LPARAM))mbrfn },

 

You can use whatever member function you like for ON_MESSAGE, but it must take WPARAM and LPARAM and return LRESULT. If you try to pass any other kind of function, C++ will have a conniption. 
The only remaining mystery is the funny-looking AfxSig_xxx symbols. To understand what they're for, stop a moment to consider how CWnd knows which arguments should be passed to your handler function. In AFX_MSGMAP_ENTRY, every function is declared as AFX_PMSG, which is a pointer to a CCmdTarget member function that takes no arguments and returns void.

你可以用任意你喜欢的成员函数来给ON_MESSAGE，但是必须要带有WPARAM and LPARAM参数并且返回LRESULT。如果你传了其他类型函数，c++回报做

唯一保留的秘密是有趣的AfxSig_xxx符号。为了明白他们，休息一下考虑cwnd如何知道那个参数应该给你的handle函数。在AFX_MSGMAP_ENTRY，每个函数声明为AFX_PMSG，他使指向CCmdTarget的成员函数，不需要参数

 

 

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

 

So how can the dispatch code pass arguments to your handler functions? That's where the AfxSig (signature) codes come in. Here's how WindowProc actually calls your function once it's found the right message map entry.

分发码如何传递参数到你的handle函数呢？那就是AfxSig？？这里是WindowProc如何调用你的函数的代码

 

 

 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

 •

 }

 

AfxSig_is means the function takes a string (s) and returns an int (i). AfxSig_lwl means it takes a WORD and LONG, and returns a LONG (lwl). And so on. AFXMSG_.H defines a zillion or so different signatures—well, actually there are 55.

AfxSig_is表示函数参数为字串返回int。AfxSig_lwl表示参数为word和long，返回long。AFXMSG_.H定义了55个这样的函数

 

 

 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)

 •

 •

 •

 };

 

You get the idea. That "union MessageMapFunctions mmf" you saw in WindowProc is a bit of grotesquery used to "cast" the function without casting it:

 

 

 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

    •

 };

 

There's only one real function (pfn), but depending how you access it through the union, pfn_is is a string-returning-int function, pfn_lwl is word-and-long-returning-long and so on. What's pretty on the outside is sometimes ghastly on the inside. Fortunately, you don't have to look. I only showed you so you wouldn't think I was hiding anything, and so you can count your blessings you never have to write code like that.
Having said that, now let me tell you how you might use this stuff if you're the masochistic type. Say you have some messages of your own. WM_RUN_FOR_CONGRESS and WM_KICK_THE_BUMS_OUT. The first takes a pointer to a CCongressionalDistrict; the second, a pointer to a CListOfBums. The easiest way to handle these is to use ON_MESSAGE and do old-world casting:

下面是如何处理你自定义的消息

 

 

 BEGN_MESSAGE_MAP(...)

    ON_MESSAGE(WM_RUN_FOR_CONGRESS, OnRunForCongress)

 

 •

 •

 •

 END_MESSAGE_MAP()

 

 LRESULT OnRunForCongress(WPARAM wp, LPARAM, lp)

 {

    CCongressionalDistrict* pCd = (CCongressionalDistrict*)lp;

 •

 •

 •

 }

 

But say you're writing a library. Maybe even an MFC extension library. You don't want to make programmers remember that LPARAM is the district. Or maybe your fastidiousness exceeds that of Felix Unger. You don't want to use ON_MESSAGE and put disgusting casts in your code. You want ON_WM_RUN_FOR_CONGRESS and ON_WM_KICK_THE_BUMS_OUT, so programmers can use macros in their message maps. Ok, just do it. 
"But what AfxSig code should I use?" Why, AfxSig_is, of course. String-returning-int. Because it doesn't matter, a pointer-to-string is the same as a pointer-to-CCongressionalDistrict is the same as a pointer-to-anything when it comes to pushing it on the stack. One address, four bytes. (I'm assuming FAR pointers or Win32®.) Take a closer look at the expansion for ON_WM_CREATE: it uses AfxSig_is too! So here's your macro:

如果你写的是lib，你不想用户记住LPARAM表示区域，你可以这样

下面是你自己定义macro来让用户更加易用

 

 

 #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.
如果你要其他参数，你需要看看有没有合适的AfxSig_xxx码。但我说，大多情况不需要这样极端，ON_MESSAGE已经足够

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.

如果没有合适的entry，会调用CWnd::DefWindowProc

 

 

 CMyWnd::OnFooMumbleBletch()

 {

 •

 •

 •

    CWnd::OnFooMumbleBletch();

 }

 

The base implementations go like this.

 

 

 // (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.
Default()和DefWindowProc一样。唯一的区别是他不需要参数。因为他会从以保存的状态获取，该状态是被AfxCallWndProc保存的

 

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.

WM_COMMAND是一个重载的函数

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

 };

 

NMHDR is intended to be used as the basic header to which specific controls can append additional information. For example, the common Tool Tip control passes a notification struct like this:

 

 

 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;

 };

 

The details of TOOLTIPTEXT and NMHDR are unimportant. The main point is, there are two kinds of events: menu commands and control notifications. WM_NOTIFY is always a notification, but WM_COMMAND is sometimes a command, sometimes a notification. CWnd::WindowProc handles both events specially, sending them to Figure 6 of my elephant map.

 

Figure 6 WM_COMMAND and WM_NOTIFY Message Flow

 

 

 LRESULT CWnd::WindowProc(UINT msg, WPARAM wp, LPARAM lp)

 {

    // special case for commands

    if (msg = = WM_COMMAND)  {

       if (OnCommand(wp, lp))

          return 1L; // command handled

       else

          return DefWindowProc(msg, wp, lp);

    }

 

    // special case for notifies

    if (msg = = WM_NOTIFY) {

       LRESULT lResult = 0;

       NMHDR* pNMHDR = (NMHDR*)lp;

       if (pNMHDR->hwndFrom != NULL &&

                             OnNotify(wp, lp, &lResult))

          return lResult; // command handled

       else

          return DefWindowProc(msg, wp, lp);

    }

 •

 •

 •

 }

 

If WindowProc is the first stop on the message processing highway, OnCommand is the first stop on a major fork for all WM_COMMAND messages. If you can't or don't want to use message maps to handle a particular command, you can override OnCommand. Two common reasons for doing this are when the command or control ID is a run-time variable, not a #define symbol or if you want to trap a range of commands in one fell swoop in 16-bit MFC, which doesn't support ON_COMMAND_RANGE.

 

 

 CMyFrameWnd::OnCommand(WPARAM wp, LPARAM lp)

 {

   if (wp= =m_nPrintCommandID)  // ID stored in data member

       OnPrint();

 

   else if (ID_FOO_FIRST<=wp && wp<=ID_FOO_LAST)

      // Handle range of IDs

       OnFooCommands(wp, lp);

 

    return CFrameWnd::OnCommand(wp, lp);

 }

 

These are convenient applications for OnCommand, but the real reasons for handling commands and notifications specially are more fundamental: to give controls a chance to handle their own notifications and to let nonwindow objects process them.

Child Knows Best 
How many times have I said it? Objects should implement their own behavior! This applies to controls. Controls emit notifications whenever something interesting happens, like when the user changes the contents of an edit control or clicks the drop-down button on a combo box. Notification is nice, but often it makes more sense for controls to handle their own notifications. 
Say you have a combo box in your dance choreography application that displays a list of mambo figures, which you generate on-the-fly when the user presses the drop-down button. The normal way of doing things in Windows is to make the dialog handle the ON_CBN_DROPDOWN notification and fill the combo box. Yuck! What if you want to use your combo box in another dialog? It's not reusable! Unless you adhere to the copy-and-paste school of reusability: copy-and-paste the code from one dialog to another.
Why do that when you can create a nice self-contained combo box that handles its own CBN_DROPDOWN? All you have to do is override OnChildNotify. MFC calls this virtual function whenever the parent receives a notification from a child window.

我说了多少次了，对象应该实现他们自己的行为！着同样适用于控件。控件每当发生了什么感兴趣的事情就会发出通知，比如用户改变edit内容，点击combobox的下拉按钮。通知很好，但要控件处理他们自己的通知更合理

比如你有一个combobox，显示xxx显示内容是动态生成的。一般做法是叫dialog处理ON_CBN_DROPDOWN通知然后填上combobox。那如果你想在另外一个dialog里面如何使用这个combobox？不重用！

为什么不能创建一个字包含的combobox，他处理自己的CBN_DROPDOWN？你需要做的只是重载OnChildNotify，mfc每当父亲收到子窗口的通知后就会调用这个虚函数

 

 BOOL CWnd::OnCommand(WPARAM wParam, LPARAM lParam)

 {

 •

 •

 •

 // if WM_COMMAND is really a child notification:

 if (pChild->OnChildNotify(message, wParam, lParam, pLResult))

       return TRUE;

 •

 •

 •

 }

 

CWnd::OnNotify does the same thing. OnCommand and OnNotify give children first crack at their own notifications. So you can write your combo box like this:

OnCommand and OnNotify给了孩子机会首先检查他们自己的通知，你的combobox可以如下

 

 

 BOOL CMamboCombo::OnChildNotify(UINT msg, WPARAM wp, LPARAM lp,LRESULT* pResult)

 {

    if (msg= =WM_COMMAND) {

       int nCode = // extract notification code, depends

                   // on Win version

       if (nCode= =CBN_DROPDOWN) {

          // fill combo box

          return FALSE;  // Pass to parent dialog

       }

    }

    return CComboBox::OnChildNotify(msg, wp, lp, pResult);

 }

 

Now CMamboCombo is entirely self-contained. Whether you return TRUE or FALSE is up to you. It seems better to return FALSE, so dialogs can still know the drop-down button was pressed if they want to. It's up to you.
Like PreTranslateMessage, OnChildNotify corrects the architecturally challenged design of Windows. MFC uses it for other messages too. MFC directs the owner-draw messages (WM_COMPAREITEM, WM_MEASUREITEM, WM_DRAWITEM, WM_DELETEITEM) back at the controls that sent them, so they can draw themselves instead of having the parent window do it. In fact, that's the only reason the LPRESULT* argument is required for OnChildNotify: WM_COMPAREITEM is one of the few Windows messages that uses the return code to indicate something significant: positive, negative, or zero to indicate the result of the comparison. 

Mother of All Targets 
So much for children. The major, and I mean major, reason for handling commands differently from other messages is so nonwindow objects can get them. You all know documents can handle commands—just put ON_ COMMAND in your document's message map. But it may never have occurred to you that this isn't something built into Windows! It's a feature of the MFC document/view architecture.
In fact, come to think of it, how come documents even have message maps? Because CDocument is derived from CCmdTarget, the root of all classes that can have message maps and thus handle commands. CDocument, CWnd, CWinApp (or CWinThread), and CDocTemplate are all derived from CCmdTarget, whose only role in life is to provide a common base for these "command targets."

处理command和其他消息不同的主要原因是：非窗口对象可以收到他们！比如documents

事实上，为什么document有消息map？这是因为documen从ccmdtarget继承

 

 

 CObject

   CCmdTarget

     CWnd

     CWinThread       // (Win32 only)

       CWinApp

     CDocTemplate

     CDocument

 

And the heart of CCmdTarget is CCmdTarget::OnCmdMsg, the next major major stop on the command route. If the child doesn't handle the notification, or if the message wasn't a notification at all, but a command, OnCommand calls OnCmdMsg. OnNotify behaves similarly.

他的心脏就是CCmdTarget::OnCmdMsg，是command路由中的第二站
CCmdTarget::OnCmdMsg is yet another virtual function. It's the command target analog of WindowProc: the function that does the actual dispatching. But only for commands and notifications. WindowProc is a CWnd function that dispatches window messages; OnCmdMsg is a CCmdTarget function that dispatches commands and notifications. OnCmdMsg only handles message map entries generated by the macros in Figure 7. It looks in the message map for an entry whose ID and nCode (in the case of a notification) match the ones for WM_COMMAND or WM_NOTIFY. If it finds one, it calls that function. I won't bore you with the details, it's exactly the same AfxSig unpleasantness that goes on in WindowProc. 
But wait a minute. That still doesn't explain how documents get commands! WindowProc calls OnCommand calls OnCmdMsg—but the object doing the calling is still whichever CWnd got the command. How do documents get commands? Well, I only told you what CCmdTarget::OnCmdMsg does. Don't forget OnCmdMsg is virtual. Other classes can do other things. In particular, CFrameWnd overrides CCmdMsg to pass commands to views and the application object.

那么document如何受到command呢？是因为CFrameWnd重载了CCmdMsg从而把command传给view和其他object

 

 

 BOOL CFrameWnd::OnCmdMsg(...)

 {

    if (pActiveView->OnCmdMsg(...))

       return TRUE;      // handled by view

 

    if (CWnd::OnCmdMsg(...))

       return TRUE;      // handled by me

 

    if (pApp->OnCmdMsg(...))

       return TRUE;      // handled by app

 

    return FALSE;        // not handled

 }

 

Figure 8 illustrates this. And can you guess what CView:: OnCmdMsg does? That's right, it calls its document's OnCmdMsg function! So commands are not automatically routed to all the CCmdTargets in the world, only the active view, document, frame and application. And only because CFrameWnd makes it so. 

 

Figure 8 Document/View Command Routing

 

So far, all the routing I've been talking about takes place within a single window (or its children, for OnChildNotify). Not until CFrameWnd gets involved does anything get routed outside the window. This explains one of the common mysteries I mentioned at the outset: how come sometimes when you add a child window, the menu items are grayed even though you have ON_COMMAND handlers in your child window's message map? The answer: because the child window isn't automatically hooked up to the interstate system. The only objects that get main frame commands automatically are the active view, document, frame and application. If you want your arbitrary CGizmoWnd nonview child window to handle main frame commands, you've gotta hook it up yourself! Don't worry, it's easy.

 

 

 BOOL CMyView::OnCmdMsg(...)

 {

    if (CMyView::OnCmdMsg(...))

       return TRUE;   // handled by view/doc

 

    return m_wndGizmo.OnCmdMsg(...); // pass to gizmo

 }

 

Or you might want to give the gizmo first crack. Either way, it's up to you to call OnCmdMsg for any CCmdTarget you want to receive commands. Before you start wondering why MFC doesn't do that, consider that calling OnCmdMsg for every CCmdTarget in the universe is not only expensive, it doesn't really make sense. The document/view architecture is one model, the one MFC supports. You're perfectly free to implement other designs, but you have to do a little typing to make things work.
There's one legitimate complaint, however: there's no way for new objects to hook themselves up to the routing mechanism. The app, frame, window, or some other container must explicitly call OnCmdMsg for the new objects. It would be nice to have a way of registering new command targets with the application, say CWinApp::RegisterCmdTarget, so new command targets could hook themselves up to the command highway without requiring their parents or other supra-entities to participate. Then your gizmo control could hook itself up. No need to modify CMainFrame:: OnCmdMsg. Maybe one of our friends in Redmond will read this and add it to the next release of MFC. 

Ooey GUI 
We're almost finished; you should be feeling quite stuffed. In case you hadn't noticed, I've covered the first two elephant chunks: getting/translating messages and processing them. There's just one more piece left to digest, user interface objects. Once again, I'll begin with a history lesson.
Millennia ago, shortly after the wheel was invented, but before the advent of HDTV, hominids had problems initializing menus in their Windows-based apps. They wanted to gray their menu items when commands were unavailable, instead of dropping a stone on the user's head. The big question was whether you should maintain menus in real time, enabling and disabling them as your program's state changes or whether you should gray them on demand, when it's time to display the menu.
Neanderthals chose the continuous-update approach while Cro-Magnons opted for do-it-on-demand. This not only explains why Neanderthals became extinct, it accounts for WM_INITMENUPOPUP. Windows sends this message when the user clicks a menu, just before the menu is drawn. You can enable and disable items, set checks and radio buttons, change text, whatever you like. This represented a great technological advance, on a par with toilet paper. But the code still lived in that big switch statement, along with all the other message-handling code fragments. That meant your program's entire state had to be accessible from the window proc. Fortunately, they'd already invented globals. 
Then C++ and MFC came along and our friends in Redmond screamed, "No, no, no! That's not the way to do it! Each menu item is really a little user interface object! Anybody who wants to should be able to turn it on or off!" Thus was born CCmdUI. These little doohickeys get passed around the cocktail party like hors d'oeuvres. Any command target can take one. Whichever object you decide knows best what the state of a particular menu item should be can enable, disable, check, uncheck, or otherwise update it. If File Save is enabled only when the document has been modified, then the document should do the enabling/disabling of that command. If views are the place to gray Window Split, then by all means do it there. If CBeanCounter knows how many beans to display in the bean pane, it can do the displaying.
MFC implements this goodness by piggybacking on the general command routing system. Once you have that command highway up and running, it's no big deal to send a special message across the interstate. CN_UPDATE_COMMAND_UI is the message. It goes to all the OnCmdMsg functions, just like WM_COMMAND. Only instead of WPARAM and LPARAM, MFC cooks up a thing called a CCmdUI and passes a pointer to it. ON_UPDATE_COMMAND_UI sticks a CN_UPDATE_COMMAND_UI handler in your message map, and voilà, the UI object winds up at your doorstep. There are only two complicating details: first, CCmdUI objects comes in several flavors for updating menu items, controls, toolbar buttons, and status bar panes. Second, CN_UPDATE_ COMMAND_UI messages originate in several places.
I'll start with the first one, since that's the easy part. The base CCmdUI class is used for menu items or controls. It stores a pointer to menu or window, and has virtual functions to change the underlying object's state.

 

 

 class CCmdUI {

    CMenu* m_pMenu;      // if a menu

    CWnd*  m_pOther;     // if a window

 •

 •

 •

 public:

    virtual void Enable(BOOL bOn = TRUE);

    virtual void SetCheck(int nCheck = 1);

    virtual void SetRadio(BOOL bOn = TRUE);

    virtual void SetText(LPCTSTR lpszText);

 

    void DoUpdate(CCmdTarget* pTarget,

                 BOOL bDisableIfNoHndler);

 };

 

SetText ends up calling either ModifyMenu or SetWindowText, depending on whether m_pMenu or m_pOther is set. Likewise, CCmdUI::Enable calls EnableMenuItem or EnableWindow. Derived variants CStatusCmdUI and CToolCmdUI are used for status bar panes and toolbar buttons. CStatusCmdUI::SetText calls SetPaneText; CToolCmdUI::SetText does nothing, since toolbar buttons are bitmap buttons, which have no text. You get the idea. The point is, MFC uses different CCmdUI classes to represent different kinds of user interface objects. Polymorphism working to serve you. 
As for when CN_UPDATE_COMMAND_UI gets sent, well, if you're thinking WM_INITMENUPOPUP, you're on the right track. When CFrameWnd gets WM_INITMENUPOPUP, it creates a CCmdUI object, initializes it successively to each menu item in the menu, and calls DoUpate for each one. The details are a bit tedious, but the basic idea goes like this:

 

 

 void CFrameWnd::OnInitMenuPopup(CMenu* pMenu, UINT, BOOL bSysMenu)

 {

 •

 • // Reader's Digest version

 •

    CCmdUI ui;

    ui.m_nIndexMax = pMenu->GetMenuItemCount();

    for (ui.m_nIndex = 0; ui.m_nIndex < ui.m_nIndexMax; ui.m_nIndex++) {

       ui.m_nID = pMenu->GetMenuItemID(ui.m_nIndex);

       ui.DoUpdate(this, m_bAutoMenuEnable);

    }

 }

 

I'm glossing over some details because I want to focus on CCmdUI::DoUpdate. This is the function that sends the CN_UPDATE_COMMAND_UI message on its merry way.

 

 

 void CCmdUI::DoUpdate(CCmdTarget* pTarget, BOOL bDisableIfNoHndler)

 {

 •

 •

 •

    pTarget->OnCmdMsg(m_nID, CN_UPDATE_COMMAND_UI, this, NULL)

 •

 •

 •

 }

 

The first argument, pTarget, is the command target, the one whose OnCmdMsg is called and whose message map is used to dispatch the message. Usually it's the main frame window, so the message goes to the active view, document, frame window, and application. 
The second argument is a flag that indicates whether the object should be disabled if there's no handler for it. CFrameWnd passes m_bAutoMenuEnable, which is TRUE by default. You may have noticed that MFC automatically grays menu items for commands that have no handlers. If you add File->Barf to your menu but don't add a handler for ID_FILE_BARF, the command is disabled. This is where it happens. 
How does DoUpate know if the command has a handler or not? That's one of the details I omitted. DoUpdate sends a CN_COMMAND code to OnCmdMsg, exactly as if it were going to execute the command, only it passes a little struct, AFX_CMDHANDLERINFO. The presence of this structure tells OnCmdMsg not to actually do the command, just indicate what function it'd use if it did.

 

 

 struct AFX_CMDHANDLERINFO

 {

    CCmdTarget* pTarget;             // command target

    void (CCmdTarget::*pmf)(void);   // message map

                                     // function

 };

 

 BOOL CCmdTarget::OnCmdMsg(UINT nID, int nCode, void* pExtra,

                       AFX_CMDHANDLERINFO* pHandlerInfo)

 {

 •

 •

 •

    if (pHandlerInfo != NULL)

    {

       // just fill in the information, don't do the

       // command (actually happens in

       // CCmdTarget::DispatchCmdMsg)

       pHandlerInfo->pTarget = this;

       pHandlerInfo->pmf = mmf.pfn;

       return TRUE;

    }

 •

 •

 •

 }

 

If OnCmdMsg comes back FALSE, nothing handled the command. So if you ever want to know if a particular command or notification is handled, and by what object, just create an AFX_CMDHANDLERINFO object on the stack and pass it to OnCmdMsg (along with the command ID and notification code, of course). If it comes back TRUE, something handles the command and you can look at AFX_ CMDHANDLERINFO to see what.
The idea behind automatic disabling is that as different kinds of views and/or frames become active (and thus different message maps come into play), the commands that have no handlers are automatically disabled. This is a nice feature, and handles one whole category of menu enabling/disabling without your having to write a line of code. But sometimes you're writing a shell of a program that you want to use to demo the UI before everything is implemented. Then the automatic graying can be a pain. The best way to enable menu items is to write stub handlers for them. You can write a generic OnNotImplemented function and hook it to every command. But if you're lazy, or don't want to rely on programmers remembering to use OnNotImplemented, a quick way to disable the disabling is to set m_bAutoMenuEnable = FALSE in your frame window constructor.
So much for menus. What about status bar panes and toolbar buttons? When your app or thread is just hanging around doing nothing, CWinThread::OnIdle sends WM_IDLEUPDATECMDUI to the main window and all its descendants. This MFC-specific message is every item's cue to update itself. CToolBar and CStatusBar catch it and update their buttons and panes. If you need to know the details, read the source.
There's one more function you need to know about before calling it quits: CWnd::UpdateDialogControls. This function updates all the controls in a window (usually a dialog) by sending CN_UPDATE_ COMMAND_UI to each one.

 

 

 void

 CWnd::UpdateDialogControls(CCmdTarget*

   pTarget, BOOL bDisableIfNoHndler)

 {

 •

 •

 •

    CCmdUI ui;

    for (pCtrl = /* each child

            control in "this" */) {

     ui.m_pOther = pCtrl;

     // it's a window, not a menu

     ui.m_nID=pCtrl-GetDlgCtrlID();

     ui.DoUpdate(pTarget,

                 bDisableIfNoHndler);

    }

 }

 

This function lets you use the ON_ UPDATE_COMMAND_UI mechanism for dialogs. You can code your dialog's message map and handler functions as you would for a frame or view, then call UpdateDialogControls to update the buttons. For pTarget, you should pass the command target whose message map contains the handlers, usually the dialog itself or perhaps your main frame. You must call UpdateDialogControls whenever you want to do the update. For modeless dialogs, you could do it whenever your frame gets WM_IDLEUPDATECMDUI, but this won't work for modal dialogs because your message pump is suspended during a modal dialog. For modal dialogs, it's usually easier to call UpdateDialogControls whenever something happens that you know might affect the state of the controls (sort of an improved version of the old Neanderthal approach). You could also do it when the parent window gets WM_ENTERIDLE, which Windows sends whenever your modal dialog goes idle. 

CMDLEARN 
Whew! That's plenty of theory to grok in one day.Figure 9 shows the Grand Unified Theory of message and command routing, a considerable improvement overFigure 1. Now it's time to write some code!

 

Figure 9 Figure 1 Revised

 

CMDLEARN is an ordinary old doc/view app that displays information about files. Figure 10 shows it in action with three files open. But the real purpose of CMDLEARN isn't to show information about files—CMDLEARN is a multipurpose command routing demo program with three main features. 

 

Figure 10 CMDLEARN

 

First, CMDLEARN traces all calls to WindowProc, OnCommand, and OnCmdMsg for windows and command targets. Its tracing is way better than the unreadable stuff MFC gives you. Second, CMDLEARN pulls a few command routing tricks. It routes WM_TIMER messages to all the open documents in the form of a command, and it routes commands to a new CCmdTarget. Finally, CMDLEARN contains a dialog with a special combo box that reroutes button messages to itself to create a self-contained combo-box-with-add-and-delete-buttons.
When you run CMDLEARN, it dumps a whole bunch of stuff to a file called TRACE.OUT. I used a file instead of debug output because CMDLEARN generates a ton of diagnostics and also to avoid requiring the debugger. Instead of displaying the kind of unformatted gobbledygook only an assembly language hacker could read, which is what you get with MFC's command and message tracing, CMDLEARN generates pretty output like Figure 11. It knows about MFC's private WM_XXX messages and standard ID_MUMBLE commands, as well as CMDLEARN's own commands like ID_TRACE_MSG. You can run CMDLEARN, invoke some commands, and examine the output to see what happened. 
 Figure 11 is a fragment of a trace that shows what happens when I did File Open in CMDLEARN. I've added running play-by-play in the form of C++-style comments. It should make everything I've been talking about a little more clear. Figure 12 is another trace fragment that shows the tool bar buttons and status bar panes getting updated as a result of a WM_IDLEUPDATECMDUI message. These traces were generated with message tracing off, so you don't see zillions of WM_XXXs traveling all over the place.
CMsgTracer writes the file. It also implements its own command and command update handlers for trace messages and trace commands. For this to work, the application class CApp routes commands to the one-and-only-one instance of CMsgTracer.

 

 

 BOOL CApp::OnCmdMsg(UINT nID, int nCode,

                    void* pExtra, AFX_CMDHANDLERINFO* pHandlerInfo)

 {

    if (TWinApp::OnCmdMsg(nID, nCode, pExtra, pHandlerInfo))

       return TRUE;     // handled by doc/view/frame/app

 

 

    // Not handled by doc/view: pass to tracer

    return theTracer.OnCmdMsg(nID, nCode, pExtra, pHandlerInfo);

 }

 

The intercepting of WindowProc, OnCommand, and OnCmdMsg is done using template classes. For details, read the sidebar entitled "Born Again Templates." 
My specification for CMDLEARN called for its views to update themselves continually. Rather than setting a timer for each view (I'd run out of timers pretty quick), CMDLEARN sets one timer in the main window. Then, whenever the clock ticks, CMainFrame sends a command to all its documents.

 

 

 void CMainFrame::OnTimer(UINT nIDEvent)

 {

    if (nIDEvent = = ID_UPDATE_STATUS) {

       CAppDocs alldocs;

       alldocs.SendCommand(ID_UPDATE_STATUS);

    }

 }

 

This effectively lets documents handle WM_ TIMER. CAppDocs is a helper class I wrote that calls OnCmdMsg directly for each open document. You might find it useful in your own apps. The main point is to show how you can use OnCmdMsg as a general mechanism to send messages to any command target. When a doc gets ID_ UPDATE_STATUS, it updates itself. Only if something has changed does CFildDoc bother to update its views. You can witness this feature in action by editing a file while it's open in CMDLEARN: the file size and modification dates are updated to reflect your changes. And if the file is deleted, the window automatically closes with a little popping sound. (Try it!)
Why not just call OnUpdateStatus from the CMainFrame::OnTimer, instead of sending a command? That would work, but it has a major drawback. It requires casting CDocument* to CFileDoc*. In other words, the app must know that the document is really a CFileDoc. This means you can't have other doc templates with other doc classes, or if you do, you must make a provision for them. The simplest way is to do what Windows does: just send a unique integer command code, and any doc that wants to can handle it. Since all I wanted to do is to tell the documents "update yourself," a command is all I needed. Had I wanted to send more information, I'd have defined my own NMHDR class and used CAppDocs::SendNotify.

 

 

 struct MyNMHDR : public NMHDR { // WM_NOTIFY struct

    LPCSTR   whereBill; // Bill's last known whereabouts

    double   worthBill; // Bill's last known net worth

 };

 

 void CMainFrame::OnTimer(UINT nIDEvent)

 {

    if (nIDEvent = = ID_UPDATE_STATUS) {

       CAppDocs alldocs;

       MyNMHDR nmhdr;

       nmhdr.whereBill = "BurgerMaster";

       nmhdr.worthBill = 8.3994e43;

       alldocs.SendNotify(0, ID_UPDATE_STATUS, &nmhdr); // send info to all docs

    }

 }

 

Finally, CMDLEARN contains a dialog that actually does a bit of command rerouting. This dialog was inspired by a reader, Jean-Louis Leroy, who wrote asking if there were some way to make his list box handle button clicks, instead of the dialog. He had a list box with First and Last buttons that selected the first and last items and wanted to build a reusable list box-with-buttons object. 
 Figure 13 shows my version of this. The dialog contains a combo box with Add and Delete buttons. If you type some text in the edit box, the Add button is enabled, and pressing it adds the text to the list. If an item is selected, you can press Delete to delete it. If not, Delete is disabled. The normal Windows way to implement this sort of thing is to put all the code in the dialog. But as Jean-Louis observed, this is not reusable. If you want to use the same combo box in another dialog, you have to copy and paste a lot of code. That's gauche. 

 

Figure 13 ComboCombo

 

 Figure 14 shows how I implemented CComboCombo, a self-contained combo box with Add and Delete buttons. Figure 15 shows the message flow.

 

Figure 15 Combo Box Message Flow

 

In CComboCombo, a new class, COwnedButton, represents the buttons. COwnedButton overrides OnChildNotify to handle its own notifications (such as BN_CLICKED): it sends them its owner window instead of its parent. A flag prevents infinite recursion when the owner calls OnChildNotify again. I could've created a new data member to store the owner, but it was expedient and harmless to use MFC's m_hWndOwner. I didn't want to use SetParent, because child windows are clipped by their parents and the buttons would disappear.
CComboCombo contains two COwnedButtons, for Add and Delete. CComboCombo::SubclassControls hooks everything up: it subclasses the combo box as well as the buttons, and it assigns itself ownership of the buttons so the buttons send their notifications to it. A dialog using CComboCombo must call SubclassControls with the IDs of the combo box and both buttons. 
Once CComboCombo hooks everything up, it calls UpdateButtons to update (enable/disable) the dialog buttons. UpdateButtons is a helper function that calls UpdateDialogControls for the parent dialog, using itself as the command target—that is, its own message map—instead of the frame window or dialog. CComboCombo calls UpdateButtons any time the buttons need updating, such as after adding or deleting an item.
CComboCombo overrides its own OnChildNotify to handle a couple of notifications: when the edit control changes (CBN_EDITCHANGE) or the selection changes (CBN_SELCHANGE), the buttons need to be updated, so CComboCombo calls UpdateButtons.
CComboCombo implements ON_ COMMAND_RANGE and ON_ UPDATE_COMMAND_UI_RANGE handlers for Add and Delete. Since the IDs of these commands are not known until run time, the range is 0 to 0xFFFF: in other words, all commands. The handlers look for IDs equal to the IDs specified by SubclassControls.
The result of all this is an entirely self-contained class. To use CComboCombo, all you have to do is include COMCOMBO.H, add a CComboCombo to your dialog, and call CComboCombo::SubclassControls in OnInitDialog. See DLGCOMBO.H and DLGCOMBO.CPP in the source code on any MSJ bulletin board. You can adopt the CComboCombo approach any time you have a group of controls that you want to act as a unit.
Well, that's it. Time to go. I hope you learned something besides what it's like to eat elephant. If all this was too overwhelming, you might try reading MFC Technical Note 6, "Message Maps," and 21, "Command and Message Routing," as well as Bob Chiverton's C/C++ Q&A column in the November 1992 MSJ. If you understood everything, just go ahead and pronounce yourself a Command Routing Guru. That and a buck twenty-five'll get you a ride on the subway.

 

From the July 1995 issue of Microsoft Systems Journal. Get it at your local newsstand, or better yet, subscribe.