CDocument 类

提供用户定义文档类的基本功能。

语法

class CDocument : public CCmdTarget

成员

公共构造函数

名称	描述
CDocument::CDocument	构造 CDocument 对象。

公共方法

名称	描述
CDocument::AddView	将视图附加到文档。
CDocument::BeginReadChunks	初始化区块读取。
CDocument::CanCloseFrame	高级可重写；在关闭查看此文档的框架窗口之前调用。
CDocument::ClearChunkList	清除区块列表。
CDocument::ClearPathName	清除文档对象的路径。
CDocument::DeleteContents	调用以执行文档清理。
CDocument::FindChunk	查找具有指定 GUID 的区块。
CDocument::GetAdapter	返回一个指针，指向实现 IDocument 接口的对象。
CDocument::GetDocTemplate	返回一个指针，指向描述文档类型的文档模板。
CDocument::GetFile	返回指向所需 CFile 对象的指针。
CDocument::GetFirstViewPosition	返回视图列表中第一个视图的位置；用于开始迭代。
CDocument::GetNextView	循环访问与文档关联的视图列表。
CDocument::GetPathName	返回文档数据文件的路径。
CDocument::GetThumbnail	调用以创建位图，由缩略图提供程序用于显示缩略图。
CDocument::GetTitle	返回文档的标题。
CDocument::InitializeSearchContent	调用以初始化搜索处理程序的搜索内容。
CDocument::IsModified	指示文档自上次保存后是否进行过修改。
CDocument::IsSearchAndOrganizeHandler	指示是否为“搜索和组织”处理程序创建了此 CDocument 对象实例。
CDocument::LoadDocumentFromStream	调用以从流加载文档数据。
CDocument::OnBeforeRichPreviewFontChanged	在更改 Rich Preview 字体之前调用。
CDocument::OnChangedViewList	在将视图添加到文档或从文档移除视图之后调用。
CDocument::OnCloseDocument	调用以关闭文档。
CDocument::OnCreatePreviewFrame	当框架需要为 Rich Preview 创建预览框架时调用。
CDocument::OnDocumentEvent	由框架调用以响应文档事件。
CDocument::OnDrawThumbnail	在派生类中重写此方法以绘制缩略图的内容。
CDocument::OnLoadDocumentFromStream	当框架需要从流加载文档数据时调用。
CDocument::OnNewDocument	调用以创建新文档。
CDocument::OnOpenDocument	调用以打开现有文档。
CDocument::OnPreviewHandlerQueryFocus	指示预览处理程序通过调用 GetFocus 函数返回 HWND。
CDocument::OnPreviewHandlerTranslateAccelerator	指示预览处理程序处理从正在运行预览处理程序的进程的消息泵传递的击键。
CDocument::OnRichPreviewBackColorChanged	当 Rich Preview 背景色更改时调用。
CDocument::OnRichPreviewFontChanged	当 Rich Preview 字体更改时调用。
CDocument::OnRichPreviewSiteChanged	当 Rich Preview 站点更改时调用。
CDocument::OnRichPreviewTextColorChanged	当 Rich Preview 文本颜色更改时调用。
CDocument::OnSaveDocument	调用以将文档保存到磁盘。
CDocument::OnUnloadHandler	卸载预览处理程序时由框架调用。
CDocument::PreCloseFrame	在框架窗口关闭之前调用。
CDocument::ReadNextChunkValue	读取下一个区块值。
CDocument::ReleaseFile	释放文件以使其可供其他应用程序使用。
CDocument::RemoveChunk	移除具有指定 GUID 的区块。
CDocument::RemoveView	从文档分离视图。
CDocument::ReportSaveLoadException	高级可重写；当由于异常而无法完成打开或保存操作时调用。
CDocument::SaveModified	高级可重写；调用以询问用户是否应保存文档。
CDocument::SetChunkValue	设置区块值。
CDocument::SetModifiedFlag	设置一个标志，指示自上次保存文档以来已修改文档。
CDocument::SetPathName	设置文档使用的数据文件的路径。
CDocument::SetTitle	设置文档的标题。
CDocument::UpdateAllViews	通知所有视图文档已修改。

受保护方法

名称	描述
CDocument::OnFileSendMail	发送附加了文档的邮件。
CDocument::OnUpdateFileSendMail	如果存在邮件支持，则启用“发送邮件”命令。

公共数据成员

