Classe CDocument

Fornece a funcionalidade básica para classes de documento definidas pelo usuário.

Sintaxe

class CDocument : public CCmdTarget

Membros

Construtores públicos

Nome	Descrição
CDocument::CDocument	Constrói um objeto CDocument.

Métodos públicos

Nome	Descrição
CDocument::AddView	Anexa uma exibição ao documento.
CDocument::BeginReadChunks	Inicializa a leitura em partes.
CDocument::CanCloseFrame	Substituível avançado; chamado antes de fechar uma janela com moldura exibindo este documento.
CDocument::ClearChunkList	Limpa a lista de partes.
CDocument::ClearPathName	Limpa o caminho do objeto do documento.
CDocument::DeleteContents	Chamado para executar a limpeza do documento.
CDocument::FindChunk	Procura uma parte com GUID especificado.
CDocument::GetAdapter	Retorna um ponteiro para a interface IDocument de implementação de objeto.
CDocument::GetDocTemplate	Retorna um ponteiro para o modelo de documento que descreve o tipo do documento.
CDocument::GetFile	Retorna um ponteiro para o objeto CFile desejado.
CDocument::GetFirstViewPosition	Retorna a posição do primeiro na lista de exibições; usado para iniciar a iteração.
CDocument::GetNextView	Itera por meio da lista de exibições associadas ao documento.
CDocument::GetPathName	Retorna o caminho do arquivo de dados do documento.
CDocument::GetThumbnail	Chamado para criar um bitmap a ser usado pelo provedor de miniaturas para exibir miniaturas.
CDocument::GetTitle	Recupera o título do documento.
CDocument::InitializeSearchContent	Chamado para inicializar o conteúdo da pesquisa para o Manipulador de Pesquisa.
CDocument::IsModified	Indica se o documento foi modificado desde que foi salvo pela última vez.
CDocument::IsSearchAndOrganizeHandler	Informa se essa instância do CDocument objeto foi criada para o manipulador Search & Organiz.
CDocument::LoadDocumentFromStream	Chamado para carregar dados do documento do fluxo.
CDocument::OnBeforeRichPreviewFontChanged	Chamado antes que a fonte de Visualização Avançada seja alterada.
CDocument::OnChangedViewList	Chamado depois que uma exibição é adicionada ou removida do documento.
CDocument::OnCloseDocument	Chamado para fechar o documento.
CDocument::OnCreatePreviewFrame	Chamado pela estrutura quando ela precisa criar um quadro de visualização para Visualização Avançada.
CDocument::OnDocumentEvent	Chamado pela estrutura em resposta a um evento de documento.
CDocument::OnDrawThumbnail	Substitua esse método em uma classe derivada para desenhar o conteúdo da miniatura.
CDocument::OnLoadDocumentFromStream	Chamado pela estrutura quando ela precisa carregar os dados do documento do fluxo.
CDocument::OnNewDocument	Chamado para criar um novo documento.
CDocument::OnOpenDocument	Chamado para abrir um documento existente.
CDocument::OnPreviewHandlerQueryFocus	Direciona o manipulador de visualização para retornar o HWND ao chamar a função GetFocus.
CDocument::OnPreviewHandlerTranslateAccelerator	Direciona o manipulador de visualização para manipular um pressionamento de tecla passado da bomba de mensagem do processo no qual o manipulador de visualização está em execução.
CDocument::OnRichPreviewBackColorChanged	Chamado quando a cor da tela de fundo da Visualização Avançada foi alterada.
CDocument::OnRichPreviewFontChanged	Chamado quando a fonte da Visualização Avançada foi alterada.
CDocument::OnRichPreviewSiteChanged	Chamado quando o site da Visualização Avançada foi alterado.
CDocument::OnRichPreviewTextColorChanged	Chamado quando a cor do texto da Visualização Avançada foi alterada.
CDocument::OnSaveDocument	Chamado para salvar o documento no disco.
CDocument::OnUnloadHandler	Chamado pela estrutura quando o manipulador de visualização está sendo descarregado.
CDocument::PreCloseFrame	Chamado antes que a janela com moldura seja fechada.
CDocument::ReadNextChunkValue	Lê o valor da próxima parte.
CDocument::ReleaseFile	Libera um arquivo para disponibilizá-lo para uso por outros aplicativos.
CDocument::RemoveChunk	Remove uma parte com GUID especificado.
CDocument::RemoveView	Desanexa uma exibição do documento.
CDocument::ReportSaveLoadException	Substituível avançado; chamado quando uma operação de abrir ou salvar não pode ser concluída devido a uma exceção.
CDocument::SaveModified	Substituível avançado; chamado para perguntar ao usuário se o documento deve ser salvo.
CDocument::SetChunkValue	Define um valor de parte.
CDocument::SetModifiedFlag	Define um sinalizador que indica que você modificou o documento desde que ele foi salvo pela última vez.
CDocument::SetPathName	Define o caminho do arquivo de dados usado pelo documento.
CDocument::SetTitle	Define o título do documento.
CDocument::UpdateAllViews	Notifica todos os modos de exibição de que o documento foi modificado.

