CDocument Class

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CDocument Class.

Provides the basic functionality for user-defined document classes.

Syntax

class CDocument : public CCmdTarget

Members

Public Constructors

Name	Description
CDocument::CDocument	Constructs a `CDocument` object.

Public Methods

Name	Description
CDocument::AddView	Attaches a view to the document.
CDocument::BeginReadChunks	Initializes chunk reading.
CDocument::CanCloseFrame	Advanced overridable; called before closing a frame window viewing this document.
CDocument::ClearChunkList	Clears the chunk list.
CDocument::ClearPathName	Clears the path of the document object.
CDocument::DeleteContents	Called to perform cleanup of the document.
CDocument::FindChunk	Looks for a chunk with specified GUID.
CDocument::GetAdapter	Returns a pointer to object implementing `IDocument` interface.
CDocument::GetDocTemplate	Returns a pointer to the document template that describes the type of the document.
CDocument::GetFile	Returns a pointer to the desired `CFile` object.
CDocument::GetFirstViewPosition	Returns the position of the first in the list of views; used to begin iteration.
CDocument::GetNextView	Iterates through the list of views associated with the document.
CDocument::GetPathName	Returns the path of the document's data file.
CDocument::GetThumbnail	Called to create a bitmap to be used by thumbnail provider to display thumbnail.
CDocument::GetTitle	Returns the document's title.
CDocument::InitializeSearchContent	Called to initialize search content for Search Handler.
CDocument::IsModified	Indicates whether the document has been modified since it was last saved.
CDocument::IsSearchAndOrganizeHandler	Tells whether this instance of `CDocument` object was created for Search & Organize handler.
CDocument::LoadDocumentFromStream	Called to load document data from stream.
CDocument::OnBeforeRichPreviewFontChanged	Called before Rich Preview font is changed.
CDocument::OnChangedViewList	Called after a view is added to or removed from the document.
CDocument::OnCloseDocument	Called to close the document.
CDocument::OnCreatePreviewFrame	Called by the framework when it needs to create a preview frame for Rich Preview.
CDocument::OnDocumentEvent	Called by the framework in response to a document event.
CDocument::OnDrawThumbnail	Override this method in a derived class to draw content of thumbnail.
CDocument::OnLoadDocumentFromStream	Called by the framework when it needs to load the document data from stream.
CDocument::OnNewDocument	Called to create a new document.
CDocument::OnOpenDocument	Called to open an existing document.
CDocument::OnPreviewHandlerQueryFocus	Directs the preview handler to return the HWND from calling the GetFocus Function.
CDocument::OnPreviewHandlerTranslateAccelerator	Directs the preview handler to handle a keystroke passed up from the message pump of the process in which the preview handler is running.
CDocument::OnRichPreviewBackColorChanged	Called when Rich Preview background color has changed.
CDocument::OnRichPreviewFontChanged	Called when Rich Preview font has changed.
CDocument::OnRichPreviewSiteChanged	Called when Rich Preview site has changed.
CDocument::OnRichPreviewTextColorChanged	Called when Rich Preview text color has changed.
CDocument::OnSaveDocument	Called to save the document to disk.
CDocument::OnUnloadHandler	Called by the framework when the preview handler is being unloaded.
CDocument::PreCloseFrame	Called before the frame window is closed.
CDocument::ReadNextChunkValue	Reads next chunk value.
CDocument::ReleaseFile	Releases a file to make it available for use by other applications.
CDocument::RemoveChunk	Removes a chunk with specified GUID.
CDocument::RemoveView	Detaches a view from the document.
CDocument::ReportSaveLoadException	Advanced overridable; called when an open or save operation cannot be completed because of an exception.
CDocument::SaveModified	Advanced overridable; called to ask the user whether the document should be saved.
CDocument::SetChunkValue	Sets a chunk value.
CDocument::SetModifiedFlag	Sets a flag indicating that you have modified the document since it was last saved.
CDocument::SetPathName	Sets the path of the data file used by the document.
CDocument::SetTitle	Sets the document's title.
CDocument::UpdateAllViews	Notifies all views that document has been modified.

Protected Methods

Name	Description
CDocument::OnFileSendMail	Sends a mail message with the document attached.
CDocument::OnUpdateFileSendMail	Enables the Send Mail command if mail support is present.

Public Data Members

Name	Description
CDocument::m_bGetThumbnailMode	Specifies that `CDocument` object was created by dllhost for thumbnails. Should be checked in `CView::OnDraw`.
CDocument::m_bPreviewHandlerMode	Specifies that `CDocument` object was created by prevhost for `Rich Preview`. Should be checked in `CView::OnDraw`.
CDocument::m_bSearchMode	Specifies that `CDocument` object was created by indexer or other search application.
CDocument::m_clrRichPreviewBackColor	Specifies background color of Rich Preview window. This color is set by host.
CDocument::m_clrRichPreviewTextColor	Specifies foreground color of Rich Preview window. This color is set by host.
CDocument::m_lfRichPreviewFont	Specifies text font for Rich Preview window. This font information is set by host.