“属性”	描述
CDocument::m_bGetThumbnailMode	指定 CDocument 对象是由 dllhost 为缩略图创建的。 应在 CView::OnDraw 中检查。
CDocument::m_bPreviewHandlerMode	指定 CDocument 对象是由 prevhost 为 Rich Preview 创建的。 应在 CView::OnDraw 中检查。
CDocument::m_bSearchMode	指定 CDocument 对象是由索引器或其他搜索应用程序创建的。
CDocument::m_clrRichPreviewBackColor	指定 Rich Preview 窗口的背景色。 此颜色由主机设置。
CDocument::m_clrRichPreviewTextColor	指定 Rich Preview 窗口的前景色。 此颜色由主机设置。
CDocument::m_lfRichPreviewFont	指定 Rich Preview 窗口的文本字体。 此字体信息由主机设置。

注解

文档表示用户通常使用“打开文件”命令打开并使用“保存文件”命令保存的数据单元。

CDocument 支持标准操作，例如创建、加载和保存文档。 框架使用 CDocument 定义的接口来操作文档。

应用程序可以支持多种文档类型；例如，应用程序可能同时支持电子表格和文本文档。 每种类型的文档都有一个关联的文档模板；文档模板指定用于该类型文档的资源（例如，菜单、图标或快捷键表）。 每个文档都包含一个指向其关联 CDocTemplate 对象的指针。

用户通过与文档关联的 CView 对象与其交互。 视图在框架窗口中呈现文档的图像，并将用户输入解释为对文档的操作。 一个文档可以有多个与之关联的视图。 当用户在文档上打开窗口时，框架会创建一个视图并将其附加到文档。 文档模板指定使用何种类型的视图和框架窗口来显示每种类型的文档。

文档是框架标准命令路由的一部分，因此可以从标准用户界面组件（例如“保存文件”菜单项）接收命令。 文档接收活动视图转发的命令。 如果文档不处理给定命令，它会将命令转发到管理它的文档模板。

当文档的数据被修改时，它的每个视图都必须反映这些修改。 CDocument 提供 UpdateAllViews 成员函数来通知视图此类更改，因此视图可以根据需要重新绘制自己。 框架还会提示用户在关闭已修改的文件之前对其进行保存。

若要在典型应用程序中实现文档，必须执行以下操作：

• 对于每种类型的文档，从 CDocument 派生一个类。

• 添加成员变量来存储每个文档的数据。

• 实现成员函数来读取和修改文档数据。 文档的视图是这些成员函数最重要的用户。

• 在文档类中重写 CObject::Serialize 成员函数，以在磁盘中写入和读取文档数据。

如果存在邮件支持 (MAPI)，则 CDocument 支持通过邮件发送文档。 请参阅文章 MAPI 和 MFC 中的 MAPI 支持。

有关 CDocument 的详细信息，请参阅序列化、文档/视图体系结构主题和文档/视图创建。

继承层次结构

CObject

CCmdTarget

CDocument

要求

标头：afxwin.h

CDocument::AddView

调用此函数以将视图附加到文档。

void AddView(CView* pView);

参数

pView
指向要添加的视图。

备注

此函数将指定视图添加到与文档关联的视图列表；它还将视图的文档指针设置为此文档。 框架会在将新创建的视图对象附加到文档时调用此函数；这发生在响应“新建文件”、“打开文件”或“新建窗口”命令或拆分拆分器窗口时。

仅当手动创建和附加视图时才调用此函数。 通常，通过定义 CDocTemplate 对象来关联文档类、视图类和框架窗口类，让框架连接文档和视图。

示例

// 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

初始化区块读取。

virtual void BeginReadChunks ();

注解

CDocument::CanCloseFrame

在显示文档的框架窗口关闭之前由框架调用。

virtual BOOL CanCloseFrame(CFrameWnd* pFrame);

参数

pFrame
指向附加到文档的视图的框架窗口。

返回值

如果关闭框架窗口是安全的，则为非零；否则为 0。

备注

默认实现将检查是否有其他显示文档的框架窗口。 如果指定的框架窗口是最后一个显示文档的框架窗口，该函数会提示用户在修改后保存文档。 如果要在框架窗口关闭时执行特殊处理，请重写此函数。 这是一个高级可重写函数。

CDocument::CDocument

构造 CDocument 对象。

CDocument();

备注

框架将为你处理文档创建。 重写 OnNewDocument 成员函数以按文档执行初始化；这在单文档界面 (SDI) 应用程序中尤为重要。