Métodos protegidos

Nome	Descrição
CDocument::OnFileSendMail	Envia uma mensagem de email com o documento anexado.
CDocument::OnUpdateFileSendMail	Habilita o comando Enviar email se o suporte de email estiver presente.

Membros de Dados Públicos

Nome	Descrição
CDocument::m_bGetThumbnailMode	Especifica que o objeto CDocument foi criado por dllhost para miniaturas. Deve ser verificado em CView::OnDraw.
CDocument::m_bPreviewHandlerMode	Especifica que o objeto CDocument foi criado por prevhost para Rich Preview. Deve ser verificado em CView::OnDraw.
CDocument::m_bSearchMode	Especifica que o objeto CDocument foi criado pelo indexador ou outro aplicativo de pesquisa.
CDocument::m_clrRichPreviewBackColor	Especifica a cor da tela de fundo da janela de Visualização Avançada. Essa cor é definida pelo host.
CDocument::m_clrRichPreviewTextColor	Especifica a cor de primeiro plano da janela de Visualização Avançada. Essa cor é definida pelo host.
CDocument::m_lfRichPreviewFont	Especifica a fonte de texto para a janela de Visualização Avançada. Essas informações de fonte são definidas pelo host.

Comentários

Um documento representa a unidade de dados que o usuário normalmente abre com o comando Abrir Arquivo e salva com o comando Salvar Arquivo.

CDocument dá suporte a operações padrão, como criar um documento, carregá-lo e salvá-lo. A estrutura manipula documentos usando a interface definida por CDocument.

Um aplicativo pode oferecer suporte a mais de um tipo de documento; por exemplo, um aplicativo pode dar suporte a planilhas e documentos de texto. Cada tipo de documento tem um modelo de documento associado; o modelo de documento especifica quais recursos (por exemplo, menu, ícone ou tabela de teclas aceleradoras) são usados para esse tipo de documento. Cada documento contém um ponteiro para seu objeto CDocTemplate associado.

Os usuários interagem com um documento por meio do(s) objeto(s) CView associado(s) a ele. Uma exibição renderiza uma imagem do documento em uma janela com moldura e interpreta a entrada do usuário como operações no documento. Um documento pode ter vários modos de exibição associados a ele. Quando o usuário abre uma janela em um documento, a estrutura cria uma exibição e a anexa ao documento. O modelo de documento especifica que tipo de exibição e janela com moldura são usados para exibir cada tipo de documento.

Os documentos fazem parte do roteamento de comando padrão da estrutura e, consequentemente, recebem comandos de componentes padrão da interface do usuário (como o item de menu Salvar arquivo). Um documento recebe comandos encaminhados pela exibição ativa. Se o documento não manipular um determinado comando, ele encaminhará o comando para o modelo de documento que o gerencia.

Quando os dados de um documento são modificados, cada um de seus modos de exibição deve refletir essas modificações. CDocument fornece a função membro UpdateAllViews para que você notifique os modos de exibição dessas alterações, de modo que as exibições possam se repintar conforme necessário. A estrutura também solicita que o usuário salve um arquivo modificado antes de fechá-lo.

Para implementar documentos em um aplicativo típico, você deve fazer o seguinte:

• Derive uma classe de CDocument para cada tipo de documento.

• Adicione variáveis de membro para armazenar os dados de cada documento.

• Implemente funções membro para ler e modificar os dados do documento. Os modos de exibição do documento são os usuários mais importantes dessas funções membro.

• Substitua a função membro CObject::Serialize na classe de documento para gravar e ler os dados do documento de e para o disco.

CDocument dá suporte ao envio do documento por email se o suporte de email (MAPI) estiver presente. Consulte os artigos MAPI e Suporte a MAPI no MFC.

Para obter mais informações sobre CDocument, consulte Serialização, Tópicos de Arquitetura de Documento/Exibição e Criação de Documentos/Exibições.

Hierarquia de herança

CObject

CCmdTarget

CDocument

Requisitos

Cabeçalhoafxwin.h:

CDocument::AddView

Chame essa função para anexar uma exibição ao documento.

void AddView(CView* pView);

Parâmetros

pView
Aponta para a exibição que está sendo adicionada.

Comentários

Essa função adiciona o modo de exibição especificado à lista de exibições associadas ao documento. A função também define o ponteiro de documento da exibição para este documento. A estrutura chama essa função ao anexar um objeto de exibição recém-criado a um documento; isso ocorre em resposta a um comando Novo Arquivo, Abrir Arquivo ou Nova Janela, ou quando uma janela separadora é dividida.