Remarks

A document represents the unit of data that the user typically opens with the File Open command and saves with the File Save command.

CDocument supports standard operations such as creating a document, loading it, and saving it. The framework manipulates documents using the interface defined by CDocument.

An application can support more than one type of document; for example, an application might support both spreadsheets and text documents. Each type of document has an associated document template; the document template specifies what resources (for example, menu, icon, or accelerator table) are used for that type of document. Each document contains a pointer to its associated CDocTemplate object.

Users interact with a document through the CView object(s) associated with it. A view renders an image of the document in a frame window and interprets user input as operations on the document. A document can have multiple views associated with it. When the user opens a window on a document, the framework creates a view and attaches it to the document. The document template specifies what type of view and frame window are used to display each type of document.

Documents are part of the framework's standard command routing and consequently receive commands from standard user-interface components (such as the File Save menu item). A document receives commands forwarded by the active view. If the document doesn't handle a given command, it forwards the command to the document template that manages it.

When a document's data is modified, each of its views must reflect those modifications. CDocument provides the UpdateAllViews member function for you to notify the views of such changes, so the views can repaint themselves as necessary. The framework also prompts the user to save a modified file before closing it.

To implement documents in a typical application, you must do the following:

Derive a class from CDocument for each type of document.
Add member variables to store each document's data.
Implement member functions for reading and modifying the document's data. The document's views are the most important users of these member functions.
Override the CObject::Serialize member function in your document class to write and read the document's data to and from disk.

CDocument supports sending your document via mail if mail support (MAPI) is present. See the articles MAPI and MAPI Support in MFC.

For more information on CDocument, see Serialization, Document/View Architecture Topics, and Document/View Creation.

Inheritance Hierarchy

CObject

CCmdTarget

CDocument

Requirements

Header: afxwin.h

CDocument::AddView

Call this function to attach a view to the document.

void AddView(CView* pView);

Parameters

pView
Points to the view being added.

Remarks

This function adds the specified view to the list of views associated with the document; the function also sets the view's document pointer to this document. The framework calls this function when attaching a newly created view object to a document; this occurs in response to a File New, File Open, or New Window command or when a splitter window is split.

Call this function only if you are manually creating and attaching a view. Typically you will let the framework connect documents and views by defining a CDocTemplate object to associate a document class, view class, and frame window class.

Example

// The following example toggles two views in an SDI (single document
// interface) frame window. A design decision must be made as to
// whether to leave the inactive view connected to the document,
// such that the inactive view continues to receive OnUpdate
// notifications from the document. It is usually desirable to
// keep the inactive view continuously in sync with the document, even 
// though it is inactive. However, doing so incurs a performance cost,
// as well as the programming cost of implementing OnUpdate hints.
// It may be less expensive, in terms of performance and/or programming,
// to re-sync the inactive view with the document only with it is 
// reactivated. This example illustrates this latter approach, by 
// reconnecting the newly active view and disconnecting the newly 
// inactive view, via calls to CDocument::AddView and RemoveView.

void CMainFrame::OnViewChange(UINT nCmdID)
// There is an ON_COMMAND_RANGE message map entry associated with
// OnViewChange:
// ON_COMMAND_RANGE(ID_VIEW_CHANGE1, ID_VIEW_CHANGE2, &OnViewChange)
{
   CView* pViewAdd;
   CView* pViewRemove;
   CDocument* pDoc = GetActiveDocument();

   // cvView1 and cvView2 are enum members defined in my CMainFrame class
   if((nCmdID == ID_VIEW_CHANGE1) && (m_currentView == cvView1))
      return;
   if((nCmdID == ID_VIEW_CHANGE2) && (m_currentView == cvView2))
      return;

   if (nCmdID == ID_VIEW_CHANGE2)
   {
      if (m_pView2 == NULL)
      {
         m_pView1 = GetActiveView();
         m_pView2 = new CMyView2;

         //Note that if OnSize has been overridden in CMyView2 
         //and GetDocument() is used in this override it can 
         //cause assertions and, if the assertions are ignored,
         //cause access violation.

         m_pView2->Create(NULL, NULL, AFX_WS_DEFAULT_VIEW, rectDefault, this, 
            AFX_IDW_PANE_FIRST + 1, NULL);
      }
      pViewAdd = m_pView2;
      pViewRemove = m_pView1;
      m_currentView = cvView2;
   }
   else
   {
      pViewAdd = m_pView1;
      pViewRemove = m_pView2;
      m_currentView = cvView1;
   }

   // Set the child i.d. of the active view to AFX_IDW_PANE_FIRST,
   // so that CFrameWnd::RecalcLayout will allocate to this 
   // "first pane" that portion of   the frame window's client area 
   // not allocated to control   bars.  Set the child i.d. of the 
   // other view to anything other than AFX_IDW_PANE_FIRST; this
   // examples switches the child id's of the two views.

   int nSwitchChildID = pViewAdd->GetDlgCtrlID();
   pViewAdd->SetDlgCtrlID(AFX_IDW_PANE_FIRST);
   pViewRemove->SetDlgCtrlID(nSwitchChildID);

   // Show the newly active view and hide the inactive view.

   pViewAdd->ShowWindow(SW_SHOW);
   pViewRemove->ShowWindow(SW_HIDE);

   // Connect the newly active view to the document, and
   // disconnect the inactive view.
   pDoc->AddView(pViewAdd);
   pDoc->RemoveView(pViewRemove);

   SetActiveView(pViewAdd);
   RecalcLayout();
}