CDocument::ClearChunkList

清除区块列表。

virtual void ClearChunkList ();

备注

CDocument::ClearPathName

清除文档对象的路径。

virtual void ClearPathName();

备注

从 CDocument 对象清除路径会导致应用程序在下次保存文档时提示用户。 这使得“保存” 命令的行为类似于“另存为”命令。

CDocument::DeleteContents

由框架调用以删除文档数据，而不销毁 CDocument 对象本身。

virtual void DeleteContents();

备注

在将要销毁文档之前调用它。 还可以调用它来确保文档在重用之前为空。 这对于仅使用一个文档的 SDI 应用程序尤其重要；每当用户创建或打开另一个文档时，就会重用该文档。 调用此函数以实现“编辑”->“全部清除”或类似命令，该命令将删除所有文档数据。 此函数的默认实现不执行任何操作。 重写此函数以删除文档中的数据。

示例

// 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

查找具有指定 GUID 的区块。

virtual POSITION FindChunk(
    REFCLSID guid,
    DWORD pid);

参数

guid
指定要查找的区块的 GUID。

pid
指定要查找的区块的 PID。

返回值

如果成功，则为内部区块列表中的位置。 否则为 NULL。

备注

CDocument::GetAdapter

返回一个指针，指向实现 IDocument 接口的对象。

virtual ATL::IDocument* GetAdapter();

返回值

一个指针，指向实现 IDocument 接口的对象。

注解

CDocument::GetDocTemplate

调用此函数以获取指向此文档类型的文档模板的指针。

CDocTemplate* GetDocTemplate() const;

返回值

指向此文档类型的文档模板的指针；如果文档不由文档模板管理，则为 NULL。

示例

// 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

调用此成员函数以获取指向 CFile 对象的指针。

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

参数

lpszFileName
一个字符串，它是所需文件的路径。 路径可以是相对路径，也可以是绝对路径。

pError
指向现有文件异常对象的指针，该对象指示操作的完成状态。

nOpenFlags
共享和访问模式。 指定打开文件时要执行的操作。 可以使用按位 OR (|) 运算符组合 CFile 构造函数 CFile::CFile 中列出的选项。 一个访问权限和一个共享选项是必需的；modeCreate 和 modeNoInherit 模式是可选的。

返回值

一个指向 CFile 对象的指针。

CDocument::GetFirstViewPosition

调用此函数以获取与文档关联的视图列表中第一个视图的位置。

virtual POSITION GetFirstViewPosition() const;

返回值

可用于与 GetNextView 成员函数进行迭代的 POSITION 值。

示例

//To get the first view in the list of views:
//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

调用此函数以循环访问文档的所有视图。

virtual CView* GetNextView(POSITION& rPosition) const;

参数

rPosition
对先前调用 GetNextView 或 GetFirstViewPosition 成员函数返回的 POSITION 值的引用。 此值不得为 NULL。

返回值

指向由 rPosition 标识的视图的指针。

备注

该函数返回由 rPosition 标识的视图，然后将 rPosition 设置为列表中下一个视图的 POSITION 值。 如果检索到的视图是列表中的最后一个，则 rPosition 设置为 NULL。

示例

//To get the first view in the list of views:
//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

调用此函数以获取文档磁盘文件的完全限定路径。

const CString& GetPathName() const;

返回值

文档的完全限定路径。 如果文档尚未保存或没有与之关联的磁盘文件，则此字符串为空。

CDocument::GetThumbnail

创建由缩略图提供程序用于显示缩略图的位图。

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

参数

cx
指定位图的宽度和高度。

phbmp
当函数成功返回时，包含位图的句柄。

pdwAlpha
当函数成功返回时，包含一个指定 alpha 通道值的 DWORD。

返回值

如果成功创建了缩略图的位图，则返回 TRUE；否则返回 FALSE。

注解

CDocument::GetTitle

调用此函数以获取文档的标题，该标题通常派生自文档的文件名。

const CString& GetTitle() const;

返回值

文档的标题。

CDocument::InitializeSearchContent

调用以初始化搜索处理程序的搜索内容。

virtual void InitializeSearchContent ();

备注

在派生类中重写此方法以初始化搜索内容。 内容应是一个字符串，其各部分由“;”分隔。 例如，“点; 矩形; OLE 项”。

CDocument::IsModified

调用此函数以确定文档自上次保存后是否进行过修改。