Chame essa função somente se você estiver criando e anexando manualmente uma exibição. Normalmente, você permitirá que a estrutura conecte documentos e exibições definindo um objeto CDocTemplate para associar uma classe de documento, classe de exibição e a classe de janela com moldura.

Exemplo

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

Inicializa a leitura em partes.

virtual void BeginReadChunks ();

Comentários

CDocument::CanCloseFrame

Chamado pela estrutura antes fechar uma janela com moldura que exibe o documento.

virtual BOOL CanCloseFrame(CFrameWnd* pFrame);

Parâmetros

pFrame
Aponta para a janela com moldura de uma exibição anexado ao documento.

Valor de retorno

Diferente de zero se for seguro fechar a janela com moldura; caso contrário, 0.

Comentários

A implementação padrão verifica se há outras janelas com moldura exibindo o documento. Se a janela com moldura especificada for a última que exibe o documento, a função solicitará que o usuário salve o documento se ele tiver sido modificado. Substitua essa função se você quiser executar processamento especial quando uma janela com moldura for fechada. Essa é uma substituição avançada.

CDocument::CDocument

Constrói um objeto CDocument.

CDocument();

Comentários

A estrutura manipula a criação de documentos para você. Substitua a função membro OnNewDocument para executar a inicialização por documento. Isso é particularmente importante em aplicativos de interface SDI (single-document interface).

CDocument::ClearChunkList

Limpa a lista de partes.

virtual void ClearChunkList ();

Comentários

CDocument::ClearPathName

Limpa o caminho do objeto do documento.

virtual void ClearPathName();

Comentários

Limpar o caminho de um objeto CDocument faz com que o aplicativo solicite confirmação ao usuário quando o documento for salvo da próxima vez. Isso faz com que um comando Salvar se comporte como um comando Salvar como.

CDocument::DeleteContents

Chamado pela estrutura para excluir os dados do documento sem destruir o próprio objeto CDocument.

virtual void DeleteContents();

Comentários

É chamado pouco antes do documento ser destruído. Ele também é chamado para garantir que um documento esteja vazio antes de ser reutilizado. Isso é especialmente importante para um aplicativo SDI, que usa apenas um documento, pois o documento é reutilizado sempre que o usuário cria ou abre outro documento. Chame essa função para implementar um comando "Edit Clear All" ou semelhante que exclui todos os dados do documento. A implementação padrão dessa função não faz nada. Substitua essa função para excluir os dados no documento.

Exemplo

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

Procura uma parte com GUID especificado.

virtual POSITION FindChunk(
    REFCLSID guid,
    DWORD pid);

Parâmetros

guid
Especifica o GUID de uma parte a ser encontrada.

pid
Especifica um PID de uma parte a ser encontrada.

Valor de retorno

Posição na lista de partes internas se tiver êxito. Caso contrário, NULL.

Comentários

CDocument::GetAdapter

Retorna um ponteiro para um objeto implementando a interface IDocument.

virtual ATL::IDocument* GetAdapter();

Valor de retorno

Um ponteiro para um objeto implementando a interface IDocument.

Comentários

CDocument::GetDocTemplate

Chame essa função para obter um ponteiro do modelo de documento para esse tipo de documento.

CDocTemplate* GetDocTemplate() const;

Valor de retorno

Um ponteiro para o modelo de documento para esse tipo de documento ou NULL, se o documento não for gerenciado por um modelo de documento.

Exemplo

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

Chame essa função membro para obter um ponteiro para um objeto CFile.

virtual CFile* GetFile(
    LPCTSTR lpszFileName,
    UINT nOpenFlags,
    CFileException* pError);

Parâmetros

lpszFileName
Uma cadeia de caracteres que é o caminho para o arquivo desejado. O caminho pode ser relativo ou absoluto.

pError
Um ponteiro para um objeto de exceção de arquivo existente que indica o status de conclusão da operação.

nOpenFlags
Compartilhamento e modo de acesso. Ele especifica a ação a ser executada ao abrir o arquivo. Você pode combinar opções listadas no construtor CFile CFile::CFile usando o operador OR (|) bit a bit. São necessárias uma permissão de acesso e uma opção de compartilhamento; e os modos modeCreate e modeNoInherit são opcionais.

Valor de retorno

Um ponteiro para um objeto CFile.

CDocument::GetFirstViewPosition

Chame essa função para obter a posição da primeira exibição na lista de exibições associadas ao documento.

virtual POSITION GetFirstViewPosition() const;

Valor de retorno

Um valor POSITION que pode ser usado para iteração com a função membro GetNextView.

Exemplo

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

Chame essa função para iterar em todos os modos de exibição do documento.

