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	指出是否已針對 Search & Organize 處理程式建立此物件的實例 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	Rtf 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	指定 Rtf Preview 視窗的文字字型。 此字型資訊是由主機所設定。

備註

檔代表使用者通常會使用 [檔案開啟] 命令開啟的數據單位，並使用 [檔案儲存] 命令儲存。

CDocument 支援標準作業，例如建立檔、載入檔，以及儲存檔。 架構會使用 所 CDocument定義的介面來管理檔。

應用程式可以支援一種以上的檔案類型;例如，應用程式可能同時支援電子錶格和文字檔。 每種類型的檔都有相關聯的檔範本;檔範本會指定用於該檔案類型的資源（例如功能表、圖示或快捷鍵表格）。 每個檔都包含其相關聯 CDocTemplate 物件的指標。

使用者透過 CView 與其相關聯的對象與文件互動。 檢視會在框架視窗中轉譯檔的影像，並將使用者輸入解譯為檔上的作業。 檔可以有多個相關聯的檢視。 當使用者在文件上開啟視窗時，架構會建立檢視並將它附加至檔。 檔範本會指定使用何種類型的檢視和框架視窗來顯示每種類型的檔。

檔是架構標準命令路由的一部分，因此會從標準使用者介面元件接收命令（例如 [檔案儲存] 功能表項）。 檔會接收使用中檢視轉送的命令。 如果文件未處理指定的命令，它會將命令轉送至管理它的檔範本。

修改文件的數據時，每個檢視都必須反映這些修改。 CDocumentUpdateAllViews提供成員函式，讓您通知檢視這類變更，因此檢視可以視需要重新重繪。 架構也會提示使用者先儲存修改過的檔案，再關閉它。

若要在一般應用程式中實作檔，您必須執行下列動作：

• 從衍生每個檔案類型的類別 CDocument 。

• 新增成員變數以儲存每個文件的數據。

• 實作成員函式來讀取和修改文件的數據。 檔的檢視是這些成員函式中最重要的使用者。

• CObject::Serialize覆寫文件類別中的成員函式，以在磁碟中寫入和讀取文件的數據。

CDocument 如果郵件支援 （MAPI） 存在，支援透過郵件傳送您的檔案。 請參閱 MFC 中的 MAPI 和 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 會導致應用程式在下一次儲存檔時提示使用者。 這會使 Save 命令的行為就像另存新檔命令一樣。

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;

傳回值

POSITION值，可用於與成員函式的GetNextView反覆專案。

範例

//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
包含 DWORD ，指定成功傳回函式時的Alpha色板值。

傳回值

如果已成功建立縮圖的點陣圖，則傳 TRUE 回 ，否則 FALSE傳回 。

備註

CDocument::GetTitle

呼叫此函式以取得文件的標題，該標題通常衍生自文件的檔名。

const CString& GetTitle() const;

傳回值

檔的標題。

CDocument::InitializeSearchContent

呼叫 以初始化搜尋處理程式的搜尋內容。

virtual void InitializeSearchContent ();

備註

覆寫衍生類別中的這個方法，以初始化搜尋內容。 內容應該是以 “;” 分隔部分的字串。 例如，「point;矩形;ole item”。

CDocument::IsModified

呼叫此函式，以判斷檔自上次儲存后是否已修改。

virtual BOOL IsModified();

傳回值

如果檔自上次儲存後已修改，則為非零;否則為 0。

CDocument::IsSearchAndOrganizeHandler

指出是否已針對 Search & Organize 處理程式建立這個 實例 CDocument 。

BOOL IsSearchAndOrganizeHandler() const;

傳回值

TRUE如果已針對 Search & Organize 處理程式建立這個 實體CDocument，則傳回 。

備註

此函式目前只會針對在行程伺服器外實作的 Rich Preview 處理程式傳回 TRUE 。 您可以在應用程式層級設定適當的旗標 （m_bPreviewHandlerMode、 m_bSearchModem_bGetThumbnailMode、 ），讓此函式傳回 TRUE。

CDocument::LoadDocumentFromStream

呼叫 以從數據流載入文件數據。

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

參數

pStream
數據流的指標。 殼層會提供此數據流。

dwGrfMode
數據流的存取模式。

傳回值

S_OK 如果載入作業成功，則為 ，否則 HRESULT 為錯誤碼。

備註

您可以在衍生類別中覆寫此方法，以自定義如何從數據流載入數據。

CDocument::m_bGetThumbnailMode

指定 CDocument 物件是由 dllhost 建立的縮圖。 應該簽入 CView::OnDraw。

BOOL m_bGetThumbnailMode;

備註

TRUE 表示檔是由 dllhost 為縮圖所建立。

CDocument::m_bPreviewHandlerMode

指定 CDocument 物件是由 prevhost for Rich Preview 所建立。 應該簽入 CView::OnDraw。

BOOL m_bPreviewHandlerMode;

備註

TRUE 表示檔是由 prevhost for 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。

的特殊實 OnFileSendMail 作，可 COleDocument 正確處理複合檔案。

CDocument 如果郵件支援 （MAPI） 存在，支援透過郵件傳送您的檔案。 請參閱 MFC 中的 MAPI 主題和 MAPI 支援文章。

CDocument::OnLoadDocumentFromStream

