`CDocTemplate` 类

项目
04/03/2023

定义文档模板基本功能的抽象基类。

语法

class CDocTemplate : public CCmdTarget

成员

受保护构造函数

名称	描述
`CDocTemplate::CDocTemplate`	构造 `CDocTemplate` 对象。

公共方法

名称	描述
`CDocTemplate::AddDocument`	将文档添加到模板。
`CDocTemplate::CloseAllDocuments`	关闭与此模板关联的所有文档。
`CDocTemplate::CreateNewDocument`	创建新文档。
`CDocTemplate::CreateNewFrame`	创建包含文档和视图的新框架窗口。
`CDocTemplate::CreateOleFrame`	创建已启用 OLE 的框架窗口。
`CDocTemplate::CreatePreviewFrame`	创建用于丰富预览的子框架。
`CDocTemplate::GetDocString`	检索与文档类型关联的字符串。
`CDocTemplate::GetFirstDocPosition`	检索与此模板关联的第一个文档的位置。
`CDocTemplate::GetNextDoc`	检索文档和下一个文档的位置。
`CDocTemplate::InitialUpdateFrame`	初始化框架窗口，并（可选）使其可见。
`CDocTemplate::LoadTemplate`	加载给定 `CDocTemplate` 或派生类的资源。
`CDocTemplate::MatchDocType`	确定文档类型与此模板之间匹配的置信度。
`CDocTemplate::OpenDocumentFile`	打开路径名指定的文件。
`CDocTemplate::RemoveDocument`	从模板中删除文档。
`CDocTemplate::SaveAllModified`	保存与此模板关联的所有文档，这些文档已被修改。
`CDocTemplate::SetContainerInfo`	在编辑就地 OLE 项时确定 OLE 容器的资源。
`CDocTemplate::SetDefaultTitle`	在文档窗口的标题栏中显示默认标题。
`CDocTemplate::SetPreviewInfo`	设置进程外预览控件。
`CDocTemplate::SetServerInfo`	确定在就地嵌入或编辑服务器文档时的资源和类。

备注

你通常在实现应用程序的 InitInstance 函数时创建一个或多个文档模板。文档模板定义了三种类之间的关系：

派生自 CDocument 的文档类。
视图类，显示上面列出的文档类中的数据。可以从 CView、CScrollView、CFormView 或 CEditView 派生此类。（你也可以直接使用 CEditView。）
包含视图的框架窗口类。对于单文档界面 (SDI) 应用程序，从 CFrameWnd 派生此类。对于多文档界面 (MDI) 应用程序，从 CMDIChildWnd 派生此类。如果不需要自定义框架窗口的行为，可以直接使用 CFrameWnd 或 CMDIChildWnd 而无需派生自己的类。

应用程序对于它支持的每种类型的文档都有一个文档模板。例如，如果应用程序同时支持电子表格和文本文档，则该应用程序有两个文档模板对象。每个文档模板负责创建和管理其类型的所有文档。

文档模板存储指向文档、视图和框架窗口类的 CRuntimeClass 对象的指针。这些 CRuntimeClass 对象是在构建文档模板时指定的。

文档模板包含与文档类型一起使用的资源的 ID（例如菜单、图标或快捷键表资源）。文档模板还具有包含有关其文档类型的附加信息的字符串。其中包括文档类型的名称（例如，“工作表”）和文件扩展名（例如，“.xls”）。（可选）它可以包含应用程序的用户界面、Windows 文件管理器以及对象链接与嵌入 (OLE) 支持使用的其他字符串。

如果应用程序是 OLE 容器和/或服务器，则文档模板还会定义在就地激活期间使用的菜单的 ID。如果应用程序是 OLE 服务器，则文档模板会定义就地激活期间使用的工具栏和菜单的 ID。可以通过调用 SetContainerInfo 和 SetServerInfo 来指定这些额外的 OLE 资源。

因为 CDocTemplate 是抽象类，所以不能直接使用该类。典型应用程序使用 Microsoft 基础类库提供的两个 CDocTemplate 派生类之一：实现 SDI 的 CSingleDocTemplate 和实现 MDI 的 CMultiDocTemplate。有关使用文档模板的详细信息，请参阅这些类。

如果应用程序需要与 SDI 或 MDI 完全不同的用户界面范例，你可以从 CDocTemplate 派生自己的类。

有关 CDocTemplate 的详细信息，请参阅文档模板和文档/视图创建过程。

继承层次结构

CObject

CCmdTarget

CDocTemplate

要求