virtual CView* GetNextView(POSITION& rPosition) const;

Parâmetros

rPosition
Uma referência a um valor POSITION retornado por uma chamada anterior para as funções membro GetNextView ou GetFirstViewPosition. Esse valor não deve ser NULL.

Valor de retorno

Um ponteiro para a exibição identificada por rPosition.

Comentários

A função retorna a exibição identificada por rPosition e, em seguida, define rPosition como o valor POSITION da próxima exibição na lista. Se a exibição recuperada for a última da lista, rPosition será definido como NULL.

Exemplo

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

Chame essa função para obter o caminho totalmente qualificado do arquivo de disco do documento.

const CString& GetPathName() const;

Valor de retorno

O caminho totalmente qualificado do documento. Essa cadeia de caracteres estará vazia se o documento não tiver sido salvo ou não tiver um arquivo de disco associado a ele.

CDocument::GetThumbnail

Cria um bitmap a ser usado pelo provedor de miniaturas para exibir a miniatura.

virtual BOOL GetThumbnail(
    UINT cx,
    HBITMAP* phbmp,
    DWORD* pdwAlpha);

Parâmetros

cx
Especifica a largura e a altura do bitmap.

phbmp
Contém um identificador para um bitmap, quando a função retorna com êxito.

pdwAlpha
Contem um DWORD especificando o valor do canal alfa, quando a função retorna com êxito.

Valor de retorno

Retorna TRUE se um bitmap para a miniatura foi criado com êxito; caso contrário FALSE.

Comentários

CDocument::GetTitle

Chame essa função para obter o título do documento, que geralmente é derivado do nome de arquivo do documento.

const CString& GetTitle() const;

Valor de retorno

O título do documento.

CDocument::InitializeSearchContent

Chamado para inicializar o conteúdo da pesquisa para o Manipulador de Pesquisa.

virtual void InitializeSearchContent ();

Comentários

Substitua esse método em uma classe derivada para inicializar o conteúdo da pesquisa. O conteúdo deve ser uma cadeia de caracteres com partes delimitadas por ";". Por exemplo, "ponto; retângulo; item ole".

CDocument::IsModified

Chame essa função para determinar se o documento foi modificado desde que foi salvo pela última vez.

virtual BOOL IsModified();

Valor de retorno

Diferente de zero, se o documento foi modificado desde que foi salvo pela última vez; caso contrário, 0.

CDocument::IsSearchAndOrganizeHandler

Informa se essa instância de CDocument foi criada para o manipulador Search & Organiz.

BOOL IsSearchAndOrganizeHandler() const;

Valor de retorno

Retorna TRUE se essa instância de CDocument foi criada para o manipulador Search & Organiz.

Comentários

Atualmente, essa função retorna TRUE apenas para manipuladores de visualização avançada implementados em um servidor fora do processo. Você pode definir os sinalizadores apropriados (m_bPreviewHandlerMode, m_bSearchMode, m_bGetThumbnailMode) no nível do aplicativo para fazer essa função retornar TRUE.

CDocument::LoadDocumentFromStream

Chamado para carregar dados do documento de um fluxo.

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

Parâmetros

pStream
Um ponteiro para um fluxo. Esse fluxo é fornecido pelo Shell.

dwGrfMode
Modo de acesso ao fluxo.

Valor de retorno

S_OK se a operação de carga for bem-sucedida; caso contrário, HRESULT com um código de erro.

Comentários

Você pode substituir esse método em uma classe derivada para personalizar como carregar dados do fluxo.

CDocument::m_bGetThumbnailMode

Especifica que o objeto CDocument foi criado por dllhost para miniaturas. Deve ser verificado em CView::OnDraw.

BOOL m_bGetThumbnailMode;

Comentários

TRUE indica que o documento foi criado por dllhost para miniaturas.

CDocument::m_bPreviewHandlerMode

Especifica que o objeto CDocument foi criado por prevhost para Visualização Avançada. Deve ser verificado em CView::OnDraw.

BOOL m_bPreviewHandlerMode;

Comentários

TRUE indica que o documento foi criado por prevhost para Visualização Avançada.

CDocument::m_bSearchMode

Especifica que o objeto CDocument foi criado pelo indexador por ou outro aplicativo de pesquisa.

BOOL m_bSearchMode;

Comentários

TRUE indica que o objeto foi criado pelo indexador por ou outro aplicativo de pesquisa.

CDocument::m_clrRichPreviewBackColor

Especifica a cor da tela de fundo da janela de Visualização Avançada. Essa cor é definida pelo host.

COLORREF m_clrRichPreviewBackColor;

Comentários

CDocument::m_clrRichPreviewTextColor

Especifica a cor de primeiro plano da janela de Visualização Avançada. Essa cor é definida pelo host.

