What Is a Document?

A document is a collection of data in your application with which the user interacts. Although the word ****document seems to imply something of a textual nature, it isn’t limited to text. It could be data for a game, a geometric model, a text file, a collection of data on the distribution of orange trees in California, or, indeed, anything you want. The term document is just a convenient label for the application data in your program, treated as a unit.

You won’t be surprised to hear that a document is defined as an object of a document class. Your document class is derived from the CDocument class in the MFC library, and you add your own data members to store items that your application requires, and member functions to support processing of that data. Your application is not limited to a single document type; you can define multiple document classes when there are several different kinds of documents involved in your application.

Handling application data in this way enables standard mechanisms to be provided within the MFC for managing a collection of application data as a unit and for storing the data on disk. These mechanisms are inherited by your document class from CDocument, so you get a broad range of functionality built into your application automatically, without having to write any code.

Document Interfaces

You have a choice as to whether your program deals with just one document at a time, or with several. The Single Document Interface (SDI) is supported by the MFC for programs that require only one document to be open at a time. A program using this interface is an SDI application.

For programs needing several documents to be open at one time, you use the Multiple Document Interface (MDI). With the MDI, as well as being able to open multiple documents of one type, your program can also be organized to handle documents of different types simultaneously with each document displayed in its own window. Of course, you need to supply the code to deal with processing all the types of documents you intend to use. In an MDI application, each document is displayed in a child window of the application window. You also have an application variant called the multiple top-level document architecture where each document window is a child of the desktop.

What Is a View?

A view always relates to a particular document object. A document object contains a set of application data, and a view is an object that provides a mechanism for displaying some or all of that data. A view defines how the data is to be displayed in a window and how the user can interact with it. You define a view class by deriving it from the MFC class, CView. Note that a view object and the window, in which it is displayed, are distinct. The window in which a view appears is called a frame window. A view is displayed in its own window that exactly fills the client area of a frame window. Figure 12-1 illustrates how a document might be displayed in two views.

In Figure 12-1, each view displays all the data that the document contains in a different form, although a view could display just part of the data if that’s what’s required.

A document can have as many view objects associated with it as you want. Each view can provide a different presentation of the document data or a subset of the data. If you were dealing with text, for example, different views could display independent blocks of text from the same document. For a program handling graphical data, you could display the document data at different scales in separate windows, or in different formats, such as a textual representation of the elements that form the image. Figure 12-1 illustrates a document that contains numerical data — product sales data by month — where one view provides a bar chart representation of sales performance and a second view shows the data in the form of a graph.

Linking a Document and Its Views

The MFC incorporates a mechanism for integrating a document with its views, and each frame window with a currently active view. A document automatically maintains a list of pointers to its associated views, and a view object has a data member holding a pointer to the document to which it relates. Each frame window stores a pointer to the currently active view. The coordination between a document, a view, and a frame window is established by another MFC class of objects called document templates.

Document Templates

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. A document template object creates document objects and frame window objects, and views for a document are created by a frame window object. The application object that is fundamental to every MFC application creates the document template object. Figure 12-2 shows a graphical representation of these interrelationships.

Figure 12-2 uses dashed arrows to show how pointers are used to relate objects. These pointers enable function members of one object to access the public data or function members in the interface of another object.

Your Application and MFC

Figure 12-3 shows the four basic classes that are going to appear in virtually all your MFC-based Windows applications:

• The application class CMyApp
• The frame window class CMyWnd
• The view class CMyView, which defines how data contained in CMyDoc is to be displayed in the client area of a window created by a CMyWnd object
• The document class CMyDoc, defining a document to contain the application data

The names for these classes are specific to an application, but the derivation from the MFC is much the same, although there can be alternative base classes, particularly with the view class. The MFC provides several variations of the view class that provide a lot of prepackaged functionality, saving you lots of coding. You normally don’t need to extend the document template class so the standard CSingleDocTemplate class usually suffices in an SDI program. CMultiDocTemplate is the document template class in an MDI program and this is also derived from CDocTemplate. An MDI application also contains an additional class that defines a child window.