virtual BOOL IsModified();

返回值

如果文档自上次保存后进行过修改，则为非零；否则为 0。

CDocument::IsSearchAndOrganizeHandler

指示是否是为“搜索和组织”处理程序创建了此 CDocument 实例。

BOOL IsSearchAndOrganizeHandler() const;

返回值

如果为“搜索和组织”处理程序创建了此 CDocument 实例，则返回 TRUE。

注解

目前，此函数仅针对进程外服务器中实现的 Rich Preview 处理程序返回 TRUE。 可以在应用程序级别设置适当的标志（m_bPreviewHandlerMode、m_bSearchMode、m_bGetThumbnailMode），使此函数返回 TRUE。

CDocument::LoadDocumentFromStream

调用以从流加载文档数据。

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

参数

pStream
指向流的指针。 此流由 Shell 提供。

dwGrfMode
流的访问模式。

返回值

如果加载操作成功，则返回 S_OK；否则返回带有错误代码的 HRESULT。

注解

可以在派生类中重写此方法，以自定义如何从流加载数据。

CDocument::m_bGetThumbnailMode

指定 CDocument 对象是由 dllhost 为缩略图创建的。 应在 CView::OnDraw 中检查。

BOOL m_bGetThumbnailMode;

备注

TRUE 指示文档是由 dllhost 为缩略图创建的。

CDocument::m_bPreviewHandlerMode

指定 CDocument 对象是由 prevhost 为 Rich Preview 创建的。 应在 CView::OnDraw 中检查。

BOOL m_bPreviewHandlerMode;

备注

TRUE 指示文档是由 prevhost 为 Rich Preview 创建的。

CDocument::m_bSearchMode

指定 CDocument 对象是由索引器或其他搜索应用程序创建的。

BOOL m_bSearchMode;

注解

TRUE 指示文档是由索引器或其他搜索应用程序创建的。

CDocument::m_clrRichPreviewBackColor

指定 Rich Preview 窗口的背景色。 此颜色由主机设置。

COLORREF m_clrRichPreviewBackColor;

备注

CDocument::m_clrRichPreviewTextColor

指定 Rich Preview 窗口的前景色。 此颜色由主机设置。

COLORREF m_clrRichPreviewTextColor;

备注

CDocument::m_lfRichPreviewFont

指定 Rich Preview 窗口的文本字体。 此字体信息由主机设置。

CFont m_lfRichPreviewFont;

备注

CDocument::OnBeforeRichPreviewFontChanged

在更改 Rich Preview 字体之前调用。

virtual void OnBeforeRichPreviewFontChanged();

注解

CDocument::OnChangedViewList

在将视图添加到文档或从文档移除视图后，由框架调用。

virtual void OnChangedViewList();

备注

此函数的默认实现将检查是否正在移除最后一个视图，如果是，则删除文档。 如果要在框架添加或移除视图时执行特殊处理，请重写此函数。 例如，如果希望文档在没有附加视图的情况下仍保持打开状态，请重写此函数。

CDocument::OnCloseDocument

关闭文档时由框架调用，通常作为“关闭文件”命令的一部分。

virtual void OnCloseDocument();

备注

此函数的默认实现会销毁所有用于查看文档的框架，关闭视图，清理文档内容，然后调用 DeleteContents 成员函数删除文档数据。

如果要在框架关闭文档时执行特殊的清理处理，请重写此函数。 例如，如果文档代表数据库中的一条记录，你可能希望重写此函数以关闭数据库。 应从重写中调用此函数的基类版本。

CDocument::OnCreatePreviewFrame

当框架需要为 Rich Preview 创建预览框架时调用。

virtual BOOL OnCreatePreviewFrame();

返回值

如果成功创建框架，则返回 TRUE；否则返回 FALSE。

备注

CDocument::OnDocumentEvent

由框架调用以响应文档事件。

virtual void OnDocumentEvent(DocumentEvent deEvent);

参数

deEvent
[in] 描述事件类型的枚举数据类型。

备注

文档事件可能会影响多个类。 此方法负责处理影响 CDocument 类以外的类的文档事件。 目前，唯一必须响应文档事件的类是 CDataRecoveryHandler 类。 CDocument 类有其他可重写的方法负责处理对 CDocument 的影响。

下表列出了 deEvent 的可能值及其对应的事件。

值	相应事件
onAfterNewDocument	创建了一个新文档。
onAfterOpenDocument	打开了一个新文档。
onAfterSaveDocument	文档已保存。
onAfterCloseDocument	文档已关闭。