COLORREF m_clrRichPreviewTextColor;

Comentários

CDocument::m_lfRichPreviewFont

Especifica a fonte de texto para a janela de Visualização Avançada. Essas informações de fonte são definidas pelo host.

CFont m_lfRichPreviewFont;

Comentários

CDocument::OnBeforeRichPreviewFontChanged

Chamado antes que a fonte de Visualização Avançada seja alterada.

virtual void OnBeforeRichPreviewFontChanged();

Comentários

CDocument::OnChangedViewList

Chamado pela estrutura depois que uma exibição é adicionada ou removida do documento.

virtual void OnChangedViewList();

Comentários

A implementação padrão dessa função verifica se a última exibição está sendo removida e, nesse caso, exclui o documento. Substitua essa função se você quiser executar um processamento especial quando a estrutura adicionar ou remover uma exibição. Por exemplo, se você quiser que um documento permaneça aberto mesmo quando não houver exibições anexadas a ele, substitua essa função.

CDocument::OnCloseDocument

Chamado pela estrutura quando o documento é fechado, normalmente como parte do comando Fechar arquivo.

virtual void OnCloseDocument();

Comentários

A implementação padrão dessa função destrói todos os quadros usados para exibir o documento, fecha a exibição, limpa o conteúdo do documento e chama a função membro DeleteContents para excluir os dados do documento.

Substitua essa função se você quiser executar processamento de limpeza especial quando a estrutura fecha um documento. Por exemplo, se o documento representa um registro em um banco de dados, talvez você queira substituir essa função para fechar o banco de dados. Você deve chamar a versão de classe base dessa função na substituição.

CDocument::OnCreatePreviewFrame

Chamado pela estrutura quando ela precisa criar um quadro de visualização para Visualização Avançada.

virtual BOOL OnCreatePreviewFrame();

Valor de retorno

Retorna TRUE se o painel foi criado com êxito; caso contrário, FALSE.

Comentários

CDocument::OnDocumentEvent

Chamado pela estrutura em resposta a um evento de documento.

virtual void OnDocumentEvent(DocumentEvent deEvent);

Parâmetros

deEvent
[in] Um tipo de dados enumerado que descreve o tipo do evento.

Comentários

Eventos de documento podem afetar várias classes. Esse método é responsável por lidar com eventos de documento que afetam classes diferentes da Classe CDocument. Atualmente, a única classe que deve responder a eventos de documento é a Classe CDataRecoveryHandler. A classe CDocument tem outros métodos substituíveis responsáveis para lidar com o efeito na CDocument.

A tabela a seguir lista os valores possíveis para deEvent e os eventos aos quais eles correspondem.

Valor	Evento correspondente
onAfterNewDocument	Um novo documento foi criado.
onAfterOpenDocument	Um novo documento foi aberto.
onAfterSaveDocument	O documento foi salvo.
onAfterCloseDocument	O documento foi fechado.

CDocument::OnDrawThumbnail

Substitua esse método em uma classe derivada para desenhar a miniatura.

virtual void OnDrawThumbnail(
    CDC& dc,
    LPRECT lprcBounds);

Parâmetros

dc
Uma referência a um contexto de dispositivo.

lprcBounds
Especifica um retângulo delimitador da área onde a miniatura deve ser desenhada.

Comentários

CDocument::OnFileSendMail

Envia uma mensagem por meio do host de email residente (se houver) com o documento como um anexo.

void OnFileSendMail();

Comentários

OnFileSendMail chama OnSaveDocument para serializar (salvar) documentos sem título e modificados em um arquivo temporário, que é enviado por email. Se o documento não tiver sido modificado, um arquivo temporário não é necessário e o original será enviado. OnFileSendMail carregará MAPI32.DLL se ainda não tiver sido carregado.

Uma implementação especial de OnFileSendMail para COleDocument lida com arquivos compostos corretamente.

CDocument dá suporte ao envio do documento por email se o suporte de email (MAPI) estiver presente. Consulte os artigos Tópicos de MAPI e Suporte a MAPI no MFC.

CDocument::OnLoadDocumentFromStream

Chamado pela estrutura quando ela precisa carregar os dados do documento de um fluxo.

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

Parâmetros

pStream
Um ponteiro para um fluxo de entrada.

grfMode
Modo de acesso ao fluxo.

Valor de retorno

S_OK se o carregamento for bem-sucedido, caso contrário, um código de erro.

Comentários

CDocument::OnNewDocument

Chamado pela estrutura como parte do comando Novo arquivo.

virtual BOOL OnNewDocument();

Valor de retorno

Diferente de zero se o documento foi inicializado com êxito; caso contrário, 0.

Comentários

