Класс 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 Вызывается при изменении цвета текста с расширенным просмотром.
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 Задает цвет фона окна "Расширенный просмотр". Этот цвет задается узлом.
CDocument::m_clrRichPreviewTextColor Задает цвет переднего плана окна "Расширенный просмотр". Этот цвет задается узлом.
CDocument::m_lfRichPreviewFont Задает текстовый шрифт для окна Rich Preview. Эти сведения о шрифте задаются узлом.

Замечания

Документ представляет единицу данных, которые пользователь обычно открывает с помощью команды "Открыть файл" и сохраняется с помощью команды "Сохранить файл".

CDocument поддерживает стандартные операции, такие как создание документа, его загрузка и сохранение. Платформа управляет документами с помощью интерфейса, определенного .CDocument

Приложение может поддерживать несколько типов документов; Например, приложение может поддерживать как электронные таблицы, так и текстовые документы. Каждый тип документа имеет связанный шаблон документа; Шаблон документа указывает, какие ресурсы (например, меню, значок или таблицу акселератора) используются для этого типа документа. Каждый документ содержит указатель на связанный CDocTemplate объект.

Пользователи взаимодействуют с документом через CView связанные с ним объекты. Представление отображает изображение документа в окне фрейма и интерпретирует входные данные пользователя как операции с документом. Документ может иметь несколько представлений, связанных с ним. Когда пользователь открывает окно в документе, платформа создает представление и присоединяет его к документу. Шаблон документа определяет тип окна представления и фрейма для отображения каждого типа документа.

Документы являются частью стандартной маршрутизации команд платформы и, следовательно, получают команды из стандартных компонентов пользовательского интерфейса (например, пункт меню "Сохранить файл"). Документ получает команды, пересылаемые активным представлением. Если документ не обрабатывает указанную команду, он перенаправит команду в шаблон документа, который управляет им.

При изменении данных документа каждое из его представлений должно отражать эти изменения. CDocumentUpdateAllViews предоставляет функцию-член для уведомления о таких изменениях, чтобы представления могли перенакрасить себя по мере необходимости. Платформа также предложит пользователю сохранить измененный файл перед закрытием файла.

Чтобы реализовать документы в обычном приложении, необходимо выполнить следующие действия.

  • Производный класс от CDocument каждого типа документа.

  • Добавьте переменные-члены для хранения данных каждого документа.

  • Реализуйте функции-члены для чтения и изменения данных документа. Представления документа являются наиболее важными пользователями этих функций-членов.

  • Переопределите CObject::Serialize функцию-член в классе документов, чтобы записывать и считывать данные документа на диск и с диска.

CDocument поддерживает отправку документа по почте, если присутствует поддержка почты (MAPI). См. статьи MAPI и MAPI Support in MFC.

Дополнительные сведения см. в CDocumentразделах по сериализации, архитектуре документа и представления архитектуры и создании документов и представлений.

Иерархия наследования

CObject

CCmdTarget

CDocument

Requirements

Заголовок.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, использующего только один документ; Документ повторно используется всякий раз, когда пользователь создает или открывает другой документ. Вызовите эту функцию для реализации команды Edit Clear All или аналогичной команды, которая удаляет все данные документа. Реализация по умолчанию этой функции не выполняет никаких действий. Переопределите эту функцию, чтобы удалить данные в документе.

Пример

// 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
Указывает идентификатор идентификатора блока для поиска.

Возвращаемое значение

При успешном выполнении позиции в списке внутренних блоков. В противном случае — значение 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
Режим общего доступа и общего доступа. Указывает действие, которое необходимо предпринять при открытии файла. Параметры, перечисленные в конструкторе CFile::CFile CFile, можно объединить с помощью побитового оператора OR (|). Требуется одно разрешение на доступ и один вариант общего доступа; Режимы 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
Ссылка на POSITION значение, возвращаемое предыдущим вызовом GetNextView функций или GetFirstViewPosition членов. Это значение не должно быть NULL.

Возвращаемое значение

Указатель на представление, определяемое по rPosition.

Замечания

Функция возвращает представление, rPosition определенное и затем задает rPositionPOSITION значение следующего представления в списке. Если полученное представление является последним в списке, 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 значение альфа-канала, когда функция возвращается успешно.

Возвращаемое значение

Возвращает, TRUE если растровое изображение для эскиза было создано успешно; в противном случае FALSE.

Замечания

CDocument::GetTitle

Вызовите эту функцию, чтобы получить заголовок документа, который обычно является производным от имени файла документа.

const CString& GetTitle() const;

Возвращаемое значение

Заголовок документа.

CDocument::InitializeSearchContent

Вызывается для инициализации содержимого поиска для обработчика поиска.

virtual void InitializeSearchContent ();

Замечания

Переопределите этот метод в производном классе, чтобы инициализировать содержимое поиска. Содержимое должно быть строкой с разделителями ";". Например, "point; Прямоугольник; ole item".

CDocument::IsModified

Вызовите эту функцию, чтобы определить, был ли документ изменен с момента последнего сохранения.

virtual BOOL IsModified();

Возвращаемое значение

Ненулевое значение, если документ был изменен с момента последнего сохранения; в противном случае — 0.

CDocument::IsSearchAndOrganizeHandler

