COleClientItem Classe

Define a interface de contêiner para itens OLE.

Sintaxe

class COleClientItem : public CDocItem

Membros

Construtores Públicos

Métodos Públicos

Métodos Protegidos

Observações

Um item OLE representa dados, criados e mantidos por um aplicativo de servidor, que podem ser incorporados "perfeitamente" em um documento para que pareça ao usuário como um único documento. O resultado é um "documento composto" composto pelo item OLE e um documento contido.

Um item OLE pode ser incorporado ou vinculado. Se ele estiver incorporado, seus dados serão armazenados como parte do documento composto. Se ele estiver vinculado, seus dados serão armazenados como parte de um arquivo separado criado pelo aplicativo de servidor e somente um link para esse arquivo será armazenado no documento composto. Todos os itens OLE contêm informações especificando o aplicativo de servidor 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 de servidor; Esses substituíveis geralmente funcionam como notificações. Isso permite que o aplicativo de servidor informe o contêiner sobre as alterações que o usuário faz ao editar o item OLE ou para recuperar informações necessárias durante a edição.

COleClientItem pode ser usado com a classe COleDocument, COleLinkingDoc ou COleServerDoc . Para usar COleClientItemo , derive uma classe dele e implemente a função de 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 de membro OnGetItemPosition . Esta função fornece informações sobre a posição exibida do item OLE.

Para obter mais informações sobre como usar a interface de contêiner, consulte os artigos Containers: Implementing a Container and Activation.

Hierarquia de herança

CObject

CCmdTarget

CDocItem

COleClientItem

Requerimentos

Cabeçalho: afxole.h

COleClientItem::Ativar

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

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

Parâmetros

nVerbo
Especifica o verbo executar. Pode ser um dos seguintes:

O valor -1 é normalmente um alias para outro verbo. Se a edição aberta não for suportada, -2 terá o mesmo efeito que -1. Para obter valores adicionais, consulte IOleObject::D oVerb no SDK do Windows.

Pré-visualização
Ponteiro para a janela de exibição de contêiner que contém o item OLE; Isso é usado pelo aplicativo de servidor para ativação in-loco. Esse parâmetro deve ser NULL se o contêiner não oferecer suporte à ativação in-loco.

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

Observações

Se o aplicativo de servidor foi escrito usando o Microsoft Foundation Class Library, essa função faz com que a função de membro OnDoVerb do objeto correspondente COleServerItem seja executada.

Se o verbo primário for Edit e zero for especificado no parâmetro nVerb , o aplicativo de servidor será iniciado para permitir que o item OLE seja editado. Se o aplicativo contêiner suportar ativação in-loco, a edição pode ser feita no local. Se o contêiner não suportar a 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 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 oferecer suporte a apenas uma ação, ele executará essa ação, independentemente do valor especificado no parâmetro nVerb .

Para obter mais informações, consulte IOleObject::D oVerb no SDK do Windows.

COleClientItem::ActivateAs

Usa os recursos 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 ao ID de classe atual do item. O ID da classe deve representar o tipo do objeto real, conforme armazenado, a menos que seja um link. Nesse caso, deve ser o CLSID do item ao qual o link se refere. O COleConvertDialog fornece automaticamente a ID de classe correta para o item.

clsidNovo
Uma referência ao ID da classe de destino.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

Isso é chamado automaticamente por COleConvertDialog::D oConvert. Geralmente não é chamado 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 COleDataObject objeto que será inicializado para permitir o acesso aos dados no item OLE.

COleClientItem::CanActivate

Chamado pela estrutura quando o usuário solicita a ativação in-loco do item OLE; O valor de retorno desta 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.

Observações

A implementação padrão permite 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, consulte IOleInPlaceSite::CanInPlaceActivate no SDK do Windows.

COleClientItem::CanCreateFromData

Verifica se um aplicativo de contêiner pode criar um objeto incorporado a partir de um determinado COleDataObject objeto.

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 incorporado a partir do COleDataObject objeto, caso contrário, 0.

