Classe COleDocument

A classe base para documentos OLE que dão suporte à edição visual.

Sintaxe

class COleDocument : public CDocument

Membros

Construtores públicos

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

Métodos públicos

Nome	Descrição
COleDocument::AddItem	Adiciona um item à lista de itens mantidos no documento.
COleDocument::ApplyPrintDevice	Define o dispositivo de destino de impressão para todos os itens de cliente no documento.
COleDocument::EnableCompoundFile	Faz com que os documentos sejam armazenados usando o formato de arquivo de Armazenamento Estruturado de OLE.
COleDocument::GetInPlaceActiveItem	Retorna o item OLE que está ativo no local atualmente.
COleDocument::GetNextClientItem	Obtém o próximo item do cliente para iteração.
COleDocument::GetNextItem	Obtém o próximo item do documento para iteração.
COleDocument::GetNextServerItem	Obtém o próximo item de servidor para iteração.
COleDocument::GetPrimarySelectedItem	Retorna o item OLE selecionado primariamente no documento.
COleDocument::GetStartPosition	Obtém a posição inicial para iniciar a iteração.
COleDocument::HasBlankItems	Verifica se há itens em branco no documento.
COleDocument::OnShowViews	Chamado quando o documento se torna visível ou invisível.
COleDocument::RemoveItem	Remove um item da lista de itens mantidos no documento.
COleDocument::UpdateModifiedFlag	Marca o documento como modificado se algum dos itens OLE contidos foram modificados.

Métodos protegidos

Nome	Descrição
COleDocument::OnEditChangeIcon	Identifica eventos no comando de menu Ícone de Alteração.
COleDocument::OnEditConvert	Identifica a conversão de um objeto inserido ou vinculado de um tipo para outro.
COleDocument::OnEditLinks	Identifica eventos no comando Links no menu Editar.
COleDocument::OnFileSendMail	Envia uma mensagem de email com o documento anexado.
COleDocument::OnUpdateEditChangeIcon	Chamado pela estrutura para atualizar a interface do usuário do comando para a opção de menu Ícone Editar/Alterar.
COleDocument::OnUpdateEditLinksMenu	Chamado pela estrutura para atualizar a interface do usuário do comando para a opção de menu Editar/Links.
COleDocument::OnUpdateObjectVerbMenu	Chamado pela estrutura para atualizar a interface do usuário de comando para a opção de menu Editar/ ObjectName e o submenu Verbo acessado de Editar/ ObjectName.
COleDocument::OnUpdatePasteLinkMenu	Chamado pela estrutura para atualizar a interface do usuário do comando para a opção de menu Colar Especial.
COleDocument::OnUpdatePasteMenu	Chamado pela estrutura para atualizar a interface do usuário do comando para a opção de menu Colar.

Comentários

COleDocument é derivado de CDocument, o que permite que seus aplicativos OLE usem a arquitetura de documento/exibição fornecida pela biblioteca Microsoft Foundation Class.

COleDocument trata um documento como uma coleção de objetos CDocItem para tratar itens OLE. Os aplicativos de contêiner e de servidor exigem essa arquitetura porque seus documentos devem ser capazes de conter itens OLE. As classes COleServerItem e COleClientItemderivadas de CDocItem, gerenciam as interações entre aplicativos e itens OLE.

Se você estiver gravando um aplicativo de contêiner simples, derive sua classe de documento de COleDocument. Se você estiver gravando um aplicativo de contêiner que dá suporte à vinculação aos itens inseridos contidos em seus documentos, derive sua classe de documento de COleLinkingDoc. Se você estiver gravando um aplicativo de servidor ou um contêiner/servidor de combinação, derive sua classe de documento de COleServerDoc. COleLinkingDoc e COleServerDoc são derivados de COleDocument, portanto, essas classes herdam todos os serviços disponíveis em COleDocument e CDocument.

Para usar COleDocument, derive uma classe dele e adicione funcionalidade para gerenciar os dados não OLE do aplicativo, bem como itens inseridos ou vinculados. Se você definir que CDocItemclasses derivadas armazenem os dados nativos do aplicativo, é possível usar a implementação padrão definida por COleDocument para armazenar os dados OLE e não OLE. Você também pode criar suas próprias estruturas de dados para armazenar seus dados não OLE separadamente dos itens OLE. Para obter mais informações, consulte o artigo Contêineres: arquivos compostos.

CDocument dá suporte ao envio do documento por email se o suporte de email (MAPI) estiver presente. COleDocument atualizou o OnFileSendMail para tratar documentos compostos corretamente. Para obter mais informações, consulte os artigos MAPI e Suporte ao MAPI no MFC.

Hierarquia de herança

CObject

CCmdTarget

CDocument

