COleDocument Classe

A classe base para documentos OLE que suportam edição visual.

Sintaxe

class COleDocument : public CDocument

Membros

Construtores Públicos

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

Métodos Públicos

Designação	Descrição
COleDocument::AddItem	Adiciona um item à lista de itens mantidos pelo documento.
COleDocument::ApplyPrintDevice	Define o dispositivo de destino de impressão para todos os itens do cliente no documento.
COleDocument::EnableCompoundFile	Faz com que os documentos sejam armazenados usando o formato de arquivo OLE Structured Storage.
COleDocument::GetInPlaceActiveItem	Retorna o item OLE que está ativo no momento.
COleDocument::GetNextClientItem	Obtém o próximo item de cliente para iteração.
COleDocument::GetNextItem	Obtém o próximo item de documento para iteração.
COleDocument::GetNextServerItem	Obtém o próximo item de servidor para iteração.
COleDocument::GetPrimarySelectedItem	Retorna o item OLE selecionado primário 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 pelo documento.
COleDocument::UpdateModifiedFlag	Marca o documento como modificado se algum dos itens OLE contidos tiver sido modificado.

Métodos Protegidos

Designação	Descrição
COleDocument::OnEditChangeIcon	Manipula eventos no comando de menu Alterar ícone.
COleDocument::OnEditConvert	Manipula a conversão de um objeto incorporado ou vinculado de um tipo para outro.
COleDocument::OnEditLinks	Manipula eventos no comando Links no menu Editar.
COleDocument::OnFileSendMail	Envia uma mensagem de correio com o documento anexado.
COleDocument::OnUpdateEditChangeIcon	Chamado pela estrutura para atualizar a interface do usuário do comando para a opção de menu Editar/Alterar ícone.
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 o comando UI para a opção de menu Edit/ ObjectName e o submenu Verb acessado de Edit/ 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 do CDocument, que permite que seus aplicativos OLE usem a arquitetura de documento/exibição fornecida pela Microsoft Foundation Class Library.

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

Se você estiver escrevendo um aplicativo de contêiner simples, derive sua classe de documento de COleDocument. Se você estiver escrevendo um aplicativo de contêiner que ofereça suporte à vinculação aos itens incorporados contidos por seus documentos, derive sua classe de documento de COleLinkingDoc . Se você estiver escrevendo 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 incorporados ou vinculados. Se você definir CDocItemclasses derivadas para armazenar os dados nativos do aplicativo, poderá usar a implementação padrão definida por COleDocument para armazenar seus dados OLE e não OLE. Você também pode projetar 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 Containers: Compound Files.

CDocument suporta o envio do seu documento por correio se o suporte por correio (MAPI) estiver presente. COleDocument atualizou OnFileSendMail para lidar com documentos compostos corretamente. Para obter mais informações, consulte os artigos MAPI e Suporte MAPI no MFC.

Hierarquia de herança

CObject

CCmdTarget

CDocument

COleDocument

Requerimentos

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 de COleClientItem incorporados no documento de contêiner do seu 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

Esta função atualiza o dispositivo de destino de impressão para todos os itens, mas não atualiza o cache de apresentação para esses 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 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 obter mais informações, consulte a estrutura de PRINTDLG no SDK do Windows.

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

COleDocument::COleDocument

Constrói um objeto COleDocument.

COleDocument();

COleDocument::EnableCompoundFile

Chame essa função se quiser armazenar o documento usando o formato de arquivo composto.

void EnableCompoundFile(BOOL bEnable = TRUE);

Parâmetros

bAtivar
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 do COleDocument. Para obter mais informações sobre documentos compostos, consulte o artigo Containers: Compound Files.

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

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

COleDocument::GetInPlaceActiveItem

Chame essa função para obter o item OLE que está atualmente ativado no lugar na janela de quadro que contém a exibição identificada 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 único item OLE ativo in-loco; NULL se não houver nenhum item OLE atualmente no estado "ativo in-loco".

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 de membro GetStartPosition.

Valor de retorno