CDocument::BeginReadChunks

Initializes chunk reading.

virtual void BeginReadChunks ();

Remarks

CDocument::CanCloseFrame

Called by the framework before a frame window displaying the document is closed.

virtual BOOL CanCloseFrame(CFrameWnd* pFrame);

Parameters

pFrame
Points to the frame window of a view attached to the document.

Return Value

Nonzero if it is safe to close the frame window; otherwise 0.

Remarks

The default implementation checks if there are other frame windows displaying the document. If the specified frame window is the last one that displays the document, the function prompts the user to save the document if it has been modified. Override this function if you want to perform special processing when a frame window is closed. This is an advanced overridable.

CDocument::CDocument

Constructs a CDocument object.

CDocument();

Remarks

The framework handles document creation for you. Override the OnNewDocument member function to perform initialization on a per-document basis; this is particularly important in single document interface (SDI) applications.

CDocument::ClearChunkList

Clears the chunk list.

virtual void ClearChunkList ();

Remarks

CDocument::ClearPathName

Clears the path of the document object.

virtual void ClearPathName();

Remarks

Clearing the path from a CDocument object causes the application to prompt the user when the document is next saved. This makes a Save command behave like a Save As command.

CDocument::DeleteContents

Called by the framework to delete the document's data without destroying the CDocument object itself.

virtual void DeleteContents();

Remarks

It is called just before the document is to be destroyed. It is also called to ensure that a document is empty before it is reused. This is particularly important for an SDI application, which uses only one document; the document is reused whenever the user creates or opens another document. Call this function to implement an "Edit Clear All" or similar command that deletes all of the document's data. The default implementation of this function does nothing. Override this function to delete the data in your document.

Example

// This example is the handler for an Edit Clear All command.
void CExampleDoc::OnEditClearAll()
{
   DeleteContents();
   UpdateAllViews(NULL);   
}

void CExampleDoc::DeleteContents()
{
   // Re-initialize document data here.
}

CDocument::FindChunk

Looks for a chunk with a specified GUID.

virtual POSITION FindChunk(
    REFCLSID guid,  
    DWORD pid);

Parameters

guid
Specifies the GUID of a chunk to find.

pid
Specifies a PID of a chunk to find.

Return Value

Position in the internal chunk list if successful. Otherwise NULL.

Remarks

CDocument::GetAdapter

Returns a pointer to an object implementing the IDocument interface.

virtual ATL::IDocument* GetAdapter();

Return Value

A pointer to an object implementing the IDocument interface.

Remarks

CDocument::GetDocTemplate

Call this function to get a pointer to the document template for this document type.

CDocTemplate* GetDocTemplate() const;

Return Value

A pointer to the document template for this document type, or NULL if the document is not managed by a document template.

Example

   // This example accesses the doc template object to construct
   // a default document name such as SHEET.XLS, where "sheet"
   // is the base document name and ".xls" is the file extension
   // for the document type.
   CString strDefaultDocName, strBaseName, strExt;
   CDocTemplate* pDocTemplate = GetDocTemplate();
   if (!pDocTemplate->GetDocString(strBaseName, CDocTemplate::docName)
      || !pDocTemplate->GetDocString(strExt, CDocTemplate::filterExt))
   {
      AfxThrowUserException(); // These doc template strings will
         // be available if you created the application using AppWizard
         // and specified the file extension as an option for
         // the document class produced by AppWizard.
   }
   strDefaultDocName = strBaseName + strExt;

CDocument::GetFile

Call this member function to get a pointer to a CFile object.

virtual CFile* GetFile(
    LPCTSTR lpszFileName,  
    UINT nOpenFlags,  
    CFileException* pError);

Parameters

lpszFileName
A string that is the path to the desired file. The path may be relative or absolute.

pError
A pointer to an existing file-exception object that indicates the completion status of the operation.

nOpenFlags
Sharing and access mode. Specifies the action to take when opening the file. You can combine options listed in the CFile constructor CFile::CFile by using the bitwise OR (|) operator. One access permission and one share option are required; the modeCreate and modeNoInherit modes are optional.

Return Value

A pointer to a CFile object.