CDocument::OnDrawThumbnail

在派生类中重写此方法以绘制缩略图。

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

参数

dc
对设备上下文的引用。

lprcBounds
指定应绘制缩略图的区域的边框。

备注

CDocument::OnFileSendMail

通过常驻邮件主机（如果有）发送包含文档作为附件的邮件。

void OnFileSendMail();

备注

OnFileSendMail 调用 OnSaveDocument 以将无标题和修改过的文档序列化（保存）到临时文件中，然后通过电子邮件发送该文件。 如果文档未修改过，则不需要临时文件；将发送原件。 OnFileSendMail 将加载 MAPI32.DLL（如果尚未加载）。

COleDocument 的 OnFileSendMail 的特殊实现可以正确处理复合文件。

如果存在邮件支持 (MAPI)，则 CDocument 支持通过邮件发送文档。 请参阅文章 MAPI 主题和 MFC 中的 MAPI 支持。

CDocument::OnLoadDocumentFromStream

当框架需要从流加载文档数据时调用。

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

参数

pStream
指向传入流的指针。

grfMode
流的访问模式。

返回值

如果加载成功，则为 S_OK；否则为错误代码。

备注

CDocument::OnNewDocument

由框架作为“新建文件”命令的一部分调用。

virtual BOOL OnNewDocument();

返回值

如果文档已成功初始化，则为非零；否则为 0。

备注

此函数的默认实现将调用 DeleteContents 成员函数以确保文档为空，然后将新文档标记为干净。 重写此函数以初始化新文档的数据结构。 应从重写中调用此函数的基类版本。

如果用户在 SDI 应用程序中选择“新建文件”命令，框架将使用此函数重新初始化现有文档，而不是创建新文档。 如果用户在多文档界面 (MDI) 应用程序中选择“新建文件”，框架每次都会创建一个新文档，然后调用此函数对其进行初始化。 你必须将初始化代码放在此函数中，而不是放在构造函数中，以便“新建文件”命令在 SDI 应用程序中生效。

请注意，有时会调用 OnNewDocument 两次。 当文档作为 ActiveX 文档服务器嵌入时会发生这种情况。 该函数第一次由 CreateInstance 方法（由 COleObjectFactory 派生类公开）调用，第二次由 InitNew 方法（由 COleServerDoc 派生类公开）调用。

示例

以下示例演示了初始化文档对象的替代方法。

// 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

由框架作为“打开文件”命令的一部分调用。

virtual BOOL OnOpenDocument(LPCTSTR lpszPathName);

参数

lpszPathName
指向要打开的文档的路径。

返回值

如果已成功加载文档，则为非零；否则为 0。

注解

此函数的默认实现会打开指定文件，调用 DeleteContents 成员函数以确保文档为空，调用 CObject::Serialize 以读取文件内容，然后将文档标记为干净。 如果要使用存档机制或文件机制以外的其他机制，请重写此函数。 例如，可以编写一个应用程序，其中文档表示数据库中的记录，而不是单独的文件。

如果用户在 SDI 应用程序中选择“打开文件”命令，框架将使用此函数重新初始化现有 CDocument 对象，而不是创建新对象。 如果用户在 MDI 应用程序中选择“打开文件”，则框架每次都会构造一个新的 CDocument 对象，然后调用此函数对其进行初始化。 你必须将初始化代码放在此函数中，而不是放在构造函数中，以便“打开文件”命令在 SDI 应用程序中生效。

示例

以下示例演示了初始化文档对象的替代方法。

// 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

指示预览处理程序返回通过调用 GetFocus 函数检索到的 HWND。

virtual HRESULT OnPreviewHandlerQueryFocus(HWND* phwnd);

参数

phwnd
[out] 此方法返回时，包含一个指针，指向通过从预览处理程序的前台线程调用 GetFocus 函数返回的 HWND。

返回值

如果成功，则返回 S_OK；否则返回错误值。

备注

CDocument::OnPreviewHandlerTranslateAccelerator

指示预览处理程序处理从正在运行预览处理程序的进程的消息泵传递的击键。

virtual HRESULT OnPreviewHandlerTranslateAccelerator(MSG* pmsg);

参数

pmsg
[in] 指向窗口消息的指针。

返回值

