A document template manages the document objects in your program, as well as the windows and views associated with each of them. There is one document template for each type of document that you have in your application. If you have two or more documents of the same type, you need only one document template to manage them. To be more specific about the role of a document template, a document template object creates document objects and frame window objects, and views of a document are created by a frame window object. The application object that is fundamental to every MFC application creates the document template object itself. Figure 14-2 shows a graphical representation of these interrelationships.

Figure 14.2. FIGURE 14-2

The diagram uses dashed arrows to show how pointers are used to relate objects. These pointers enable function members of one class object to access the public data or the function members in the interface of another object.

MFC has two classes for defining document templates. For SDI applications, the MFC library class CSingleDocTemplate is used. This is relatively straightforward because an SDI application has only one document and usually just one view. MDI applications are rather more complicated. They have multiple documents active at one time, so a different class, CMultiDocTemplate, is needed to define the document template. You'll see more of these classes as we progress into developing application code.

If you select the Solution Explorer tab and expand the list by clicking the [unfilled] symbol for TextEditor files and then click the [unfilled] symbol for each of the Source Files, Header Files, and Resource Files folders, you'll see the complete list of files for the project, as shown in Figure 14-9. To collapse any expanded branch of the tree, just click the [filled] symbol.

Figure 14.9. FIGURE 14-9

Figure 14-9 shows the pane as a floating window to make the complete list of files visible at one time; you can arrange for any of the tabbed panes to be floating by clicking the down arrow at the top of the pane and selecting from the list of possible positions. As you can see, there are a total of 19 files shown in the project, excluding ReadMe.txt. You can view the contents of any of the files simply by double-clicking the file name. The contents of the file selected are displayed in the Editor window. Try it out with the ReadMe.txt file. You'll see that it contains a brief explanation of the contents of each of the files that make up the project. I won't repeat the descriptions of the files here, because they are very clearly summarized in ReadMe.txt.

The access to your project presented by the Class View tab is often much more convenient than that of Solution Explorer because classes are the basis for the organization of the application. When you want to look at the code, it's typically the definition of a class or the implementation of a member function you'll want to look at, and from Class View you can go directly to either. On occasions, however, Solution Explorer comes in handy. If you want to check the #include directives in a .cpp file, using Solution Explorer, you can open the file you're interested in directly.

In the Class View pane, you can expand the TextEditor classes item to show the classes defined for the application. Clicking the name of any class shows the members of that class in the lower pane. In the Class View pane shown in Figure 14-10, the CTextEditorDoc class has been selected.

Figure 14.10. FIGURE 14-10

Figure 14-10 shows the Class View pane in its docked state. The icons code the various kinds of things that you can display. You will find a key to what each icon indicates if you look at the Class View documentation.

You can see that you have the four classes that I discussed earlier that are fundamental to an MFC application: CTextEditorApp for the application, CMainFrame for the application frame window, CTextEditorDoc for the document, and CTextEditorView for the view. You also have a class CAboutDlg that defines objects that support the dialog box that appears when you select the menu item Help

Figure 14.11. FIGURE 14-11

The application object, theApp, appears twice because there is an extern statement for theApp in TextEditor.h and the definition for theApp is in TextEditor.cpp. If you double-click either of the appearances of theApp in Class View, it will take you to the corresponding statement. indicators is an array of indicators recording the status of caps lock, num lock, and scroll lock that are displayed in the status bar. The remaining three variables relate to the management of the toolbars in the application. If you double-click any of these, you will see its definition.

To view the code for a class definition in the Editor pane, you just double-click the class name in the tree in Class View. Similarly, to view the code for a member function, double-click the function name. Note that you can drag the edges of any of the panes in an IDE window to view its contents or your code more easily. You can hide or show the Solution Explorer set of panes by clicking the Autohide button at the right end of the pane title bar.

I won't go into the classes in complete detail here — you'll just get a feel for how they look and I'll highlight a few important aspects. Note that the precise content of each class that is generated by the Application Wizard depends on the options you select when creating the project. If you double-click the name of a class in the Class View, the code defining the class is displayed. Take a look at the application class, CTextEditorApp, first. The definition for this class is shown here:

// TextEditor.h : main header file for the TextEditor application
//
#pragma once

#ifndef __AFXWIN_H__
      #error "include 'stdafx.h' before including this file for PCH"
#endif

#include "resource.h" // main symbols


// CTextEditorApp:
// See TextEditor.cpp for the implementation of this class
//

class CTextEditorApp : public CWinAppEx
{
public:
      CTextEditorApp();


// Overrides
public:
      virtual BOOL InitInstance();

// Implementation
      BOOL  m_bHiColorIcons;

      virtual void PreLoadState();
      virtual void LoadCustomState();
      virtual void SaveCustomState();

      afx_msg void OnAppAbout();
      DECLARE_MESSAGE_MAP()
};