标头：afxwin.h

`CDocTemplate::AddDocument`

使用此函数将文档添加到模板。

virtual void AddDocument(CDocument* pDoc);

参数

pDoc
指向要添加的文档的指针。

备注

派生类 CMultiDocTemplate 和 CSingleDocTemplate 会重写此函数。如果你从 CDocTemplate 派生自己的文档模板类，则派生类必须重写此函数。

`CDocTemplate::CDocTemplate`

构造 CDocTemplate 对象。

CDocTemplate (
    UINT nIDResource,
    CRuntimeClass* pDocClass,
    CRuntimeClass* pFrameClass,
    CRuntimeClass* pViewClass);

参数

nIDResource
指定与文档类型一起使用的资源的 ID。这可能包括菜单、图标、快捷键表和字符串资源。

字符串资源最多包含由 \n 字符分隔的七个子字符串（如果不包含子字符串，则需要 \n 字符作为占位符；但是，结尾的 \n 字符不是必需的）；这些子字符串描述文档类型。有关子字符串的信息，请参阅 GetDocString。此字符串资源可在应用程序的资源文件中找到。例如：

// MYCALC.RC
STRINGTABLE PRELOAD DISCARDABLE
BEGIN
  IDR_SHEETTYPE "\nSheet\nWorksheet\nWorksheets (*.myc)\n.myc\n MyCalcSheet\nMyCalc Worksheet"
END

请注意，此字符串以 \n 字符开头；这是因为第一个子字符串不用于 MDI 应用程序，因此不包括在内。可以使用字符串编辑器编辑此字符串；整个字符串在字符串编辑器中显示为单个条目，而不是七个单独的条目。

pDocClass
指向文档类的 CRuntimeClass 对象。此类是你定义的用于表示文档的 CDocument 派生类。

pFrameClass
指向框架窗口类的 CRuntimeClass 对象。此类可以是 CFrameWnd 派生类，或者如果你需要主框架窗口的默认行为，此类也可以是 CFrameWnd 本身。

pViewClass
指向视图类的 CRuntimeClass 对象。此类是你定义用于显示文档的CView 派生类。

注解

使用此成员函数构造 CDocTemplate 对象。动态分配一个 CDocTemplate 对象并将其从应用程序类的 InitInstance 成员函数传递给 CWinApp::AddDocTemplate。

`CDocTemplate::CloseAllDocuments`

调用此成员函数以关闭所有打开的文档。

virtual void CloseAllDocuments(BOOL bEndSession);

参数

bEndSession
未使用。

注解

此成员函数通常用作文件退出命令的一部分。此函数的默认实现调用 CDocument::DeleteContents 成员函数来删除文档的数据，然后关闭附加到文档的所有视图的框架窗口。

如果想要求用户在文档关闭之前执行特殊的清理处理，请重写此函数。例如，如果文档代表数据库中的一条记录，你可能希望重写此函数以关闭数据库。

`CDocTemplate::CreateNewDocument`

调用此成员函数以创建与此文档模板关联的类型的新文档。

virtual CDocument* CreateNewDocument();

返回值

指向新创建文档的指针，如果发生错误，则为 NULL。

`CDocTemplate::CreateNewFrame`

创建包含文档和视图的新框架窗口。

virtual CFrameWnd* CreateNewFrame(
    CDocument* pDoc,
    CFrameWnd* pOther);

参数

pDoc
新框架窗口应引用的文档。可以为 NULL。

pOther
新框架窗口将基于的框架窗口。可以为 NULL。

返回值

指向新创建的框架窗口的指针，如果发生错误，则为 NULL。

备注

CreateNewFrame 使用传递给构造函数的 CRuntimeClass 对象来创建一个附加有视图和文档的新框架窗口。如果 pDoc 参数为 NULL，则框架会输出 TRACE 消息。

pOther 参数用于实现 Window New 命令。它提供了一个框架窗口，在该窗口上对新框架窗口进行建模。新的框架窗口通常被创建为不可见的。调用此函数可在“文件新建”和“文件打开”的标准框架实现之外创建框架窗口。

`CDocTemplate::CreateOleFrame`

创建 OLE 框架窗口。

CFrameWnd* CreateOleFrame(
    CWnd* pParentWnd,
    CDocument* pDoc,
    BOOL bCreateView);

参数

pParentWnd
指向框架的父窗口的指针。

pDoc
指向新 OLE 框架窗口应引用的文档的指针。

bCreateView
确定视图是否随框架一同创建。

返回值