The arrows in Figure 12-3 point from a derived class to a base class. The MFC classes shown here form quite a complex inheritance structure, but these are just a very small part of the complete MFC structure. You need not be concerned about the details of the complete MFC hierarchy, but it is important to have a general appreciation of it if you want to understand what the inherited members of your classes are. You will not see any of the definitions of the base classes in your code, but the inherited members in a derived class are accumulated from the direct base class and each of the indirect base classes in the hierarchy. To determine what members one of your program’s classes has, you need to know from which classes it inherits. After you know that, you can look up its members using the Help facility.

You don’t need to worry about remembering which classes you need to have in your program and what base classes to use in their definition. As you’ll see next, all of this is taken care of for you by Visual C++.

Creating an SDI Application

Select the Application Type option from the list in the left dialog pane. The default option selected is Multiple documents with the tabbed option, which selects the MDI with each document in its own tabbed page; the appearance of this is shown at the top left in the dialog so that you’ll know what to expect. Select the Single document Application type option, the MFC standard Project style option, and the Windows Native/Default option from the drop-down list of visual styles. The representation for the application that is shown top-left changes to a single window, as shown in Figure 12-5.

Some of the other options you have for the application type are:

If you hover the mouse cursor over any of the options, a tooltip will be displayed explaining the option.

You have several options for the Project style. I’ll select the MFC Standard option and suggest that you do the same. I also selected Windows Native/Default from the Visual style and colors drop-down list. This makes the application appearance the same as your current operating system.

You can also choose how the MFC library is used in your project. The default choice of using the MFC library as a shared DLL (Dynamic Link Library) means that your program links to MFC routines at run time. This reduces the size of the executable file that you’ll generate, but requires the MFC DLL to be on the machine that’s running it. Your application’s .exe module and the MFC .dll together may be bigger than if you statically link the MFC library. If you opt for static linking, the MFC library routines are included in the executable module for your program when it is built. If you keep the default option, several programs running simultaneously using the dynamic link library can all share a single copy of the library in memory.

If you select Document Template Properties in the left pane of the dialog, you can enter a file extension for files that the program creates in the right pane. The extension txt is a good choice for this example. You can also enter a Filter Name, which is the name of the filter that will appear in Open and Save As dialogs to filter the file list so only files with your file extension are displayed.

If you select User Interface Features from the list in the left pane, you get a further set of options that can be included in your application:

In the Command bars sub-options you can choose whether you use a classic Windows menu with a docking toolbar, an Internet Explorer style toolbar, a menu bar and toolbar that you can customize at run time, or a ribbon. The User-defined toolbars and images sub-option allows the toolbar and images to be customized at run time. The Personalized menu behavior sub-option enables menus to display only the items used most frequently. You would typically use a ribbon with applications that complement Microsoft Office. In this example, we will use the classic menu with a classic docking toolbar.

You should be aware of a couple of features under the Advanced Features set of options. One is Printing and print preview, which is selected by default, and the other is the number of files on the recent file list. You can increase the latter to whatever you think is useful for the application. Printing and print preview add the standard Page Setup, Print Preview, and Print items to the File menu, and the Application Wizard also provides code to support these functions. You can uncheck all the other options for the example.

The Generated Classes option in the left pane of the dialog displays a list of the classes that will be generated, as shown in Figure 12-6.

You can highlight any class in the list by clicking it, and the boxes below show the class name, the header filename in which the class definition will be stored, the base class, and the name of the source file containing the implementation of the class. The class definition is always in an .h file, and the member function definitions are always in a .cpp file.

You can alter everything except the base class for the CTextEditorDoc class. The only thing you can change for CTextEditorApp is the class name. Try clicking the other classes in the list. For CMainFrame, you can alter everything except the base class, and for the CTextEditorView class shown in Figure 12-6, you can change the base class as well. Click the down arrow to display the list of other classes that you can have as a base class. The capability built into your view class depends on which base class you select:

Because you’ve called the application TextEditor, with the notion that it is able to edit text, choose CEditView to get basic text editing. You can now click Finish to generate the program files for a fully working base program using the options you’ve chosen. This will take a little while.

MFC Application Wizard Output

All the program files generated by the Application Wizard are stored in the TextEditor project folder, which is a subfolder to the solution folder with the same name. There are resource files in the res subfolder to the project folder. The IDE provides several ways for you to view the information relating to your project:

You can switch to view any of these by selecting from the View menu or clicking on a tab label. If you right-click TextEditor in the Solution Explorer pane and select Properties from the pop-up, the project properties window is displayed, as shown in Figure 12-7.

The left pane shows the property groups you can select to be displayed in the right pane. Currently, the General group of properties is displayed. You can change the value for a property in the right pane by clicking it and selecting a new value from the drop-down list box to the right of the property name or, in some cases, by entering a new value.

At the top of the property pages window, you can see the current project configuration and the target platform when the project is built. You can change these by selecting from the drop-down list for each. By selecting All Configurations you can change properties for both the Debug and Release configurations.

Viewing Project Files

The left pane in the IDE can display several tabs. The most useful are the Solution Explorer, Class View, and Resource View tabs. You can hide the currently visible tab by clicking the down arrow in the top right of the pane and selecting Hide from the menu. I’ll just show the three interesting tabs in figures. I’ll also show the pane as an undocked window, which you get by dragging its title bar away from the edge of the main window.

If you select the Solution Explorer tab and expand the list by clicking the arrow symbol for TextEditor files and then click the arrow 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 12-8. To collapse any expanded branch of the tree, just click the arrow symbol.

There are a total of 18 files shown in the project, excluding ReadMe.txt. You can view the contents of any file by double-clicking the filename. 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.

Viewing Classes

The Class View tab is often more convenient than the Solution Explorer tab because classes are the basis for the organization of the application. When you want to look at the code, it’s typically a class definition or the implementation of a member function you want, and from Class View you can go directly to either. The Solution Explorer pane comes in handy when you want to check the #include directives in a .cpp file. From 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 12-9, the CTextEditorDoc class has been selected.

The icons characterize the things that are displayed. You will find a key to what the icons indicate in the Class View documentation. Search for “Class View and Object Browser Icons.” 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 CAboutDlg class that defines objects that support the dialog box that appears when you select the menu item Help About in the application. If you select Global Functions and Variables, you’ll see that it contains three items, as in Figure 12-10.

The application object, theApp, appears twice because there is an extern statement for theApp in TextEditor.h and a definition for it in TextEditor.cpp. If you double-click either of the appearances of theApp, it will take you to the corresponding statement. indicators is an array of four IDs for items that appear in the status bar: a separator, caps lock status, num lock status, and scroll lock status.

To view the code for a class definition double-click the class name 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 set of panes by clicking the close button at the right end of the pane title bar.

// 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 CWinApp
{
public:
  CTextEditorApp();
 
 
// Overrides
public:
  virtual BOOL InitInstance();
 
// Implementation
  afx_msg void OnAppAbout();
  DECLARE_MESSAGE_MAP()
};
 
extern CTextEditorApp theApp;

// MainFrm.h : interface of the CMainFrame class
//
 
#pragma once
 
class CMainFrame : public CFrameWnd
{
 
protected: // create from serialization only
  CMainFrame();
  DECLARE_DYNCREATE(CMainFrame)
 
// Attributes
public:
 
// Operations
public:
 
// Overrides
public:
  virtual BOOL PreCreateWindow(CREATESTRUCT& cs);
 
// Implementation
public:
  virtual ~CMainFrame();
#ifdef _DEBUG
  virtual void AssertValid() const;
  virtual void Dump(CDumpContext& dc) const;
#endif
 
protected:  // control bar embedded members
  CToolBar          m_wndToolBar;
  CStatusBar        m_wndStatusBar;
 
// Generated message map functions
protected:
  afx_msg int OnCreate(LPCREATESTRUCT lpCreateStruct);
  DECLARE_MESSAGE_MAP()
 
};