Observações

A COleDataObject classe é usada em transferências de dados para recuperar dados em vários formatos da área de transferência, através de arrastar e soltar, ou de um item OLE incorporado.

Os contêineres podem usar essa função para decidir ativar ou desabilitar os comandos Editar colar e Editar colar especial.

Para obter mais informações, consulte o artigo Data Objects and Data Sources (OLE).

COleClientItem::CanCreateLinkFromData

Verifica se um aplicativo contêiner pode criar um objeto vinculado a partir de um determinado COleDataObject objeto.

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 a partir do COleDataObject objeto.

Observações

A COleDataObject classe é usada em transferências de dados para recuperar dados em vários formatos da área de transferência, através de arrastar e soltar, ou de um item OLE incorporado.

Os contêineres podem usar essa função para decidir ativar ou desabilitar os comandos Editar colar especial e Editar colar link.

Para obter mais informações, consulte o artigo Data Objects and Data Sources (OLE).

COleClientItem::CanPaste

Chame essa função para ver se um item OLE incorporado pode ser colado da área de transferência.

static BOOL PASCAL CanPaste();

Valor de retorno

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

Observações

Para obter mais informações, consulte 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.

Observações

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

COleClientItem::Fechar

Chame essa função para alterar o estado de um item OLE do estado em execução para o estado carregado, ou seja, carregado com seu 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 que circunstâncias o item OLE é salvo quando retorna ao estado carregado. Pode ter um dos seguintes valores:

• OLECLOSE_SAVEIFDIRTY Salve o item OLE.

• OLECLOSE_NOSAVE Não salve o item OLE.

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

Observações

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

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

COleClientItem::COleClientItem

Constrói um COleClientItem objeto e o adiciona à coleção de itens de documento do documento 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 do COleDocument .

Observações

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

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

• CreateFromClipboard

• CreateFromData

• CreateFromFile

• CreateStaticFromClipboard

• CreateStaticFromData

• CreateLinkFromClipboard

• CreateLinkFromData

• CreateLinkFromFile

• CreateNewItem

• CriarCloneDe

COleClientItem::ConvertTo

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

virtual BOOL ConvertTo(REFCLSID clsidNew);

Parâmetros

clsidNovo
O ID de classe do tipo de destino.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

Isso é chamado automaticamente por COleConvertDialog. Não é necessário chamá-lo 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 do link devem ser copiadas para a Área de Transferência, permitindo que um item vinculado seja colado; caso contrário, FALSE.

Observações

Normalmente, você chama essa função ao escrever manipuladores de mensagens para os comandos Copiar ou Recortar no menu Editar. Você deve 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, consulte 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 for bem-sucedido; caso contrário, 0.

Observações

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 incorporado a partir do conteúdo da Área de Transferência.

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

Parâmetros

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

cfFormato
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 a renderização estiver OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se desejar especificar informações de formato adicionais além do formato da Á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 FORMATETC estrutura.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

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

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

COleClientItem::CreateFromData

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

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.

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

cfFormato
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 a renderização estiver OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se desejar especificar informações de formato adicionais além do formato da Á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 FORMATETC estrutura.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

As operações de transferência de dados, como colar da Área de Transferência ou operações de arrastar e soltar, fornecem COleDataObject objetos que contêm as informações oferecidas por um aplicativo de servidor. Geralmente é usado na sua substituição de CView::OnDrop.

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

COleClientItem::CreateFromFile

Chame essa função para criar um item OLE incorporado 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 a partir do qual o item OLE deve ser criado.

CLSID
Reservado para uso futuro.

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

cfFormato
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 a renderização estiver OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se desejar especificar informações de formato adicionais além do formato da Á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 FORMATETC estrutura.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

A estrutura chama essa função de COleInsertDialog::CreateItem se o usuário escolher OK na caixa de diálogo Inserir objeto quando o botão Criar a partir do arquivo estiver selecionado.

Para obter mais informações, consulte 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

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