CDocument::GetFirstViewPosition

Call this function to get the position of the first view in the list of views associated with the document.

virtual POSITION GetFirstViewPosition() const;

Return Value

A POSITION value that can be used for iteration with the GetNextView member function.

Example

//To get the first view in the list of views:
// POSITION pos = GetFirstViewPosition();
// CView* pFirstView = GetNextView(pos);
//
// This example uses CDocument::GetFirstViewPosition
// and GetNextView to repaint each view.
// An easier way to accomplish the same result is to call
// UpdateAllViews(NULL);
void CExampleDoc::OnRepaintAllViews()
{
   POSITION pos = GetFirstViewPosition();
   while (pos != NULL)
   {
      CView* pView = GetNextView(pos);
      pView->UpdateWindow();
   }   
}

CDocument::GetNextView

Call this function to iterate through all of the document's views.

virtual CView* GetNextView(POSITION& rPosition) const;

Parameters

rPosition
A reference to a POSITION value returned by a previous call to the GetNextView or GetFirstViewPosition member functions. This value must not be NULL.

Return Value

A pointer to the view identified by rPosition.

Remarks

The function returns the view identified by rPosition and then sets rPosition to the POSITION value of the next view in the list. If the retrieved view is the last in the list, then rPosition is set to NULL.

Example

//To get the first view in the list of views:
// POSITION pos = GetFirstViewPosition();
// CView* pFirstView = GetNextView(pos);
//
// This example uses CDocument::GetFirstViewPosition
// and GetNextView to repaint each view.
// An easier way to accomplish the same result is to call
// UpdateAllViews(NULL);
void CExampleDoc::OnRepaintAllViews()
{
   POSITION pos = GetFirstViewPosition();
   while (pos != NULL)
   {
      CView* pView = GetNextView(pos);
      pView->UpdateWindow();
   }   
}

CDocument::GetPathName

Call this function to get the fully qualified path of the document's disk file.

const CString& GetPathName() const;

Return Value

The document's fully qualified path. This string is empty if the document has not been saved or does not have a disk file associated with it.

CDocument::GetThumbnail

Creates a bitmap to be used by the thumbnail provider to display the thumbnail.

virtual BOOL GetThumbnail(
    UINT cx,  
    HBITMAP* phbmp,  
    DWORD* pdwAlpha);

Parameters

cx
Specifies the width and height of the bitmap.

phbmp
Contains a handle to a bitmap, when the function returns successfully.

pdwAlpha
Contains a DWORD specifying the alpha channel value, when the function returns successfully.

Return Value

Returns TRUE if a bitmap for the thumbnail was created successfully; otherwise FALSE.

Remarks

CDocument::GetTitle

Call this function to get the document's title, which is usually derived from the document's filename.

const CString& GetTitle() const;

Return Value

The document's title.

CDocument::InitializeSearchContent

Called to initialize search content for the Search Handler.

virtual void InitializeSearchContent ();

Remarks

Override this method in a derived class to initialize search content. The content should be a string with parts delimited by ";". For example, "point; rectangle; ole item".

CDocument::IsModified

Call this function to determine whether the document has been modified since it was last saved.

virtual BOOL IsModified();

Return Value

Nonzero if the document has been modified since it was last saved; otherwise 0.

CDocument::IsSearchAndOrganizeHandler

Tells whether this instance of CDocument was created for the Search & Organize handler.

BOOL IsSearchAndOrganizeHandler() const;

Return Value

Returns TRUE if this instance of CDocument was created for the Search & Organize handler.

Remarks

Currently this function returns TRUE only for Rich Preview handlers implemented in an out of process server. You can set the appropriate flags (m_bPreviewHandlerMode, m_bSearchMode, m_bGetThumbnailMode) at your application level to make this function return TRUE.

CDocument::LoadDocumentFromStream

Called to load document data from a stream.

virtual HRESULT LoadDocumentFromStream(
    IStream* pStream,  
    DWORD dwGrfMode);

Parameters

pStream
A pointer to a stream. This stream is supplied by the Shell.

dwGrfMode
Access mode to the stream.

Return Value

S_OK if the load operation succeeds, otherwise HRESULT with an error code.

Remarks

You can override this method in a derived class to customize how to load data from the stream.

CDocument::m_bGetThumbnailMode

Specifies that the CDocument object was created by dllhost for thumbnails. Should be checked in CView::OnDraw.

BOOL m_bGetThumbnailMode;

Remarks

TRUE indicates that the document was created by dllhost for thumbnails.

CDocument::m_bPreviewHandlerMode

Specifies that the CDocument object was created by prevhost for Rich Preview. Should be checked in CView::OnDraw.

BOOL m_bPreviewHandlerMode;

Remarks

TRUE indicates that the document was created by prevhost for Rich Preview.

CDocument::m_bSearchMode

Specifies that the CDocument object was created by indexer or by another search application.