如果成功，则返回指向框架窗口的指针；否则返回 NULL。

备注

如果 bCreateView 为零，则创建一个空帧。

`CDocTemplate::GetDocString`

检索与文档类型关联的字符串。

virtual BOOL GetDocString(
    CString& rString,
    enum DocStringIndex index) const;

参数

rString
对 CString 对象的引用，该对象将在函数返回时包含字符串。

index
从描述文档类型的字符串中检索的子字符串的索引。此参数可以具有下列值之一：

CDocTemplate::windowTitle 显示在应用程序窗口标题栏中的名称（例如，“Microsoft Excel”）。仅存在于 SDI 应用程序的文档模板中。
CDocTemplate::docName 默认文档名称的根（例如，“Sheet”）。每当用户从“文件”菜单中选择“新建”命令时，这个根加上一个数字就被用作这种类型的新文档的默认名称（例如，“Sheet1”或“Sheet2”）。如果未指定，则默认使用“无标题”。
CDocTemplate::fileNewName 此文档类型的名称。如果应用程序支持多种类型的文档，则此字符串会显示在“文件新建”对话框中（例如，“工作表”）。如果未指定，则无法使用“文件新建”命令访问文档类型。
CDocTemplate::filterName 文档类型的描述和匹配此类型文档的通配符筛选器。此字符串显示在“文件打开”对话框的“文件类型列表”下拉列表中（例如，“工作表 (*.xls)”）。如果未指定，则无法使用“文件打开”命令访问文档类型。
CDocTemplate::filterExt 此类型文档的扩展名（例如，“.xls”）。如果未指定，则无法使用“文件打开”命令访问文档类型。
CDocTemplate::regFileTypeId 要存储在 Windows 维护的注册数据库中的文档类型的标识符。此字符串仅供内部使用（例如，“ExcelWorksheet”）。如果未指定，则无法使用 Windows 文件管理器注册文档类型。
CDocTemplate::regFileTypeName 要存储在注册数据库中的文档类型的名称。此字符串可能会显示在访问注册数据库的应用程序的对话框中（例如，“Microsoft Excel 工作表”）。

返回值

如果找到指定的子字符串，则非零；否则为 0。

注解

调用此函数以检索描述文档类型的特定子字符串。包含这些子字符串的字符串存储在文档模板中，并且派生自应用程序资源文件中的字符串。框架调用此函数来获取应用程序用户界面所需的字符串。如果为应用程序的文档指定了文件扩展名，则框架在向 Windows 注册数据库添加条目时也会调用此函数；这使得能够从 Windows 文件管理器打开文档。

仅当你从 CDocTemplate 派生自己的类时才调用此函数。

`CDocTemplate::GetFirstDocPosition`

检索与此模板关联的第一个文档的位置。

virtual POSITION GetFirstDocPosition() const = 0;

返回值

可用于循环访问与此文档模板关联的文档列表的 POSITION 值；如果列表为空，则为 NULL。

备注

使用此函数可获取与此模板关联的文档列表中第一个文档的位置。使用 POSITION 值作为 CDocTemplate::GetNextDoc 的参数来循环访问与模板关联的文档列表。

CSingleDocTemplate 和 CMultiDocTemplate 均重写此纯虚函数。从 CDocTemplate 派生的任何类也必须重写此函数。

`CDocTemplate::GetNextDoc`

检索由 rPos 标识的列表元素，然后将 rPos 设置为列表中下一个条目的 POSITION 值。

virtual CDocument* GetNextDoc(POSITION& rPos) const = 0;

返回值

指向与此模板关联的文档列表中的下一个文档的指针。

参数

rPos
对先前调用 GetFirstDocPosition 或 GetNextDoc 返回的 POSITION 值的引用。

备注

如果检索到的元素是列表中的最后一个元素，则 rPos 的新值设置为 NULL。

如果通过调用 GetFirstDocPosition 建立初始位置，则可以在正向迭代循环中使用 GetNextDoc。

必须确保 POSITION 值代表列表中的有效位置。如果该值无效，则 Microsoft 基础类库的调试版本会断言。

`CDocTemplate::InitialUpdateFrame`

初始化框架窗口，并（可选）使其可见。

virtual void InitialUpdateFrame(
    CFrameWnd* pFrame,
    CDocument* pDoc,
    BOOL bMakeVisible = TRUE);

参数

pFrame
需要初始更新的框架窗口。

pDoc
框架关联到的文档。可以为 NULL。

bMakeVisible
指示框架是否应变为可见和活动状态。