cfFormato
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 a renderização estiver OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se desejar especificar informações de formato adicionais além do formato da Á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 FORMATETC estrutura.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

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

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

COleClientItem::CreateLinkFromData

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

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.

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

cfFormato
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 a renderização estiver OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se desejar especificar informações de formato adicionais além do formato da Á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 FORMATETC estrutura.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

Chame isso durante uma operação de soltar quando o usuário indica que um link deve ser criado. Ele também pode ser usado para manipular o comando Editar Colagem. Ele é chamado pela estrutura em COleClientItem::CreateLinkFromClipboard e em COlePasteSpecialDialog::CreateItem quando a opção Link foi selecionada.

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

COleClientItem::CreateLinkFromFile

Chame essa função para criar um item OLE vinculado a partir 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 a partir do qual o item OLE deve ser criado.

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

cfFormato
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 a renderização estiver OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se desejar especificar informações de formato adicionais além do formato da Á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 FORMATETC estrutura.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

A estrutura chama essa função se o usuário escolher OK na caixa de diálogo Inserir objeto quando o botão Criar a partir do arquivo estiver selecionado e a caixa de seleção Link estiver marcada. É chamado de COleInsertDialog::CreateItem.

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

COleClientItem::CreateNewItem

Chame essa função para criar um item incorporado; esta função inicia o aplicativo de servidor que permite ao usuário criar 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.

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

cfFormato
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 a renderização estiver OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se desejar especificar informações de formato adicionais além do formato da Á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 FORMATETC estrutura.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

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

Para obter mais informações, consulte 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

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

cfFormato
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 a renderização estiver OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se desejar especificar informações de formato adicionais além do formato da Á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 FORMATETC estrutura.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

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

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

COleClientItem::CreateStaticFromData

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

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.

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

cfFormato
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 a renderização estiver OLERENDER_FORMAT ou OLERENDER_DRAW. Forneça um valor para esse parâmetro somente se desejar especificar informações de formato adicionais além do formato da Á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 FORMATETC estrutura.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

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

Usado em COlePasteSpecialDialog::CreateItem quando Static é selecionado.

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

COleClientItem::D eactivate

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

void Deactivate();

Observações

Normalmente, você desativa um item OLE ativo in-loco quando o usuário clica com o mouse na área do cliente fora dos limites do item. Observe que desativar o item OLE descartará seu estado de desfazer, tornando impossível chamar a função de membro ReactivateAndUndo .

Se o seu aplicativo suportar desfazer, não chame Deactivate, em vez disso, chame DeactivateUI.

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

COleClientItem::D eactivateUI

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

void DeactivateUI();

Observações

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

Esta 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 undo no aplicativo do servidor, caso o comando undo do contêiner seja escolhido imediatamente após a desativação do item.

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

COleClientItem::D elete

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

void Delete(BOOL bAutoDelete = TRUE);

Parâmetros

bExclusão automática
Especifica se o item deve ser removido do documento.

Observações

Essa função chama a função Release member, que por sua vez exclui o objeto C++ para o item, removendo permanentemente o item OLE do documento. Se o item OLE estiver incorporado, 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::D oDragDrop

Chame a DoDragDrop função de membro 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 deslocamento de lpItemRect onde a posição do mouse estava no momento do arrasto.

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

dwEfeitos
Determina os efeitos que a fonte de arrasto permitirá na operação de arrastar.

lpRectStartArrastar
Ponteiro para o retângulo que define onde o arrasto 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 devem ser removidos.

Observações

A operação de arrastar e soltar não é iniciada imediatamente. Ele aguarda até que o cursor do mouse saia do retângulo especificado por lpRectStartDrag ou até que um número especificado 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 arrasto é armazenado da seguinte forma:

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

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

• Windows 95/98 Tempo de atraso de arrasto é armazenado em uma versão em cache do WIN. INI.

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

COleClientItem::D oVerb

Chamada DoVerb para executar o verbo especificado.

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

Parâmetros