extern CTextEditorApp theApp;
                                                                         

The CTextEditorApp class derives from CWinAppEx and includes a constructor, a virtual function InitInstance(), a function OnAppAbout(), three functions concerned with dealing with the application state, and a macro DECLARE_MESSAGE_MAP().

The DECLARE_MESSAGE_MAP() macro is concerned with defining which Windows messages are handled by which function members of the class. The macro appears in the definition of any class that may process Windows messages. Of course, our application class inherits a lot of functions and data members from the base class, and you will be looking further into these as you expand the program examples. If you take a look at the beginning of the code for the class definition, you will notice that the #pragma once directive prevents the file being included more than once. Following that is a group of preprocessor directives that ensure that the stdafx.h file is included before this file.

The application frame window for our SDI program is created by an object of the class CMainFrame, which is defined by the following code:

class CMainFrame : public CFrameWndEx
{
protected: // create from serialization only
      CMainFrame();
      DECLARE_DYNCREATE(CMainFrame)

// Attributes
public:

// Operations
public:

// Overrides
public:
      virtual BOOL PreCreateWindow(CREATESTRUCT& cs);
      virtual BOOL LoadFrame(UINT nIDResource, DWORD dwDefaultStyle =
             WS_OVERLAPPEDWINDOW | FWS_ADDTOTITLE, CWnd* pParentWnd =
             NULL, CCreateContext* pContext = NULL);

// Implementation
public:
      virtual ~CMainFrame();
#ifdef _DEBUG
      virtual void AssertValid() const;
      virtual void Dump(CDumpContext& dc) const;
#endif

protected:  // control bar embedded members
      CMFCMenuBar       m_wndMenuBar;
      CMFCToolBar       m_wndToolBar;
      CMFCStatusBar     m_wndStatusBar;
      CMFCToolBarImages m_UserImages;

// Generated message map functions
protected:
      afx_msg int OnCreate(LPCREATESTRUCT lpCreateStruct);
      afx_msg void OnViewCustomize();
      afx_msg LRESULT OnToolbarCreateNew(WPARAM wp, LPARAM lp);
      DECLARE_MESSAGE_MAP()
};

This class is derived from CFrameWndEx, which provides most of the functionality required for our application frame window. The derived class includes four protected data members — m_wndMenuBar, m_wndToolBar, m_wndStatusBar, and m_UserImages — which are instances of the MFC classes CMFCMenuBar, CMFCToolBar, CMFCStatusBar, and CMFCToolBarImages, respectively. The first three of these objects create and manage the menu bar, the toolbar that provides buttons to access standard menu functions, and the status bar that appears at the bottom of the application window. The fourth objects hold the images that are to appear on toolbar buttons.

The definition of the CTextEditorDoc class that was supplied by the MFC Application wizard is:

class CTextEditorDoc : public CDocument
{
protected: // create from serialization only
      CTextEditorDoc();
      DECLARE_DYNCREATE(CTextEditorDoc)

// Attributes
public:

// Operations
public:

// Overrides
public:
      virtual BOOL OnNewDocument();
      virtual void Serialize(CArchive& ar);
#ifdef SHARED_HANDLERS
      virtual void InitializeSearchContent();
      virtual void OnDrawThumbnail(CDC& dc, LPRECT lprcBounds);
#endif // SHARED_HANDLERS

// Implementation
public:
      virtual ~CTextEditorDoc();
#ifdef _DEBUG
      virtual void AssertValid() const;
      virtual void Dump(CDumpContext& dc) const;
#endif

protected:

// Generated message map functions
protected:
      DECLARE_MESSAGE_MAP()

#ifdef SHARED_HANDLERS
      // Helper function that sets search content for a Search Handler
      void SetSearchContent(const CString& value);
#endif // SHARED_HANDLERS

#ifdef SHARED_HANDLERS
private:

CString m_strSearchContent;
      CString m_strThumbnailContent;
#endif // SHARED_HANDLERS
};

As in the case of the previous classes, most of the meat comes from the base class and is therefore not apparent here. The DECLARE_DYNCREATE() macro that appears after the constructor (and was also used in the CMainFrame class) enables an object of the class to be created dynamically by synthesizing it from data read from a file. When you save an SDI document object, the frame window that contains the view is saved along with your data. This allows everything to be restored when you read it back. Reading and writing a document object to a file is supported by a process called serialization. You will see how to write your own documents to file using serialization and then reconstruct them from the file data in the examples we will develop.

The document class also includes the DECLARE_MESSAGE_MAP() macro in its definition to enable Windows messages to be handled by class member functions if necessary.

The view class in our SDI application is defined as:

class CTextEditorView : public CEditView
{
protected: // create from serialization only
      CTextEditorView();
      DECLARE_DYNCREATE(CTextEditorView)

// Attributes
public:
      CTextEditorDoc* GetDocument() const;

// Operations
public:

// Overrides
public:
      virtual BOOL PreCreateWindow(CREATESTRUCT& cs);
protected:
      virtual BOOL OnPreparePrinting(CPrintInfo* pInfo);
      virtual void OnBeginPrinting(CDC* pDC, CPrintInfo* pInfo);
      virtual void OnEndPrinting(CDC* pDC, CPrintInfo* pInfo);

// Implementation
public:
      virtual ~CTextEditorView();
#ifdef _DEBUG
      virtual void AssertValid() const;
      virtual void Dump(CDumpContext& dc) const;
#endif

protected:

// Generated message map functions
protected:
      afx_msg void OnFilePrintPreview();

afx_msg void OnRButtonUp(UINT nFlags, CPoint point);
      afx_msg void OnContextMenu(CWnd* pWnd, CPoint point);
      DECLARE_MESSAGE_MAP()
};

#ifndef _DEBUG  // debug version in TextEditorView.cpp
inline CTextEditorDoc* CTextEditorView::GetDocument() const
   { return reinterpret_cast<CTextEditorDoc*>(m_pDocument); }
#endif

As you specified in the Application Wizard dialog box, the view class is derived from the class CEditView, which already includes basic text handling facilities. The GetDocument() function returns a pointer to the document object corresponding to the view, and you will be using this to access data in the document object when you add your own extensions to the view class.

To compile and link the program, click Build

There are two implementations of the CTextEditorView class member function GetDocument() in the code generated by Application Wizard. The one in the .cpp file for the CEditView class is used for the debug version of the program. You will normally use this during program development because it provides validation of the pointer value stored for the document. (This is stored in the inherited data member m_pDocument in the view class.) The version that applies to the release version of your program you can find after the class definition in the TextEditorView.h file. This version is declared as inline and it does not validate the document pointer. The GetDocument() function just provides a link to the document object. You can call any of the functions in the interface to the document class using the pointer to the document that the function returns.

By default, you have debug capability included in your program. As well as the special version of GetDocument(), there are lots of checks in the MFC code that are included in this case. If you want to change this, you can use the drop-down list box in the Build toolbar to choose the release configuration, which doesn't contain all the debug code.

To execute the program, press Ctrl+F5. Because you chose CEditView as the base class for the CTextEditorView class, the program is a fully functioning, simple text editor. You can enter text in the window, as shown in Figure 14-12.

Figure 14.12. FIGURE 14-12

Note that the application has scroll bars for viewing text outside the visible area within the window, and, of course, you can resize the window by dragging the boundaries. All the items under all menus are fully operational so you can save and retrieve files, you can cut and paste text, and you can print the text in the window — and all that without writing a single line of code! As you move the cursor over the toolbar buttons or the menu options, prompts appear in the status bar describing the functions that are invoked, and if you let the cursor linger on a toolbar button, a tooltip is displayed showing its purpose. (You'll learn about tooltips in more detail in Chapter 15.)

As in the trivial MFC example you looked at in an earlier chapter, the application object is created at global scope in our SDI program. You can see this if you expand the Global Functions and Variables item in the Class View, and then double-click theApp. In the Editor window, you'll see this statement:

CTextEditorApp theApp;

This declares the object theApp as an instance of our application class CTextEditorApp. The statement is in the file TextEditor.cpp, which also contains member function declarations for the application class, and the definition of the CAboutDlg class.

After the object theApp has been created, the MFC-supplied WinMain() function is called. This, in turn, calls two member functions of the theApp object. First, it calls InitInstance(), which provides for any initialization of the application that is necessary, and then Run(), which provides initial handling for Windows messages. The WinMain() function does not appear explicitly in the project source code, because it is supplied by the MFC class library and is called automatically when the application starts.

SetRegistryKey(_T("Local AppWizard-Generated Applications"));
LoadStdProfileSettings(4);  // Load standard INI file options (including MRU)

HKEY_CURRENT_USERSoftwareHortonTextEditor

pDocTemplate = new CSingleDocTemplate(
    IDR_MAINFRAME,
    RUNTIME_CLASS(CTextEditorDoc),
    RUNTIME_CLASS(CMainFrame),       // main SDI frame window
    RUNTIME_CLASS(CTextEditorView));

You can build the program in exactly the same way as the previous example. Then, if you execute it, you get the application window shown in Figure 14-14.

Figure 14.14. FIGURE 14-14

In addition to the main application window, you have a separate document window with the caption Sketch1. Sketch1 is the default name for the initial document, and it has the extension .ske if you save it. You can create additional views for the document by selecting the Window

Figure 14.15. FIGURE 14-15

You can't yet actually create any data in the application because we haven't added any code to do that, but all the code for creating documents and views has already been included by the Application Wizard.