A implementação padrão dessa função chama a função membro DeleteContents para garantir que o documento está e, em seguida, marca o novo documento como limpo. Substitua essa função para inicializar a estrutura de dados em um novo documento. Você deve chamar a versão de classe base dessa função na substituição.

Se o usuário escolher o comando Novo Arquivo em um aplicativo SDI, a estrutura usará essa função para reinicializar o documento existente, em vez de criar um novo. Se o usuário escolher Novo Arquivo em um aplicativo MDI (interface de vários documentos), a estrutura criará um novo documento a cada vez e chamará essa função para inicializá-lo. Você deve colocar o código de inicialização nessa função em vez de no construtor para que o comando Novo Arquivo seja eficaz em aplicativos SDI.

Observe que há casos em que OnNewDocument é chamado duas vezes. Isso ocorre quando o documento é inserido como um Servidor de Documentos ActiveX. A função é chamada pela primeira vez pelo método CreateInstance (exposto pela classe derivada de COleObjectFactory) e uma segunda vez pelo método InitNew (exposto pela classe derivada de COleServerDoc).

Exemplo

Os exemplos a seguir ilustram métodos alternativos de inicializar um objeto de documento.

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

Chamado pela estrutura como parte do comando Abrir Arquivo.

virtual BOOL OnOpenDocument(LPCTSTR lpszPathName);

Parâmetros

lpszPathName
Aponta para o caminho do documento a ser aberto.

Valor de retorno

Diferente de zero se o documento foi carregado com êxito; caso contrário, 0.

Comentários

A implementação padrão dessa função abre o arquivo especificado, chama a função membro DeleteContents para garantir que o documento está vazio, chama CObject::Serialize para ler o conteúdo do arquivo e, em seguida, marca o documento como limpo. Substitua essa função se você quiser usar algo diferente do mecanismo de arquivo ou do mecanismo de arquivo. Por exemplo, você pode gravar um aplicativo em que os documentos representam registros em um banco de dados em vez de arquivos separados.

Se o usuário escolher o comando Abrir Arquivo em um aplicativo SDI, a estrutura usará essa função para reinicializar o objeto CDocument existente, em vez de criar um novo. Se o usuário escolher Abrir Arquivo em um aplicativo MDI, a estrutura cada vez construirá um novo objeto CDocument e chamará essa função para inicializá-lo. Você deve colocar o código de inicialização nessa função em vez de no construtor para que o comando Abrir Arquivo seja eficaz em aplicativos SDI.

Exemplo

Os exemplos a seguir ilustram métodos alternativos de inicializar um objeto de documento.

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

Direciona o manipulador de visualização para retornar o HWND recuperado ao chamar a função GetFocus.

virtual HRESULT OnPreviewHandlerQueryFocus(HWND* phwnd);

Parâmetros

phwnd
[out] Quando esse método retorna, contém um ponteiro para o HWND retornado pela chamada da função GetFocus do thread em primeiro plano do manipulador de visualização.

Valor de retorno

Retorna S_OK se tiver êxito; ou retorna um valor de erro, caso contrário.

Comentários

CDocument::OnPreviewHandlerTranslateAccelerator

Direciona o manipulador de visualização para manipular um pressionamento de tecla passado da bomba de mensagem do processo no qual o manipulador de visualização está em execução.

virtual HRESULT OnPreviewHandlerTranslateAccelerator(MSG* pmsg);

Parâmetros

pmsg
[in] Um ponteiro para uma mensagem de janela.

Valor de retorno

Se a mensagem de pressionamento de tecla puder ser processada pelo manipulador de visualização, ele a processará e retornará S_OK. Se o manipulador de visualização não puder processar a mensagem de pressionamento de tecla, ele a oferecerá ao host por meio de IPreviewHandlerFrame::TranslateAccelerator. Se o host processar a mensagem, esse método retornará S_OK. Se o host não processar a mensagem, esse método retornará S_FALSE.

Comentários

CDocument::OnRichPreviewBackColorChanged

Chamado quando a cor da tela de fundo da Visualização Avançada foi alterada.

virtual void OnRichPreviewBackColorChanged();

Comentários

CDocument::OnRichPreviewFontChanged

Chamado quando a fonte da Visualização Avançada foi alterada.

virtual void OnRichPreviewFontChanged();

Comentários

CDocument::OnRichPreviewSiteChanged

Chamado quando o site da Visualização Avançada foi alterado.

virtual void OnRichPreviewSiteChanged();

Comentários

CDocument::OnRichPreviewTextColorChanged

Chamado quando a cor do texto da Visualização Avançada foi alterada.

virtual void OnRichPreviewTextColorChanged();

Comentários

CDocument::OnSaveDocument

Chamado pela estrutura como parte do comando Salvar Arquivo ou Salvar Arquivo Como.

virtual BOOL OnSaveDocument(LPCTSTR lpszPathName);

Parâmetros