COleDocument

Requisitos

Cabeçalho: afxole.h

COleDocument::AddItem

Chame essa função para adicionar um item ao documento.

virtual void AddItem(CDocItem* pItem);

Parâmetros

pItem
Ponteiro para o item de documento que está sendo adicionado.

Comentários

Você não precisa chamar essa função explicitamente quando ela é chamada pelo construtor COleClientItem ou COleServerItem que aceita um ponteiro para um documento.

COleDocument::ApplyPrintDevice

Chame essa função para alterar o dispositivo de destino de impressão para todos os itens COleClientItem inseridos no documento de contêiner do aplicativo.

BOOL ApplyPrintDevice(const DVTARGETDEVICE* ptd);
BOOL ApplyPrintDevice(const PRINTDLG* ppd);

Parâmetros

ptd
Ponteiro para uma estrutura de dados DVTARGETDEVICE, que contém informações sobre o novo dispositivo de destino de impressão. Pode ser NULL.

ppd
Ponteiro para uma estrutura de dados PRINTDLG, que contém informações sobre o novo dispositivo de destino de impressão. Pode ser NULL.

Valor de retorno

Diferente de zero se a função foi bem-sucedida, caso contrário, 0.

Comentários

Essa função atualiza o dispositivo de destino de impressão para todos os itens, mas não atualiza o cache de apresentação desses itens. Para atualizar o cache de apresentação de um item, chame COleClientItem::UpdateLink.

Os argumentos para essa função contêm informações que o OLE usa para identificar o dispositivo de destino. A estrutura PRINTDLG contém informações que o Windows usa para inicializar a caixa de diálogo Imprimir comum. Depois que o usuário fecha a caixa de diálogo, o Windows retorna informações sobre as seleções do usuário nessa estrutura. O membro m_pd de um objeto CPrintDialog é uma estrutura PRINTDLG.

Para mais informações, confira a estrutura PRINTDLG no SDK do Windows.

Para mais informações, confira a estrutura DVTARGETDEVICE no SDK do Windows.

COleDocument::COleDocument

Constrói um objeto COleDocument.

COleDocument();

COleDocument::EnableCompoundFile

Chame essa função se você desejar armazenar o documento usando o formato de arquivo composto.

void EnableCompoundFile(BOOL bEnable = TRUE);

Parâmetros

bEnable
Especifica se o suporte a arquivos compostos está habilitado ou desabilitado.

Comentários

Isso também é chamado de armazenamento estruturado. Normalmente, você chama essa função do construtor de sua classe derivada COleDocument. Para obter mais informações sobre documentos compostos, consulte o artigo Contêineres: arquivos compostos.

Se você não chamar essa função de membro, os documentos serão armazenados em um formato de arquivo não estruturado ("simples").

Depois que o suporte a arquivos compostos estiver habilitado ou desabilitado para um documento, a configuração não deve ser alterada durante o tempo de vida do documento.

COleDocument::GetInPlaceActiveItem

Chame essa função para obter o item OLE que está ativado no momento na janela de quadros que contém o modo de exibição identificado por pWnd.

virtual COleClientItem* GetInPlaceActiveItem(CWnd* pWnd);

Parâmetros

pWnd
Ponteiro para a janela que exibe o documento do contêiner.

Valor de retorno

Um ponteiro para o item OLE ativo único e no local e NULL se não houver nenhum item OLE no estado "ativo no local" no momento.

COleDocument::GetNextClientItem

Chame essa função repetidamente para acessar cada um dos itens do cliente em seu documento.

COleClientItem* GetNextClientItem(POSITION& pos) const;

Parâmetros

pos
Uma referência a um valor POSITION definido por uma chamada anterior para GetNextClientItem. O valor inicial é retornado pela função membro GetStartPosition.

Valor de retorno

Um ponteiro para o próximo item do cliente no documento ou NULL se não houver mais itens de cliente.

Comentários

Após cada chamada, o valor de pos é definido para o próximo item no documento, que pode ou não ser um item de cliente.

Exemplo

// pDoc points to a COleDocument object
POSITION pos = pDoc->GetStartPosition();
COleClientItem* pItem;
CString strType;
while ((pItem = pDoc->GetNextClientItem(pos)) != NULL)
{
   // Use pItem
   pItem->GetUserType(USERCLASSTYPE_FULL, strType);
   TRACE(strType);
}

COleDocument::GetNextItem

Chame essa função repetidamente para acessar cada um dos itens em seu documento.

virtual CDocItem* GetNextItem(POSITION& pos) const;

Parâmetros

pos
Uma referência a um valor POSITION definido por uma chamada anterior para GetNextItem. O valor inicial é retornado pela função membro GetStartPosition.

Valor de retorno

