`CDocTemplate` 類別

發行項
07/05/2024

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

語法

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 檔類型的描述，以及符合此類型檔的通配符篩選。此字串會顯示在 [開啟檔案] 對話方塊中的 [類型清單檔案] 下拉式清單中（例如，「工作表」（*.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 呼叫。此外，如果先前沒有使用中檢視，則會使用框架視窗的主要檢視;主要檢視是子標識碼為的 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

參數

備註