Document Templates and the Document/View Creation Process

1.

To manage the complex process of creating documents with their associated views and frame windows, the framework uses two document template classes: CSingleDocTemplate for SDI applications and CMultiDocTemplate for MDI applications. A CSingleDocTemplate can create and store one document of one type at a time. A CMultiDocTemplate keeps a list of many open documents of one type.

Some applications support multiple document types. For example, an application might support text documents and graphics documents. In such an application, when the user chooses the New command on the File menu, a dialog box shows a list of possible new document types to open. For each supported document type, the application uses a distinct document template object. The following figure illustrates the configuration of an MDI application that supports two document types and shows several open documents.

An MDI Application with Two Document Types

Document templates are created and maintained by the application object. One of the key tasks performed during your application's InitInstance function is to construct one or more document templates of the appropriate kind. This feature is described in Document Template Creation . The application object stores a pointer to each document template in its template list and provides an interface for adding document templates.

If you need to support two or more document types, you must add an extra call to AddDocTemplate for each document type.

An icon is registered for each document template based on its position in the application's list of document templates. The order of the document templates is determined by the order they are added with calls to AddDocTemplate . MFC assumes that the first Icon resource in the application is the application icon, the next Icon resource is the first document icon, and so on.

For example, a document template is the third of three for the application. If there is an Icon resource in the application at index 3, that icon is used for the document template. If not, the icon at index 0 is used as a default.

 

2.

When creating a new document in response to a New or Open command from the File menu, the document template also creates a new frame window through which to view the document.

The document-template constructor specifies what types of documents, windows, and views the template will be able to create. This is determined by the arguments you pass to the document-template constructor. The following code illustrates creation of a CMultiDocTemplate for a sample application:

	Copy Code
AddDocTemplate( new CMultiDocTemplate( IDR_SCRIBTYPE, RUNTIME_CLASS( CScribDoc ), RUNTIME_CLASS( CMDIChildWnd ), RUNTIME_CLASS( CScribView ) ) );

The pointer to a new CMultiDocTemplate object is used as an argument to AddDocTemplate . Arguments to the CMultiDocTemplate constructor include the resource ID associated with the document type's menus and accelerators, and three uses of the RUNTIME_CLASS macro. RUNTIME_CLASS returns the CRuntimeClass object for the C++ class named as its argument. The three CRuntimeClass objects passed to the document-template constructor supply the information needed to create new objects of the specified classes during the document creation process. The example shows creation of a document template that creates CScribDoc objects with CScribView objects attached. The views are framed by standard MDI child frame windows.

 

3.

The framework supplies implementations of the New and Open commands (among others) on the File menu. Creation of a new document and its associated view and frame window is a cooperative effort among the application object, a document template, the newly created document, and the newly created frame window. The following table summarizes which objects create what.

Object Creators

Creator	Creates
Application object	Document template
Document template	Document
Document template	Frame window
Frame window	View

4.

To help put the document/view creation process in perspective, consider a running program: a document, the frame window used to contain the view, and the view associated with the document.

• A document keeps a list of the views of that document and a pointer to the document template that created the document.

• A view keeps a pointer to its document and is a child of its parent frame window.

• A document frame window keeps a pointer to its current active view.

• A document template keeps a list of its open documents.

• The application keeps a list of its document templates.

• Windows keeps track of all open windows so it can send messages to them.

These relationships are established during document/view creation. The following table shows how objects in a running program can access other objects. Any object can obtain a pointer to the application object by calling the global function AfxGetApp .

Gaining Access to Other Objects in Your Application

From object	How to access other objects
Document	Use GetFirstViewPosition and GetNextView to access the document's view list. Call GetDocTemplate to get the document template.
View	Call GetDocument to get the document. Call GetParentFrame to get the frame window.
Document frame window	Call GetActiveView to get the current view. Call GetActiveDocument to get the document attached to the current view.
MDI frame window	Call MDIGetActive to get the currently active CMDIChildWnd .

Typically, a frame window has one view, but sometimes, as in splitter windows, the same frame window contains multiple views. The frame window keeps a pointer to the currently active view; the pointer is updated any time another view is activated.

Note

A pointer to the main frame window is stored in the m_pMainWnd member variable of the application object. A call to OnFileNew in your override of the InitInstance member function of CWinApp sets m_pMainWnd for you. If you do not call OnFileNew , you must set the variable's value in InitInstance yourself. (SDI COM component (server) applications may not set the variable if /Embedding is on the command line.) Note that m_pMainWnd is now a member of class CWinThread rather than CWinApp .

5.

The following figures give an overview of the creation process for documents, views, and frame windows. Other articles that focus on the participating objects provide further details.

Upon completion of this process, the cooperating objects exist and store pointers to each other. The following figures show the sequence in which objects are created. You can follow the sequence from figure to figure.

Sequence in Creating a Document

Sequence in Creating a Frame Window

Sequence in Creating a View

For information about how the framework initializes the new document, view, and frame-window objects, see classes CDocument , CView , CFrameWnd , CMDIFrameWnd , and CMDIChildWnd in the MFC Library Reference. Also see Technical Note 22 , which explains the creation and initialization processes further under its discussion of the framework's standard commands for the New and Open items on the File menu.

Initializing Your Own Additions to These Classes

The preceding figures also suggest the points at which you can override member functions to initialize your application's objects. An override of OnInitialUpdate in your view class is the best place to initialize the view. The OnInitialUpdate call occurs immediately after the frame window is created and the view within the frame window is attached to its document. For example, if your view is a scroll view (derived from CScrollView rather than CView ), you should set the view size based on the document size in your OnInitialUpdate override. (This process is described in the description of class CScrollView .) You can override the CDocument member functions OnNewDocument and OnOpenDocument to provide application-specific initialization of the document. Typically, you must override both since a document can be created in two ways.

In most cases, your override should call the base class version. For more information, see the named member functions of classes CDocument , CView , CFrameWnd , and CWinApp in the MFC Library Reference.