nVerbo
Especifica o verbo executar. Pode incluir um dos seguintes elementos:

O valor -1 é normalmente um alias para outro verbo. Se a edição aberta não for suportada, -2 terá o mesmo efeito que -1. Para obter valores adicionais, consulte IOleObject::D oVerb no SDK do Windows.

Pré-visualização
Ponteiro para a janela de visualização; Isso é usado pelo servidor para ativação in-loco. Este parâmetro deve ser NULL se o aplicativo 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

Diferente de zero se o verbo foi executado com sucesso; caso contrário, 0.

Observações

Esta função chama a função Ativar membro para executar o verbo. Ele também captura exceções e exibe uma caixa de mensagem para o usuário se uma for lançada.

Se o verbo primário for Edit e zero for especificado no parâmetro nVerb , o aplicativo de servidor será iniciado para permitir que o item OLE seja editado. Se o aplicativo contêiner suportar ativação in-loco, a edição pode ser feita no local. Se o contêiner não suportar a 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 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 oferecer suporte a apenas uma ação, ele executará essa ação, independentemente do valor especificado no parâmetro nVerb .

COleClientItem::D raw

Chame essa função para desenhar o item OLE no retângulo delimitador especificado usando o contexto de 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.

lpLimites
Ponteiro para um objeto 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 aspeto do item OLE, ou seja, como ele deve ser exibido. Se nDrawAspect for -1, o último aspeto definido usando SetDrawAspect será usado. Para obter mais informações sobre valores possíveis para esse sinalizador, consulte SetDrawAspect.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

A função pode usar a representação de metarquivo do item OLE criado pela função de 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 seu modo de mapeamento atual). 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 a exibição exibida e a imagem impressa final.

Para obter mais informações, consulte IViewObject::D raw no SDK do Windows.

COleClientItem::GetActiveView

Retorna o modo de exibição no qual o item está ativado no local.

CView* GetActiveView() const;

Valor de retorno

Um ponteiro para a vista; 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

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

nDrawAspect
Especifica o aspeto do item OLE cujos limites devem ser recuperados. Para valores possíveis, consulte SetDrawAspect.

Valor de retorno

Diferente de zero se for bem-sucedido; 0 se o item OLE estiver em branco.

Observações

Esta 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 MM_HIMETRIC unidades.

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

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

COleClientItem::GetClassID

Retorna o ID de classe do item na memória apontada por pClassID.

void GetClassID(CLSID* pClassID) const;

Parâmetros

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

Observações

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

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

COleClientItem::GetClipboardData

Chame essa função para obter um COleDataSource objeto contendo todos os dados que seriam colocados na área de transferência por uma chamada para a função de 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 do link devem ser incluídos; caso contrário, FALSE.

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

lpTamanho
O tamanho do objeto em pixels.

Observações

GetClipboardData é chamado como a implementação padrão de OnGetClipboardData. Substitua OnGetClipboardData somente se quiser oferecer formatos de dados além dos oferecidos pelo CopyToClipboard. Coloque esses formatos no objeto antes ou depois de COleDataSource chamar CopyToClipboarde, em seguida, passe o COleDataSource objeto 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, você definiria seu próprio formato para passar essas informações e colocá-lo COleDataSource no 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.

Observações

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

COleClientItem::GetDrawAspect

Chame a GetDrawAspect função de membro para determinar o "aspeto" 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.

Observações

O aspeto 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

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

nDrawAspect
Especifica o aspeto do item OLE cujos limites devem ser recuperados. Para valores possíveis, consulte SetDrawAspect.

Valor de retorno

Diferente de zero se for bem-sucedido; 0 se o item OLE estiver em branco.

Observações

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

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

COleClientItem::GetIconFromRegistry

Chame essa função de 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.

Observações

Esta função de 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 de membro abre a imagem executável do servidor e recupera o ícone estático associado ao servidor como ele foi registrado.

COleClientItem::GetIconicMetafile

Recupera o metarquivo usado para desenhar o ícone do item.

HGLOBAL GetIconicMetafile();

