Classe COleClientItem

Define a interface do contêiner para itens OLE.

Sintaxe

class COleClientItem : public CDocItem

Membros

Construtores públicos

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

Métodos públicos

Nome	Descrição
COleClientItem::Activate	Abre o item OLE para uma operação e, em seguida, executa o verbo especificado.
COleClientItem::ActivateAs	Ativa o item como outro tipo.
COleClientItem::AttachDataObject	Acessa os dados no objeto OLE.
COleClientItem::CanCreateFromData	Indica se um aplicativo de contêiner pode criar um objeto inserido.
COleClientItem::CanCreateLinkFromData	Indica se um aplicativo de contêiner pode criar um objeto vinculado.
COleClientItem::CanPaste	Indica se a Área de Transferência contém um item OLE inserível ou estático.
COleClientItem::CanPasteLink	Indica se a Área de Transferência contém um item OLE vinculável.
COleClientItem::Close	Fecha um link para um servidor, mas não destrói o item OLE.
COleClientItem::ConvertTo	Converte o item em outro tipo.
COleClientItem::CopyToClipboard	Copia o item OLE para a Área de Transferência.
COleClientItem::CreateCloneFrom	Cria uma duplicata de um item existente.
COleClientItem::CreateFromClipboard	Cria um item inserido da Área de Transferência.
COleClientItem::CreateFromData	Cria um item inserido de um objeto de dados.
COleClientItem::CreateFromFile	Cria um item inserido de um arquivo.
COleClientItem::CreateLinkFromClipboard	Cria um item vinculado da Área de Transferência.
COleClientItem::CreateLinkFromData	Cria um item vinculado de um objeto de dados.
COleClientItem::CreateLinkFromFile	Cria um item vinculado de um arquivo.
COleClientItem::CreateNewItem	Cria um item inserido iniciando o aplicativo para servidores.
COleClientItem::CreateStaticFromClipboard	Cria um item estático da Área de Transferência.
COleClientItem::CreateStaticFromData	Cria um item estático de um objeto de dados.
COleClientItem::Deactivate	Desativa o item.
COleClientItem::DeactivateUI	Restaura a interface do usuário do aplicativo de contêiner para o estado original.
COleClientItem::Delete	Exclui ou fecha o item OLE se ele for um item vinculado.
COleClientItem::DoDragDrop	Executa uma operação arrastar e soltar.
COleClientItem::DoVerb	Executa o verbo especificado.
COleClientItem::Draw	Desenha o item OLE.
COleClientItem::GetActiveView	Obtém a exibição na qual o item é ativado no local.
COleClientItem::GetCachedExtent	Retorna os limites do retângulo do item OLE.
COleClientItem::GetClassID	Obtém a ID da classe do item atual.
COleClientItem::GetClipboardData	Obtém os dados que seriam colocados na Área de Transferência chamando a função membro CopyToClipboard.
COleClientItem::GetDocument	Retorna o objeto COleDocument que contém o item atual.
COleClientItem::GetDrawAspect	Obtém a exibição atual do item para renderização.
COleClientItem::GetExtent	Retorna os limites do retângulo do item OLE.
COleClientItem::GetIconFromRegistry	Recupera um identificador para um ícone associado ao servidor de um CLSID específico.
COleClientItem::GetIconicMetafile	Obtém o meta-arquivo usado para desenhar o ícone do item.
COleClientItem::GetInPlaceWindow	Retorna um ponteiro para a janela de edição in-loco do item.
COleClientItem::GetItemState	Obtém o estado atual do item.
COleClientItem::GetLastStatus	Retorna o status da última operação OLE.
COleClientItem::GetLinkUpdateOptions	Retorna a atualização de um item vinculado (recurso avançado).
COleClientItem::GetType	Retorna o tipo (inserido, vinculado ou estático) do item OLE.
COleClientItem::GetUserType	Obtém uma cadeia de caracteres que descreve o tipo do item.
COleClientItem::IsInPlaceActive	Retorna TRUE se o item está ativo in-loco.
COleClientItem::IsLinkUpToDate	Retorna TRUE se um item vinculado está atualizado com o respectivo documento de origem.
COleClientItem::IsModified	Retorna TRUE se o item foi modificado desde que foi salvo pela última vez.
COleClientItem::IsOpen	Retorna TRUE se o item está aberto no aplicativo para servidores no momento.
COleClientItem::IsRunning	Retorna TRUE se o aplicativo para servidores do item está em execução.
COleClientItem::OnActivate	Chamada pela estrutura para notificar o item de que ele está ativado.
COleClientItem::OnActivateUI	Chamada pela estrutura para notificar o item de que ele está ativado e deve mostrar a respectiva interface do usuário.
COleClientItem::OnChange	Chamada quando o servidor altera o item OLE. Implementação exigida.
COleClientItem::OnDeactivate	Chamada pela estrutura quando um item é desativado.
COleClientItem::OnDeactivateUI	Chamada pela estrutura quando o servidor removeu a interface de usuário in-loco correspondente.
COleClientItem::OnGetClipboardData	Chamada pela estrutura para obter os dados a serem copiados para a Área de Transferência.
COleClientItem::OnInsertMenus	Chamada pela estrutura para criar um menu composto.
COleClientItem::OnRemoveMenus	Chamada pela estrutura para remover os menus do contêiner de um menu composto.
COleClientItem::OnSetMenu	Chamada pela estrutura para instalar e remover um menu composto.
COleClientItem::OnShowControlBars	Chamada pela estrutura para mostrar e ocultar barras de controle.
COleClientItem::OnUpdateFrameTitle	Chamada pela estrutura para atualizar a barra de título da janela do quadro.
COleClientItem::ReactivateAndUndo	Reativa o item e desfaz a última operação de edição in-loco.
COleClientItem::Release	Libera a conexão com um item vinculado OLE e fecha-a se ela estava aberta. Não destrói o item do cliente.
COleClientItem::Reload	Recarrega o item após uma chamada para ActivateAs.
COleClientItem::Run	Executa o aplicativo associado ao item.
COleClientItem::SetDrawAspect	Define o modo de exibição atual do item para renderização.
COleClientItem::SetExtent	Define o retângulo delimitador do item OLE.
COleClientItem::SetHostNames	Define os nomes exibidos pelo servidor ao editar o item OLE.
COleClientItem::SetIconicMetafile	Armazena em cache o meta-arquivo usado para desenhar o ícone do item.
COleClientItem::SetItemRects	Define o retângulo delimitador do item.
COleClientItem::SetLinkUpdateOptions	Define o modo de atualização para um item vinculado (recurso avançado).
COleClientItem::SetPrintDevice	Define o dispositivo de destino de impressão para este item cliente.
COleClientItem::UpdateLink	Atualiza o cache de apresentação de um item.

Métodos protegidos

Nome	Descrição
COleClientItem::CanActivate	Chamada pela estrutura para determinar se a ativação in-loco é permitida.
COleClientItem::OnChangeItemPosition	Chamada pela estrutura quando a posição de um item é alterada.
COleClientItem::OnDeactivateAndUndo	Chamada pela estrutura para desfazer após a ativação.
COleClientItem::OnDiscardUndoState	Chamada pela estrutura para descartar as informações de estado de undo do item.
COleClientItem::OnGetClipRect	Chamada pela estrutura para obter as coordenadas de retângulo de recorte do item.
COleClientItem::OnGetItemPosition	Chamada pela estrutura para obter a posição do item em relação à exibição.
COleClientItem::OnGetWindowContext	Chamada pela estrutura quando um item é ativado no local.
COleClientItem::OnScrollBy	Chamada pela estrutura para rolar o item para exibição.
COleClientItem::OnShowItem	Chamada pela estrutura para exibir o item OLE.

Comentários

Um item OLE representa dados, criados e mantidos por um aplicativo para servidores, que podem ser incorporados "perfeitamente" em um documento para que eles tenham aparência consistente. O resultado é um "documento composto", constituído pelo item OLE e um documento que o contém.

Um item OLE pode ser inserido ou vinculado. Se ele for inserido, os dados dele serão armazenados como parte do documento composto. Se ele for vinculado, os dados dele serão armazenados como parte de um arquivo separado criado pelo aplicativo para servidores e apenas um link para esse arquivo será armazenado no documento composto. Todos os itens OLE contêm informações que especificam o aplicativo para servidores que deve ser chamado para editá-los.

COleClientItem define várias funções substituíveis que são chamadas em resposta a solicitações do aplicativo para servidores; essas substituições geralmente atuam como notificações. Isso permite que o aplicativo para servidores informe o contêiner de alterações feitas pelo usuário ao editar o item OLE ou recuperar as informações necessárias durante a edição.

COleClientItem pode ser usado com a classe COleDocument, COleLinkingDoc ou COleServerDoc. Para usar COleClientItem, derive uma classe dela e implemente a função membro OnChange, que define como o contêiner responde às alterações feitas no item. Para dar suporte à ativação in-loco, substitua a função membro OnGetItemPosition. Essa função fornece informações sobre a posição exibida do item OLE.

Para obter mais informações sobre como usar a interface do contêiner, consulte os artigos Contêineres: implementando um contêiner e Ativação.

Observação

O SDK do Windows refere-se a itens inseridos e vinculados como "objetos" e se refere a tipos de itens como "classes". Essa referência usa o termo "item" para distinguir a entidade OLE do objeto C++ correspondente e o termo "tipo" para distinguir a categoria OLE da classe C++.

Hierarquia de herança

CObject

CCmdTarget

CDocItem

COleClientItem

Requisitos

Cabeçalho: afxole.h

COleClientItem::Activate

