DocumentView Fundamentals

[Previous] [Next]

Let's begin our exploration of the document/view architecture with a conceptual look at the various objects involved and the relationships they share with one another. Figure 9-1 shows a schematic representation of an SDI document/view application. The frame window is the application's top-level window. It's normally a WS_OVERLAPPEDWINDOW-style window with a resizing border, a title bar, a system menu, and minimize, maximize, and close buttons. The view is a child window sized to fit the frame window so that it becomes, for all practical purposes, the frame window's client area. The application's data is stored in the document object, a visible representation of which appears in the view. For an SDI application, the frame window class is derived from CFrameWnd, the document class is derived from CDocument, and the view class is derived from CView or a related class such as CScrollView.

click to view at full size.

Figure 9-1. The SDI document/view architecture.

The arrows represent data flow. The application object provides the message loop that pumps messages to the frame window and the view. The view object translates mouse and keyboard input into commands that operate on the data stored in the document object, and the document object provides the data that the view needs to render its output. The individual objects interact in other ways, too, but you'll find the big picture easier to grasp after you've learned more about the role each object plays in a program's operation and have written a document/view application or two of your own.

The architecture depicted in Figure 9-1 has very real implications for the design and operation of an application program. In an MFC 1.0_style application, a program's data is often stored in member variables declared in the frame window class. The frame window draws "views" of that data by accessing its own member variables and using GDI functions encapsulated in the CDC class to draw into its client area. The document/view architecture enforces a modular program design by encapsulating data in a stand-alone document object and providing a view object for the program's screen output. A document/view application never grabs a client-area device context for its frame window and draws into it; instead, it draws into the view. It looks as if the drawing is being done in the frame window, but in reality all output goes to the view. You can draw into the frame window if you want to, but you won't see the output because the client area of an SDI frame window is completely obscured by the view.

The InitInstance Function Revisited

One of the most interesting aspects of an SDI document/view application is the way in which the frame window, document, and view objects are created. If you look at the InitInstance function for an SDI application generated by AppWizard, you'll see something like this:

 CSingleDocTemplate* pDocTemplate; pDocTemplate = new CSingleDocTemplate (     IDR_MAINFRAME,     RUNTIME_CLASS (CMyDoc),     RUNTIME_CLASS (CMainFrame),     RUNTIME_CLASS (CMyView) ); AddDocTemplate (pDocTemplate);      CCommandLineInfo cmdInfo; ParseCommandLine (cmdInfo); if (!ProcessShellCommand (cmdInfo))     return FALSE; m_pMainWnd->ShowWindow (SW_SHOW); m_pMainWnd->UpdateWindow ();

This code is quite different from the startup code in the sample programs in Part I of this book. Let's look more closely at this InitInstance function to see what it takes to get a document/view application up and running. To begin with, the statements

 CSingleDocTemplate* pDocTemplate; pDocTemplate = new CSingleDocTemplate (     IDR_MAINFRAME,     RUNTIME_CLASS (CMyDoc),     RUNTIME_CLASS (CMainFrame),     RUNTIME_CLASS (CMyView) );

create an SDI document template from MFC's CSingleDocTemplate class. The SDI document template is a crucial element of an SDI document/view application. It identifies the document class used to manage the application's data, the frame window class that encloses views of that data, and the view class used to draw visual representations of the data. The document template also stores a resource ID that the framework uses to load menus, accelerators, and other resources that shape the application's user interface. AppWizard uses the resource ID IDR_MAINFRAME in the code that it generates. The RUNTIME_CLASS macro surrounding the class names returns a pointer to a CRuntimeClass structure for the specified class, which enables the framework to create objects of that class at run time. This dynamic creation mechanism is another important element of the document/view architecture. I'll describe how it works a little later in this chapter.

After the document template is created, the statement

 AddDocTemplate (pDocTemplate);

adds it to the list of document templates maintained by the application object. Each template registered in this way defines one document type the application supports. SDI applications register just one document type, but MDI applications can—and sometimes do—register several types.

The statements

 CCommandLineInfo cmdInfo; ParseCommandLine (cmdInfo);

use CWinApp::ParseCommandLine to initialize a CCommandLineInfo object with values reflecting the parameters entered on the command line, which often include a document file name. The statements

 if (!ProcessShellCommand (cmdInfo))     return FALSE;