BOOL m_bSearchMode;

Remarks

TRUE indicates that the document was created by indexer or by another search application.

CDocument::m_clrRichPreviewBackColor

Specifies the background color of the Rich Preview window. This color is set by host.

COLORREF m_clrRichPreviewBackColor;

Remarks

CDocument::m_clrRichPreviewTextColor

Specifies the foreground color of the Rich Preview window. This color is set by host.

COLORREF m_clrRichPreviewTextColor;

Remarks

CDocument::m_lfRichPreviewFont

Specifies the text font for the Rich Preview window. This font information is set by host.

CFont m_lfRichPreviewFont;

Remarks

CDocument::OnBeforeRichPreviewFontChanged

Called before the Rich Preview font is changed.

virtual void OnBeforeRichPreviewFontChanged();

Remarks

CDocument::OnChangedViewList

Called by the framework after a view is added to or removed from the document.

virtual void OnChangedViewList();

Remarks

The default implementation of this function checks whether the last view is being removed and, if so, deletes the document. Override this function if you want to perform special processing when the framework adds or removes a view. For example, if you want a document to remain open even when there are no views attached to it, override this function.

CDocument::OnCloseDocument

Called by the framework when the document is closed, typically as part of the File Close command.

virtual void OnCloseDocument();

Remarks

The default implementation of this function destroys all of the frames used for viewing the document, closes the view, cleans up the document's contents, and then calls the DeleteContents member function to delete the document's data.

Override this function if you want to perform special cleanup processing when the framework closes a document. For example, if the document represents a record in a database, you may want to override this function to close the database. You should call the base class version of this function from your override.

CDocument::OnCreatePreviewFrame

Called by the framework when it needs to create a preview frame for Rich Preview.

virtual BOOL OnCreatePreviewFrame();

Return Value

Returns TRUE if the frame is created successfully; otherwise FALSE.

Remarks

CDocument::OnDocumentEvent

Called by the framework in response to a document event.

virtual void OnDocumentEvent(DocumentEvent deEvent);

Parameters

[in] deEvent
An enumerated data type that describes the type of event.

Remarks

Document events may affect multiple classes. This method is responsible for handling document events that affect classes other than the CDocument Class. Currently, the only class that must respond to document events is the CDataRecoveryHandler Class. The CDocument class has other overrideable methods responsible for handling the effect on the CDocument.

The following table lists the possible values for deEvent and the events that they correspond to.

Value	Corresponding Event
`onAfterNewDocument`	A new document was created.
`onAfterOpenDocument`	A new document was opened.
`onAfterSaveDocument`	The document was saved.
`onAfterCloseDocument`	The document was closed.

CDocument::OnDrawThumbnail

Override this method in a derived class to draw the thumbnail.

virtual void OnDrawThumbnail(
    CDC& dc,  
    LPRECT lprcBounds);

Parameters

dc
A reference to a device context.

lprcBounds
Specifies a bounding rectangle of the area where the thumbnail should be drawn.

Remarks

CDocument::OnFileSendMail

Sends a message via the resident mail host (if any) with the document as an attachment.

void OnFileSendMail();

Remarks

OnFileSendMail calls OnSaveDocument to serialize (save) untitled and modified documents to a temporary file, which is then sent via electronic mail. If the document has not been modified, a temporary file is not needed; the original is sent. OnFileSendMail loads MAPI32.DLL if it has not already been loaded.

A special implementation of OnFileSendMail for COleDocument handles compound files correctly.

CDocument supports sending your document via mail if mail support (MAPI) is present. See the articles MAPI Topics and MAPI Support in MFC.

CDocument::OnLoadDocumentFromStream

Called by the framework when it needs to load the document data from a stream.

virtual HRESULT OnLoadDocumentFromStream(
    IStream* pStream,  
    DWORD grfMode);

Parameters

pStream
A pointer to an incoming stream.

grfMode
Access mode to the stream.

Return Value

S_OK if the load is successful; otherwise an error code.

Remarks

CDocument::OnNewDocument

Called by the framework as part of the File New command.

virtual BOOL OnNewDocument();

Return Value

Nonzero if the document was successfully initialized; otherwise 0.

Remarks

The default implementation of this function calls the DeleteContents member function to ensure that the document is empty and then marks the new document as clean. Override this function to initialize the data structure for a new document. You should call the base class version of this function from your override.

If the user chooses the File New command in an SDI application, the framework uses this function to reinitialize the existing document, rather than creating a new one. If the user chooses File New in a multiple document interface (MDI) application, the framework creates a new document each time and then calls this function to initialize it. You must place your initialization code in this function instead of in the constructor for the File New command to be effective in SDI applications.

Note that there are cases where OnNewDocument is called twice. This occurs when the document is embedded as an ActiveX Document Server. The function is first called by the CreateInstance method (exposed by the COleObjectFactory-derived class) and a second time by the InitNew method (exposed by the COleServerDoc-derived class).