Chame essa função para executar o verbo especificado em vez de DoVerb para que você possa fazer seu processamento quando uma exceção for gerada.

void Activate(
    LONG nVerb,
    CView* pView,
    LPMSG lpMsg = NULL);

Parâmetros

nVerb
Especifica o verbo a ser executado. Pode ser um dos seguintes:

Valor	Significado	Símbolo
- 0	Verbo primário	OLEIVERB_PRIMARY
- 1	Verbo secundário	(Nenhuma)
- 1	Exibir item para edição	OLEIVERB_SHOW
- 2	Editar item em janela separada	OLEIVERB_OPEN
- 3	Ocultar item	OLEIVERB_HIDE

O valor -1 normalmente é um alias para outro verbo. Se não houver suporte para edição aberta, -2 terá o mesmo efeito que -1. Para obter valores adicionais, confira IOleObject::DoVerb no SDK do Windows.

pView
Ponteiro para a janela de exibição de contêiner que contém o item OLE; isso é usado pelo aplicativo para servidores para ativação in-loco. Esse parâmetro deverá ser NULL se o contêiner não der suporte à ativação in-loco.

lpMsg
Ponteiro para a mensagem que fez com que o item fosse ativado.

Comentários

Se o aplicativo para servidores foi escrito usando a biblioteca Microsoft Foundation Class, essa função fará com que a função membro OnDoVerb do objeto correspondente COleServerItem seja executada.

Se o verbo primário for Editar e zero for especificado no parâmetro nVerb, o aplicativo para servidores será iniciado para permitir que o item OLE seja editado. Se o aplicativo de contêiner der suporte à ativação in-loco, a edição poderá ser feita no local. Se o contêiner não der suporte à ativação in-loco (ou se o verbo Abrir for especificado), o servidor será iniciado em uma janela separada e a edição poderá ser feita lá. Normalmente, quando o usuário do aplicativo de contêiner clica duas vezes no item OLE, o valor do verbo primário no parâmetro nVerb determina qual ação o usuário pode executar. No entanto, se o servidor der suporte a apenas uma ação, ele tomará essa ação, independentemente do valor especificado no parâmetro nVerb.

Para obter mais informações, confira IOleObject::DoVerb no SDK do Windows.

COleClientItem::ActivateAs

Usa as instalações de conversão de objeto do OLE para ativar o item como se fosse um item do tipo especificado por clsidNew.

virtual BOOL ActivateAs(
    LPCTSTR lpszUserType,
    REFCLSID clsidOld,
    REFCLSID clsidNew);

Parâmetros

lpszUserType
Ponteiro para uma cadeia de caracteres que representa o tipo de usuário de destino, como "Documento do Word".

clsidOld
Uma referência à ID da classe atual do item. A ID de classe deve representar o tipo do objeto real, conforme armazenado, a menos que ele seja um link. Nesse caso, ela deve ser o CLSID do item ao qual o link se refere. O COleConvertDialog fornece automaticamente a ID de classe correta para o item.

clsidNew
Uma referência à ID da classe de destino.

Valor de retorno

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

Comentários

Essa função é chamada automaticamente por COleConvertDialog::DoConvert. Normalmente, ela não é chamada diretamente.

COleClientItem::AttachDataObject

Chame essa função para inicializar um COleDataObject para acessar os dados no item OLE.

void AttachDataObject(COleDataObject& rDataObject) const;

Parâmetros

rDataObject
Referência a um objeto COleDataObject que será inicializado para permitir o acesso aos dados no item OLE.

COleClientItem::CanActivate

Chamada pela estrutura quando o usuário solicita a ativação in-loco do item OLE; o valor retornado dessa função determina se a ativação in-loco é permitida.

virtual BOOL CanActivate();

Valor de retorno

Diferente de zero se a ativação in-loco for permitida; caso contrário, 0.

Comentários

A implementação padrão permitirá a ativação in-loco se o contêiner tiver uma janela válida. Substitua essa função para implementar uma lógica especial para aceitar ou recusar a solicitação de ativação. Por exemplo, uma solicitação de ativação pode ser recusada se o item OLE for muito pequeno ou não estiver visível no momento.

Para obter mais informações, confira IOleInPlaceSite::CanInPlaceActivate no SDK do Windows.

COleClientItem::CanCreateFromData

Verifica se um aplicativo de contêiner pode criar um objeto inserido com base no objeto COleDataObject fornecido.

static BOOL PASCAL CanCreateFromData(const COleDataObject* pDataObject);

Parâmetros

pDataObject
Ponteiro para o objeto COleDataObject a partir do qual o item OLE deve ser criado.

Valor de retorno

Diferente de zero se o contêiner puder criar um objeto inserido com base no objeto COleDataObject; caso contrário, 0.

Comentários

A classe COleDataObject é usada em transferências de dados para recuperar dados em vários formatos da Área de Transferência, por meio de arrastar e soltar ou de um item OLE inserido.

Os contêineres podem usar essa função para decidir habilitar ou desabilitar os respectivos comandos Editar/Colar e Editar/Colar Especial.

Para obter mais informações, confira o artigo Objetos de Dados e Fontes de Dados (OLE).

COleClientItem::CanCreateLinkFromData

Verifica se um aplicativo de contêiner pode criar um objeto vinculado com base no objeto COleDataObject fornecido.

static BOOL PASCAL CanCreateLinkFromData(const COleDataObject* pDataObject);

Parâmetros

pDataObject
Ponteiro para o objeto COleDataObject a partir do qual o item OLE deve ser criado.

Valor de retorno

Diferente de zero se o contêiner puder criar um objeto vinculado com base no objeto COleDataObject.

Comentários

A classe COleDataObject é usada em transferências de dados para recuperar dados em vários formatos da Área de Transferência, por meio de arrastar e soltar ou de um item OLE inserido.

Os contêineres podem usar essa função para decidir habilitar ou desabilitar seus comandos Editar/Colar Especial e Editar/Colar Link.

Para obter mais informações, confira o artigo Objetos de Dados e Fontes de Dados (OLE).

COleClientItem::CanPaste

Chame essa função para ver se um item OLE inserido pode ser colado da Área de Transferência.

static BOOL PASCAL CanPaste();

Valor de retorno

Não zero se um item OLE inserido puder ser colado da Área de Transferência; caso contrário, 0.

Comentários

Para obter mais informações, confira OleGetClipboard e OleQueryCreateFromData no SDK do Windows.

COleClientItem::CanPasteLink

Chame essa função para ver se um item OLE vinculado pode ser colado da Área de Transferência.

static BOOL PASCAL CanPasteLink();

Valor de retorno

Diferente de zero se um item OLE vinculado puder ser colado da Área de Transferência; caso contrário, 0.

Comentários

Para obter mais informações, confira OleGetClipboard e OleQueryLinkFromData no SDK do Windows.

COleClientItem::Close

Chame essa função para alterar o estado de um item OLE do estado de execução para o estado carregado, ou seja, carregado com o respectivo manipulador na memória, mas com o servidor não em execução.

void Close(OLECLOSE dwCloseOption = OLECLOSE_SAVEIFDIRTY);

Parâmetros

dwCloseOption
Sinalizador especificando em quais circunstâncias o item OLE é salvo quando ele retorna ao estado carregado. Ele pode ter um dos seguintes valores:

• OLECLOSE_SAVEIFDIRTY Salvar o item OLE.

• OLECLOSE_NOSAVE Não salvar o item OLE.

• OLECLOSE_PROMPTSAVE Solicitar ao usuário se deseja salvar o item OLE.

Comentários

Essa função não tem efeito quando o item OLE não está em execução.

Para obter mais informações, confira IOleObject::Close no SDK do Windows.

COleClientItem::COleClientItem

Constrói um objeto COleClientItem e o adiciona à coleção de itens de documento do documento de contêiner, que constrói apenas o objeto C++ e não executa nenhuma inicialização OLE.

COleClientItem(COleDocument* pContainerDoc = NULL);

Parâmetros

pContainerDoc
Ponteiro para o documento de contêiner que conterá este item. Pode ser qualquer derivado de COleDocument.

Comentários

Se você passar um ponteiro NULL, nenhuma adição será feita ao documento de contêiner. Você precisa chamar explicitamente COleDocument::AddItem.

Você precisa chamar uma das seguintes funções membro de criação antes de usar o item OLE:

• CreateFromClipboard

• CreateFromData

• CreateFromFile

• CreateStaticFromClipboard

• CreateStaticFromData

• CreateLinkFromClipboard

• CreateLinkFromData

• CreateLinkFromFile

• CreateNewItem

• CreateCloneFrom

COleClientItem::ConvertTo

Chame essa função membro para converter o item no tipo especificado por clsidNew.

virtual BOOL ConvertTo(REFCLSID clsidNew);

Parâmetros

clsidNew
A ID de classe do tipo de destino.

Valor de retorno

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

Comentários

Essa função é chamada automaticamente por COleConvertDialog. Não é necessário chamá-la diretamente.

COleClientItem::CopyToClipboard

Chame essa função para copiar o item OLE para a Área de Transferência.

void CopyToClipboard(BOOL bIncludeLink = FALSE);

Parâmetros

bIncludeLink
TRUE se as informações de link devem ser copiadas para a Área de Transferência, permitindo que um item vinculado seja colado; caso contrário, FALSE.

Comentários

Normalmente, você chama essa função ao escrever manipuladores de mensagens para os comandos Copiar ou Recortar no menu Editar. Você precisa implementar a seleção de itens em seu aplicativo de contêiner se quiser implementar os comandos Copiar ou Recortar.

Para obter mais informações, confira OleSetClipboard no SDK do Windows.

COleClientItem::CreateCloneFrom

