`CDocTemplate` 類別

發行項
10/12/2023

定義文件範本基本功能的抽象基底類別。

語法

class CDocTemplate : public CCmdTarget

成員

受保護的建構函式

名稱	描述
`CDocTemplate::CDocTemplate`	建構 `CDocTemplate` 物件。

公用方法

名稱	描述
`CDocTemplate::AddDocument`	將檔新增至範本。
`CDocTemplate::CloseAllDocuments`	關閉與此範本相關聯的所有檔。
`CDocTemplate::CreateNewDocument`	建立新的檔。
`CDocTemplate::CreateNewFrame`	建立包含檔和檢視的新框架視窗。
`CDocTemplate::CreateOleFrame`	建立已啟用 OLE 的框架視窗。
`CDocTemplate::CreatePreviewFrame`	建立用於 Rich Preview 的子框架。
`CDocTemplate::GetDocString`	擷取與檔案類型相關聯的字串。
`CDocTemplate::GetFirstDocPosition`	擷取與此範本相關聯的第一份檔位置。
`CDocTemplate::GetNextDoc`	擷取檔及下一個檔的位置。
`CDocTemplate::InitialUpdateFrame`	初始化框架視窗，並選擇性地讓它可見。
`CDocTemplate::LoadTemplate`	載入指定 `CDocTemplate` 或衍生類別的資源。
`CDocTemplate::MatchDocType`	決定檔案類型與此範本之間的比對信賴度。
`CDocTemplate::OpenDocumentFile`	開啟 pathname 所指定的檔案。
`CDocTemplate::RemoveDocument`	從範本中移除檔。
`CDocTemplate::SaveAllModified`	儲存與此範本相關聯的所有檔，這些檔已經過修改。
`CDocTemplate::SetContainerInfo`	在編輯就地 OLE 專案時，判斷 OLE 容器的資源。
`CDocTemplate::SetDefaultTitle`	在文件視窗的標題列中顯示預設標題。
`CDocTemplate::SetPreviewInfo`	安裝程式脫離進程預覽處理常式。
`CDocTemplate::SetServerInfo`	當伺服器檔內嵌或就地編輯時，決定資源和類別。

備註

您通常會在應用程式函式的 InitInstance 實作中建立一或多個檔範本。檔範本會定義三種類別之間的關聯性：

檔類別，衍生自 CDocument 。
檢視類別，顯示上面所列檔類別的資料。您可以從、、 CScrollViewCFormView 或 CEditView 衍生這個類別 CView 。（您也可以直接使用 CEditView 。
包含檢視的框架視窗類別。針對單一檔介面（SDI）應用程式，您可以從衍生此類別 CFrameWnd 。針對多個檔介面（MDI）應用程式，您可以從衍生此類別 CMDIChildWnd 。如果您不需要自訂框架視窗的行為，則可以使用或 CMDIChildWnd 直接不使用 CFrameWnd 衍生您自己的類別。

您的應用程式針對它支援的每個檔案類型都有一個檔範本。例如，如果您的應用程式同時支援試算表和文字檔，應用程式就會有兩個檔範本物件。每個檔範本都負責建立和管理其類型的所有檔。

檔範本會儲存檔、檢視和框架視窗類別之物件的指標 CRuntimeClass 。建構檔範本時會指定這些 CRuntimeClass 物件。

檔範本包含與檔案類型搭配使用的資源識別碼（例如功能表、圖示或快速鍵資料表資源）。檔範本也有字串，其中包含其檔案類型的其他資訊。其中包括檔案類型的名稱（例如「Worksheet」）和副檔名（例如「.xls」。或者，它可以包含應用程式使用者介面、Windows 檔案管理員和物件連結和內嵌（OLE）支援所使用的其他字串。

如果您的應用程式是 OLE 容器和/或伺服器，檔範本也會定義就地啟用期間所使用的功能表識別碼。如果您的應用程式是 OLE 伺服器，檔範本會定義就地啟用期間所使用的工具列和功能表識別碼。您可以藉由呼叫 SetContainerInfo 和 SetServerInfo 來指定這些額外的 OLE 資源。