Example

The following examples illustrate alternative methods of initializing a document object.

// Method 1: In an MDI application, the simplest place to do 
// initialization is in the document constructor.  The framework 
// always creates a new document object for File New or File Open.
CExampleDoc::CExampleDoc()
{
   // Do initialization of MDI document here.
}

// Method 2: In an SDI or MDI application, do all initialization 
// in an override of OnNewDocument, if you are certain that
// the initialization is effectively saved upon File Save
// and fully restored upon File Open, via serialization.
BOOL CMyDoc::OnNewDocument()
{
   if (!CDocument::OnNewDocument())
      return FALSE;

   // Do initialization of new document here.

   return TRUE;
}

// Method 3: If the initialization of your document is not
// effectively saved and restored by serialization (during File Save
// and File Open), then implement the initialization in single
// function (named InitMyDocument in this example).  Call the
// shared initialization function from overrides of both
// OnNewDocument and OnOpenDocument.
BOOL CExampleDoc::OnNewDocument()
{
   if (!CDocument::OnNewDocument())
      return FALSE;

   InitMyDocument(); // call your shared initialization function

   // If your new document object requires additional initialization
   // not necessary when the document is deserialized via File Open,
   // then perform that additional initialization here.
   
   return TRUE;
}

CDocument::OnOpenDocument

Called by the framework as part of the File Open command.

virtual BOOL OnOpenDocument(LPCTSTR lpszPathName);

Parameters

lpszPathName
Points to the path of the document to be opened.

Return Value

Nonzero if the document was successfully loaded; otherwise 0.

Remarks

The default implementation of this function opens the specified file, calls the DeleteContents member function to ensure that the document is empty, calls CObject::Serialize to read the file's contents, and then marks the document as clean. Override this function if you want to use something other than the archive mechanism or the file mechanism. For example, you might write an application where documents represent records in a database rather than separate files.

If the user chooses the File Open command in an SDI application, the framework uses this function to reinitialize the existing CDocument object, rather than creating a new one. If the user chooses File Open in an MDI application, the framework constructs a new CDocument object each time and then calls this function to initialize it. You must place your initialization code in this function instead of in the constructor for the File Open command to be effective in SDI applications.

Example

The following examples illustrate alternative methods of initializing a document object.

// Method 1: In an MDI application, the simplest place to do 
// initialization is in the document constructor.  The framework 
// always creates a new document object for File New or File Open.
CExampleDoc::CExampleDoc()
{
   // Do initialization of MDI document here.
}

// Method 2: In an SDI or MDI application, do all initialization 
// in an override of OnNewDocument, if you are certain that
// the initialization is effectively saved upon File Save
// and fully restored upon File Open, via serialization.
BOOL CMyDoc::OnNewDocument()
{
   if (!CDocument::OnNewDocument())
      return FALSE;

   // Do initialization of new document here.

   return TRUE;
}

// Method 3: If the initialization of your document is not
// effectively saved and restored by serialization (during File Save
// and File Open), then implement the initialization in single
// function (named InitMyDocument in this example).  Call the
// shared initialization function from overrides of both
// OnNewDocument and OnOpenDocument.
BOOL CExampleDoc::OnNewDocument()
{
   if (!CDocument::OnNewDocument())
      return FALSE;

   InitMyDocument(); // call your shared initialization function

   // If your new document object requires additional initialization
   // not necessary when the document is deserialized via File Open,
   // then perform that additional initialization here.
   
   return TRUE;
}

// Additional example of OnOpenDocument()
BOOL CExampleDoc::OnOpenDocument(LPCTSTR lpszPathName)
{
   if (!CDocument::OnOpenDocument(lpszPathName))
      return FALSE;

   InitMyDocument(); // call your shared initialization function

   return TRUE;
}

CDocument::OnPreviewHandlerQueryFocus

Directs the preview handler to return the HWND retrieved from calling the GetFocus function.

virtual HRESULT OnPreviewHandlerQueryFocus(HWND* phwnd);

Parameters

phwnd
[out] When this method returns, contains a pointer to the HWND returned from calling the GetFocus function from the preview handler's foreground thread.

Return Value

Returns S_OK if successful; or an error value otherwise.

Remarks

CDocument::OnPreviewHandlerTranslateAccelerator

Directs the preview handler to handle a keystroke passed up from the message pump of the process in which the preview handler is running.

virtual HRESULT OnPreviewHandlerTranslateAccelerator(MSG* pmsg);

Parameters

pmsg
[in] A pointer to a window message.

Return Value

If the keystroke message can be processed by the preview handler, the handler processes it and returns S_OK. If the preview handler cannot process the keystroke message, it offers it to the host via IPreviewHandlerFrame::TranslateAccelerator. If the host processes the message, this method returns S_OK. If the host does not process the message, this method returns S_FALSE.

Remarks

CDocument::OnRichPreviewBackColorChanged