Chame essa função para criar uma cópia do item OLE especificado.

BOOL CreateCloneFrom(const COleClientItem* pSrcItem);

Parâmetros

pSrcItem
Ponteiro para o item OLE a ser duplicado.

Valor de retorno

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

Comentários

A cópia é idêntica ao item de origem. Você pode usar essa função para dar suporte a operações de desfazer.

COleClientItem::CreateFromClipboard

Chame essa função para criar um item inserido a partir do conteúdo da Área de Transferência.

BOOL CreateFromClipboard(
    OLERENDER render = OLERENDER_DRAW,
    CLIPFORMAT cfFormat = 0,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

render
Sinalizador especificando como o servidor renderizará o item OLE. Para obter os valores possíveis, confira OLERENDER no SDK do Windows.

cfFormat
Especifica o formato de dados da Área de Transferência a ser armazenado em cache ao criar o item OLE.

lpFormatEtc
Ponteiro para uma estrutura FORMATETC usada se render for OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado por cfFormat. Se você omitir esse parâmetro, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

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

Comentários

Normalmente, você chama essa função do manipulador de mensagens para o comando Colar no menu Editar. (O comando Colar será habilitado pela estrutura se a função membro CanPaste retornar um valor diferente de zero.)

Para obter mais informações, confira OLERENDER e FORMATETC no SDK do Windows.

COleClientItem::CreateFromData

Chame essa função para criar um item inserido a partir de um objeto COleDataObject.

BOOL CreateFromData(
    COleDataObject* pDataObject,
    OLERENDER render = OLERENDER_DRAW,
    CLIPFORMAT cfFormat = 0,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

pDataObject
Ponteiro para o objeto COleDataObject a partir do qual o item OLE deve ser criado.

render
Sinalizador especificando como o servidor renderizará o item OLE. Para obter os valores possíveis, confira OLERENDER no SDK do Windows.

cfFormat
Especifica o formato de dados da Área de Transferência a ser armazenado em cache ao criar o item OLE.

lpFormatEtc
Ponteiro para uma estrutura FORMATETC usada se render for OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado por cfFormat. Se você omitir esse parâmetro, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

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

Comentários

Operações de transferência de dados, como colar da Área de Transferência ou operações de arrastar e soltar, fornecem objetos COleDataObject que contêm as informações oferecidas por um aplicativo para servidores. Geralmente, ele é usado quando você substitui CView::OnDrop.

Para obter mais informações, confira OleCreateFromData, OLERENDER e FORMATETC no SDK do Windows.

COleClientItem::CreateFromFile

Chame essa função para criar um item OLE inserido a partir de um arquivo.

BOOL CreateFromFile(
    LPCTSTR lpszFileName,
    REFCLSID clsid = CLSID_NULL,
    OLERENDER render = OLERENDER_DRAW,
    CLIPFORMAT cfFormat = 0,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

lpszFileName
Ponteiro para o nome do arquivo do qual o item OLE deve ser criado.

clsid
Reservado para uso futuro.

render
Sinalizador especificando como o servidor renderizará o item OLE. Para obter os valores possíveis, confira OLERENDER no SDK do Windows.

cfFormat
Especifica o formato de dados da Área de Transferência a ser armazenado em cache ao criar o item OLE.

lpFormatEtc
Ponteiro para uma estrutura FORMATETC usada se render for OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado por cfFormat. Se você omitir esse parâmetro, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

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

Comentários

A estrutura chamará essa função de COleInsertDialog::CreateItem se o usuário escolher OK na caixa de diálogo Inserir Objeto quando o botão Criar do Arquivo estiver selecionado.

Para obter mais informações, confira OleCreateFromFile, OLERENDER e FORMATETC no SDK do Windows.

COleClientItem::CreateLinkFromClipboard

Chame essa função para criar um item vinculado a partir do conteúdo da Área de Transferência.

BOOL CreateLinkFromClipboard(
    OLERENDER render = OLERENDER_DRAW,
    CLIPFORMAT cfFormat = 0,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

render
Sinalizador especificando como o servidor renderizará o item OLE. Para obter os valores possíveis, confira OLERENDER no SDK do Windows.

cfFormat
Especifica o formato de dados da Área de Transferência a ser armazenado em cache ao criar o item OLE.

lpFormatEtc
Ponteiro para uma estrutura FORMATETC usada se render for OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado por cfFormat. Se você omitir esse parâmetro, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

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

Comentários

Normalmente, você chama essa função do manipulador de mensagens para o comando Colar Link no menu Editar. (O comando Colar Link será habilitado na implementação padrão do COleDocument se a Área de Transferência contiver um item OLE que possa ser vinculado.)

Para obter mais informações, confira OLERENDER e FORMATETC no SDK do Windows.

COleClientItem::CreateLinkFromData

Chame essa função para criar um item vinculado a partir de um objeto COleDataObject.

BOOL CreateLinkFromData(
    COleDataObject* pDataObject,
    OLERENDER render = OLERENDER_DRAW,
    CLIPFORMAT cfFormat = 0,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

pDataObject
Ponteiro para o objeto COleDataObject a partir do qual o item OLE deve ser criado.

render
Sinalizador especificando como o servidor renderizará o item OLE. Para obter os valores possíveis, confira OLERENDER no SDK do Windows.

cfFormat
Especifica o formato de dados da Área de Transferência a ser armazenado em cache ao criar o item OLE.

lpFormatEtc
Ponteiro para uma estrutura FORMATETC usada se render for OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado por cfFormat. Se você omitir esse parâmetro, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

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

Comentários

Chame isso durante uma operação de descarte quando o usuário indicar que um link deve ser criado. Ela também pode ser usada para manipular o comando Editar/Colar. Ela é chamada pela estrutura em COleClientItem::CreateLinkFromClipboard e em COlePasteSpecialDialog::CreateItem quando a opção Vincular foi selecionada.

Para obter mais informações, confira OleCreateLinkFromData, OLERENDER e FORMATETC no SDK do Windows.

COleClientItem::CreateLinkFromFile

Chame essa função para criar um item OLE vinculado de um arquivo.

BOOL CreateLinkFromFile(
    LPCTSTR lpszFileName,
    OLERENDER render = OLERENDER_DRAW,
    CLIPFORMAT cfFormat = 0,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

lpszFileName
Ponteiro para o nome do arquivo do qual o item OLE deve ser criado.

render
Sinalizador especificando como o servidor renderizará o item OLE. Para obter os valores possíveis, confira OLERENDER no SDK do Windows.

cfFormat
Especifica o formato de dados da Área de Transferência a ser armazenado em cache ao criar o item OLE.

lpFormatEtc
Ponteiro para uma estrutura FORMATETC usada se render for OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado por cfFormat. Se você omitir esse parâmetro, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

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

Comentários

A estrutura chamará essa função se o usuário escolher OK na caixa de diálogo Inserir Objeto quando o botão Criar do Arquivo estiver selecionado e a caixa de seleção Vincular estiver marcada. Ela é chamada de COleInsertDialog::CreateItem.

Para obter mais informações, confira OleCreateLinkToFile, OLERENDER e FORMATETC no SDK do Windows.

COleClientItem::CreateNewItem

Chame essa função para criar um item inserido; essa função inicia o aplicativo para servidores que permite que o usuário crie o item OLE.

BOOL CreateNewItem(
    REFCLSID clsid,
    OLERENDER render = OLERENDER_DRAW,
    CLIPFORMAT cfFormat = 0,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

clsid
ID que identifica exclusivamente o tipo de item OLE a ser criado.

render
Sinalizador especificando como o servidor renderizará o item OLE. Para obter os valores possíveis, confira OLERENDER no SDK do Windows.

cfFormat
Especifica o formato de dados da Área de Transferência a ser armazenado em cache ao criar o item OLE.

lpFormatEtc
Ponteiro para uma estrutura FORMATETC usada se render for OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado por cfFormat. Se você omitir esse parâmetro, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

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

Comentários

A estrutura chamará essa função se o usuário escolher OK na caixa de diálogo Inserir Objeto quando o botão Criar estiver selecionado.

Para obter mais informações, confira OleCreate, OLERENDER e FORMATETC no SDK do Windows.

COleClientItem::CreateStaticFromClipboard

Chame essa função para criar um item estático a partir do conteúdo da Área de Transferência.

BOOL CreateStaticFromClipboard(
    OLERENDER render = OLERENDER_DRAW,
    CLIPFORMAT cfFormat = 0,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

render
Sinalizador especificando como o servidor renderizará o item OLE. Para obter os valores possíveis, confira OLERENDER no SDK do Windows.

cfFormat
Especifica o formato de dados da Área de Transferência a ser armazenado em cache ao criar o item OLE.

lpFormatEtc
Ponteiro para uma estrutura FORMATETC usada se render for OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado por cfFormat. Se você omitir esse parâmetro, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

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

Comentários

Um item estático contém os dados de apresentação, mas não os dados nativos; consequentemente, ele não pode ser editado. Normalmente, você chama essa função se a função membro CreateFromClipboard falha.

Para obter mais informações, confira OLERENDER e FORMATETC no SDK do Windows.

COleClientItem::CreateStaticFromData

Chame essa função para criar um item estático a partir de um objeto COleDataObject.

BOOL CreateStaticFromData(
    COleDataObject* pDataObject,
    OLERENDER render = OLERENDER_DRAW,
    CLIPFORMAT cfFormat = 0,
    LPFORMATETC lpFormatEtc = NULL);

Parâmetros

pDataObject
Ponteiro para o objeto COleDataObject a partir do qual o item OLE deve ser criado.

render
Sinalizador especificando como o servidor renderizará o item OLE. Para obter os valores possíveis, confira OLERENDER no SDK do Windows.

cfFormat
Especifica o formato de dados da Área de Transferência a ser armazenado em cache ao criar o item OLE.

lpFormatEtc
Ponteiro para uma estrutura FORMATETC usada se render for OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se você quiser especificar informações de formato adicionais além do formato de área de transferência especificado por cfFormat. Se você omitir esse parâmetro, os valores padrão serão usados para os outros campos na estrutura FORMATETC.

Valor de retorno

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

Comentários

Um item estático contém os dados de apresentação, mas não os dados nativos; consequentemente, ele não pode ser editado. Isso é essencialmente o mesmo que CreateStaticFromClipboard, exceto que um item estático pode ser criado de um COleDataObject arbitrário, não apenas da Área de Transferência.

Usado em COlePasteSpecialDialog::CreateItem quando a opção Estático é selecionada.

Para obter mais informações, confira OleCreateStaticFromData, OLERENDER e FORMATETC no SDK do Windows.

COleClientItem::Deactivate

Chame essa função para desativar o item OLE e liberar todos os recursos associados.

void Deactivate();

Comentários

Normalmente, você desativa um item OLE ativo no local quando o usuário clica com o mouse na área do cliente fora dos limites do item. Observe que a desativação do item OLE descartará seu estado de desfazer dele, impossibilitando a chamada da função membro ReactivateAndUndo.

Se o aplicativo der suporte a desfazer, não chame Deactivate; em vez disso, chame DeactivateUI.

Para obter mais informações, confira IOleInPlaceObject::InPlaceDeactivate no SDK do Windows.

COleClientItem::DeactivateUI

Chame essa função quando o usuário desativar um item que foi ativado no local.

void DeactivateUI();

Comentários

Essa função restaura a interface do usuário do aplicativo de contêiner para o estado original, ocultando menus e outros controles que foram criados para ativação in-loco.

Essa função não libera as informações de estado de desfazer para o item. Essas informações são retidas para que ReactivateAndUndo possa ser usado posteriormente para executar um comando desfazer no aplicativo para servidores, caso o comando desfazer do contêiner seja escolhido imediatamente após desativar o item.

Para obter mais informações, confira IOleInPlaceObject::InPlaceDeactivate no SDK do Windows.

COleClientItem::Delete

Chame essa função para excluir o item OLE do documento de contêiner.

void Delete(BOOL bAutoDelete = TRUE);

Parâmetros

bAutoDelete
Especifica se o item deve ser removido do documento.

Comentários

Essa função chama a função membro Release que, por sua vez, exclui o objeto C++ do item, removendo permanentemente o item OLE do documento. Se o item OLE estiver inserido, os dados nativos do item serão excluídos. Ele sempre fecha um servidor em execução; portanto, se o item for um link aberto, essa função o fechará.

COleClientItem::DoDragDrop

Chame a função membro DoDragDrop para executar uma operação de arrastar e soltar.

DROPEFFECT DoDragDrop(
    LPCRECT lpItemRect,
    CPoint ptOffset,
    BOOL bIncludeLink = FALSE,
    DWORD dwEffects = DROPEFFECT_COPY | DROPEFFECT_MOVE,
    LPCRECT lpRectStartDrag = NULL);

Parâmetros

lpItemRect
O retângulo do item na tela em coordenadas do cliente (pixels).

ptOffset
O desvio de lpItemRect em que a posição do mouse estava no momento do arrasto.

bIncludeLink
Defina-o como TRUE se os dados do link devem ser copiados para a Área de Transferência. Defina-o como FALSE se o aplicativo para servidores não der suporte a links.

dwEffects
Determina os efeitos que a origem do arrasto permitirá na operação de arrastar.

lpRectStartDrag
O ponteiro para o retângulo que define onde a ação de arrastar realmente começa. Para obter mais informações, consulte a seção Comentários a seguir.

Valor de retorno

Um valor DROPEFFECT. Se for DROPEFFECT_MOVE, os dados originais deverão ser removidos.

Comentários

A operação do tipo "arrastar e soltar" não é iniciada imediatamente. Ela aguarda até que o cursor do mouse deixe o retângulo especificado por lpRectStartDrag ou até que um número específico de milissegundos tenha passado. Se lpRectStartDrag for NULL, o tamanho do retângulo será de um pixel.

O tempo de atraso é especificado por uma configuração de chave do Registro. Você pode alterar o tempo de atraso chamando CWinApp::WriteProfileString ou CWinApp::WriteProfileInt. Se você não especificar o tempo de atraso, um valor padrão de 200 milissegundos será usado. O tempo de atraso de arrastar é armazenado da seguinte maneira:

• O tempo de atraso de arrastar do Windows NT é armazenado em HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\NT\CurrentVersion\IniFileMapping\win.ini\Windows\DragDelay.

• O tempo de atraso de arrastar do Windows 3.x é armazenado no arquivo WIN.INI, na seção [Windows}.

• O tempo de atraso de arrastar do Windows 95/98 é armazenado em uma versão armazenada em cache do WIN.INI.

Para obter mais informações sobre como as informações de atraso de arrastar são armazenadas no Registro ou no arquivo .INI, confira WriteProfileString no SDK do Windows.

COleClientItem::DoVerb

Chame DoVerb para executar o verbo especificado.

virtual BOOL DoVerb(
    LONG nVerb,
    CView* pView,
    LPMSG lpMsg = NULL);

Parâmetros

nVerb
Especifica o verbo a ser executado. Pode incluir um dos seguintes:

Valor	Significado	Símbolo
- 0	Verbo primário	OLEIVERB_PRIMARY
- 1	Verbo secundário	(Nenhuma)
- 1	Exibir item para edição	OLEIVERB_SHOW
- 2	Editar item em janela separada	OLEIVERB_OPEN
- 3	Ocultar item	OLEIVERB_HIDE

O valor -1 normalmente é um alias para outro verbo. Se não houver suporte para edição aberta, -2 terá o mesmo efeito que -1. Para obter valores adicionais, confira IOleObject::DoVerb no SDK do Windows.

pView
Ponteiro para a janela de exibição; isso é usado pelo servidor para ativação in-loco. Esse parâmetro deverá ser NULL se o aplicativo de contêiner não permitir a ativação in-loco.

lpMsg
Ponteiro para a mensagem que fez com que o item fosse ativado.

Valor de retorno

Não zero se o verbo foi executado com êxito; caso contrário, 0.

Comentários

Essa função chama a função membro Activate para executar o verbo. Ela também capturará exceções e, se uma for gerada, exibirá uma caixa de mensagem para o usuário.

Se o verbo primário for Editar e zero for especificado no parâmetro nVerb, o aplicativo para servidores será iniciado para permitir que o item OLE seja editado. Se o aplicativo de contêiner der suporte à ativação in-loco, a edição poderá ser feita no local. Se o contêiner não der suporte à ativação in-loco (ou se o verbo Abrir for especificado), o servidor será iniciado em uma janela separada e a edição poderá ser feita lá. Normalmente, quando o usuário do aplicativo de contêiner clica duas vezes no item OLE, o valor do verbo primário no parâmetro nVerb determina qual ação o usuário pode executar. No entanto, se o servidor der suporte a apenas uma ação, ele tomará essa ação, independentemente do valor especificado no parâmetro nVerb.

COleClientItem::Draw

Chame essa função para desenhar o item OLE no retângulo delimitador especificado usando o contexto do dispositivo especificado.

BOOL Draw(
    CDC* pDC,
    LPCRECT lpBounds,
    DVASPECT nDrawAspect = (DVASPECT)-1);

Parâmetros

pDC
Ponteiro para um objeto CDC usado para desenhar o item OLE.

lpBounds
Ponteiro para um objeto CRect ou estrutura RECT que define o retângulo delimitador no qual desenhar o item OLE (em unidades lógicas determinadas pelo contexto do dispositivo).

nDrawAspect
Especifica o aspecto do item OLE, ou seja, como ele deve ser exibido. Se nDrawAspect for -1, o último aspecto definido usando SetDrawAspect será usado. Para obter mais informações sobre os valores possíveis, confira SetDrawAspect.

Valor de retorno

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

Comentários

A função pode usar a representação de meta-arquivo do item OLE criado pela função membro OnDraw de COleServerItem.

Normalmente, você usa Draw para exibição de tela, passando o contexto do dispositivo de tela como pDC. Nesse caso, você precisa especificar apenas os dois primeiros parâmetros.

O parâmetro lpBounds identifica o retângulo no contexto do dispositivo de destino (em relação ao modo de mapeamento atual dele). A renderização pode envolver o dimensionamento da imagem e pode ser usada por aplicativos de contêiner para impor uma exibição que é dimensionada entre o modo de exibição exibido e a imagem impressa final.

Para obter mais informações, confira IViewObject::Draw no SDK do Windows.

COleClientItem::GetActiveView

Retorna a exibição na qual o item está ativado no local.

CView* GetActiveView() const;

Valor de retorno

Um ponteiro para a exibição; caso contrário, NULL se o item não estiver ativado no local.

COleClientItem::GetCachedExtent

Chame essa função para recuperar o tamanho do item OLE.

BOOL GetCachedExtent(
    LPSIZE lpSize,
    DVASPECT nDrawAspect = (DVASPECT)-1);

Parâmetros

lpSize
Ponteiro para uma estrutura SIZE ou um objeto CSize que receberá as informações de tamanho.

nDrawAspect
Especifica o aspecto do item OLE cujos limites devem ser recuperados. Para saber os valores possíveis, confira SetDrawAspect.

Valor de retorno

Diferente de zero se tiver êxito; 0 se o item OLE estiver em branco.

Comentários

Essa função fornece as mesmas informações que GetExtent. No entanto, você pode chamar GetCachedExtent para obter informações de extensão durante o processamento de outros manipuladores OLE, como OnChange. As dimensões estão em unidades MM_HIMETRIC.

Isso é possível porque GetCachedExtent usa a interface IViewObject2 em vez de usar a interface IOleObject para obter a extensão desse item. O objeto COM IViewObject2 armazena em cache as informações de extensão usadas na chamada anterior para IViewObject::Draw.

Para obter mais informações, confira IViewObject2::GetExtent no SDK do Windows.

COleClientItem::GetClassID

Retorna a ID de classe do item na memória apontado por pClassID.

void GetClassID(CLSID* pClassID) const;

Parâmetros

pClassID
Ponteiro para um identificador do tipo CLSID para recuperar a ID da classe. Para obter informações sobre a CLSID, confira o SDK do Windows.

Comentários

A ID da classe é um número de 128 bits que identifica exclusivamente o aplicativo que edita o item.

Para obter mais informações, confira IPersist::GetClassID no SDK do Windows.

COleClientItem::GetClipboardData

Chame essa função para obter um objeto COleDataSource que contenha todos os dados que seriam colocados na Área de Transferência por uma chamada para a função membro CopyToClipboard.

void GetClipboardData(
    COleDataSource* pDataSource,
    BOOL bIncludeLink = FALSE,
    LPPOINT lpOffset = NULL,
    LPSIZE lpSize = NULL);

Parâmetros

pDataSource
Ponteiro para um objeto COleDataSource que receberá os dados contidos no item OLE.

bIncludeLink
TRUE se os dados de link devem ser incluídos; caso contrário, FALSE.

lpOffset
O deslocamento do cursor do mouse da origem do objeto em pixels.

lpSize
O tamanho do objeto em pixels.

Comentários

GetClipboardData é chamada como a implementação padrão de OnGetClipboardData. Substitua OnGetClipboardData somente se você quiser oferecer formatos de dados além daqueles oferecidos por CopyToClipboard. Coloque esses formatos no objeto COleDataSource antes ou depois da chamada CopyToClipboard e passe o objeto COleDataSource para a função COleDataSource::SetClipboard. Por exemplo, se você quiser que a posição do item OLE em seu documento de contêiner o acompanhe na Área de Transferência, defina um formato próprio para passar essas informações e coloque-o em COleDataSource antes de chamar CopyToClipboard.

COleClientItem::GetDocument

Chame essa função para obter um ponteiro para o documento que contém o item OLE.

COleDocument* GetDocument() const;

Valor de retorno

Um ponteiro para o documento que contém o item OLE. NULL se o item não fizer parte de um documento.

Comentários

Esse ponteiro permite o acesso ao objeto COleDocument que você passou como um argumento para o construtor COleClientItem.

COleClientItem::GetDrawAspect

Chame a função membro GetDrawAspect para determinar o "aspecto" (ou exibição) atual do item.

DVASPECT GetDrawAspect() const;

Valor de retorno

Um valor da enumeração DVASPECT, cujos valores são listados na referência para SetDrawAspect.

Comentários

O aspecto especifica como o item deve ser renderizado.

COleClientItem::GetExtent

Chame essa função para recuperar o tamanho do item OLE.

BOOL GetExtent(
    LPSIZE lpSize,
    DVASPECT nDrawAspect = (DVASPECT)- 1);

Parâmetros

lpSize
Ponteiro para uma estrutura SIZE ou um objeto CSize que receberá as informações de tamanho.

nDrawAspect
Especifica o aspecto do item OLE cujos limites devem ser recuperados. Para saber os valores possíveis, confira SetDrawAspect.

Valor de retorno

Diferente de zero se tiver êxito; 0 se o item OLE estiver em branco.

Comentários

Se o aplicativo para servidores foi escrito usando a biblioteca Microsoft Foundation Class, essa função fará com que a função membro OnGetExtent do objeto correspondente COleServerItem seja chamada. Observe que o tamanho recuperado pode diferir do tamanho definido pela última vez pela função membro SetExtent; o tamanho especificado por SetExtent é tratado como uma sugestão. As dimensões estão em unidades MM_HIMETRIC.

Observação

Não chame GetExtent durante o processamento de um manipulador OLE, como OnChange. Em vez disso, chame GetCachedExtent.

Para obter mais informações, confira IOleObject::GetExtent no SDK do Windows.

COleClientItem::GetIconFromRegistry

Chame essa função membro para recuperar um identificador para um recurso de ícone associado ao servidor de um CLSID específico.

HICON GetIconFromRegistry() const;

static HICON GetIconFromRegistry(CLSID& clsid);

Parâmetros

clsid
Uma referência ao CLSID para o servidor associado ao ícone.

Valor de retorno

Um identificador válido para o recurso de ícone ou NULL se o ícone do servidor, ou um ícone padrão, não puder ser encontrado.

Comentários

Essa função membro não iniciará o servidor nem obterá um ícone dinamicamente, mesmo que o servidor já esteja em execução. Em vez disso, essa função membro abre a imagem executável do servidor e recupera o ícone estático associado ao servidor conforme ele foi registrado.

COleClientItem::GetIconicMetafile

Recupera o meta-arquivo usado para desenhar o ícone do item.

HGLOBAL GetIconicMetafile();

Valor de retorno

Um identificador para o meta-arquivo em caso de êxito; caso contrário, NULL.

Comentários

Se não houver nenhum ícone atual, um ícone padrão será retornado. Essa função é chamada automaticamente pelas caixas de diálogo MFC/OLE e geralmente não é chamada diretamente.

Essa função também chama SetIconicMetafile para armazenar o meta-arquivo em cache para uso posterior.

COleClientItem::GetInPlaceWindow

Chame a função membro GetInPlaceWindow para obter um ponteiro para a janela na qual o item foi aberto para edição in-loco.

CWnd* GetInPlaceWindow();

Valor de retorno

Um ponteiro para a janela de edição in-loco do item; NULL se o item não estiver ativo ou se o servidor não estiver disponível.

Comentários

Essa função deve ser chamada apenas para itens que estão ativos in-loco.

COleClientItem::GetItemState

Chame essa função para obter o estado atual do item OLE.

UINT GetItemState() const;

Valor de retorno

Um valor enumerado COleClientItem::ItemState, que pode ser um dos seguintes: emptyState, loadedState, openState, activeState, activeUIState. Para obter informações sobre esses estados, confira o artigo Contêineres: estados de cliente-item.

Comentários

Para ser notificado quando o estado do item OLE for alterado, use a função membro OnChange.

Para obter mais informações, confira o artigo Contêineres: estados de cliente-item.

COleClientItem::GetLastStatus

Retorna o código de status da última operação OLE.

SCODE GetLastStatus() const;

Valor de retorno

Um valor SCODE.

Comentários

Para funções membro que retornam um valor booliano FALSE ou outras funções membro que retornam NULL, GetLastStatus retorna informações de falha mais detalhadas. Lembre-se de que a maioria das funções membro OLE gera exceções para erros mais graves. As informações específicas sobre a interpretação do SCODE dependem da chamada OLE subjacente que retornou pela última vez um valor de SCODE.

Para obter mais informações sobre o SCODE, confira Estrutura de códigos de erro COM na documentação do SDK do Windows.

COleClientItem::GetLinkUpdateOptions

Chame essa função para obter o valor atual da opção de atualização de link para o item OLE.

OLEUPDATE GetLinkUpdateOptions();

Valor de retorno

Um dos seguintes valores:

• OLEUPDATE_ALWAYS Atualizar o item vinculado sempre que possível. Essa opção dá suporte ao botão de opção Atualização automática de link na caixa de diálogo Links.

• OLEUPDATE_ONCALL Atualizar o item vinculado somente na solicitação do aplicativo de contêiner (quando a função membro UpdateLink for chamada). Essa opção dá suporte ao botão de opção Atualização manual de link na caixa de diálogo Links.

Comentários

Esta é uma operação avançada.

Essa função é chamada automaticamente pela classe COleLinksDialog.

Para obter mais informações, confira IOleLink::GetUpdateOptions no SDK do Windows.

COleClientItem::GetType

Chame essa função para determinar se o item OLE está inserido ou vinculado ou estático.

OLE_OBJTYPE GetType() const;

Valor de retorno

Um inteiro sem sinal com um dos seguintes valores:

• OT_LINK O item OLE é um link.

• OT_EMBEDDED O item OLE está inserido.

• OT_STATIC O item OLE é estático, ou seja, ele contém apenas dados de apresentação, não dados nativos e, portanto, não pode ser editado.

COleClientItem::GetUserType

Chame essa função para obter a cadeia de caracteres visível pelo usuário que descreve o tipo do item OLE, como "Documento do Word".

void GetUserType(
    USERCLASSTYPE nUserClassType,
    CString& rString);

Parâmetros

nUserClassType
Um valor que indica a variante desejada da cadeia de caracteres que descreve o tipo do item OLE. Esse pode ter um dos seguintes valores:

• USERCLASSTYPE_FULL O nome completo do tipo exibido para o usuário.

• USERCLASSTYPE_SHORT Um nome curto (máximo de 15 caracteres) para uso em menus pop-up e na caixa de diálogo Editar Links.

• USERCLASSTYPE_APPNAME Nome do aplicativo que atende a classe.

rString
Uma referência a um objeto CString para o qual a cadeia de caracteres que descreve o tipo do item OLE deve ser retornada.

Comentários

Geralmente, essa é a entrada no banco de dados de registro do sistema.

Se o nome de tipo completo for solicitado, mas não estiver disponível, o nome curto será usado em vez disso. Se nenhuma entrada para o tipo de item OLE for encontrada no banco de dados de registro ou se não houver nenhum tipo de usuário registrado para o tipo de item OLE, o tipo de usuário atualmente armazenado no item OLE será usado. Se esse nome de tipo de usuário for uma cadeia de caracteres vazia, "Objeto Desconhecido" será usado.

Para obter mais informações, confira IOleObject::GetUserType no SDK do Windows.

COleClientItem::IsInPlaceActive

Chame essa função para ver se o item OLE está ativo no local.

BOOL IsInPlaceActive() const;

Valor de retorno

Diferente de zero se o item OLE estiver ativo in-loco; caso contrário, 0.

Comentários

É comum executar uma lógica diferente dependendo se o item está sendo editado no local. A função verifica se o estado do item atual é igual ao activeState ou ao activeUIState.

COleClientItem::IsLinkUpToDate

Chame essa função para conferir se o item OLE está atualizado.

BOOL IsLinkUpToDate() const;

Valor de retorno

Diferente de zero se o item OLE estiver atualizado; caso contrário, 0.

Comentários

Um item vinculado poderá estar desatualizado se o documento de origem tiver sido atualizado. Um item inserido que contém links dentro dele pode ficar desatualizado da mesma forma. A função faz uma verificação recursiva do item OLE. Observe que determinar se um item OLE está desatualizado pode ser tão caro quanto realmente executar uma atualização.

Essa função é chamada automaticamente pela implementação de COleLinksDialog.

Para obter mais informações, confira IOleObject::IsUpToDate no SDK do Windows.

COleClientItem::IsModified

Chame essa função para ver se o item OLE está sujo (modificado desde que foi salvo pela última vez).

BOOL IsModified() const;

Valor de retorno

Diferente de zero se o item OLE estiver sujo; caso contrário, 0.

Comentários

Para obter mais informações, confira IPersistStorage::IsDirty no SDK do Windows.

COleClientItem::IsOpen

Chame essa função para ver se o item OLE está aberto; ou seja, aberto em uma instância do aplicativo para servidores em execução em uma janela separada.

BOOL IsOpen() const;

Valor de retorno

Diferente de zero se o item OLE estiver aberto; caso contrário, 0.

Comentários

Ele é usado para determinar quando desenhar o objeto com um padrão de hachura. Um objeto aberto deve ter um padrão de hachura desenhado em cima do objeto. Você pode usar um objeto CRectTracker para fazer isso.

COleClientItem::IsRunning

Chame essa função para ver se o item OLE está em execução; ou seja, se o item está carregado e em execução no aplicativo para servidores.

BOOL IsRunning() const;

Valor de retorno

Diferente de zero se o item OLE estiver em execução; caso contrário, 0.

Comentários

Para obter mais informações, confira OleIsRunning no SDK do Windows.

COleClientItem::OnActivate

Chamada pela estrutura para notificar o item de que ele acabou de ser ativado no local.

virtual void OnActivate();

Comentários

Observe que essa função é chamada para indicar que o servidor está em execução, não para indicar que sua interface do usuário foi instalada no aplicativo de contêiner. Neste ponto, o objeto não tem uma interface do usuário ativa (não é activeUIState). Ele não instalou os próprios menus ou barra de ferramentas. A função membro OnActivateUI é chamada quando isso acontece.

A implementação padrão chama a função membro OnChange com OLE_CHANGEDSTATE como um parâmetro. Substitua essa função para executar o processamento personalizado quando um item ficar ativo no local.

COleClientItem::OnActivateUI

A estrutura chama OnActivateUI quando o objeto entrou no estado ativo da interface do usuário.

virtual void OnActivateUI();

Comentários

O objeto agora instalou a própria barra de ferramentas e menus.

A implementação padrão lembra o HWND do servidor para chamadas GetServerWindow posteriores.

COleClientItem::OnChange

Chamada pela estrutura quando o usuário modifica, salva ou fecha o item OLE.

virtual void OnChange(
    OLE_NOTIFICATION nCode,
    DWORD dwParam);

Parâmetros

nCode
O motivo pelo qual o servidor alterou esse item. Ele pode ter um dos seguintes valores:

• OLE_CHANGED A aparência do item OLE foi alterada.

• OLE_SAVED O item OLE foi salvo.

• OLE_CLOSED O item OLE foi fechado.

• OLE_CHANGED_STATE O item OLE foi alterado de um estado para outro.

dwParam
Se nCode for OLE_SAVED ou OLE_CLOSED, esse parâmetro não será usado. Se nCode for OLE_CHANGED, esse parâmetro especificará o aspecto do item OLE que foi alterado. Para obter os valores possíveis, confira o parâmetro dwParam de COleClientItem::Draw. Se nCode for OLE_CHANGED_STATE, esse parâmetro será um valor enumerado COleClientItem::ItemState e descreverá o estado que está sendo inserido. Ele pode ter um dos seguintes valores: emptyState, loadedState, openState, activeState ou activeUIState.

Comentários

(Se o aplicativo para servidores for escrito usando a biblioteca Microsoft Foundation Class, essa função será chamada em resposta às Notify funções membro de COleServerDoc ou COleServerItem.) A implementação padrão marcará o documento de contêiner como modificado se nCode for OLE_CHANGED ou OLE_SAVED.

Para OLE_CHANGED_STATE, o estado atual retornado de GetItemState ainda será o estado antigo, o que significa que o estado era atual antes dessa alteração de estado.

Substitua essa função para responder a alterações no estado do item OLE. Normalmente, você atualiza a aparência do item invalidando a área na qual o item é exibido. Chame a implementação da classe base no início da substituição.

COleClientItem::OnChangeItemPosition

Chamada pela estrutura para notificar o contêiner de que a extensão do item OLE foi alterada durante a ativação in-loco.

virtual BOOL OnChangeItemPosition(const CRect& rectPos);

Parâmetros

rectPos
Indica a posição do item em relação à área de cliente do aplicativo de contêiner.

Valor de retorno

Diferente de zero se a posição do item for alterada com êxito; caso contrário, 0.

Comentários

A implementação padrão determina o novo retângulo visível do item OLE e chama SetItemRects com os novos valores. A implementação padrão calcula o retângulo visível para o item e passa essas informações para o servidor.

Substitua essa função para aplicar regras especiais à operação de redimensionamento/movimentação. Se o aplicativo for gravado no MFC, isso resultará nessa chamada porque o servidor chamou COleServerDoc::RequestPositionChange.

COleClientItem::OnDeactivate

Chamada pela estrutura quando o item OLE faz a transição do estado ativo local (activeState) para o estado carregado, o que significa que ele é desativado após uma ativação in-loco.

virtual void OnDeactivate();

Comentários

Observe que essa função é chamada para indicar que o item OLE está fechado, não que a respectiva interface do usuário foi removida do aplicativo de contêiner. Quando isso ocorre, a função membro OnDeactivateUI é chamada.

A implementação padrão chama a função membro OnChange com OLE_CHANGEDSTATE como um parâmetro. Substitua essa função para executar o processamento personalizado quando um item ativo in-loco for desativado. Por exemplo, se você der suporte ao comando desfazer em seu aplicativo de contêiner, poderá substituir essa função para descartar o estado de desfazer, indicando que a última operação executada no item OLE não poderá ser desfeita depois que o item tiver sido desativado.

COleClientItem::OnDeactivateAndUndo

Chamada pela estrutura quando o usuário invoca o comando desfazer depois de ativar o item OLE no local.

virtual void OnDeactivateAndUndo();

Comentários

A implementação padrão chama DeactivateUI para desativar a interface do usuário do servidor. Substitua essa função se você estiver implementando o comando desfazer em seu aplicativo de contêiner. Em sua substituição, chame a versão da classe base da função e desfaça o último comando executado em seu aplicativo.

Para obter mais informações, confira IOleInPlaceSite::DeactivateAndUndo no SDK do Windows.

COleClientItem::OnDeactivateUI

Chamada quando o usuário desativa um item que foi ativado no local.

virtual void OnDeactivateUI(BOOL bUndoable);

Parâmetros

bUndoable
Especifica se as alterações de edição podem ser desfeitas.

Comentários

Essa função restaura a interface do usuário do aplicativo de contêiner para o estado original, ocultando menus e outros controles que foram criados para ativação in-loco.

Se bUndoable for FALSE, o contêiner deverá desabilitar o comando desfazer, descartando o estado de desfazer do contêiner, pois indica que a última operação executada pelo servidor não pode ser desfeita.

COleClientItem::OnDiscardUndoState

Chamada pela estrutura quando o usuário executa uma ação que descarta o estado de desfazer durante a edição do item OLE.

virtual void OnDiscardUndoState();

Comentários

A implementação padrão não tem ação. Substitua essa função se você estiver implementando o comando desfazer em seu aplicativo de contêiner. Na substituição, descarte o estado de desfazer do aplicativo de contêiner.

Se o servidor tiver sido gravado com a biblioteca Microsoft Foundation Class, o servidor poderá fazer com que essa função seja chamada chamando COleServerDoc::DiscardUndoState.

Para obter mais informações, confira IOleInPlaceSite::DiscardUndoState no SDK do Windows.

COleClientItem::OnGetClipboardData

Chamada pela estrutura para obter um objeto COleDataSource que contém todos os dados que seriam colocados na Área de Transferência por uma chamada para a função membro CopyToClipboard ou DoDragDrop.

virtual COleDataSource* OnGetClipboardData(
    BOOL bIncludeLink,
    LPPOINT lpOffset,
    LPSIZE lpSize);

Parâmetros

bIncludeLink
Defina isso como TRUE se os dados de link devem ser copiados para a área de transferência. Defina isso como FALSE se o aplicativo de servidor não der suporte a links.

lpOffset
Ponteiro para o deslocamento do cursor do mouse da origem do objeto em pixels.

lpSize
Ponteiro para o tamanho do objeto em pixels.

Valor de retorno

Um ponteiro para um objeto COleDataSource que contém os dados da área de transferência.

Comentários

A implementação padrão dessa função chama GetClipboardData.

COleClientItem::OnGetClipRect

A estrutura chama a função membro OnGetClipRect para obter as coordenadas do retângulo de recorte do item que está sendo editado no local.

virtual void OnGetClipRect(CRect& rClipRect);

Parâmetros

rClipRect
Ponteiro para um objeto da classe CRect que conterá as coordenadas do retângulo de recorte do item.

Comentários

As coordenadas estão em pixels em relação à área de cliente da janela do aplicativo de contêiner.

A implementação padrão simplesmente retorna o retângulo do cliente da exibição na qual o item está ativo in-loco.

COleClientItem::OnGetItemPosition

A estrutura chama a função membro OnGetItemPosition para obter as coordenadas do item que está sendo editado no local.

virtual void OnGetItemPosition(CRect& rPosition);

Parâmetros

rPosition
Referência ao objeto CRect que conterá as coordenadas de posição do item.

Comentários

As coordenadas estão em pixels em relação à área de cliente da janela do aplicativo de contêiner.

A implementação padrão dessa função não faz nada. Aplicativos que dão suporte à edição in-loco exigem a implementação dela.

COleClientItem::OnGetWindowContext

Chamada pela estrutura quando um item é ativado no local.

virtual BOOL OnGetWindowContext(
    CFrameWnd** ppMainFrame,
    CFrameWnd** ppDocFrame,
    LPOLEINPLACEFRAMEINFO lpFrameInfo);

Parâmetros

ppMainFrame
Ponteiro para um ponteiro para a janela do quadro principal.

ppDocFrame
Ponteiro para um ponteiro para a janela do quadro do documento.

lpFrameInfo
Ponteiro para uma estrutura OLEINPLACEFRAMEINFO que receberá informações da janela do quadro.

Valor de retorno

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

Comentários

Essa função é usada para recuperar informações sobre a janela pai do item OLE.

Se o contêiner for um aplicativo MDI, a implementação padrão retornará um ponteiro para o objeto CMDIFrameWnd em ppMainFrame e um ponteiro para o objeto CMDIChildWnd ativo em ppDocFrame. Se o contêiner for um aplicativo SDI, a implementação padrão retornará um ponteiro para o objeto CFrameWnd em ppMainFrame e retornará NULO em ppDocFrame. A implementação padrão também preenche os membros de lpFrameInfo.

Substitua essa função somente se a implementação padrão não atender ao seu aplicativo; por exemplo, se o aplicativo tiver um paradigma de interface do usuário diferente do SDI ou do MDI. Essa é uma substituição avançada.

Para obter mais informações, confira IOleInPlaceSite::GetWindowContext e a estrutura OLEINPLACEFRAMEINFO no SDK do Windows.

COleClientItem::OnInsertMenus

Chamada pela estrutura durante a ativação in-loco para inserir os menus do aplicativo de contêiner em um menu vazio.

virtual void OnInsertMenus(
    CMenu* pMenuShared,
    LPOLEMENUGROUPWIDTHS lpMenuWidths);

Parâmetros

pMenuShared
Aponta para um menu vazio.

lpMenuWidths
Aponta para uma matriz de seis valores LONG que indicam quantos menus estão em cada um dos seguintes grupos de menus: Arquivo, Editar, Contêiner, Objeto, Janela, Ajuda. O aplicativo de contêiner é responsável pelos grupos de menus Arquivo, Contêiner e Janela, correspondentes aos elementos 0, 2 e 4 dessa matriz.

Comentários

Em seguida, esse menu é passado para o servidor, que insere menus próprios, criando um menu composto. Essa função pode ser chamada repetidamente para criar vários menus compostos.

A implementação padrão insere em pMenuShared os menus de contêiner in-loco; ou seja, os grupos de menus Arquivo, Contêiner e Janela. CDocTemplate::SetContainerInfo é usado para definir esse recurso de menu. A implementação padrão também atribui os valores apropriados aos elementos 0, 2 e 4 em lpMenuWidths, dependendo do recurso de menu. Substitua essa função se a implementação padrão não for apropriada para seu aplicativo; por exemplo, se o aplicativo não usar modelos de documento para associar recursos a tipos de documento. Se você substituir essa função, também deverá substituir OnSetMenu e OnRemoveMenus. Essa é uma substituição avançada.

Para obter mais informações, confira IOleInPlaceFrame::InsertMenus no SDK do Windows.

COleClientItem::OnRemoveMenus

Chamada pela estrutura para remover os menus do contêiner do menu composto especificado quando a ativação in-loco terminar.

virtual void OnRemoveMenus(CMenu* pMenuShared);

Parâmetros

pMenuShared
Aponta para o menu composto construído por chamadas para a função membro OnInsertMenus.

Comentários

A implementação padrão remove de pMenuShared os menus de contêiner in-loco; ou seja, os grupos de menus Arquivo, Contêiner e Janela. Substitua essa função se a implementação padrão não for apropriada para seu aplicativo; por exemplo, se o aplicativo não usar modelos de documento para associar recursos a tipos de documento. Se você substituir essa função, provavelmente também deverá substituir OnInsertMenus e OnSetMenu. Essa é uma substituição avançada.

Os submenus em pMenuShared poderão ser compartilhados por mais de um menu composto se o servidor tiver chamado OnInsertMenusrepetidamente. Portanto, você não deve excluir nenhum submenu em sua substituição de OnRemoveMenus; você deve apenas desanexá-los.

Para obter mais informações, confira IOleInPlaceFrame::RemoveMenus no SDK do Windows.

COleClientItem::OnScrollBy

Chamada pela estrutura para rolar o item OLE em resposta às solicitações do servidor.

virtual BOOL OnScrollBy(CSize sizeExtent);

Parâmetros

sizeExtent
Especifica as distâncias, em pixels, para rolar nas direções x e y.

Valor de retorno

Diferente de zero se o item foi rolado; 0 se o item não pôde ser rolado.

Comentários

Por exemplo, se o item OLE estiver parcialmente visível e o usuário se mover para fora da região visível ao executar a edição in-loco, essa função será chamada para manter o cursor visível. A implementação padrão não tem ação. Substitua essa função para rolar o item pela quantidade especificada. Observe que, como resultado da rolagem, a parte visível do item OLE pode ser alterada. Chame SetItemRects para atualizar o retângulo visível do item.

Para obter mais informações, confira IOleInPlaceSite::Scroll no SDK do Windows.

COleClientItem::OnSetMenu

Chamada pela estrutura duas vezes quando a ativação in-loco começa e termina; a primeira vez para instalar o menu composto e a segunda vez (com holemenu igual a NULL) para removê-lo.

virtual void OnSetMenu(
    CMenu* pMenuShared,
    HOLEMENU holemenu,
    HWND hwndActiveObject);

Parâmetros

pMenuShared
Ponteiro para o menu composto construído por chamadas para a função membro OnInsertMenus e a função InsertMenu.

holemenu
Identificador para o descritor de menu retornado pela função OleCreateMenuDescriptor ou NULL se o código de expedição for removido.

hwndActiveObject
Identificador para a janela de edição do item OLE. Essa é a janela que receberá comandos de edição do OLE.

Comentários

A implementação padrão instala ou remove o menu composto e chama a função OleSetMenuDescriptor para instalar ou remover o código de expedição. Substitua essa função se a implementação padrão não for apropriada para seu aplicativo. Se você substituir essa função, provavelmente também deverá substituir OnInsertMenus e OnRemoveMenus. Essa é uma substituição avançada.

Para obter mais informações, confira OleCreateMenuDescriptor, OleSetMenuDescriptor e IOleInPlaceFrame::SetMenu no SDK do Windows.

COleClientItem::OnShowControlBars

Chamada pela estrutura para mostrar e ocultar as barras de controle do aplicativo de contêiner.

virtual BOOL OnShowControlBars(
    CFrameWnd* pFrameWnd,
    BOOL bShow);

Parâmetros

pFrameWnd
Ponteiro para a janela do quadro do aplicativo de contêiner. Ela pode ser uma janela do quadro principal ou uma janela filho do MDI.

bShow
Especifica se as barras de controle devem ser mostradas ou ocultas.

Valor de retorno

Diferente de zero se a chamada de função causar uma alteração no estado das barras de controle; 0 se a chamada não causar nenhuma alteração ou se pFrameWnd não apontar para a janela do quadro do contêiner.

Comentários

Essa função retornará 0 se as barras de controle já estiverem no estado especificado por bShow. Isso ocorreria, por exemplo, se as barras de controle estiverem ocultas e bShow fosse FALSE.

A implementação padrão remove a barra de ferramentas da janela do quadro de nível superior.

COleClientItem::OnShowItem

Chamada pela estrutura para exibir o item OLE, tornando-o totalmente visível durante a edição.

virtual void OnShowItem();

Comentários

Ele é usado quando o aplicativo de contêiner dá suporte a links para itens inseridos (ou seja, se você derivou sua classe de documento de COleLinkingDoc). Essa função é chamada durante a ativação in-loco ou quando o item OLE é uma fonte de link e o usuário deseja editá-la. A implementação padrão ativa a primeira exibição no documento de contêiner. Substitua essa função para rolar o documento para que o item OLE fique visível.

COleClientItem::OnUpdateFrameTitle

Chamada pela estrutura durante a ativação in-loco para atualizar a barra de título da janela do quadros.

virtual BOOL OnUpdateFrameTitle();

Valor de retorno

Diferente de zero se essa função tiver atualizado com êxito o título do quadro, caso contrário, zero.

Comentários

A implementação padrão não altera o título da janela do quadro. Substitua essa função se você quiser um título de quadro diferente para seu aplicativo, por exemplo, "aplicativo de servidor - item em nome do documento" (como em" Microsoft Excel – planilha em RELATÓRIO.DOC"). Essa é uma substituição avançada.

COleClientItem::ReactivateAndUndo

Chame essa função para reativar o item OLE e desfazer a última operação executada pelo usuário durante a edição in-loco.

BOOL ReactivateAndUndo();

Valor de retorno

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

Comentários

Se o aplicativo de contêiner der suporte ao comando desfazer, chame essa função se o usuário escolher o comando desfazer imediatamente após desativar o item OLE.

Se o aplicativo para servidores for gravado com as bibliotecas do Microsoft Foundation Class, essa função fará com que o servidor chame COleServerDoc::OnReactivateAndUndo.

Para obter mais informações, confira IOleInPlaceObject::ReactivateAndUndo no SDK do Windows.

COleClientItem::Release

Chame essa função para limpar os recursos usados pelo item OLE.

virtual void Release(OLECLOSE dwCloseOption = OLECLOSE_NOSAVE);

Parâmetros

dwCloseOption
Sinalizador especificando em quais circunstâncias o item OLE é salvo quando ele retorna ao estado carregado. Para obter uma lista de valores possíveis, confira COleClientItem::Close.

Comentários

Release é chamado pelo destruidor COleClientItem.

Para obter mais informações, confira IUnknown::Release no SDK do Windows.

COleClientItem::Reload

Fecha e recarrega o item.

BOOL Reload();

Valor de retorno

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

Comentários

Chame a função Reload depois de ativar o item como um item de outro tipo por uma chamada para ActivateAs.

COleClientItem::Run

Executa o aplicativo associado a este item.

void Run();

Comentários

Chame a função membro Run para iniciar o aplicativo para servidores antes de ativar o item. Isso é feito automaticamente por Activate e DoVerb, portanto, geralmente não é necessário chamar essa função. Chame essa função se for necessário executar o servidor para definir um atributo de item, como SetExtent, antes de executar DoVerb.

COleClientItem::SetDrawAspect

Chame a função membro SetDrawAspect para definir o "aspecto", ou exibição, do item.

virtual void SetDrawAspect(DVASPECT nDrawAspect);

Parâmetros

nDrawAspect
Um valor da enumeração DVASPECT. Esse parâmetro pode ter um dos seguintes valores:

• DVASPECT_CONTENT O item é representado de maneira que ele possa ser exibido como um objeto inserido dentro do respectivo contêiner.

• DVASPECT_THUMBNAIL O item é renderizado em uma representação de "miniatura" para que ele possa ser exibido em uma ferramenta de navegação.

• DVASPECT_ICON O item é representado por um ícone.

• DVASPECT_DOCPRINT O item é representado como se tivesse sido impresso usando o comando Imprimir no menu Arquivo.

Comentários

O aspecto especifica como o item deve ser renderizado por Draw quando o valor padrão do argumento nDrawAspect dessa função é usado.

Essa função é chamada automaticamente por Alterar Ícone (e outros diálogos que chamam a caixa de diálogo Alterar Ícone diretamente) para habilitar o aspecto de exibição icônico quando solicitado pelo usuário.

COleClientItem::SetExtent

Chame essa função para especificar quanto espaço está disponível para o item OLE.

void SetExtent(
    const CSize& size,
    DVASPECT nDrawAspect = DVASPECT_CONTENT);

Parâmetros

size
Um objeto CSize que contém as informações de tamanho.

nDrawAspect
Especifica o aspecto do item OLE cujos limites devem ser definidos. Para saber os valores possíveis, confira SetDrawAspect.

Comentários

Se o aplicativo para servidores foi escrito usando a biblioteca Microsoft Foundation Class, essa função fará com que a função membro OnSetExtent do objeto correspondente COleServerItem seja chamada. Depois, o item OLE pode ajustar a própria exibição adequadamente. As dimensões precisam estar em unidades MM_HIMETRIC. Chame essa função quando o usuário redimensionar o item OLE ou se você der suporte a alguma forma de negociação de layout.

Para obter mais informações, confira IOleObject::SetExtent no SDK do Windows.

COleClientItem::SetHostNames

Chame essa função para especificar o nome do aplicativo de contêiner e o nome do contêiner para um item OLE inserido.

void SetHostNames(
    LPCTSTR lpszHost,
    LPCTSTR lpszHostObj);

Parâmetros

lpszHost
Ponteiro para o nome visível do usuário do aplicativo de contêiner.

lpszHostObj
Ponteiro para uma cadeia de caracteres de identificação do contêiner que contém o item OLE.

Comentários

Se o aplicativo para servidores foi gravado usando a biblioteca Microsoft Foundation Class, essa função chamará a função membro OnSetHostNames do documento COleServerDoc que contém o item OLE. Essas informações são usadas em títulos de janela quando o item OLE está sendo editado. Sempre que um documento de contêiner é carregado, a estrutura chama essa função para todos os itens OLE no documento. SetHostNames é aplicável somente a itens inseridos. Não será necessário chamar essa função sempre que um item OLE inserido for ativado para edição.

Essa função também é chamada automaticamente com o nome do aplicativo e o nome do documento quando um objeto é carregado ou quando um arquivo é salvo em um nome diferente. Assim, normalmente não é necessário chamar essa função diretamente.

Para obter mais informações, confira IOleObject::SetHostNames no SDK do Windows.

COleClientItem::SetIconicMetafile

Armazena em cache o meta-arquivo usado para desenhar o ícone do item.

BOOL SetIconicMetafile(HGLOBAL hMetaPict);

Parâmetros

hMetaPict
Um identificador do meta-arquivo usado para desenhar o ícone do item.

Valor de retorno

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

Comentários

Use GetIconicMetafile para recuperar o meta-arquivo.

O parâmetro hMetaPict é copiado para o item; portanto, hMetaPict precisa ser liberado pelo chamador.

COleClientItem::SetItemRects

Chame essa função para definir o retângulo delimitador ou o retângulo visível do item OLE.

BOOL SetItemRects(
    LPCRECT lpPosRect = NULL,
    LPCRECT lpClipRect = NULL);

Parâmetros

lprcPosRect
Ponteiro para o retângulo que contém os limites do item OLE em relação à janela pai, nas coordenadas do cliente.

lprcClipRect
Ponteiro para o retângulo que contém os limites da parte visível do item OLE em relação à janela pai dele, nas coordenadas do cliente.

Valor de retorno

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

Comentários

Essa função é chamada pela implementação padrão da função membro OnChangeItemPosition. Você deverá chamar essa função sempre que a posição ou a parte visível do item OLE for alterada. Normalmente, isso significa que você a chama das funções membro OnSize e OnScrollBy da sua exibição.

Para obter mais informações, confira IOleInPlaceObject::SetObjectRects no SDK do Windows.

COleClientItem::SetLinkUpdateOptions

Chame essa função para definir a opção de atualização de link para a apresentação do item vinculado especificado.

void SetLinkUpdateOptions(OLEUPDATE dwUpdateOpt);

Parâmetros

dwUpdateOpt
O valor da opção de atualização de link para este item. O valor precisa ser um dos seguintes:

• OLEUPDATE_ALWAYS Atualizar o item vinculado sempre que possível. Essa opção dá suporte ao botão de opção Atualização automática de link na caixa de diálogo Links.

• OLEUPDATE_ONCALL Atualizar o item vinculado somente na solicitação do aplicativo de contêiner (quando a função membro UpdateLink for chamada). Essa opção dá suporte ao botão de opção Atualização manual de link na caixa de diálogo Links.

Comentários

Normalmente, você não deve alterar as opções de atualização escolhidas pelo usuário na caixa de diálogo Links.

Para obter mais informações, confira IOleLink::SetUpdateOptions no SDK do Windows.

COleClientItem::SetPrintDevice

Chame essa função para alterar o dispositivo de destino de impressão para este item.

BOOL SetPrintDevice(const DVTARGETDEVICE* ptd);
BOOL SetPrintDevice(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 o item, mas não atualiza o cache de apresentação. Para atualizar o cache de apresentação de um item, chame UpdateLink.

Os argumentos para essa função contêm informações que o sistema 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 sobre essa estrutura, confira PRINTDLG no SDK do Windows.

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

COleClientItem::UpdateLink

Chame essa função para atualizar os dados de apresentação do item OLE imediatamente.

BOOL UpdateLink();

Valor de retorno

Diferente de zero em caso de êxito. Caso contrário, 0.

Comentários

Para itens vinculados, a função localiza a origem do link para obter uma nova apresentação para o item OLE. Esse processo pode envolver a execução de um ou mais aplicativos para servidores, o que pode ser demorado. Para itens inseridos, a função opera recursivamente, verificando se o item inserido contém links que podem estar desatualizados e atualizando-os. O usuário também pode atualizar manualmente links individuais usando a caixa de diálogo Links.

Para obter mais informações, confira IOleLink::Update no SDK do Windows.

Confira também

MFCBIND de exemplo do MFC
OCLIENT de exemplo do MFC
Classe CDocItem
Gráfico da hierarquia
Classe COleServerItem