Valor de retorno

Um identificador para o metarquivo, se bem-sucedido; caso contrário, NULL.

Observações

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

Esta função também chama SetIconicMetafile para armazenar em cache o metarquivo para uso posterior.

COleClientItem::GetInPlaceWindow

Chame a GetInPlaceWindow função de membro 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 estiver indisponível.

Observações

Esta 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 COleClientItem::ItemState valor enumerado, que pode ser um dos seguintes: emptyState, loadedState, openState, , activeStateactiveUIState. Para obter informações sobre esses estados, consulte o artigo Containers: Client-Item States.

Observações

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

Para obter mais informações, consulte o artigo Containers: Client-Item States.

COleClientItem::GetLastStatus

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

SCODE GetLastStatus() const;

Valor de retorno

Um valor SCODE.

Observações

Para funções de membro que retornam um valor BOOL de FALSE, ou outras funções de membro que retornam NULL, GetLastStatus retorna informações de falha mais detalhadas. Esteja ciente de que a maioria das funções de membro OLE lançam 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 SCODE.

Para obter mais informações sobre SCODE, consulte 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 Atualize o item vinculado sempre que possível. Esta opção suporta o botão de opção Atualização automática de link na caixa de diálogo Vínculos.

• OLEUPDATE_ONCALL Atualize o item vinculado somente mediante solicitação do aplicativo contêiner (quando a função de membro UpdateLink é chamada). Esta opção suporta o botão de opção Atualização manual de links na caixa de diálogo Vínculos.

Observações

Esta é uma operação avançada.

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

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

COleClientItem::GetType

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

OLE_OBJTYPE GetType() const;

Valor de retorno

Um inteiro não assinado com um dos seguintes valores:

• OT_LINK O item OLE é um link.

• OT_EMBEDDED O item OLE está incorporado.

• OT_STATIC O item OLE é estático, ou seja, 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. Isso pode ter um dos seguintes valores:

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

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

• USERCLASSTYPE_APPNAME Nome do aplicativo que serve 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.

Observações

Esta é muitas vezes a entrada na base de dados de registo do sistema.

Se o nome completo do tipo for solicitado, mas não estiver disponível, o nome abreviado será usado. 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, consulte IOleObject::GetUserType no SDK do Windows.

COleClientItem::IsInPlaceActive

Chame essa função para ver se o item OLE está ativo in-loco.

BOOL IsInPlaceActive() const;

Valor de retorno

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

Observações

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

COleClientItem::IsLinkUpToDate

Chame essa função para ver 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.

Observações

Um item vinculado pode estar desatualizado se seu documento de origem tiver sido atualizado. Um item incorporado que contém links dentro dele também pode ficar desatualizado. 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.

Isso é chamado automaticamente pela implementação COleLinksDialog .

Para obter mais informações, consulte 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.

Observações

Para obter mais informações, consulte 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 de servidor 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.

Observações

Ele é usado para determinar quando desenhar o objeto com um padrão de eclosão. Um objeto aberto deve ter um padrão de escotilha desenhado sobre o 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 do servidor.

BOOL IsRunning() const;

Valor de retorno

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

Observações

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

COleClientItem::OnActivate

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

virtual void OnActivate();

Observações

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 contêiner. Neste ponto, o objeto não tem uma interface de usuário ativa (não activeUIStateé ). Ele não instalou seus menus ou barra de ferramentas. A função de membro OnActivateUI é chamada quando isso acontece.

A implementação padrão chama a função de membro OnChange com OLE_CHANGEDSTATE como parâmetro. Substitua essa função para executar o processamento personalizado quando um item se torna ativo in-loco.

COleClientItem::OnActivateUI

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

virtual void OnActivateUI();

Observações

O objeto já instalou sua barra de ferramentas e menus.

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

COleClientItem::OnChange

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

virtual void OnChange(
    OLE_NOTIFICATION nCode,
    DWORD dwParam);

Parâmetros