"process" the command line parameters. Among other things, ProcessShellCommand calls CWinApp::OnFileNew to start the application with an empty document if no file name was entered on the command line, or CWinApp::OpenDocumentFile to load a document if a document name was specified. It's during this phase of the program's execution that the framework creates the document, frame window, and view objects using the information stored in the document template. (In case you're wondering, the document object is created first, followed by the frame window and then the view.) ProcessShellCommand returns TRUE if the initialization succeeds and FALSE if it doesn't. If initialization is successful, the statements

 m_pMainWnd->ShowWindow (SW_SHOW); m_pMainWnd->UpdateWindow ();

display the application's frame window (and by extension, the view) on the screen.

After the application is started and the document, frame window, and view objects are created, the message loop kicks in and the application begins to retrieve and process messages. Unlike MFC 1.0_type applications, which typically map all messages to member functions of the frame window class, document/view applications divide message processing among the application, document, view, and frame window objects. The framework does a lot of work in the background to make this division of labor possible. In Windows, only windows can receive messages, so MFC implements a sophisticated command-routing mechanism that sends certain types of messages from one object to another in a predefined order until one of the objects processes the message or the message is passed to ::DefWindowProc for default processing. When we discuss command routing later in this chapter, it will become abundantly clear why command routing is a powerful feature of MFC whose absence would severely inhibit the usefulness of the document/view architecture.

The Document Object

In a document/view application, data is stored in a document object. The document object is created when the framework instantiates a class derived from CDocument. The term document is somewhat misleading because it stirs up visions of word processors and spreadsheet programs and other types of applications that deal with what we traditionally think of as documents. In reality, the "document" part of document/view is much more general than that. A document can be almost anything, from a deck of cards in a poker simulation to an online connection to a remote data source; it is an abstract representation of a program's data that draws a clear boundary between how the data is stored and how it is presented to the user. Typically, the document object provides public member functions that other objects, primarily views, can use to access the document's data. All handling of the data is performed by the document object itself.

A document's data is often stored in member variables of the derived document class. The Scribble tutorial supplied with Microsoft Visual C++ exposes its data directly to other objects by declaring its data members public, but stricter encapsulation is achieved by making document data private and providing public member functions for accessing it. The document object in a text editing program, for example, might store characters in a CByteArray object and provide AddChar and RemoveChar functions so that the view can convert the mouse and keyboard messages it receives into commands to add and remove characters. Other functions, such as AddLine and DeleteLine, could further enrich the interface between the document object and the views connected to it.

CDocument Operations

In MFC literature, "operation" is the term used to describe nonvirtual class member functions. A derived document class inherits several important operations from CDocument, some of which are listed in the following table.

Key CDocument Operations

Function	Description
GetFirstViewPosition	Returns a POSITION value that can be passed to GetNextView to begin enumerating the views associated with this document
GetNextView	Returns a CView pointer to the next view in the list of views associated with this document
GetPathName	Retrieves the document's file name and path—for example, "C:\Documents\Personal\MyFile.doc"; returns an empty string if the document hasn't been named
GetTitle	Retrieves the document's title—for example, "MyFile"; returns an empty string if the document hasn't been named
IsModified	Returns a nonzero value if the document contains unsaved data or 0 if it doesn't
SetModifiedFlagS	Sets or clears the document's modified flag, which indicates whether the document contains unsaved data
UpdateAllViews	Updates all views associated with the document by calling each view's OnUpdate function

Of these functions, SetModifiedFlag and UpdateAllViews are the two that you'll use the most. You should call SetModifiedFlag whenever the document's data is modified. This function sets a flag inside the document object that tells MFC the document contains unsaved data, which allows MFC to prompt the user before closing a document that contains unsaved changes. You can determine for yourself whether a document is "dirty" with IsModified. UpdateAllViews commands all the views attached to a document to update themselves. Under the hood, UpdateAllViews calls each view's OnUpdate function, whose default action is to invalidate the view to force a repaint. In an application that supports multiple views of its documents, calling UpdateAllViews whenever the document's data changes keeps all the different views in sync. Even a single-view application can call UpdateAllViews to refresh the view based on the data currently contained in the document.

A document object can enumerate its views and communicate with each view individually by using GetFirstViewPosition and GetNextView to walk the list of views. The excerpt below from the MFC source code file Doccore.ccp demonstrates how UpdateAllViews uses GetFirstViewPosition and GetNextView to call each view's OnUpdate function.

 POSITION pos = GetFirstViewPosition(); while (pos != NULL) {     CView* pView = GetNextView(pos);              pView->OnUpdate(pSender, lHint, pHint); }

Given that OnUpdate is a protected member function of CView, you might wonder how this code can even compile. The answer is that CDocument is declared a friend of CView in Afxwin.h. You can freely call GetFirstViewPosition and GetNextView from your own code, but you can call OnUpdate from your document class only if you, too, declare the document to be a friend of the view.

CDocument Overridables

CDocument also includes several virtual functions, or "overridables," that can be overridden to customize a document's behavior. Some of these functions are almost always overridden in a derived document class. The four most commonly used overridables are shown in the following table.

Key CDocument Overridables

Function	Description
OnNewDocument	Called by the framework when a new document is created. Override to apply specific initializations to the document object each time a new document is created.
OnOpenDocument	Called by the framework when a document is loaded from disk. Override to apply specific initializations to the document object each time a document is loaded.
DeleteContents	Called by the framework to delete the document's contents. Override to free memory and other resources allocated to the document before it is closed.
Serialize	Called by the framework to serialize the document to or from disk. Override to provide document-specific serialization code so that documents can be loaded and saved.

In an SDI application, MFC instantiates the document object once—when the application starts up—and reuses that object over and over as document files are opened and closed. Because the document object is created just one time, initializations performed by the document's class constructor are executed only once, too. But what if your derived document class contains member variables that you want to reinitialize whenever a new document is created or an existing document is loaded from disk?

That's where OnNewDocument and OnOpenDocument come in. MFC calls the document's OnNewDocument function whenever a new document is created. Typically, that occurs when the user chooses New from the File menu. MFC calls OnOpenDocument when a document is loaded from disk—that is, whenever the user selects Open from the File menu. You can perform one-time initializations in an SDI document class's constructor. But if you want to perform certain initializations anytime a document is created or opened, you must override OnNewDocument or OnOpenDocument.

MFC provides default implementations of OnNewDocument and OnOpenDocument that shoulder the burden of creating new documents and opening existing documents. If you override OnNewDocument and OnOpenDocument, you should call the equivalent functions in the base class, as shown here:

 BOOL CMyDoc::OnNewDocument () {     if (!CDocument::OnNewDocument ())         return FALSE;     // Insert application-specific initialization code here.     return TRUE; } BOOL CMyDoc::OnOpenDocument (LPCTSTR lpszPathName) {     if (!CDocument::OnOpenDocument (lpszPathName))         return FALSE;     // Insert application-specific initialization code here.     return TRUE; }

Generally speaking, MFC applications more commonly override OnNewDocument than OnOpenDocument. Why? Because OnOpenDocument indirectly calls the document's Serialize function, which initializes a document's persistent data members with values retrieved from a document file. Only nonpersistent data members—those that aren't initialized by Serialize—need to be initialized in OnOpenDocument. OnNewDocument, by contrast, performs no default initialization of the document's data members. If you add data members to a document class and want those data members reinitialized whenever a new document is created, you need to override OnNewDocument.

Before a new document is created or opened, the framework calls the document object's virtual DeleteContents function to delete the document's existing data. Therefore, an SDI application can override CDocument::DeleteContents and take the opportunity to free any resources allocated to the document and perform other necessary cleanup chores in preparation for reusing the document object. MDI applications generally follow this model also, although MDI document objects differ from SDI document objects in that they are individually created and destroyed as the user opens and closes documents.

When a document is opened or saved, the framework calls the document object's Serialize function to serialize the document's data. You implement the Serialize function so that it streams the document's data in and out; the framework does everything else, including opening the file for reading or writing and providing a CArchive object to insulate you from the vagaries of physical disk I/O. A derived document class's Serialize function is typically structured like this:

 void CMyDoc::Serialize (CArchive& ar) {     if (ar.IsStoring ()) {         // Write the document's persistent data to the archive.     }     else { // Loading, not storing         // Read the document's persistent data from the archive.     } }

In place of the comments, you include code that streams the document's persistent data to or from an archive using the serialization mechanism described in Chapter 6. For a simple document class whose data consists of two strings stored in CString member variables named m_strName and m_strPhone, you could write Serialize like this:

 void CMyDoc::Serialize (CArchive& ar) {     if (ar.IsStoring ()) {         ar << m_strName << m_strPhone;     }     else { // Loading, not storing.         ar >> m_strName >> m_strPhone;     } }

If your document's data is composed of primitive data types and serializable classes like CString, writing a Serialize function is exceedingly easy because all input and output can be performed with the << and >> operators. For structures and other nonserializable data types, you can use the CArchive functions Read and Write. CArchive even includes ReadString and WriteString functions for serializing raw strings. If all else fails, you can call CArchive::GetFile to get a CFile pointer for interacting directly with the file attached to the archive. You'll see this technique used in Chapter 13's HexDump program.

Other CDocument overridables that aren't used as often but that can be useful include OnCloseDocument, which is called when a document is closed; OnSaveDocument, which is called when a document is saved; SaveModified, which is called before a document containing unsaved data is closed to ask the user whether changes should be saved; and ReportSaveLoadException, which is called when an error occurs during serialization. There are others, but for the most part they constitute advanced overridables that you'll rarely find occasion to use.

The View Object

Whereas the sole purpose of a document object is to manage an application's data, view objects exist for two purposes: to render visual representations of a document on the screen and to translate the user's input—particularly mouse and keyboard messages—into commands that operate on the document's data. Thus, documents and views are tightly interrelated, and information flows between them in both directions.

MFC's CView class defines the basic properties of a view. MFC also includes a family of view classes derived from CView that add functionality to views. CScrollView, for example, adds scrolling capabilities to CView. CScrollView and other CView derivatives are discussed in Chapter 10.

The GetDocument Function

A document object can have any number of views associated with it, but a view always belongs to just one document. The framework stores a pointer to the associated document object in a view's m_pDocument data member and exposes that pointer through the view's GetDocument member function. Just as a document object can identify its views using GetFirstViewPosition and GetNextView, a view can identify its document by calling GetDocument.

When AppWizard generates the source code for a view class, it overrides the base class's GetDocument function with one that casts m_pDocument to the appropriate document type and returns the result. This override allows type-safe access to the document object and eliminates the need for an explicit cast each time GetDocument is called.

CView Overridables

Like the CDocument class, CView includes several virtual member functions that you can override in a derived class to customize a view's behavior. The key overridables are shown in the following table. The most important is a pure virtual function named OnDraw, which is called each time the view receives a WM_PAINT message. In non-document/view applications, WM_PAINT messages are processed by OnPaint handlers that use CPaintDC objects to do their drawing. In document/view applications, the framework fields the WM_PAINT message, creates a CPaintDC object, and calls the view's OnDraw function with a pointer to the CPaintDC object. The following implementation of OnDraw retrieves a CString from the document object and displays it in the center of the view:

 void CMyView::OnDraw (CDC* pDC) {     CMyDoc* pDoc = GetDocument ();     CString string = pDoc->GetString ();     CRect rect;     GetClientRect (&rect);     pDC->DrawText (string, rect,         DT_SINGLELINE ¦ DT_CENTER ¦ DT_VCENTER); }

Notice that OnDraw uses the supplied device context pointer rather than instantiate a device context of its own.

Key CView Overridables

Function	Description
OnDraw	Called to draw the document's data. Override to paint views of a document.
OnInitialUpdate	Called when a view is first attached to a document. Override to initialize the view object each time a document is created or loaded.
OnUpdate	Called when the document's data has changed and the view needs to be updated. Override to implement "smart" update behavior that redraws only the part of the view that needs redrawing rather than the entire view.

The fact that the view doesn't have to construct its own device context object is a minor convenience. The real reason the framework uses OnDraw is so that the same code can be used for output to a window, for printing, and for print previewing. When a WM_PAINT message arrives, the framework passes the view a pointer to a screen device context so that output will go to the window. When a document is printed, the framework calls the same OnDraw function and passes it a pointer to a printer device context. Because the GDI is a device-independent graphics system, the same code can produce identical (or nearly identical) output on two different devices if it uses two different device contexts. MFC takes advantage of this fact to make printing—usually a chore in Windows—a less laborious undertaking. In fact, printing from a document/view application is typically much easier than printing from a conventional application. You'll learn all about MFC's print architecture in Chapter 13.

Two other CView functions you'll frequently override in derived view classes are OnInitialUpdate and OnUpdate. Views, like documents, are constructed once and then reused over and over in SDI applications. An SDI view's OnInitialUpdate function gets called whenever a document is opened or created. The default implementation of OnInitialUpdate calls OnUpdate, and the default implementation of OnUpdate in turn invalidates the view's client area to force a repaint. Use OnInitialUpdate to initialize data members of the view class, and perform other view-related initializations on a per-document basis. In a CScrollView-derived class, for example, it's common for OnInitialUpdate to call the view's SetScrollSizes function to initialize scrolling parameters. It's important to call the base class version of OnInitialUpdate from an overridden version, or the view won't be updated when a new document is opened or created.

OnUpdate is called when a document's data is modified and someone—usually either the document object or one of the views—calls UpdateAllViews. You never have to override OnUpdate because the default implementation calls Invalidate. But in practice, you'll often override OnUpdate to optimize performance by repainting just the part of the view that needs updating rather than repainting the entire view. These so-called intelligent updates are especially helpful in multiple-view applications because they eliminate unsightly flashing in secondary views. You'll see what I mean in the Chapter 11 sample program named Sketch.

At any given time in a multiple-view application, one view is the active view and other views are said to be inactive. Generally, the active view is the one with the input focus. A view can determine when it is activated and deactivated by overriding CView::OnActivateView. The first parameter to OnActivateView is nonzero if the view is being activated and 0 if it is being deactivated. The second and third parameters are CView pointers identifying the views that are being activated and deactivated, respectively. If the pointers are equal, the application's frame window was activated without causing a change in the active view. View objects sometimes use this feature of the OnActivateView function to realize a palette. A frame window can get and set the active view with the functions CFrameWnd::GetActiveView and CFrameWnd::SetActiveView.

The Frame Window Object

So far, we've looked at the roles that application objects, document objects, and view objects play in document/view applications. But we've yet to consider the frame window object, which defines the application's physical workspace on the screen and serves as a container for a view. An SDI application uses just one frame window—a CFrameWnd that serves as the application's top-level window and frames the view. As you'll discover in the next chapter, an MDI application uses two different types of frame windows—a CMDIFrameWnd that acts as a top-level window and CMDIChildWnd windows that float within the top-level frame window and frame views of the application's documents.

Frame windows play an important and often misunderstood role in the operation of document/view applications. Beginning MFC programmers often think of a frame window as simply a window. In fact, a frame window is an intelligent object that orchestrates much of what goes on behind the scenes in a document/view application. For example, MFC's CFrameWnd class provides OnClose and OnQueryEndSession handlers that make sure the user gets a chance to save a dirty document before the application terminates or Windows shuts down. CFrameWnd also handles the all-important task of resizing a view when the frame window is resized, and it knows how to work with toolbars, status bars, and other user interface objects. It also includes member functions for manipulating toolbars and status bars, identifying active documents and views, and more.

Perhaps the best way to understand the contribution the CFrameWnd class makes is to compare it to the more generic CWnd class. The CWnd class is basically a C++ wrapper around an ordinary window. CFrameWnd is derived from CWnd and adds all the bells and whistles a frame window needs to assume a proactive role in the execution of a document/view application.

Dynamic Object Creation

If the framework is to create document, view, and frame window objects during the course of a program's execution, the classes from which those objects are constructed must support a feature known as dynamic creation. MFC's DECLARE_DYNCREATE and IMPLEMENT_DYNCREATE macros make it easy to write dynamically creatable classes. Here's all you have to do:

Derive the class from CObject.
Call DECLARE_DYNCREATE in the class declaration. DECLARE_DYNCREATE accepts just one parameter—the name of the dynamically creatable class.
Call IMPLEMENT_DYNCREATE from outside the class declaration. IMPLEMENT_DYNCREATE accepts two parameters—the name of the dynamically creatable class and the name of its base class.

You can create an instance of a class that uses these macros at run time with a statement like this one:

 RUNTIME_CLASS (CMyClass)->CreateObject ();

Using this statement is basically no different than using the new operator to create a CMyClass object, but it circumvents a shortcoming of the C++ language that prevents statements like these from working:

 CString strClassName = _T ("CMyClass"); CMyClass* ptr = new strClassName;

The compiler, of course, will try to construct an object from a class named "strClassName" because it doesn't realize that strClassName is a variable name and not a literal class name. What MFC's dynamic object creation mechanism amounts to is a means for applications to register classes in such a way that the framework can create objects of those classes.

What happens under the hood when you write a class that's dynamically creatable? The DECLARE_DYNCREATE macro adds three members to the class declaration: a static CRuntimeClass data member, a virtual function named GetRuntimeClass, and a static function named CreateObject. When you write

 DECLARE_DYNCREATE (CMyClass)

the C++ preprocessor outputs this:

 public:     static const AFX_DATA CRuntimeClass classCMyClass;     virtual CRuntimeClass* GetRuntimeClass() const;     static CObject* PASCAL CreateObject();

IMPLEMENT_DYNCREATE initializes the CRuntimeClass structure with information such as the class name and the size of each class instance. It also provides the GetRuntimeClass and CreateObject functions. If IMPLEMENT_DYNCREATE is called like this:

 IMPLEMENT_DYNCREATE (CMyClass, CBaseClass)

CreateObject is implemented like this:

 CObject* PASCAL CMyClass::CreateObject()     { return new CMyClass; }

Early versions of MFC used a different implementation of CreateObject that allocated memory using the size information stored in the class's CRuntimeClass structure and manually initialized an object in that memory space. Today's implementation of CreateObject is truer to the C++ language because if a dynamically creatable class overloads the new operator, CreateObject will use the overloaded operator.

Registering Document Types with the Operating System Shell

In Windows, you can double-click a document icon or right-click it and select Open from the context menu to open the document along with the application that created it. In addition, you can print a document by selecting Print from its context menu or dragging the document icon and dropping it over a printer icon.

For these operations to work, an application must register its document types with the operating system shell, which involves writing a series of entries to the HKEY_CLASSES_ROOT branch of the registry that identify each document type's file name extension and the commands used to open and print files of that type. Some applications perform this registration by supplying a REG file the user can merge into the registry or by writing the necessary entries into the registry programmatically with ::RegCreateKey, ::RegSetValue, and other Win32 registry functions. An MFC application, however, can make one simple function call and register every document type it supports. Calling CWinApp::RegisterShellFileTypes and passing in a TRUE parameter after calling AddDocTemplate forges critical links between the application, the documents it creates, and the operating system shell. When it creates a document/view application, AppWizard automatically includes a call to RegisterShellFileTypes in the application class's InitInstance function.

A related CWinApp function named EnableShellOpen adds a nifty feature to MDI document/view applications. If an MDI application registers its document type(s) with RegisterShellFileTypes and EnableShellOpen and the user double-clicks a document icon while the application is running, the shell doesn't automatically start a second instance of the application; first, it uses Dynamic Data Exchange (DDE) to send an "open" command to the existing instance and passes along the document's file name. A DDE handler built into MFC's CDocManager class responds by calling OnOpenDocument to open the document. Thus, the document appears in a new window inside the top-level MDI frame, just as if it had been opened with the application's File-Open command. Similar DDE commands allow running application instances to fulfill print requests placed through the operating system shell.

Command Routing

One of the most remarkable features of the document/view architecture is that an application can handle command messages almost anywhere. Command messages is MFC's term for the WM_COMMAND messages that are generated when items are selected from menus, keyboard accelerators are pressed, and toolbar buttons are clicked. The frame window is the physical recipient of most command messages, but command messages can be handled in the view class, the document class, or even the application class by simply including entries for the messages you want to handle in the class's message map. Command routing lets you put command handlers where it makes the most sense to put them rather than relegate them all to the frame window class. Update commands for menu items, toolbar buttons, and other user interface objects are also subject to command routing, so you can put ON_UPDATE_COMMAND_UI handlers in nonframe window classes as well.

The mechanism that makes command routing work lies deep within the bowels of MFC. When a frame window receives a WM_COMMAND message, it calls the virtual OnCmdMsg function featured in all CCmdTarget-derived classes to begin the routing process. The CFrameWnd implementation of OnCmdMsg looks like this:

 BOOL CFrameWnd::OnCmdMsg(...) {     // Pump through current view FIRST.     CView* pView = GetActiveView();     if (pView != NULL && pView->OnCmdMsg(...))         return TRUE;     // Then pump through frame.     if (CWnd::OnCmdMsg(...))         return TRUE;     // Last but not least, pump through application.     CWinApp* pApp = AfxGetApp();     if (pApp != NULL && pApp->OnCmdMsg(...))         return TRUE;     return FALSE; }

CFrameWnd::OnCmdMsg first routes the message to the active view by calling the view's OnCmdMsg function. If pView->OnCmdMsg returns 0, indicating that the view didn't process the message (that is, that the view's message map doesn't contain an entry for this particular message), the frame window tries to handle the message itself by calling CWnd::OnCmdMsg. If that, too, fails, the frame window then tries the application object. Ultimately, if none of the objects processes the message, CFrameWnd::OnCmdMsg returns FALSE and the framework passes the message to ::DefWindowProc for default processing.

This explains how a command message received by a frame window gets routed to the active view and the application object, but what about the document object? When CFrameWnd::OnCmdMsg calls the active view's OnCmdMsg function, the view first tries to handle the message itself. If it doesn't have a handler for the message, the view calls the document's OnCmdMsg function. If the document can't handle the message, it passes it up the ladder to the document template. Figure 9-2 shows the path that a command message travels when it's delivered to an SDI frame window. The active view gets first crack at the message, followed by the document associated with that view, the document template, the frame window, and finally the application object. The routing stops if any object along the way processes the message, but it continues all the way up to ::DefWindowProc if none of the objects' message maps contains an entry for the message. Routing is much the same for command messages delivered to MDI frame windows, with the framework making sure that all the relevant objects, including the child window frame that surrounds the active MDI view, get the opportunity to weigh in.

The value of command routing becomes apparent when you look at how a typical document/view application handles commands from menus, accelerators, and toolbar buttons. By convention, the File-New, File-Open, and File-Exit commands are mapped to the application object, where CWinApp provides OnFileNew, OnFileOpen, and OnAppExit command handlers for them. File-Save and File-Save As are normally handled by the document object, which provides default command handlers named CDocument::OnFileSave and CDocument::OnFileSaveAs. Commands to show and hide toolbars and status bars are handled by the frame window using CFrameWnd member functions, and most other commands are handled by either the document or the view.

An important point to keep in mind as you consider where to put your message handlers is that only command messages and user interface updates are subject to routing. Standard Windows messages such as WM_CHAR, WM_LBUTTONDOWN, WM_CREATE, and WM_SIZE must be handled by the window that receives the message. Mouse and keyboard messages generally go to the view, and most other messages go to the frame window. Document objects and application objects never receive noncommand messages.

click to view at full size.

Figure 9-2. Routing of command messages sent to an SDI frame window.

Predefined Command IDs and Command Handlers

When you write a document/view application, you typically don't write the handlers for all the menu commands yourself. CWinApp, CDocument, CFrameWnd, and other MFC classes provide default handlers for common menu commands such as File-Open and File-Save. In addition, the framework provides an assortment of standard menu item command IDs, such as ID_FILE_OPEN and ID_FILE_SAVE, many of which are "prewired" into the message maps of classes that use them.

The table below lists the most commonly used predefined command IDs and their associated command handlers. The "Prewired?" column indicates whether the handler is called automatically (Yes) or called only if a corresponding entry is added to the class's message map (No). You enable a prewired handler by assigning the corresponding ID to a menu item; a handler that isn't prewired is enabled only if you link the menu item ID to the function with a message-map entry. For example, you'll find default implementations of the File-New and File-Open commands in CWinApp's OnFileNew and OnFileOpen functions, but neither function is connected to the application unless you provide an ON_COMMAND message-map entry for it. CWinApp::OnAppExit, on the other hand, works all by itself and requires no message-map entry. All you have to do is assign the File-Exit menu item the ID ID_APP_EXIT, and OnAppExit will magically be called to end the application when the user selects Exit from the File menu. Why? Because CWinApp's message map contains an

 ON_COMMAND (ID_APP_EXIT, OnAppExit)

entry, and message maps, like other class members, are passed on by inheritance.

Predefined Command IDs and Command Handlers

Command ID	Menu Item	Default Handler	Prewired?
File menu
ID_FILE_NEW	New	CWinApp::OnFileNew	No
ID_FILE_OPEN	Open	CWinApp::OnFileOpen	No
ID_FILE_SAVE	Save	CDocument::OnFileSave	Yes
ID_FILE_SAVE_AS	Save As	CDocument::OnFileSaveAs	Yes
ID_FILE_PAGE_SETUP	Page Setup	None	N/A
ID_FILE_PRINT_SETUP	Print Setup	CWinApp::OnFilePrintSetup	No
ID_FILE_PRINT	Print	CView::OnFilePrint	No
ID_FILE_PRINT_PREVIEW	Print Preview	CView::OnFilePrintPreview	No
ID_FILE_SEND_MAIL	Send Mail	CDocument::OnFileSendMail	No
ID_FILE_MRU_FILE1_	N/A	CWinApp::OnOpenRecentFile	Yes
ID_FILE_MRU_FILE16
ID_APP_EXIT	Exit	CWinApp::OnAppExit	Yes
Edit menu
ID_EDIT_CLEAR	Clear	None	N/A
ID_EDIT_CLEAR_ALL	Clear All	None	N/A
ID_EDIT_CUT	Cut	None	N/A
ID_EDIT_COPY	Copy	None	N/A
ID_EDIT_PASTE	Paste	None	N/A
ID_EDIT_PASTE_LINK	Paste Link	None	N/A
ID_EDIT_PASTE_SPECIAL	Paste Special	None	N/A
ID_EDIT_FIND	Find	None	N/A
ID_EDIT_REPLACE	Replace	None	N/A
ID_EDIT_UNDO	Undo	None	N/A
ID_EDIT_REDO	Redo	None	N/A
ID_EDIT_REPEAT	Repeat	None	N/A
ID_EDIT_SELECT_ALL	SelectAll	None	N/A
View menu
ID_VIEW_TOOLBAR	Toolbar	CFrameWnd::OnBarCheck	Yes
ID_VIEW_STATUS_BAR	Status Bar	CFrameWnd::OnBarCheck	Yes
Window menu (MDI applications only)
ID_WINDOW_NEW	New Window	CMDIFrameWnd::OnWindowNew	Yes
ID_WINDOW_ARRANGE	Arrange All	CMDIFrameWnd::OnMDIWindowCmd	Yes
ID_WINDOW_CASCADE	Cascade	CMDIFrameWnd::OnMDIWindowCmd	Yes
ID_WINDOW_TILE_HORZ	Tile Horizontal	CMDIFrameWnd::OnMDIWindowCmd	Yes
ID_WINDOW_TILE_VERT	Tile Vertical	CMDIFrameWnd::OnMDIWindowCmd	Yes
Help menu
ID_APP_ABOUT	About AppName	None	N/A

MFC also provides update handlers for some commands, including these:

CFrameWnd::OnUpdateControlBarMenu for the ID_VIEW_TOOLBAR and ID_VIEW_STATUS_BAR commands
CMDIFrameWnd::OnUpdateMDIWindowCmd for the ID_WINDOW- _ARRANGE, ID_WINDOW_CASCADE, ID_WINDOW_TILE_HORZ, ID- _WINDOW_TILE_VERT, and ID_WINDOW_NEW commands
CDocument::OnUpdateFileSendMail for the ID_FILE_SEND_MAIL command

MFC's CEditView and CRichEditView classes include command handlers for some of the items in the Edit menu, but other views must provide their own.

You don't have to use the predefined command IDs or command handlers the framework provides. You can always strike out on your own and define custom command IDs, perhaps supplying message map entries to correlate your command IDs with default command handlers. You can even replace the default command handlers with handlers of your own. In short, you can use as much or as little of the framework's support as you want to. But the more you lean on the framework, the less code you'll have to write yourself.