Um ponteiro para o item do documento na posição especificada.

Comentários

Após cada chamada, o valor de pos é definido como o valor POSITION do próximo item no documento. Se o elemento recuperado for o último elemento no documento, o novo valor de pos será NULL.

Exemplo

// pDoc points to a COleDocument object
POSITION pos = pDoc->GetStartPosition();
CDocItem* pItem;
CString strType;
while (pos != NULL)
{
   pItem = pDoc->GetNextItem(pos);
   // Use pItem
   if (pItem->IsKindOf(RUNTIME_CLASS(COleClientItem)))
   {
      ((COleClientItem*)pItem)->GetUserType(USERCLASSTYPE_FULL, strType);
      TRACE(strType);
   }
}

COleDocument::GetNextServerItem

Chame essa função repetidamente para acessar cada um dos itens de servidor em seu documento.

COleServerItem* GetNextServerItem(POSITION& pos) const;

Parâmetros

pos
Uma referência a um valor POSITION definido por uma chamada anterior para GetNextServerItem. O valor inicial é retornado pela função membro GetStartPosition.

Valor de retorno

Um ponteiro para o próximo item do servidor no documento ou NULL se não houver mais itens de servidor.

Comentários

Após cada chamada, o valor de pos é definido para o próximo item no documento, que pode ou não ser um item de servidor.

Exemplo

// pDoc points to a COleDocument object
POSITION pos = pDoc->GetStartPosition();
COleServerItem* pItem;
while ((pItem = pDoc->GetNextServerItem(pos)) != NULL)
{
   // Use pItem
}

COleDocument::GetPrimarySelectedItem

Chamado pela estrutura para recuperar o item OLE selecionado no momento no modo de exibição especificado.

virtual COleClientItem* GetPrimarySelectedItem(CView* pView);

Parâmetros

pView
Ponteiro para o objeto de exibição ativa exibindo o documento.

Valor de retorno

Um ponteiro para o único item OLE selecionado e NULL se nenhum item OLE estiver selecionado ou se mais de um estiver selecionado.

Comentários

A implementação padrão pesquisa a lista de itens OLE contidos para um único item selecionado e retorna um ponteiro para ele. Se não houver nenhum item selecionado ou se houver mais de um item selecionado, a função retornará NULL. Você deve substituir a função membro CView::IsSelected em sua classe de exibição para que essa função funcione. Substitua essa função se você tiver seu próprio método de armazenar itens OLE contidos.

COleDocument::GetStartPosition

Chame essa função para obter a posição do primeiro item no documento.

virtual POSITION GetStartPosition() const;

Valor de retorno

Um valor POSITION que pode ser usado para começar a iterar por meio dos itens do documento e NULL se o documento não tiver itens.

Comentários

Passar o valor retornado para GetNextItem, GetNextClientItem ou GetNextServerItem.

COleDocument::HasBlankItems

Chame essa função para determinar se o documento contém algum item em branco.

BOOL HasBlankItems() const;

Valor de retorno

Diferente de zero se o documento contiver itens em branco. Caso contrário, 0.

Comentários

Um item em branco é aquele cujo retângulo está vazio.

COleDocument::OnEditChangeIcon

Exibe a caixa de diálogo Ícone de Alteração OLE e altera o ícone que representa o item OLE selecionado no momento para o ícone que o usuário seleciona na caixa de diálogo.

afx_msg void OnEditChangeIcon();

Comentários

OnEditChangeIcon cria e inicia uma caixa de diálogo Ícone de Alteração COleChangeIconDialog.

COleDocument::OnEditConvert

Exibe a caixa de diálogo Converter OLE e converte ou ativa o item OLE selecionado no momento de acordo com as seleções do usuário na caixa de diálogo.

afx_msg void OnEditConvert();

Comentários

OnEditConvert cria e inicia uma caixa de diálogo Converter COleConvertDialog.

Um exemplo de conversão é converter um documento do Microsoft Word em um documento do WordPad.

COleDocument::OnEditLinks

Exibe a caixa de diálogo Editar/Links do OLE.

afx_msg void OnEditLinks();

Comentários

OnEditLinks cria e inicia uma caixa de diálogo Links COleLinksDialog que permite que o usuário altere os objetos vinculados.

COleDocument::OnFileSendMail

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

afx_msg 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.

Ao contrário da implementação de OnFileSendMail for CDocument, essa função trata corretamente arquivos compostos.

Para obter mais informações, consulte os artigos Tópicos MAPI e Suporte ao MAPI no MFC.

COleDocument::OnShowViews

A estrutura chama essa função depois que o estado de visibilidade do documento é alterado.

virtual void OnShowViews(BOOL bVisible);

Parâmetros