因為 CDocTemplate 是抽象類別，您無法直接使用類別。一般應用程式會使用 Microsoft Foundation Class Library 所提供的兩 CDocTemplate 個衍生類別之一： CSingleDocTemplate ，它會實作 SDI，以及 CMultiDocTemplate 實作 MDI 的。如需使用檔範本的詳細資訊，請參閱這些類別。

如果您的應用程式需要與 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
指定搭配檔案類型使用之資源的識別碼。這可能包括功能表、圖示、快速鍵資料表和字串資源。

字串資源是由字元分隔 \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 發生錯誤，則為。

備註

CreateNewFrameCRuntimeClass會使用傳遞至建構函式的物件，建立附加檢視和檔的新框架視窗。 pDoc如果參數為 NULL ，則架構會輸出 TRACE 訊息。

參數 pOther 是用來實作 Window New 命令。它提供用來建立新框架視窗模型框架視窗的框架視窗。新的框架視窗通常會建立不可見。呼叫此函式，以在 File New 和 File Open 的標準架構實作 之外建立框架視窗。

`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」。如果未指定，則會使用「Untitled」做為預設值。
CDocTemplate::fileNewName 此檔案類型的名稱。如果應用程式支援一種以上的檔案類型，此字串會顯示在 [檔案新增 ] 對話方塊中（例如，「Worksheet」）。如果未指定，則無法使用 [檔案新增 ] 命令來存取檔案類型。
CDocTemplate::filterName 檔案類型的描述，以及符合此類型檔的萬用字元篩選。此字串會顯示在 [開啟 檔案] 對話方塊中的 [類型 清單檔案] 下拉式清單中 （例如「Worksheets（*.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 Foundation Class Library 的偵錯版本會判斷提示。

`CDocTemplate::InitialUpdateFrame`

初始化框架視窗，並選擇性地讓它可見。

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

參數

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

pDoc
與框架相關聯的檔。可以是 NULL。

bMakeVisible
指出框架是否應該變成可見且作用中。

備註

使用 CreateNewFrame 建立新框架之後呼叫 IntitialUpdateFrame 。呼叫此函式會導致該框架視窗中的檢視接收其 OnInitialUpdate 呼叫。此外，如果先前沒有使用中檢視，則會使用框架視窗的主要檢視;主要檢視是子識別碼為的 AFX_IDW_PANE_FIRST 檢視。最後，如果 bMakeVisible 為非零，則會顯示框架視窗。如果 bMakeVisible 為零，則框架視窗目前的焦點和可見狀態會保持不變。

使用 Framework 的 File New 和 File Open 實 作時，不需要呼叫此函式。

`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 。

如果兩個案例都不是 true，則函式會傳 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
啟動内嵌物件時所使用的資源識別碼。

備註

呼叫此函式，以設定當 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
在個別視窗中開啟内嵌物件時所使用的資源識別碼。

nIDOleInPlaceServer
就地啟動内嵌物件時所使用的資源識別碼。

pOleFrameClass
CRuntimeClass結構的指標，其中包含發生就地啟用時所建立之框架視窗物件的類別資訊。

pOleViewClass
CRuntimeClass結構的指標，其中包含發生就地啟用時所建立之檢視物件的類別資訊。

備註

呼叫此成員函式，以識別當使用者要求啟用内嵌物件時，伺服器應用程式將使用的資源。這些資源是由功能表和快速鍵資料表所組成。此函式通常會在應用程式的中 InitInstance 呼叫。

與 nIDOleInPlaceServer 相關聯的功能表包含分隔符號，可讓伺服器功能表與容器的功能表合併。如需合併伺服器和容器功能表的詳細資訊，請參閱功能表和資源（OLE）一文。

`CDocTemplate::CreatePreviewFrame`

建立用於 Rich Preview 的子框架。

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

參數

pParentWnd
父視窗的指標（通常是由殼層提供）。

pDoc
檔物件的指標，其內容將預覽。

傳回值

物件的有效指標 CFrameWnd ，如果建立失敗，則為 Null。

備註

`CDocTemplate::SetPreviewInfo`

設定進程外預覽處理常式。

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

參數

nIDPreviewFrame
指定預覽框架的資源識別碼。

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

參數

備註