nCódigo
O motivo pelo qual o servidor alterou este item. 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 especifica o aspeto do item OLE que foi alterado. Para valores possíveis, consulte o parâmetro dwParam de COleClientItem::D raw. Se nCode for OLE_CHANGED_STATE, esse parâmetro será um COleClientItem::ItemState valor enumerado e descreverá o estado que está sendo inserido. Pode ter um dos seguintes valores: emptyState, loadedState, openState, activeState, ou activeUIState.

Observações

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

Por OLE_CHANGED_STATE, o estado atual retornado de GetItemState ainda será o estado antigo, ou seja, o estado que 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

Chamado 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

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

Valor de retorno

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

Observações

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 esta função para aplicar regras especiais à operação de redimensionamento/movimentação. Se o aplicativo for escrito em MFC, essa chamada resultará porque o servidor chamado COleServerDoc::RequestPositionChange.

COleClientItem::OnDeactivate

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

virtual void OnDeactivate();

Observações

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

A implementação padrão chama a função de membro OnChange com OLE_CHANGEDSTATE como parâmetro. Substitua essa função para executar o processamento personalizado quando um item ativo in-loco é desativado. Por exemplo, se você oferecer suporte ao comando undo em seu aplicativo 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 pode ser desfeita depois que o item for desativado.

COleClientItem::OnDeactivateAndUndo

Chamado pela estrutura quando o usuário invoca o comando undo depois de ativar o item OLE no lugar.

virtual void OnDeactivateAndUndo();

Observações

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 undo em seu aplicativo de contêiner. Em sua substituição, chame a versão de classe base da função e, em seguida, desfaça o último comando executado em seu aplicativo.

Para obter mais informações, consulte IOleInPlaceSite::D eactivateAndUndo no SDK do Windows.

COleClientItem::OnDeactivateUI

Chamado 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 são inviáveis.

Observações

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

Se bUndoable for FALSE, o contêiner deve desabilitar o comando undo, na verdade descartando o estado de desfazer do contêiner, porque indica que a última operação executada pelo servidor não é inviável.

COleClientItem::OnDiscardUndoState

Chamado pela estrutura quando o usuário executa uma ação que descarta o estado de desfazer ao editar o item OLE.

virtual void OnDiscardUndoState();

Observações

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

Se o servidor foi escrito com o Microsoft Foundation Class Library, o servidor pode fazer com que essa função seja chamada chamando COleServerDoc::D iscardUndoState.

Para obter mais informações, consulte IOleInPlaceSite::D iscardUndoState no SDK do Windows.

COleClientItem::OnGetClipboardData

Chamado pela estrutura para obter um COleDataSource objeto contendo todos os dados que seriam colocados na área de transferência por uma chamada para a função de membro CopyToClipboard ou DoDragDrop .

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

Parâmetros

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

lpDeslocamento
Ponteiro para o deslocamento do cursor do mouse a partir da origem do objeto em pixels.

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

Observações

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

COleClientItem::OnGetClipRect

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

virtual void OnGetClipRect(CRect& rClipRect);

Parâmetros

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

Observações

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

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

COleClientItem::OnGetItemPosition

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

virtual void OnGetItemPosition(CRect& rPosition);

Parâmetros

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

Observações

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

A implementação padrão desta função não faz nada. As aplicações que suportam a edição in-loco requerem a sua implementação.

COleClientItem::OnGetWindowContext

Chamado pela estrutura quando um item é ativado no lugar.

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 for bem-sucedido; caso contrário, 0.

Observações

Esta 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á NULL 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 se adequar ao seu aplicativo; por exemplo, se seu aplicativo tiver um paradigma de interface do usuário diferente de SDI ou MDI. Este é um avançado substituível.

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

COleClientItem::OnInsertMenus

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

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

Parâmetros

pMenuCompartilhado
Aponta para um menu vazio.

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

Observações