如果预览处理程序可以处理击键消息，则处理程序对其进行处理并返回 S_OK。 如果预览处理程序无法处理击键消息，它会通过 IPreviewHandlerFrame::TranslateAccelerator 将其提供给主机。 如果主机处理该消息，则此方法返回 S_OK。 如果主机不处理该消息，则此方法返回 S_FALSE。

注解

CDocument::OnRichPreviewBackColorChanged

当 Rich Preview 背景色更改时调用。

virtual void OnRichPreviewBackColorChanged();

注解

CDocument::OnRichPreviewFontChanged

当 Rich Preview 字体更改时调用。

virtual void OnRichPreviewFontChanged();

备注

CDocument::OnRichPreviewSiteChanged

当 Rich Preview 站点更改时调用。

virtual void OnRichPreviewSiteChanged();

备注

CDocument::OnRichPreviewTextColorChanged

当 Rich Preview 文本颜色更改时调用。

virtual void OnRichPreviewTextColorChanged();

注解

CDocument::OnSaveDocument

由框架作为“保存文件”或“文件另存为”命令的一部分调用。

virtual BOOL OnSaveDocument(LPCTSTR lpszPathName);

参数

lpszPathName
指向文件应保存到的完全限定路径。

返回值

如果已成功保存文档，则为非零；否则为 0。

备注

此函数的默认实现会打开指定文件，调用 CObject::Serialize 以将文档数据写入文件，然后将文档标记为干净。 如果要在框架保存文档时执行特殊处理，请重写此函数。 例如，可以编写一个应用程序，其中文档表示数据库中的记录，而不是单独的文件。

CDocument::OnUnloadHandler

卸载预览处理程序时由框架调用。

virtual void OnUnloadHandler();

注解

CDocument::OnUpdateFileSendMail

如果存在邮件支持 (MAPI)，则启用 ID_FILE_SEND_MAIL 命令。

void OnUpdateFileSendMail(CCmdUI* pCmdUI);

参数

pCmdUI
一个指针，指向与 ID_FILE_SEND_MAIL 命令关联的 CCmdUI 对象。

备注

否则，该函数会从菜单中移除 ID_FILE_SEND_MAIL 命令，包括菜单项上方或下方（视情况而定）的分隔符。 如果路径中存在 MAPI32.DLL，并且在 WIN.INI 文件的 [Mail] 部分中，MAPI=1，则启用 MAPI。 大多数应用程序将此命令放在“文件”菜单上。

如果存在邮件支持 (MAPI)，则 CDocument 支持通过邮件发送文档。 请参阅文章 MAPI 主题和 MFC 中的 MAPI 支持。

CDocument::PreCloseFrame

此成员函数在框架窗口被销毁之前由框架调用。

virtual void PreCloseFrame(CFrameWnd* pFrame);

参数

pFrame
一个指针，指向保存关联 CDocument 对象的 CFrameWnd。

备注

可以重写此函数以提供自定义清理，但一定要调用基类。

PreCloseFrame 的默认值在 CDocument 中没有任何作用。 CDocument 派生类 COleDocument 和 CRichEditDoc 使用此成员函数。

CDocument::ReadNextChunkValue

读取下一个区块值。

virtual BOOL ReadNextChunkValue(IFilterChunkValue** ppValue);

参数

ppValue
[out] 当函数返回时，ppValue 包含读取的值。

返回值

如果成功，则不为 0；否则为 0。

备注

CDocument::ReleaseFile

框架调用此成员函数以释放文件，使其可供其他应用程序使用。

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

参数

pFile
指向要释放的 CFile 对象的指针。

bAbort
指定是使用 CFile::Close 还是 CFile::Abort 释放文件。 如果要使用 CFile::Close 释放文件，则为 FALSE；如果要使用 CFile::Abort 释放文件，则为 TRUE。

备注

如果 bAbort 为 TRUE，ReleaseFile 将调用 CFile::Abort 并释放文件。 CFile::Abort 不会引发异常。

如果 bAbort 为 FALSE，ReleaseFile 将调用 CFile::Close 并释放文件。

重写此成员函数，以要求用户在释放文件之前执行操作。

CDocument::RemoveChunk

移除具有指定 GUID 的区块。

virtual void RemoveChunk(
    REFCLSID guid,
    DWORD pid);

参数

Guid
指定要移除的区块的 GUID。

Pid
指定要移除的区块的 PID。

备注

CDocument::RemoveView

调用此函数以从文档分离视图。

void RemoveView(CView* pView);

参数