Указывает, был ли создан этот экземпляр для обработчика CDocument поиска и упорядочения.

BOOL IsSearchAndOrganizeHandler() const;

Возвращаемое значение

Возвращает, TRUE если этот экземпляр был создан для обработчика CDocument поиска и организации.

Замечания

В настоящее время эта функция возвращает TRUE только для обработчиков Rich Preview, реализованных на сервере обработки. Вы можете задать соответствующие флаги (m_bPreviewHandlerMode, m_bSearchMode, m_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 для Rich Preview. Должен быть проверка в CView::OnDraw.

BOOL m_bPreviewHandlerMode;

Замечания

TRUE указывает, что документ был создан prevhost для rich Preview.

CDocument::m_bSearchMode

Указывает, что CDocument объект был создан индексатором или другим приложением поиска.

BOOL m_bSearchMode;

Замечания

TRUE указывает, что документ был создан индексатором или другим приложением поиска.

CDocument::m_clrRichPreviewBackColor

Задает цвет фона окна "Расширенный просмотр". Этот цвет задается узлом.

COLORREF m_clrRichPreviewBackColor;

Замечания

CDocument::m_clrRichPreviewTextColor

Задает цвет переднего плана окна "Расширенный просмотр". Этот цвет задается узлом.

COLORREF m_clrRichPreviewTextColor;

Замечания

CDocument::m_lfRichPreviewFont

Задает текстовый шрифт для окна "Форматированный просмотр". Эти сведения о шрифте задаются узлом.

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 обработки составных файлов.

CDocument поддерживает отправку документа по почте, если присутствует поддержка почты (MAPI). См. статьи MAPI темы и поддержка MAPI в MFC.

CDocument::OnLoadDocumentFromStream

Вызывается платформой, когда необходимо загрузить данные документа из потока.

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

Параметры

pStream
Указатель на входящий поток.

grfMode
Режим доступа к потоку.

Возвращаемое значение

S_OK Значение , если загрузка выполнена успешно; в противном случае код ошибки.

Замечания

CDocument::OnNewDocument

Вызывается платформой в рамках команды "Создать файл".

virtual BOOL OnNewDocument();

Возвращаемое значение

Ненулевое значение, если документ был успешно инициализирован; в противном случае — 0.

Замечания

Реализация этой функции по умолчанию вызывает DeleteContents функцию-член, чтобы убедиться, что документ пуст, а затем помечает новый документ как чистый. Переопределите эту функцию, чтобы инициализировать структуру данных для нового документа. Вы должны вызвать версию базового класса этой функции из переопределения.

Если пользователь выбирает команду "Создать файл" в приложении SDI, платформа использует эту функцию для повторной инициализации существующего документа, а не для создания нового. Если пользователь выбирает "Создать файл" в приложении с несколькими интерфейсами документов (MDI), платформа создает новый документ каждый раз, а затем вызывает эту функцию для инициализации. Код инициализации необходимо поместить в эту функцию вместо конструктора, чтобы команда File New была эффективной в приложениях 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 объект каждый раз, а затем вызывает эту функцию для инициализации. Код инициализации необходимо поместить в эту функцию вместо конструктора, чтобы команда File Open была эффективной в приложениях 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] Когда этот метод возвращается, содержит указатель на HWND, возвращенный вызовом функции из GetFocus потока переднего плана обработчика предварительного просмотра.

Возвращаемое значение

Возвращает значение 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

Вызывается при изменении цвета текста форматированного просмотра.

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
Указатель на объект, связанный CCmdUI с командой ID_FILE_SEND_MAIL .

Замечания

В противном случае функция удаляет ID_FILE_SEND_MAIL команду из меню, включая разделители выше или под элементом меню соответствующим образом. MAPI включен, если MAPI32.DLL он присутствует в пути и в разделе WIN.INI [Почта] файла MAPI=1. Большинство приложений помещают эту команду в меню "Файл".

CDocument поддерживает отправку документа по почте, если присутствует поддержка почты (MAPI). См. статьи MAPI темы и поддержка MAPI в MFC.

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::Close или.CFile::Abort FALSEЗначение , если файл должен быть выпущен CFile::CloseTRUE с помощью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

Вызывается, если исключение создается (обычно или CFileExceptionCArchiveException) при сохранении или загрузке документа.

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

Параметры

lpszPathName
Указывает на имя документа, сохраненного или загруженного.

e
Указывает на исключение, которое было создано. Может иметь значение NULL.

bSaving
Флаг, указывающий на ход выполнения операции; значение nonzero, если документ сохраняется, 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
Флаг, указывающий, был ли изменен документ.

Замечания

Путем последовательного вызова этой функции необходимо убедиться, что платформа предложит пользователю сохранить изменения перед закрытием документа. Обычно для параметра следует использовать значение TRUEbModified по умолчанию. Чтобы пометить документ как чистый (неизмененные), вызовите эту функцию со значением 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::OnUpdate функцию-член в CViewпроизводном классе, чтобы оптимизировать обновление отображения представления на основе переданных сведений.

Пример

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

См. также

Пример MFC MDIDOCVW
Пример MFC SNAPVW
Пример MFC NPP
CCmdTarget Класса
Диаграмма иерархии
CCmdTarget Класса
CView Класса
CDocTemplate Класса