Este menu é então passado para o servidor, que insere seus próprios menus, criando um menu composto. Esta função pode ser chamada repetidamente para construir 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 seu aplicativo não usa modelos de documento para associar recursos a tipos de documento. Se você substituir essa função, você também deve substituir OnSetMenu e OnRemoveMenus. Este é um avançado substituível.

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

COleClientItem::OnRemoveMenus

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

virtual void OnRemoveMenus(CMenu* pMenuShared);

Parâmetros

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

Observações

A implementação padrão remove do pMenuShared os menus de contêiner in-loco, ou seja, os grupos de menus File, Container e Window. Substitua essa função se a implementação padrão não for apropriada para seu aplicativo; Por exemplo, se seu aplicativo não usa modelos de documento para associar recursos a tipos de documento. Se você substituir essa função, você provavelmente deve substituir OnInsertMenus e OnSetMenu também. Este é um avançado substituível.

Os submenus em pMenuShared podem 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, consulte IOleInPlaceFrame::RemoveMenus no SDK do Windows.

COleClientItem::OnScrollBy

Chamado pela estrutura para rolar o item OLE em resposta a solicitações do servidor.

virtual BOOL OnScrollBy(CSize sizeExtent);

Parâmetros

tamanhoExtensão
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 puder ser rolado.

Observações

Por exemplo, se o item OLE estiver parcialmente visível e o usuário se mover para fora da região visível enquanto executa a edição in-loco, essa função será chamada para manter o cursor visível. A implementação padrão não faz nada. 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, consulte IOleInPlaceSite::Scroll no SDK do Windows.

COleClientItem::OnSetMenu

Chamado 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

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

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

hwndActiveObject
Manipule a janela de edição do item OLE. Esta é a janela que receberá comandos de edição do OLE.

Observações

A implementação padrão instala ou remove o menu composto e, em seguida, chama a função OleSetMenuDescriptor para instalar ou remover o código de despacho. Substitua essa função se a implementação padrão não for apropriada para seu aplicativo. Se você substituir essa função, você provavelmente deve substituir OnInsertMenus e OnRemoveMenus também. Este é um avançado substituível.

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

COleClientItem::OnShowControlBars

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

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

Parâmetros

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

bMostrar
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 de quadro do contêiner.

Observações

Esta 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 for FALSE.

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

COleClientItem::OnShowItem

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

virtual void OnShowItem();

Observações

Ele é usado quando seu aplicativo de contêiner suporta links para itens incorporados (ou seja, se você derivou sua classe de documento de COleLinkingDoc). Esta função é chamada durante a ativação in-loco ou quando o item OLE é uma fonte de link e o usuário deseja editá-lo. 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

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

virtual BOOL OnUpdateFrameTitle();

Valor de retorno

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

Observações

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, "item - de servidor em docname" (como em, "Microsoft Excel - planilha em REPORT.DOC"). Este é um avançado substituível.

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 for bem-sucedido; caso contrário, 0.

Observações

Se seu aplicativo contêiner suportar o comando undo, chame essa função se o usuário escolher o comando undo imediatamente após desativar o item OLE.

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

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

COleClientItem::Lançamento

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 que circunstâncias o item OLE é salvo quando retorna ao estado carregado. Para obter uma lista de valores possíveis, consulte COleClientItem::Close.

Observações

Release é chamado pelo COleClientItem destruidor.

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

COleClientItem::Recarregar

Fecha e recarrega o item.

BOOL Reload();

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

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

COleClientItem::Executar

Executa o aplicativo associado a este item.

void Run();

Observações

Chame a Run função de membro para iniciar o aplicativo de servidor antes de ativar o item. Isso é feito automaticamente por Activate e DoVerb, por isso 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 SetDrawAspect função de membro para definir o "aspeto", ou visualização, do item.

virtual void SetDrawAspect(DVASPECT nDrawAspect);

Parâmetros

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

• DVASPECT_CONTENT Item é representado de tal forma que pode ser exibido como um objeto incorporado dentro de seu contêiner.

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

• DVASPECT_ICON Item é representado por um ícone.