bVisible
Indica se o documento se tornou visível ou invisível.

Comentários

A versão padrão dessa função não faz nada. Substitua ela se o aplicativo precisar executar um processamento especial quando a visibilidade do documento for alterada.

COleDocument::OnUpdateEditChangeIcon

Chamado pela estrutura para atualizar o comando Ícone de Alteração no menu Editar.

afx_msg void OnUpdateEditChangeIcon(CCmdUI* pCmdUI);

Parâmetros

pCmdUI
Um ponteiro para uma estrutura CCmdUI que representa o menu que gerou o comando de atualização. O identificador de atualização chama a função membro Enable da estrutura CCmdUI por meio de pCmdUI para atualizar a interface do usuário.

Comentários

OnUpdateEditChangeIcon atualiza a interface do usuário do comando dependendo se existe ou não um ícone válido no documento. Substitua essa função para alterar o comportamento.

COleDocument::OnUpdateEditLinksMenu

Chamado pela estrutura para atualizar o comando Links no menu Editar.

afx_msg void OnUpdateEditLinksMenu(CCmdUI* pCmdUI);

Parâmetros

pCmdUI
Um ponteiro para uma estrutura CCmdUI que representa o menu que gerou o comando de atualização. O identificador de atualização chama a função membro Enable da estrutura CCmdUI por meio de pCmdUI para atualizar a interface do usuário.

Comentários

A partir do primeiro item OLE no documento, OnUpdateEditLinksMenu acessa cada item, testa se o item é um link e, caso seja, habilita o comando Links. Substitua essa função para alterar o comportamento.

COleDocument::OnUpdateObjectVerbMenu

Chamado pela estrutura para atualizar o comando ObjectName no menu Editar e no submenu Verbo acessado do comando ObjectName, em que ObjectName é o nome do objeto OLE inserido no documento.

afx_msg void OnUpdateObjectVerbMenu(CCmdUI* pCmdUI);

Parâmetros

pCmdUI
Um ponteiro para uma estrutura CCmdUI que representa o menu que gerou o comando de atualização. O identificador de atualização chama a função membro Enable da estrutura CCmdUI por meio de pCmdUI para atualizar a interface do usuário.

Comentários

OnUpdateObjectVerbMenu atualiza a interface do usuário do comando ObjectName dependendo se existe ou não um objeto válido no documento. Se existe um objeto, o comando ObjectName no menu Editar é habilitado. Quando esse comando de menu é selecionado, é exibido o submenu Verbo. O submenu Verbo contém todos os comandos de verbo disponíveis para o objeto, como Editar, Propriedades e assim por diante. Substitua essa função para alterar o comportamento.

COleDocument::OnUpdatePasteLinkMenu

Chamado pela estrutura para determinar se um item OLE vinculado pode ser colado da área de transferência.

afx_msg void OnUpdatePasteLinkMenu(CCmdUI* pCmdUI);

Parâmetros

pCmdUI
Um ponteiro para uma estrutura CCmdUI que representa o menu que gerou o comando de atualização. O identificador de atualização chama a função membro Enable da estrutura CCmdUI por meio de pCmdUI para atualizar a interface do usuário.

Comentários

O comando de menu Colar Especial está habilitado ou desabilitado, dependendo se o item pode ser colado ou não no documento.

COleDocument::OnUpdatePasteMenu

Chamado pela estrutura para determinar se um item OLE inserido pode ser colado da área de transferência.

afx_msg void OnUpdatePasteMenu(CCmdUI* pCmdUI);

Parâmetros

pCmdUI
Um ponteiro para uma estrutura CCmdUI que representa o menu que gerou o comando de atualização. O identificador de atualização chama a função membro Enable da estrutura CCmdUI por meio de pCmdUI para atualizar a interface do usuário.

Comentários

O comando e botão de menu Colar está habilitado ou desabilitado, dependendo se o item pode ser colado ou não no documento.

COleDocument::RemoveItem

Chame essa função para remover um item do documento.

virtual void RemoveItem(CDocItem* pItem);

Parâmetros

pItem
Ponteiro para o item do documento a ser removido.

Comentários

Normalmente, você não precisa chamar essa função explicitamente, ela é chamada pelos destruidores para COleClientItem e COleServerItem.

COleDocument::UpdateModifiedFlag

Chame essa função para marca o documento como modificado se algum dos itens OLE contidos foram modificados.

virtual void UpdateModifiedFlag();

Comentários

Isso permite que a estrutura solicite ao usuário que salve o documento antes de fechar, mesmo se os dados nativos no documento não tiverem sido modificados.

Confira também

CONTÊINER de exemplo do MFC
MFCBIND de exemplo do MFC
Classe CDocument
Gráfico da hierarquia