pView
指向要移除的视图。

注解

此函数从与文档关联的视图列表中移除指定视图；它还将视图的文档指针设置为 NULL。 当框架窗口关闭或拆分器窗口的窗格关闭时，框架会调用此函数。

仅当手动分离视图时才调用此函数。 通常，通过定义 CDocTemplate 对象来关联文档类、视图类和框架窗口类，让框架分离文档和视图。

有关示例实现，请参阅 AddView 中的示例。

CDocument::ReportSaveLoadException

如果在保存或加载文档时引发异常（通常是 CFileException 或 CArchiveException），则调用此函数。

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

参数

lpszPathName
指向正在保存或加载的文档的名称。

e
指向引发的异常。 可为 NULL。

bSaving
一个标志，指示正在进行的操作；如果正在保存文档，则为非零；如果正在加载文档，则为 0。

nIDPDefault
如果函数未指定更具体的错误消息，则为要显示的错误消息的标识符。

注解

默认实现将检查异常对象，并查找专门描述原因的错误消息。 如果未找到特定消息或 e 为 NULL，则使用 nIDPDefault 参数指定的常规消息。 该函数随后会显示一个包含错误消息的消息框。 如果要提供额外的自定义失败消息，请重写此函数。 这是一个高级可重写函数。

CDocument::SaveModified

在关闭已修改的文档之前由框架调用。

virtual BOOL SaveModified();

返回值

如果可以安全地继续关闭文档，则为非零；如果不应关闭文档，则为 0。

备注

此函数的默认实现将显示一个消息框，询问用户是否保存对文档的更改（如果已更改）。 如果程序需要不同的提示过程，请重写此函数。 这是一个高级可重写函数。

CDocument::SetChunkValue

设置区块值。

virtual BOOL SetChunkValue (IFilterChunkValue* pValue);

参数

pValue
指定要设置的区块值。

返回值

如果成功，则不为 0；否则为 0。

注解

CDocument::SetModifiedFlag

对文档进行任何修改后调用此函数。

virtual void SetModifiedFlag(BOOL bModified = TRUE);

参数

bModified
指示文档是否已修改的标志。

备注

通过一致地调用此函数，可以确保框架在关闭文档之前提示用户保存更改。 通常，应使用 bModified 参数的默认值 TRUE。 若要将文档标记为干净（未修改），请使用值 FALSE 调用此函数。

CDocument::SetPathName

调用此函数以指定文档磁盘文件的完全限定路径。

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

参数

lpszPathName
指向要用作文档路径的字符串。

bAddToMRU
确定是否将文件名添加到最近使用的 (MRU) 文件列表。 如果为 TRUE，则添加文件名；如果为 FALSE，则不添加。

注解

根据 bAddToMRU 的值，将路径添加或不添加到应用程序维护的 MRU 列表。 请注意，某些文档与磁盘文件无关。 仅当重写框架用来打开和保存文件的默认实现时，才调用此函数。

CDocument::SetTitle

调用此函数以指定文档的标题（在框架窗口的标题栏中显示的字符串）。

virtual void SetTitle(LPCTSTR lpszTitle);

参数

lpszTitle
指向要用作文档标题的字符串。

备注

调用此函数会更新显示文档的所有框架窗口的标题。

CDocument::UpdateAllViews

修改文档后调用此函数。

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

参数

pSender
指向修改文档的视图，如果要更新所有视图，则为 NULL。

lHint
包含有关修改的信息。

pHint
指向存储有关修改的信息的对象。

注解

应在调用 SetModifiedFlag 成员函数之后调用此函数。 此函数通知附加到文档的每个视图（pSender 指定的视图除外），文档已被修改。 在用户通过视图更改文档后，你通常会从视图类调用此函数。

此函数为每个文档视图（发送视图除外）调用 CView::OnUpdate 成员函数，并传递 pHint 和 lHint。 可使用这些参数将对文档所做修改的相关信息传递给视图。 可以使用 lHint 对信息进行编码，并且/或者可以定义一个 CObject 派生类来存储有关修改的信息并使用 pHint 传递该类的对象。 在 CView 派生类中重写 CView::OnUpdate 成员函数，以根据传递的信息优化视图显示的更新。

示例

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

另请参阅

MFC 示例 MDIDOCVW
MFC 示例 SNAPVW
MFC 示例 NPP
CCmdTarget 类
层次结构图
CCmdTarget 类
CView 类
CDocTemplate 类