• DVASPECT_DOCPRINT Item é representado como se fosse impresso usando o comando Imprimir do menu Arquivo.

Observações

O aspeto especifica como o item deve ser processado por Draw quando o valor padrão para o argumento nDrawAspect dessa função é usado.

Esta função é chamada automaticamente pelo ícone Alterar (e outras caixas de diálogo que chamam a caixa de diálogo Alterar ícone diretamente) para ativar o aspeto 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

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

nDrawAspect
Especifica o aspeto do item OLE cujos limites devem ser definidos. Para valores possíveis, consulte SetDrawAspect.

Observações

Se o aplicativo de servidor foi escrito usando a Microsoft Foundation Class Library, isso faz com que a função de membro OnSetExtent do objeto correspondente COleServerItem seja chamada. O item OLE pode então ajustar sua exibição de acordo. As dimensões devem estar em MM_HIMETRIC unidades. Chame essa função quando o usuário redimensionar o item OLE ou se você oferecer suporte a alguma forma de negociação de layout.

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

COleClientItem::SetHostNames

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

void SetHostNames(
    LPCTSTR lpszHost,
    LPCTSTR lpszHostObj);

Parâmetros

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

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

Observações

Se o aplicativo de servidor foi escrito usando a Microsoft Foundation Class Library, essa função chama a função de membro OnSetHostNames do COleServerDoc documento que contém o item OLE. Essas informações são usadas em títulos de janela quando o item OLE está sendo editado. Cada vez que um documento de contêiner é carregado, a estrutura chama essa função para todos os itens OLE no documento. SetHostNames é aplicável apenas a itens incorporados. Não é necessário chamar essa função sempre que um item OLE incorporado é ativado para edição.

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

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

COleClientItem::SetIconicMetafile

Armazena em cache o metarquivo usado para desenhar o ícone do item.

BOOL SetIconicMetafile(HGLOBAL hMetaPict);

Parâmetros

hMetaPict
Um identificador para o metarquivo usado para desenhar o ícone do item.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

Use GetIconicMetafile para recuperar o metaarquivo.

O parâmetro hMetaPict é copiado para o item; portanto, hMetaPict deve 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 à sua 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 à sua janela pai, nas coordenadas do cliente.

Valor de retorno

Diferente de zero se for bem-sucedido; caso contrário, 0.

Observações

Esta função é chamada pela implementação padrão da função de membro OnChangeItemPosition . Você deve chamar essa função sempre que a posição ou parte visível do item OLE mudar. Normalmente, isso significa que você o chama a partir das funções de membro OnSize e OnScrollBy da sua visualização.

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

COleClientItem::SetLinkUpdateOptions

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

void SetLinkUpdateOptions(OLEUPDATE dwUpdateOpt);

Parâmetros

dwUpdateOpt
O valor da opção link-update para este item. Esse valor deve ser um dos seguintes:

• OLEUPDATE_ALWAYS Atualize o item vinculado sempre que possível. Esta opção suporta o botão de opção Atualização automática de link na caixa de diálogo Vínculos.

• OLEUPDATE_ONCALL Atualize o item vinculado somente mediante solicitação do aplicativo contêiner (quando a função de membro UpdateLink é chamada). Esta opção suporta o botão de opção Atualização manual de links na caixa de diálogo Vínculos.

Observações

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

Para obter mais informações, consulte 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.

Observações

Esta 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 PRINTDLG estrutura 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, consulte PRINTDLG no SDK do Windows.

Para obter mais informações, consulte 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 no sucesso; caso contrário, 0.

Observações

Para itens vinculados, a função localiza a fonte do link para obter uma nova apresentação para o item OLE. Esse processo pode envolver a execução de um ou mais aplicativos de servidor, o que pode ser demorado. Para itens incorporados, a função opera recursivamente, verificando se o item incorporado 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 Vínculos.

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

Ver também

Exemplo MFC MFCBIND
Exemplo de MFC OCLIENT
CDocItem Classe
Gráfico de Hierarquia
COleServerItem Classe