Um ponteiro para o próximo item de 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 do 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 do 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 de membro GetStartPosition.

Valor de retorno

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

Comentários

Após cada chamada, o valor de pos é definido como o valor POSITION do próximo item do 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 do 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 de membro GetStartPosition.

Valor de retorno

Um ponteiro para o próximo item de 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 do 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 atualmente no modo de exibição especificado.

virtual COleClientItem* GetPrimarySelectedItem(CView* pView);

Parâmetros

pView
Ponteiro para o objeto de exibição ativo que exibe o documento.

Valor de retorno

Um ponteiro para o único item OLE selecionado; 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 de 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 pelos itens do documento; NULL se o documento não tiver itens.

Comentários

Passe o valor retornado para GetNextItem, GetNextClientItemou GetNextServerItem.

COleDocument::HasBlankItems

Chame essa função para determinar se o documento contém itens 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 Alterar ícone OLE e altera o ícone que representa o item OLE selecionado atualmente 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 COleChangeIconDialog Alterar ícone.

COleDocument::OnEditConvert

Exibe a caixa de diálogo Converter OLE e converte ou ativa o item OLE selecionado atualmente de acordo com as seleções de 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 OLE Editar/Links.

afx_msg void OnEditLinks();

Comentários

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

COleDocument::OnFileSendMail

Envia uma mensagem através do host de e-mail residente (se houver) com o documento como 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 correio eletrônico. Se o documento não tiver sido modificado, não é necessário um ficheiro temporário; o original é enviado. OnFileSendMail carrega MAPI32.DLL se ainda não tiver sido carregada.

Ao contrário da implementação do OnFileSendMail para CDocument, esta função lida com arquivos compostos corretamente.

Para obter mais informações, consulte os tópicos MAPI e MAPI Support in MFC artigos.

COleDocument::OnShowViews

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

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 desta função não faz nada. Substitua-o se o seu aplicativo precisar executar qualquer processamento especial quando a visibilidade do documento mudar.

COleDocument::OnUpdateEditChangeIcon

Chamado pela estrutura para atualizar o comando Alterar ícone 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 update. O manipulador de atualização chama a função de 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 da existência ou não de 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 update. O manipulador de atualização chama a função de membro Enable da estrutura CCmdUI por meio de pCmdUI para atualizar a interface do usuário.

Comentários

A partir do primeiro item OLE do documento, OnUpdateEditLinksMenu acessa cada item, testa se o item é um link e, se for um link, 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 a partir do comando ObjectName, onde ObjectName é o nome do objeto OLE incorporado 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 update. O manipulador de atualização chama a função de 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 da existência ou não de um objeto válido no documento. Se existir um objeto, o comando ObjectName no menu Editar está habilitado. Quando este comando de menu é selecionado, o submenu Verbo é exibido. O submenu Verbo contém todos os comandos verbais 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 update. O manipulador de atualização chama a função de 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á ativado ou desativado dependendo se o item pode ser colado no documento ou não.

COleDocument::OnUpdatePasteMenu

Chamado pela estrutura para determinar se um item OLE incorporado 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 update. O manipulador de atualização chama a função de membro Enable da estrutura CCmdUI por meio de pCmdUI para atualizar a interface do usuário.

Comentários

O comando e o botão do menu Colar são ativados ou desativados dependendo se o item pode ser colado no documento ou não.

COleDocument::RemoveItem

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

virtual void RemoveItem(CDocItem* pItem);

Parâmetros

pItem
Ponteiro para o item de documento a ser removido.

Comentários

Normalmente, não é necessário chamar essa função explicitamente; é chamado pelos destruidores de COleClientItem e COleServerItem.

COleDocument::UpdateModifiedFlag

Chame essa função para marcar o documento como modificado se algum dos itens OLE contidos tiver sido modificado.

virtual void UpdateModifiedFlag();

Comentários

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

Ver também

Recipiente de amostras MFC
Exemplo MFC MFCBIND
CDocument Classe
Gráfico de Hierarquia