Called when the Rich Preview background color has changed.

virtual void OnRichPreviewBackColorChanged();

Remarks

CDocument::OnRichPreviewFontChanged

Called when the Rich Preview font has changed.

virtual void OnRichPreviewFontChanged();

Remarks

CDocument::OnRichPreviewSiteChanged

Called when the Rich Preview site has changed.

virtual void OnRichPreviewSiteChanged();

Remarks

CDocument::OnRichPreviewTextColorChanged

Called when the Rich Preview text color has changed.

virtual void OnRichPreviewTextColorChanged();

Remarks

CDocument::OnSaveDocument

Called by the framework as part of the File Save or File Save As command.

virtual BOOL OnSaveDocument(LPCTSTR lpszPathName);

Parameters

lpszPathName
Points to the fully qualified path to which the file should be saved.

Return Value

Nonzero if the document was successfully saved; otherwise 0.

Remarks

The default implementation of this function opens the specified file, calls CObject::Serialize to write the document's data to the file, and then marks the document as clean. Override this function if you want to perform special processing when the framework saves a document. For example, you might write an application where documents represent records in a database rather than separate files.

CDocument::OnUnloadHandler

Called by the framework when the preview handler is unloaded.

virtual void OnUnloadHandler();

Remarks

CDocument::OnUpdateFileSendMail

Enables the ID_FILE_SEND_MAIL command if mail support (MAPI) is present.

void OnUpdateFileSendMail(CCmdUI* pCmdUI);

Parameters

pCmdUI
A pointer to the CCmdUI object associated with the ID_FILE_SEND_MAIL command.

Remarks

Otherwise the function removes the ID_FILE_SEND_MAIL command from the menu, including separators above or below the menu item as appropriate. MAPI is enabled if MAPI32.DLL is present in the path and, in the [Mail] section of the WIN.INI file, MAPI=1. Most applications put this command on the File menu.

CDocument supports sending your document via mail if mail support (MAPI) is present. See the articles MAPI Topics and MAPI Support in MFC.

CDocument::PreCloseFrame

This member function is called by the framework before the frame window is destroyed.

virtual void PreCloseFrame(CFrameWnd* pFrame);

Parameters

pFrame
Pointer to the CFrameWnd that holds the associated CDocument object.

Remarks

It can be overridden to provide custom cleanup, but be sure to call the base class as well.

The default of PreCloseFrame does nothing in CDocument. The CDocument-derived classes COleDocument and CRichEditDoc use this member function.

CDocument::ReadNextChunkValue

Reads the next chunk value.

virtual BOOL ReadNextChunkValue(IFilterChunkValue** ppValue);

Parameters

ppValue
[out] When the function returns, ppValue contains the value that was read.

Return Value

Nonzero if successful; otherwise 0.

Remarks

CDocument::ReleaseFile

This member function is called by the framework to release a file, making it available for use by other applications.

virtual void ReleaseFile(
    CFile* pFile,  
    BOOL bAbort);

Parameters

pFile
A pointer to the CFile object to be released.

bAbort
Specifies whether the file is to be released by using either CFile::Close or CFile::Abort. FALSE if the file is to be released using CFile::Close; TRUE if the file is to be released using CFile::Abort.

Remarks

If bAbort is TRUE, ReleaseFile calls CFile::Abort, and the file is released. CFile::Abort will not throw an exception.

If bAbort is FALSE, ReleaseFile calls CFile::Close and the file is released.

Override this member function to require an action by the user before the file is released.

CDocument::RemoveChunk

Removes a chunk with the specified GUID.

virtual void RemoveChunk(
    REFCLSID guid,  
    DWORD pid);

Parameters

Guid
Specifies the GUID of a chunk to be removed.

Pid
Specifies the PID of a chunk to be removed.

Remarks

CDocument::RemoveView

Call this function to detach a view from a document.

void RemoveView(CView* pView);

Parameters

pView
Points to the view being removed.

Remarks

This function removes the specified view from the list of views associated with the document; it also sets the view's document pointer to NULL. This function is called by the framework when a frame window is closed or a pane of a splitter window is closed.

Call this function only if you are manually detaching a view. Typically you will let the framework detach documents and views by defining a CDocTemplate object to associate a document class, view class, and frame window class.

See the example at AddView for a sample implementation.

CDocument::ReportSaveLoadException

Called if an exception is thrown (typically a CFileException or CArchiveException) while saving or loading the document.

virtual void ReportSaveLoadException(
    LPCTSTR lpszPathName,  
    CException* e,  
    BOOL bSaving,  
    UINT nIDPDefault);

Parameters

lpszPathName
Points to name of document that was being saved or loaded.

e
Points to the exception that was thrown. May be NULL.

bSaving
Flag indicating what operation was in progress; nonzero if the document was being saved, 0 if the document was being loaded.

nIDPDefault
Identifier of the error message to be displayed if the function does not specify a more specific one.