架構在需要從數據流載入文件數據時呼叫。

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

參數

pStream
傳入數據流的指標。

grfMode
數據流的存取模式。

傳回值

S_OK 如果載入成功，則為 ;否則為錯誤碼。

備註

CDocument::OnNewDocument

由架構呼叫做為 File New 命令的一部分。

virtual BOOL OnNewDocument();

傳回值

如果已成功初始化檔，則為非零;否則為 0。

備註

此函式的預設實作會呼叫 DeleteContents 成員函式，以確保檔是空的，然後將新文件標示為乾淨。 覆寫此函式，以初始化新文件的數據結構。 您應該從覆寫呼叫此函式的基類版本。

如果使用者在 SDI 應用程式中選擇 [檔案新增] 命令，架構會使用此函式來重新初始化現有的檔案，而不是建立新的檔。 如果使用者在多個檔介面 （MDI） 應用程式中選擇 [檔案新增]，架構每次都會建立新的檔，然後呼叫此函式來初始化它。 您必須將此函式中的初始化程式代碼放在此函式中，而不是在建構函式中，讓 File New 命令在 SDI 應用程式中生效。

請注意，在某些情況下 OnNewDocument 會呼叫兩次。 當檔內嵌為 ActiveX 檔案伺服器時，就會發生這種情況。 方法會先呼叫函式（由CreateInstanceCOleObjectFactory衍生類別公開），第二次由 方法呼叫（由InitNewCOleServerDoc衍生類別公開）。

範例

下列範例說明初始化檔物件的替代方法。

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

指示預覽處理程式傳回 HWND 從呼叫 函式擷取的 GetFocus 。

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

當 Rtf 預覽文字色彩變更時呼叫。

virtual void OnRichPreviewTextColorChanged();

備註

CDocument::OnSaveDocument

架構在 [檔案儲存] 或 [檔案另存新檔] 命令中呼叫。

virtual BOOL OnSaveDocument(LPCTSTR lpszPathName);

參數

lpszPathName
指向應該儲存盤案的完整路徑。

傳回值

如果已成功儲存檔，則為非零;否則為 0。

備註

此函式的預設實作會開啟指定的檔案、呼叫 CObject::Serialize 將文件的數據寫入檔案，然後將文件標示為乾淨。 如果您想要在架構儲存檔時執行特殊處理，請覆寫此函式。 例如，您可以撰寫應用程式，其中檔代表資料庫中的記錄，而不是個別的檔案。

CDocument::OnUnloadHandler

卸除預覽處理程式時，由架構呼叫。

virtual void OnUnloadHandler();

備註

CDocument::OnUpdateFileSendMail

ID_FILE_SEND_MAIL如果有郵件支援（MAPI），請啟用命令。

void OnUpdateFileSendMail(CCmdUI* pCmdUI);

參數

pCmdUI
與ID_FILE_SEND_MAIL命令相關聯的對象指標CCmdUI。

備註

否則，函式會 ID_FILE_SEND_MAIL 從功能表中移除命令，包括功能表項上方或下方的分隔符。 如果 MAPI32.DLL MAPI存在於路徑中，而且在檔案的 [Mail] 區段中 WIN.INI ，MAPI=1 就會啟用。 大部分的應用程式都會將此命令放在 [檔案] 功能表上。

CDocument 如果郵件支援 （MAPI） 存在，支援透過郵件傳送您的檔案。 請參閱 MFC 中的 MAPI 主題和 MAPI 支援文章。

CDocument::PreCloseFrame

框架窗口終結之前，架構會呼叫此成員函式。

virtual void PreCloseFrame(CFrameWnd* pFrame);

參數

pFrame
CFrameWnd保存相關聯CDocument物件的指標。

備註

您可以覆寫以提供自定義清除，但請務必呼叫基類。

的預設值 PreCloseFrame 在中 CDocument不會執行任何動作。 CDocument衍生類別COleDocument並使用CRichEditDoc這個成員函式。

CDocument::ReadNextChunkValue

讀取下一個區塊值。

virtual BOOL ReadNextChunkValue(IFilterChunkValue** ppValue);

參數

ppValue
[out]當函式傳回時， ppValue 包含已讀取的值。

傳回值

如果成功則為非零；否則為 0。

備註

CDocument::ReleaseFile

架構會呼叫此成員函式來釋放檔案，使其可供其他應用程式使用。

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

參數

pFile
要釋放之 CFile 物件的指標。

bAbort
指定是否要使用 或 CFile::Abort來釋放CFile::Close檔案。 FALSE 如果要使用 CFile::Close釋放檔案，則為 ， TRUE 如果要使用 CFile::Abort釋放檔案，則為 。

備註

如果 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。

備註

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除外。 使用這些參數，將資訊傳遞至檔修改的相關檢視。 您可以使用 和/或定義CObject衍生類別來編碼資訊lHint，以儲存修改的相關信息，並使用 傳遞該類別pHint的物件。 CView::OnUpdate覆寫衍生類別中的CView成員函式，以根據傳遞的資訊優化檢視顯示更新。

範例

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

另請參閱

MFC 範例 MDIDOCVW
MFC 範例 SNAPVW
MFC 範例 NPP
CCmdTarget 類
階層架構圖表
CCmdTarget 類
CView 類
CDocTemplate 類