// TextEditorDoc.h : interface of the CTextEditorDoc class
//
 
 
#pragma once
 
 
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
};

 
// TextEditorView.h : interface of the CTextEditorView class
//
 
#pragma once
 
 
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:
  DECLARE_MESSAGE_MAP()
};
 
#ifndef _DEBUG  // debug version in TextEditorView.cpp
inline CTextEditorDoc* CTextEditorView::GetDocument() const
   { return reinterpret_cast<CTextEditorDoc*>(m_pDocument); }
#endif

Running the Program

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 12-11.

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 their functions, 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 13.)

CTextEditorApp theApp;

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

Creating an MDI Application

Now let’s create an MDI application using the MFC Application Wizard. Press Ctrl+Shift+N and give the project the name Sketcher — and plan on keeping it. You’ll be expanding this into a sketching program during subsequent chapters. You should have no trouble with this procedure, because there are only a few things that you need to do differently from creating the SDI application.

1. For the Application Type group of options:
   • Leave the default option, Multiple documents, but opt out of Tabbed documents.
   • Keep Document/View architecture support.
   • Select MFC standard as the project style and Windows Native/Default as the Visual style and colors option.
2. Compound Document Support options should be the default selection, None.
3. For the Document Template Properties set of options in the dialog:
   • Specify the file extension as ske. You’ll see that you automatically get a filter for *.ske documents defined.
   • Change the Doc type name to Sketch.
   • Change the File new short name to Sketch.
4. Leave the Database Support options at the default settings, None.
5. For the User Interface Features options:
   • Keep Use a classic menu, and the sub-option, Use a classic docking toolbar.
   • Keep the other options that are selected by default: Thick frame, Minimize box, Maximize box, System menu, Initial status bar, Child minimize box and Child maximize box.
6. For the Advanced features set of options:
   • Keep the Printing and print preview option.
   • Deselect ActiveX controls, and Support Restart Manager.
7. Leave the Generated Classes options at the default settings so the base class for the CSketcherView class is CView.

You can see in the dialog with Generated Classes selected that you get an extra class for your application compared with the TextEditor example, the CChildFrame class, which is derived from CMDIChildWnd. This class provides a frame window for a view of the document that appears inside the application window created by a CMainFrame object. With an SDI application, there is a single document with a single view, so the view is displayed in the client area of the mainframe window. In an MDI application, you can have multiple documents open, and each document can have multiple views. To provide for this, each document view has its own child frame window created by a CChildFrame object. As you saw earlier, a view is displayed in a separate window, but one which exactly fills the client area of a frame window. Finally, click Finish to generate the project.

Running the Program

You can build and run the program by pressing Ctrl+F5. You get the application window shown in Figure 12-12.

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 New Window menu option. You can also create a new document by selecting File New, so that there will be two active documents in the application. The situation with two views open for a document, is shown in Figure 12-13.

You can expand either sketch window to fill the client area. You can then switch between the sketch windows through the Window drop-down menu. 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.

EXERCISES

It isn’t possible to give programming examples for this chapter, because it really just introduced the basic mechanics of creating MFC applications. There aren’t solutions to all the exercises because you will either see the answer for yourself on the screen, or be able to check your answer with the text.

1. What is the relationship between a document and a view?
2. What is the purpose of the document template in an MFC Windows program?
3. Why do you need to be careful, and plan your program structure in advance, when using the Application Wizard?
4. Code up the simple text editor program. Build both debug and release versions, and examine the types and sizes of the files produced in each case.
5. Generate the text editor application several times, trying different project styles from the Application Type in Application Wizard.

WHAT YOU LEARNED IN THIS CHAPTER