lpszPathName
Aponta para o caminho totalmente qualificado em que o arquivo deve ser salvo.

Valor de retorno

Diferente de zero se o documento foi salvo com êxito; caso contrário, 0.

Comentários

A implementação padrão dessa função abre o arquivo especificado, chama CObject::Serialize para gravar os dados do documento no arquivo e, em seguida, marca o documento como limpo. Substitua essa função se você quiser executar processamento de limpeza especial quando a estrutura salva um documento. Por exemplo, você pode gravar um aplicativo em que os documentos representam registros em um banco de dados em vez de arquivos separados.

CDocument::OnUnloadHandler

Chamado pela estrutura quando o manipulador de visualização é descarregado.

virtual void OnUnloadHandler();

Comentários

CDocument::OnUpdateFileSendMail

Habilita o comando ID_FILE_SEND_MAIL se o suporte a email (MAPI) estiver presente.

void OnUpdateFileSendMail(CCmdUI* pCmdUI);

Parâmetros

pCmdUI
Um ponteiro para o objeto CCmdUI associado ao comando ID_FILE_SEND_MAIL.

Comentários

Caso contrário, a função remove o comando ID_FILE_SEND_MAIL do menu, incluindo separadores acima ou abaixo do item de menu, conforme apropriado. MAPI está habilitado se MAPI32.DLL estiver presente no caminho e, na seção [Email] do arquivo WIN.INI, MAPI=1. A maioria dos aplicativos coloca esse comando no menu Arquivo.

CDocument dá suporte ao envio do documento por email se o suporte de email (MAPI) estiver presente. Consulte os artigos Tópicos de MAPI e Suporte a MAPI no MFC.

CDocument::PreCloseFrame

Essa função membro é chamada pela estrutura antes que a janela com moldura seja destruída.

virtual void PreCloseFrame(CFrameWnd* pFrame);

Parâmetros

pFrame
Ponteiro para o CFrameWnd que contém o objeto CDocument associado.

Comentários

Ele pode ser substituído para fornecer limpeza personalizada, mas lembre-se de chamar a classe base também.

O padrão de PreCloseFrame não faz nada em CDocument. As classes derivadas de CDocumentCOleDocument e CRichEditDoc usam essa função membro.

CDocument::ReadNextChunkValue

Lê o valor da próxima parte.

virtual BOOL ReadNextChunkValue(IFilterChunkValue** ppValue);

Parâmetros

ppValue
[out] Quando a função retorna, ppValue contém o valor que foi lido.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

CDocument::ReleaseFile

Essa função membro é chamada pela estrutura para liberar um arquivo, disponibilizando-o para uso por outros aplicativos.

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

Parâmetros

pFile
Um ponteiro para o objeto CFile a ser liberado.

bAbort
Especifica se o arquivo deve ser liberado usando CFile::Close ou CFile::Abort. FALSE se o arquivo deverá ser liberado usando CFile::Close; TRUE se o arquivo deverá ser liberado usando CFile::Abort.

Comentários

Se bAbort for TRUE, ReleaseFile chamará CFile::Abort e o arquivo será liberado. CFile::Abort não lançará uma exceção.

Se bAbort for FALSE, ReleaseFile chamará CFile::Close e o arquivo será liberado.

Substitua essa função membro para exigir uma ação do usuário antes que o arquivo seja liberado.

CDocument::RemoveChunk

Remove uma parte com o GUID especificado.

virtual void RemoveChunk(
    REFCLSID guid,
    DWORD pid);

Parâmetros

Guid
Especifica o GUID de uma parte a ser removida.

Pid
Especifica o PID de uma parte a ser removida.

Comentários

CDocument::RemoveView

Chame essa função para desanexar uma exibição de um documento.

void RemoveView(CView* pView);

Parâmetros

pView
Aponta para a exibição que está sendo removida.

Comentários

Essa função remove a exibição especificada da lista de exibições associada ao documento; também define o ponteiro do documento de exibição como NULL. Essa função é chamada pela estrutura quando uma janela com moldura é fechada ou um painel de uma janela separadora é fechado.

Chame essa função somente se você estiver desanexando manualmente uma exibição. Normalmente, você permitirá que a estrutura desanexe documentos e exibições definindo um objeto CDocTemplate para associar uma classe de documento, classe de exibição e a classe de janela com moldura.

Confira o exemplo em AddView para ver uma implementação de exemplo.

CDocument::ReportSaveLoadException

Chamado se uma exceção for lançada (normalmente um CFileException ou CArchiveException) ao salvar ou carregar o documento.

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

Parâmetros

lpszPathName
Aponta para o nome do documento que estava sendo salvo ou carregado.

e
Aponta para a exceção foi lançada. Pode ser NULL.