注解

使用 CreateNewFrame 创建新框架后调用 IntitialUpdateFrame。调用此函数会导致该框架窗口中的视图接收其 OnInitialUpdate 调用。此外，如果以前没有活动视图，则框架窗口的主视图将被激活；主视图是子 ID 为 AFX_IDW_PANE_FIRST 的视图。最后，如果 bMakeVisible 不为零，则框架窗口可见。如果 bMakeVisible 为零，则框架窗口的当前焦点和可见状态将保持不变。

使用框架的“文件新建”和“文件打开”实现时，无需调用此函数。

`CDocTemplate::LoadTemplate`

加载给定 CDocTemplate 或派生类的资源。

virtual void LoadTemplate();

备注

框架调用此成员函数来加载给定 CDocTemplate 或派生类的资源。通常会在构造过程中调用它，除非是在全局构造模板。在这种情况下，会延迟调用 LoadTemplate直到 CWinApp::AddDocTemplate 已调用。

`CDocTemplate::MatchDocType`

确定文档类型与此模板之间匹配的置信度。

virtual Confidence MatchDocType(
    LPCTSTR lpszPathName,
    CDocument*& rpDocMatch);

参数

lpszPathName
要确定其类型的文件的路径名称。

rpDocMatch
指向分配了匹配文档的文档的指针（如果 lpszPathName 指定的文件已打开）。

返回值

Confidence 枚举中的值，定义如下：

enum Confidence
    {
    noAttempt,
    maybeAttemptForeign,
    maybeAttemptNative,
    yesAttemptForeign,
    yesAttemptNative,
    yesAlreadyOpen
    };

备注

使用此函数来确定用于打开文件的文档模板的类型。例如，如果应用程序支持多种文件类型，可以使用此函数通过依次为每个模板调用 MatchDocType，并根据返回的置信值选择一个模板，来确定哪些可用文档模板适用于给定文件。

如果 lpszPathName 指定的文件已打开，则此函数返回 CDocTemplate::yesAlreadyOpen 并将文件的 CDocument 对象复制到 rpDocMatch 处的对象中。

如果文件未打开但 lpszPathName 中的扩展名与 CDocTemplate::filterExt 指定的扩展名匹配，则此函数返回 CDocTemplate::yesAttemptNative 并将 rpDocMatch 设置为 NULL。有关 CDocTemplate::filterExt 的详细信息，请参阅 CDocTemplate::GetDocString。

如果两种情况都不成立，则函数返回 CDocTemplate::yesAttemptForeign。

默认实现不返回 CDocTemplate::maybeAttemptForeign 或 CDocTemplate::maybeAttemptNative。重写此函数以实现适合应用程序的类型匹配逻辑，可能使用 Confidence 枚举中的这两个值。

`CDocTemplate::OpenDocumentFile`

打开路径指定的文件。

virtual CDocument* OpenDocumentFile(LPCTSTR lpszPathName) = 0;

virtual CDocument* OpenDocumentFile(
    LPCTSTR lpszPathName,
    BOOL bAddToMRU) = 0;

参数

lpszPathName
[in] 指向包含要打开的文档的文件路径的指针。

bAddToMRU
[in] TRUE 表示该文档是最新的文件之一；FALSE 表示该文档不是最新文件之一。

返回值

指向文件以 lpszPathName 命名的文档的指针；如果失败则为 NULL。

备注

打开路径由 lpszPathName 指定的文件。如果 lpszPathName 是 NULL，则创建一个包含与此模板关联的类型的文档的新文件。

`CDocTemplate::RemoveDocument`

从与此模板关联的文档列表中删除 pDoc 指向的文档。

virtual void RemoveDocument(CDocument* pDoc);

参数

pDoc
指向要删除的文档的指针。

备注

派生类 CMultiDocTemplate 和 CSingleDocTemplate 会重写此函数。如果你从 CDocTemplate 派生自己的文档模板类，则派生类必须重写此函数。

`CDocTemplate::SaveAllModified`

保存所有已修改的文档。

virtual BOOL SaveAllModified();

返回值

如果成功，则为非零；否则为 0。

`CDocTemplate::SetContainerInfo`

在编辑就地 OLE 项时确定 OLE 容器的资源。

void SetContainerInfo(UINT nIDOleInPlaceContainer);

参数

nIDOleInPlaceContainer
激活嵌入对象时使用的资源的 ID。

备注

调用此函数来设置就地激活 OLE 对象时要使用的资源。这些资源可能包括菜单和快捷键表。此函数通常在应用程序的 CWinApp::InitInstance 函数中调用。