Remarks

The default implementation examines the exception object and looks for an error message that specifically describes the cause. If a specific message is not found or if e is NULL, the general message specified by the nIDPDefault parameter is used. The function then displays a message box containing the error message. Override this function if you want to provide additional, customized failure messages. This is an advanced overridable.

CDocument::SaveModified

Called by the framework before a modified document is to be closed.

virtual BOOL SaveModified();

Return Value

Nonzero if it is safe to continue and close the document; 0 if the document should not be closed.

Remarks

The default implementation of this function displays a message box asking the user whether to save the changes to the document, if any have been made. Override this function if your program requires a different prompting procedure. This is an advanced overridable.

CDocument::SetChunkValue

Sets a chunk value.

virtual BOOL SetChunkValue (IFilterChunkValue* pValue);

Parameters

pValue
Specifies a chunk value to set.

Return Value

Nonzero if successful; otherwise 0.

Remarks

CDocument::SetModifiedFlag

Call this function after you have made any modifications to the document.

virtual void SetModifiedFlag(BOOL bModified = TRUE);

Parameters

bModified
Flag indicating whether the document has been modified.

Remarks

By calling this function consistently, you ensure that the framework prompts the user to save changes before closing a document. Typically you should use the default value of TRUE for the bModified parameter. To mark a document as clean (unmodified), call this function with a value of FALSE.

CDocument::SetPathName

Call this function to specify the fully qualified path of the document's disk file.

virtual void SetPathName(
    LPCTSTR lpszPathName,  
    BOOL bAddToMRU = TRUE);

Parameters

lpszPathName
Points to the string to be used as the path for the document.

bAddToMRU
Determines whether the filename is added to the most recently used (MRU) file list. If TRUE, the filename is added; if FALSE, it is not added.

Remarks

Depending on the value of bAddToMRU the path is added, or not added, to the MRU list maintained by the application. Note that some documents are not associated with a disk file. Call this function only if you are overriding the default implementation for opening and saving files used by the framework.

CDocument::SetTitle

Call this function to specify the document's title (the string displayed in the title bar of a frame window).

virtual void SetTitle(LPCTSTR lpszTitle);

Parameters

lpszTitle
Points to the string to be used as the document's title.

Remarks

Calling this function updates the titles of all frame windows that display the document.

CDocument::UpdateAllViews

Call this function after the document has been modified.

void UpdateAllViews(
    CView* pSender,  
    LPARAM lHint = 0L,  
    CObject* pHint = NULL);

Parameters

pSender
Points to the view that modified the document, or NULL if all views are to be updated.

lHint
Contains information about the modification.

pHint
Points to an object storing information about the modification.

Remarks

You should call this function after you call the SetModifiedFlag member function. This function informs each view attached to the document, except for the view specified by pSender, that the document has been modified. You typically call this function from your view class after the user has changed the document through a view.

This function calls the CView::OnUpdate member function for each of the document's views except the sending view, passing pHint and lHint. Use these parameters to pass information to the views about the modifications made to the document. You can encode information using lHint and/or you can define a CObject-derived class to store information about the modifications and pass an object of that class using pHint. Override the CView::OnUpdate member function in your CView-derived class to optimize the updating of the view's display based on the information passed.

Example

void CExampleDoc::OnUpdateAllViews()
{
   UpdateAllViews(NULL);
}

Share via

CDocument Class

Syntax

Members

Public Constructors

Public Methods

Protected Methods

Public Data Members

Remarks

Inheritance Hierarchy

Requirements

CDocument::AddView

Parameters

Remarks

Example

CDocument::BeginReadChunks

Remarks

CDocument::CanCloseFrame

Parameters

Return Value

Remarks

CDocument::CDocument

Remarks

CDocument::ClearChunkList

Remarks

CDocument::ClearPathName

Remarks

CDocument::DeleteContents

Remarks

Example

CDocument::FindChunk

Parameters

Return Value

Remarks

CDocument::GetAdapter

Return Value

Remarks

CDocument::GetDocTemplate

Return Value

Example

CDocument::GetFile

Parameters

Return Value

CDocument::GetFirstViewPosition

Return Value

Example

CDocument::GetNextView

Parameters

Return Value

Remarks

Example

CDocument::GetPathName

Return Value

CDocument::GetThumbnail

Parameters

Return Value

Remarks

CDocument::GetTitle

Return Value

CDocument::InitializeSearchContent

Remarks

CDocument::IsModified

Return Value

CDocument::IsSearchAndOrganizeHandler

Return Value

Remarks

CDocument::LoadDocumentFromStream

Parameters

Return Value

Remarks

CDocument::m_bGetThumbnailMode

Remarks

CDocument::m_bPreviewHandlerMode

Remarks

CDocument::m_bSearchMode

Remarks

CDocument::m_clrRichPreviewBackColor

Remarks

CDocument::m_clrRichPreviewTextColor

Remarks