bSaving
Sinalizador indicando qual operação estava em andamento. Diferente de zero se o documento estava sendo salvo; 0 se o documento estava sendo carregado.

nIDPDefault
Identificador da mensagem de erro a ser exibida se a função não especificar uma mais específica.

Comentários

A implementação padrão examina o objeto de exceção e procura uma mensagem de erro que descreve especificamente a causa. Se uma mensagem específica não for encontrada ou se e for NULL, a mensagem geral especificada pelo parâmetro nIDPDefault será usada. Em seguida, a função exibe uma caixa de mensagem contendo a mensagem de erro. Substitua essa função se você quiser fornecer mensagens de falha adicionais e personalizadas. Essa é uma substituição avançada.

CDocument::SaveModified

Chamado pela estrutura antes que um documento modificado seja fechado.

virtual BOOL SaveModified();

Valor de retorno

Diferente de zero se for seguro continuar e fechar o documento; 0 se o documento não deverá ser fechado.

Comentários

A implementação padrão dessa função exibe uma caixa de mensagem perguntando ao usuário se deve salvar as alterações no documento, se alguma tiver sido feita. Substitua essa função se o programa exigir um procedimento de solicitação diferente. Essa é uma substituição avançada.

CDocument::SetChunkValue

Define um valor de parte.

virtual BOOL SetChunkValue (IFilterChunkValue* pValue);

Parâmetros

pValue
Especifica um valor de parte a ser definido.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

CDocument::SetModifiedFlag

Chame essa função depois que tiver feito modificações no documento.

virtual void SetModifiedFlag(BOOL bModified = TRUE);

Parâmetros

bModified
Sinalizador indicando se o documento foi modificado.

Comentários

Ao chamar essa função de forma consistente, você garante que a estrutura solicite que o usuário salve as alterações antes de fechar um documento. Normalmente, você deve usar o valor padrão de TRUE para o parâmetro bModified. Para marcar um documento como limpo (não modificado), chame essa função com um valor de FALSE.

CDocument::SetPathName

Chame essa função para obter o caminho totalmente qualificado do arquivo de disco do documento.

virtual void SetPathName(
    LPCTSTR lpszPathName,
    BOOL bAddToMRU = TRUE);

Parâmetros

lpszPathName
Aponta para a cadeia de caracteres a ser usada como o caminho para o documento.

bAddToMRU
Determina se o nome do arquivo é adicionado à lista de arquivos MRU (usado mais recentemente). Se TRUE, o nome do arquivo foi adicionado; se FALSE, ele não foi adicionado.

Comentários

Dependendo do valor de bAddToMRU o caminho, é adicionado ou não adicionado à lista MRU mantida pelo aplicativo. Observe que alguns documentos não estão associados a um arquivo de disco. Chame essa função somente se você estiver substituindo a implementação padrão para abrir e salvar arquivos usados pela estrutura.

CDocument::SetTitle

Chame essa função para especificar o título do documento (a cadeia de caracteres exibida na barra de título de uma janela com moldura).

virtual void SetTitle(LPCTSTR lpszTitle);

Parâmetros

lpszTitle
Aponta para a cadeia de caracteres a ser usada como o título do documento.

Comentários

Chamar essa função atualiza os títulos de todas as janelas com moldura que exibem o documento.

CDocument::UpdateAllViews

Chame essa função após o documento ter sido modificado.

void UpdateAllViews(
    CView* pSender,
    LPARAM lHint = 0L,
    CObject* pHint = NULL);

Parâmetros

pSender
Aponta para a exibição que modificou o documento ou para NULL se todas as exibições devem ser atualizadas.

lHint
Contém informações sobre a modificação.

pHint
Aponta para um objeto que armazena informações sobre a modificação.

Comentários

Você deve chamar essa função depois de chamar a função membro SetModifiedFlag. Essa função informa em cada exibição anexada ao documento, exceto a exibição especificada por pSender, que o documento foi modificado. Normalmente, você chama essa função pela classe de exibição depois que o usuário altera o documento por meio de uma exibição.

Essa função chama a função membro CView::OnUpdate para cada uma das exibições do documento, exceto a exibição de envio, passando pHint e lHint. Use esses parâmetros para passar informações para as exibições sobre as modificações feitas no documento. É possível codificar informações usando lHint e/ou você pode definir uma classe derivada de CObject para armazenar informações sobre as modificações e passar um objeto dessa classe usando pHint. Substitua a função membro CView::OnUpdate na classe derivada de CView para otimizar a atualização da exibição do modo de exibição com base nas informações passadas.

Exemplo

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

Confira também

Exemplo de MFC MDIDOCVW
Exemplo de MFC SNAPVW
Exemplo de MFC NPP
Classe CCmdTarget
Gráfico da hierarquia
Classe CCmdTarget
Classe CView
Classe CDocTemplate