与 nIDOleInPlaceContainer 关联的菜单包含允许已激活就地项的菜单与容器应用程序的菜单合并的分隔符。有关合并服务器和容器菜单的详细信息，请参阅菜单和资源 (OLE) 一文。

`CDocTemplate::SetDefaultTitle`

调用此函数以加载文档的默认标题并显示在文档的标题栏中。

virtual void SetDefaultTitle(CDocument* pDocument) = 0;

参数

pDocument
指向要设置其标题的文档的指针。

备注

有关默认标题的信息，请参阅 CDocTemplate::GetDocString 中 CDocTemplate::docName 的说明。

`CDocTemplate::SetServerInfo`

确定在就地嵌入或编辑服务器文档时的资源和类。

void SetServerInfo(
    UINT nIDOleEmbedding,
    UINT nIDOleInPlaceServer = 0,
    CRuntimeClass* pOleFrameClass = NULL,
    CRuntimeClass* pOleViewClass = NULL);

参数

nIDOleEmbedding
在单独的窗口中打开嵌入对象时使用的资源的 ID。

nIDOleInPlaceServer
就地激活嵌入对象时使用的资源的 ID。

pOleFrameClass
指向 CRuntimeClass 结构的指针，该结构包含进行就地激活时创建的框架窗口对象的类信息。

pOleViewClass
指向 CRuntimeClass 结构的指针，该结构包含进行就地激活时创建的视图对象的类信息。

注解

当用户请求激活嵌入对象时，调用此成员函数来确定服务器应用程序将使用的资源。这些资源由菜单和快捷键表组成。此函数通常在应用程序的 InitInstance 中调用。

与 nIDOleInPlaceServer 关联的菜单包含允许服务器菜单与容器菜单合并的分隔符。有关合并服务器和容器菜单的详细信息，请参阅菜单和资源 (OLE) 一文。

`CDocTemplate::CreatePreviewFrame`

创建用于丰富预览的子框架。

CFrameWnd* CreatePreviewFrame(
    CWnd* pParentWnd,
    CDocument* pDoc);

参数

pParentWnd
指向父窗口的指针（通常由 Shell 提供）。

pDoc
指向将预览其内容的文档对象的指针。

返回值

指向 CFrameWnd 对象的有效指针，如果创建失败，则为 NULL。

备注

`CDocTemplate::SetPreviewInfo`

设置进程外预览控件。

void SetPreviewInfo(
    UINT nIDPreviewFrame,
    CRuntimeClass* pPreviewFrameClass = NULL,
    CRuntimeClass* pPreviewViewClass = NULL);

参数

nIDPreviewFrame
指定预览框架的资源 ID。

pPreviewFrameClass
指定指向预览框架的运行时类信息结构的指针。

pPreviewViewClass
指定指向预览视图的运行时类信息结构的指针。

备注

另请参阅

CCmdTarget 类
 层次结构图
 CSingleDocTemplate 类
 CMultiDocTemplate 类
 CDocument 类
 CView 类
 CScrollView 类
 CEditView 类
 CFormView 类
 CFrameWnd 类
 CMDIChildWnd 类

通过

CDocTemplate 类

语法

成员

受保护构造函数

公共方法

备注

继承层次结构

要求

CDocTemplate::AddDocument

参数

备注

CDocTemplate::CDocTemplate

参数

注解

CDocTemplate::CloseAllDocuments

参数

注解

CDocTemplate::CreateNewDocument

返回值

CDocTemplate::CreateNewFrame

参数

返回值

备注

CDocTemplate::CreateOleFrame

参数

返回值

备注

CDocTemplate::GetDocString

参数

返回值

注解

CDocTemplate::GetFirstDocPosition

返回值

备注

CDocTemplate::GetNextDoc

返回值

参数

备注

CDocTemplate::InitialUpdateFrame

参数

注解

CDocTemplate::LoadTemplate

备注

CDocTemplate::MatchDocType

参数

返回值

备注

CDocTemplate::OpenDocumentFile

参数

返回值

备注

CDocTemplate::RemoveDocument

参数

备注

CDocTemplate::SaveAllModified

返回值

CDocTemplate::SetContainerInfo

参数

备注

CDocTemplate::SetDefaultTitle

参数

备注

CDocTemplate::SetServerInfo

参数

注解

CDocTemplate::CreatePreviewFrame

参数

返回值

备注

CDocTemplate::SetPreviewInfo

参数

备注