Aula COleControl

Uma classe base eficiente para desenvolver controles OLE.

Sintaxe

class COleControl : public CWnd

Membros

Construtores públicos

Nome	Descrição
COleControl::COleControl	Cria um objeto COleControl.

Métodos públicos

Nome	Descrição
COleControl::AmbientAppearance	Recupera a aparência atual do controle.
COleControl::AmbientBackColor	Retorna o valor da propriedade do ambiente BackColor.
COleControl::AmbientDisplayName	Retorna o nome do controle conforme especificado pelo contêiner.
COleControl::AmbientFont	Retorna o valor da propriedade do ambiente Fonte.
COleControl::AmbientForeColor	Retorna o valor da propriedade do ambiente ForeColor.
COleControl::AmbientLocaleID	Retorna a ID de localidade do contêiner.
COleControl::AmbientScaleUnits	Retorna o tipo de unidades usadas pelo contêiner.
COleControl::AmbientShowGrabHandles	Determina se os identificadores de captura devem ser exibidos.
COleControl::AmbientShowHatching	Determina se o hatching deve ser exibido.
COleControl::AmbientTextAlign	Retorna o tipo de alinhamento de texto especificado pelo contêiner.
COleControl::AmbientUIDead	Determina se o controle deve responder a ações de interface do usuário.
COleControl::AmbientUserMode	Determina o modo do contêiner.
COleControl::BoundPropertyChanged	Notifica o contêiner que uma propriedade associada foi alterada.
COleControl::BoundPropertyRequestEdit	Solicita permissão para editar o valor da propriedade.
COleControl::ClientToParent	Converte um ponto relativo à origem do controle para um ponto relativo à origem do contêiner.
COleControl::ClipCaretRect	Ajusta um retângulo de ponto se ele for sobreposto por um controle.
COleControl::ControlInfoChanged	Chame essa função depois que o conjunto de mnemônicos manipulados pelo controle tiver sido alterado.
COleControl::DisplayError	Exibe eventos de erro de estoque para o usuário do controle.
COleControl::DoClick	Implementação do método de estoque DoClick.
COleControl::DoPropExchange	Serializa as propriedades de um objeto COleControl.
COleControl::DoSuperclassPaint	Redesenha um controle OLE que foi subclasse de um controle do Windows.
COleControl::EnableSimpleFrame	Habilita o suporte a quadros simples para um controle.
COleControl::ExchangeExtent	Serializa a largura e a altura do controle.
COleControl::ExchangeStockProps	Serializa as propriedades de estoque do controle.
COleControl::ExchangeVersion	Serializa o número de versão do controle.
COleControl::FireClick	Aciona o evento estoque Click.
COleControl::FireDblClick	Aciona o evento estoque DblClick.
COleControl::FireError	Aciona o evento estoque Error.
COleControl::FireEvent	Aciona um evento personalizado.
COleControl::FireKeyDown	Aciona o evento estoque KeyDown.
COleControl::FireKeyPress	Aciona o evento estoque KeyPress.
COleControl::FireKeyUp	Aciona o evento estoque KeyUp.
COleControl::FireMouseDown	Aciona o evento estoque MouseDown.
COleControl::FireMouseMove	Aciona o evento estoque MouseMove.
COleControl::FireMouseUp	Aciona o evento estoque MouseUp.
COleControl::FireReadyStateChange	Aciona um evento quando o estado pronto do controle é alterado.
COleControl::GetActivationPolicy	Altera o comportamento de ativação padrão de um controle que dá suporte à interface IPointerInactive.
COleControl::GetAmbientProperty	Retorna o valor da propriedade do ambiente especificado.
COleControl::GetAppearance	Retorna o valor da propriedade Appearance de ações.
COleControl::GetBackColor	Retorna o valor da propriedade da ação BackColor.
COleControl::GetBorderStyle	Retorna o valor da propriedade BorderStyle de ações.
COleControl::GetCapture	Determina se um objeto de controle ativado sem janelas tem a captura do mouse.
COleControl::GetClassID	Recupera a ID da classe OLE do controle.
COleControl::GetClientOffset	Recupera a diferença entre o canto superior esquerdo da área retangular do controle e o canto superior esquerdo da área de cliente.
COleControl::GetClientRect	Recupera o tamanho da área de cliente do controle.
COleControl::GetClientSite	Consulta um objeto para o ponteiro para seu site cliente atual dentro de seu contêiner.
COleControl::GetControlFlags	Recupera as configurações do sinalizador de controle.
COleControl::GetControlSize	Retorna a posição e o tamanho do controle OLE.
COleControl::GetDC	Fornece um meio para um controle sem janelas obter um contexto de dispositivo de seu contêiner.
COleControl::GetEnabled	Retorna o valor da propriedade de estoque Habilitada.
COleControl::GetExtendedControl	Recupera um ponteiro para um objeto de controle estendido que pertence ao contêiner.
COleControl::GetFocus	Determina se o controle tem o foco.
COleControl::GetFont	Retorna o valor da propriedade da ação Fonte.
COleControl::GetFontTextMetrics	Retorna as métricas de um objeto CFontHolder.
COleControl::GetForeColor	Retorna o valor da propriedade da ação ForeColor.
COleControl::GetHwnd	Retorna o valor da propriedade hWnd de ações.
COleControl::GetMessageString	Fornece texto da barra de status para um item de menu.
COleControl::GetNotSupported	Impede o acesso ao valor da propriedade de um controle pelo usuário.
COleControl::GetReadyState	Retorna o estado de disponibilidade do controle.
COleControl::GetRectInContainer	Retorna o retângulo do controle em relação ao contêiner.
COleControl::GetStockTextMetrics	Retorna as métricas da propriedade da ação Fonte.
COleControl::GetText	Retorna o valor da propriedade da ação Texto ou Legenda.
COleControl::GetWindowlessDropTarget	Substitua para permitir que um controle sem janelas seja o destino das operações de arrastar e soltar.
COleControl::InitializeIIDs	Informa a classe base dos IIDs que o controle usará.
COleControl::InternalGetFont	Retorna um objeto CFontHolder para a propriedade fonte de estoque.
COleControl::InternalGetText	Recupera a propriedade da açãi Legenda ou Texto.
COleControl::InternalSetReadyState	Define o estado de preparação do controle e aciona o evento de alteração de estado pronto.
COleControl::InvalidateControl	Invalida uma área do controle exibido, fazendo com que ele seja redesenhado.
COleControl::InvalidateRgn	Invalida a área de cliente da janela de contêiner dentro da região fornecida. Pode ser usado para redesenhar controles sem janelas na região.
COleControl::IsConvertingVBX	Permite o carregamento especializado de um controle OLE.
COleControl::IsModified	Determina se o estado de controle foi alterado.
COleControl::IsOptimizedDraw	Indica se o contêiner dá suporte ao desenho otimizado para a operação de desenho atual.
COleControl::IsSubclassedControl	Chamado para determinar se o controle subclasse um controle do Windows.
COleControl::Load	Redefine qualquer dado assíncrono anterior e inicia uma nova carga da propriedade assíncrona do controle.
COleControl::LockInPlaceActive	Determina se o controle pode ser desativado pelo contêiner.
COleControl::OnAmbientPropertyChange	Chamado quando a propriedade do ambiente é modificada.
COleControl::OnAppearanceChanged	Chamado quando a propriedade Appearance é modificada.
COleControl::OnBackColorChanged	Chamado quando a propriedade BackColor de ações é alterada.
COleControl::OnBorderStyleChanged	Chamado quando a propriedade BorderStyle de ações é alterada.
COleControl::OnClick	Chamado para disparar o evento de clique de estoque.
COleControl::OnClose	Avisa o controle que IOleControl::Close foi chamado.
COleControl::OnDoVerb	Chamado após a execução de um verbo de controle.
COleControl::OnDraw	Chamado quando um controle é solicitado a redesenhar a si mesmo.
COleControl::OnDrawMetafile	Chamado pelo contêiner quando um controle é solicitado a redesenhar-se usando um contexto de dispositivo de metafile.
COleControl::OnEdit	Chamado pelo contêiner para a interface do usuário, ative um controle OLE.
COleControl::OnEnabledChanged	Chamado quando a propriedade Enabled de ações é alterada.
COleControl::OnEnumVerbs	Chamado pelo contêiner para enumerar os verbos de um controle.
COleControl::OnEventAdvise	Chamado quando os manipuladores de eventos estão conectados ou desconectados de um controle.
COleControl::OnFontChanged	Chamado quando a propriedade Font de ações é alterada.
COleControl::OnForeColorChanged	Chamado quando a propriedade ForeColor de ações é alterada.
COleControl::OnFreezeEvents	Chamado quando os eventos de um controle são congelados ou descongelam.
COleControl::OnGetColorSet	Avisa o controle que IOleObject::GetColorSet foi chamado.
COleControl::OnGetControlInfo	Fornece informações mnemônicas para o contêiner.
COleControl::OnGetDisplayString	Chamado para obter uma cadeia de caracteres para representar um valor de propriedade.
COleControl::OnGetInPlaceMenu	Solicita o identificador do menu do controle que será mesclado com o menu de contêiner.
COleControl::OnGetNaturalExtent	Substitua para recuperar o tamanho de exibição do controle mais próximo do modo de tamanho e extensão propostos.
COleControl::OnGetPredefinedStrings	Retorna cadeias de caracteres que representam valores possíveis para uma propriedade.
COleControl::OnGetPredefinedValue	Retorna o valor correspondente a uma cadeia de caracteres predefinida.
COleControl::OnGetViewExtent	Substitua para recuperar o tamanho das áreas de exibição do controle (pode ser usada para habilitar o desenho de dois passes).
COleControl::OnGetViewRect	Substitua para converter o tamanho do controle em um retângulo começando em uma posição específica.
COleControl::OnGetViewStatus	Substitua para recuperar o status de exibição do controle.
COleControl::OnHideToolBars	Chamado pelo contêiner quando o controle é desativado pela interface do usuário.
COleControl::OnInactiveMouseMove	Substitua para que o contêiner do controle inativo sob o ponteiro do mouse envie WM_MOUSEMOVE mensagens para o controle.
COleControl::OnInactiveSetCursor	Substitua para que o contêiner do controle inativo sob o ponteiro do mouse envie mensagens WM_SETCURSOR para o controle.
COleControl::OnKeyDownEvent	Chamado depois que o evento KeyDown de ações foi acionado.
COleControl::OnKeyPressEvent	Chamado depois que o evento KeyPress de ações foi acionado.
COleControl::OnKeyUpEvent	Chamado depois que o evento KeyUp de ações foi acionado.
COleControl::OnMapPropertyToPage	Indica qual página de propriedade usar para editar uma propriedade.
COleControl::OnMnemonic	Chamado quando uma tecla mnemônica do controle foi pressionada.
COleControl::OnProperties	Chamado quando o verbo "Propriedades" do controle foi invocado.
COleControl::OnQueryHitPoint	Substitua para consultar se a exibição de um controle se sobrepõe a um determinado ponto.
COleControl::OnQueryHitRect	Substitua para consultar se a exibição de um controle se sobrepõe a qualquer ponto em um determinado retângulo.
COleControl::OnRenderData	Chamado pela estrutura para recuperar dados no formato especificado.
COleControl::OnRenderFileData	Chamado pela estrutura para recuperar dados de um arquivo no formato especificado.
COleControl::OnRenderGlobalData	Chamado pela estrutura para recuperar dados da memória global no formato especificado.
COleControl::OnResetState	Redefine as propriedades de um controle para os valores padrão.
COleControl::OnSetClientSite	Avisa o controle que IOleControl::SetClientSite foi chamado.
COleControl::OnSetData	Substitui os dados do controle por outro valor.
COleControl::OnSetExtent	Chamado depois que a extensão do controle foi alterada.
COleControl::OnSetObjectRects	Chamado depois que as dimensões do controle foram alteradas.
COleControl::OnShowToolBars	Chamado quando o controle foi ativado pela interface do usuário.
COleControl::OnTextChanged	Chamado quando a propriedade Texto ou Legenda de ações é alterada.
COleControl::OnWindowlessMessage	Processa mensagens de janela (além de mensagens de mouse e teclado) para controles sem janelas.
COleControl::ParentToClient	Converte um ponto relativo à origem do contêiner para um ponto relativo à origem do controle.
COleControl::PostModalDialog	Notifica o contêiner de que uma caixa de diálogo modal foi fechada.
COleControl::PreModalDialog	Notifica o contêiner de que uma caixa de diálogo modal está prestes a ser exibida.
COleControl::RecreateControlWindow	Destrói e recria a janela do controle.
COleControl::Refresh	Força uma repintação da aparência de um controle.
COleControl::ReleaseCapture	Libera a captura do mouse.
COleControl::ReleaseDC	Libera o contexto do dispositivo de exibição de um contêiner de um controle sem janelas.
COleControl::ReparentControlWindow	Redefine o pai da janela de controle.
COleControl::ResetStockProps	Inicializa as propriedades COleControl de estoque para seus valores padrão.
COleControl::ResetVersion	Inicializa o número da versão para um determinado valor.
COleControl::ScrollWindow	Permite que um controle sem janelas role uma área dentro de sua imagem ativa in-loco na exibição.
COleControl::SelectFontObject	Seleciona uma propriedade Font personalizada em um contexto de dispositivo.
COleControl::SelectStockFont	Seleciona a propriedade fonte de estoque em um contexto de dispositivo.
COleControl::SerializeExtent	Serializa ou inicializa o espaço de exibição para o controle.
COleControl::SerializeStockProps	Serializa ou inicializa as propriedades de estoque COleControl.
COleControl::SerializeVersion	Serializa ou inicializa as informações de versão do controle.
COleControl::SetAppearance	Define o valor da propriedade de ação Appearance.
COleControl::SetBackColor	Define o valor da propriedade de ações BackColor.
COleControl::SetBorderStyle	Define o valor da propriedade BorderStyle de ações.
COleControl::SetCapture	Faz com que a janela de contêiner do controle assuma a posse da captura do mouse em nome do controle.
COleControl::SetControlSize	Define a posição e o tamanho do controle OLE.
COleControl::SetEnabled	Define o valor da propriedade de ação Habilitada.
COleControl::SetFocus	Faz com que a janela de contêiner do controle assuma a posse do foco de entrada em nome do controle.
COleControl::SetFont	Define o valor da propriedade Fonte de estoque.
COleControl::SetForeColor	Define o valor da propriedade da ação ForeColor.
COleControl::SetInitialSize	Define o tamanho de um controle OLE quando exibido pela primeira vez em um contêiner.
COleControl::SetModifiedFlag	Altera o estado modificado de um controle.
COleControl::SetNotPermitted	Indica que uma solicitação de edição falhou.
COleControl::SetNotSupported	Impede a modificação do valor da propriedade de um controle pelo usuário.
COleControl::SetRectInContainer	Define o retângulo do controle em relação ao contêiner.
COleControl::SetText	Define o valor da propriedade Texto ou Legenda do estoque.
COleControl::ThrowError	Sinaliza que ocorreu um erro em um controle OLE.
COleControl::TransformCoords	Transforma valores de coordenadas entre um contêiner e o controle.
COleControl::TranslateColor	Converte um valor OLE_COLOR em um valor COLORREF.
COleControl::WillAmbientsBeValidDuringLoad	Determina se as propriedades ambiente estarão disponíveis na próxima vez que o controle for carregado.
COleControl::WindowProc	Fornece um procedimento do Windows para um objeto COleControl.

Métodos protegidos

Nome	Descrição
COleControl::DrawContent	Chamado pela estrutura quando a aparência do controle precisa ser atualizada.
COleControl::DrawMetafile	Chamado pela estrutura quando o contexto do dispositivo de metafile está sendo usado.
COleControl::IsInvokeAllowed	Habilita a invocação do método de automação.
COleControl::SetInitialDataFormats	Chamado pela estrutura para inicializar a lista de formatos de dados compatíveis com o controle.

Comentários

Derivada de CWnd, essa classe herda toda a funcionalidade de um objeto de janela do Windows, além de funcionalidades adicionais específicas do OLE, como o disparo de eventos e a capacidade de dar suporte a métodos e propriedades.

Os controles OLE podem ser inseridos em aplicativos de contêiner OLE e se comunicar com o contêiner usando um sistema bidirecional de disparo de eventos e expondo métodos e propriedades ao contêiner. Observe que os contêineres OLE padrão só dão suporte à funcionalidade básica de um controle OLE. Eles não podem dar suporte a recursos estendidos de um controle OLE. O disparo de eventos ocorre quando os eventos são enviados para o contêiner como resultado de determinadas ações que ocorrem no controle. Por sua vez, o contêiner se comunica com o controle usando um conjunto exposto de métodos e propriedades análogas às funções membros e aos membros de dados de uma classe C++. Essa abordagem permite que o desenvolvedor controle a aparência do controle e notifique o contêiner quando determinadas ações ocorrem.

Controles sem janelas

Os controles OLE podem ser usados ativos in-loco sem uma janela. Controles sem janelas têm vantagens significativas:

• Controles sem janelas podem ser transparentes e não retangulares

• Controles sem janelas reduzem o tamanho da instância e o tempo de criação do objeto

Os controles não precisam de uma janela. Serviços que uma janela oferece podem ser facilmente fornecidos por meio de uma única janela compartilhada (geralmente do contêiner) e um pouco de código de expedição. Ter uma janela é principalmente uma complicação desnecessária no objeto.

Quando a ativação sem janelas é usada, o contêiner (que tem uma janela) é responsável por fornecer serviços que, de outra forma, teriam sido fornecidos pela própria janela do controle. Por exemplo, se o controle precisar consultar o foco do teclado, consultar a captura do mouse ou obter um contexto de dispositivo, essas operações serão gerenciadas pelo contêiner. As funções de membro de operação COleControl sem janela invocam essas operações no contêiner.

Quando a ativação sem janelas é habilitada, o contêiner delega mensagens de entrada para a interface do controle IOleInPlaceObjectWindowless (uma extensão de IOleInPlaceObject para suporte sem janelas). COleControlA implementação dessa interface enviará essas mensagens por meio do mapa de mensagens do controle, depois de ajustar as coordenadas do mouse adequadamente. Você pode processar essas mensagens, como mensagens de janela comuns, adicionando as entradas correspondentes ao mapa da mensagem.

Em um controle sem janelas, você sempre deve usar as COleControl funções de membro em vez das funções de membro correspondentes CWnd ou suas funções de API do Windows relacionadas.

Os objetos de controle OLE também podem criar uma janela somente quando eles se tornam ativos, mas a quantidade de trabalho necessária para a transição inativa-ativa aumenta e a velocidade da transição diminui. Há casos em que isso é um problema: por exemplo, considere uma grade de caixas de texto. Ao fazer curso para cima e para baixo pela coluna, cada controle deve ser ativado no local e desativado. A velocidade da transição inativa/ativa afetará diretamente a velocidade de rolagem.

Para obter mais informações sobre como desenvolver uma estrutura de controle OLE, consulte os artigos Controles ActiveX do MFC e visão geral: criando um programa de controle ActiveX do MFC. Para obter informações sobre como otimizar controles OLE, incluindo controles sem janelas e sem cintilação, consulte Controles ActiveX do MFC: Otimização.

Hierarquia de herança

CObject

CCmdTarget

CWnd

COleControl

Requisitos

Cabeçalho: afxctl.h

COleControl::AmbientBackColor

Retorna o valor da propriedade do ambiente BackColor.

OLE_COLOR AmbientBackColor();

Valor de retorno

O valor atual da propriedade BackColor ambiente do contêiner, se houver. Se a propriedade não tiver suporte, essa função retornará a cor da tela de fundo do Windows definida pelo sistema.

Comentários

A propriedade Ambiente BackColor está disponível para todos os controles e é definida pelo contêiner. Observe que o contêiner não é necessário para dar suporte a essa propriedade.

COleControl::AmbientDisplayName

O nome que o contêiner atribuiu ao controle pode ser usado em mensagens de erro exibidas ao usuário.

CString AmbientDisplayName();

Valor de retorno

O nome do controle OLE. O padrão é uma cadeia de comprimento zero.

Comentários

Observe que o contêiner não é necessário para dar suporte a essa propriedade.

COleControl::AmbientFont

Retorna o valor da propriedade do ambiente Fonte.

LPFONTDISP AmbientFont();

Valor de retorno

Um ponteiro para a interface de expedição de fonte ambiente do contêiner. O valor padrão é NULL. Se o retorno não for igual a NULL, você será responsável por liberar a fonte chamando sua função membro IUnknown::Release.

Comentários

A propriedade Fonte ambiente é definida pelo contêiner e disponível para todos os controles. Observe que o contêiner não é necessário para dar suporte a essa propriedade.

COleControl::AmbientForeColor

Retorna o valor da propriedade do ambiente ForeColor.

OLE_COLOR AmbientForeColor();

Valor de retorno

O valor atual da propriedade ForeColor ambiente do contêiner, se houver. Se não houver suporte, essa função retornará a cor de texto do Windows definida pelo sistema.

Comentários

A propriedade ForeColor do ambiente está disponível para todos os controles e é definida pelo contêiner. Observe que o contêiner não é necessário para dar suporte a essa propriedade.

COleControl::AmbientLocaleID

Retorna a ID de localidade do contêiner.

LCID AmbientLocaleID();

Valor de retorno

O valor da propriedade LocaleID do contêiner, se houver. Se essa propriedade não tiver suporte, essa função retornará 0.

Comentários

O controle pode usar o LocaleID para adaptar sua interface do usuário para localidades específicas. Observe que o contêiner não é necessário para dar suporte a essa propriedade.

COleControl::AmbientAppearance

Recupera a configuração de aparência atual do objeto de controle.

short AmbientAppearance();

Valor de retorno

A aparência do controle:

• 0 Aparência simples

• 1 Aparência 3D

Comentários

Chame essa função para recuperar o valor atual da propriedade DISPID_AMBIENT_APPEARANCE para o controle.

COleControl::AmbientScaleUnits

Retorna o tipo de unidades usadas pelo contêiner.

CString AmbientScaleUnits();

Valor de retorno

A cadeia de caracteres contendo o ambiente ScaleUnits do container. Se essa propriedade não tiver suporte, essa função retornará uma cadeia de caracteres de comprimento zero.

Comentários

A propriedade ScaleUnits do ambiente do contêiner pode ser usada para exibir posições ou dimensões, rotuladas com a unidade escolhida, como twips ou centímetros. Observe que o contêiner não é necessário para dar suporte a essa propriedade.

COleControl::AmbientShowGrabHandles

Determina se o contêiner permite que o controle exiba identificadores de captura para si mesmo quando ativo.

BOOL AmbientShowGrabHandles();

Valor de retorno

Não zero se as alças de captura devem ser exibidas; caso contrário, 0. Se essa propriedade não tiver suporte, essa função retornará não zero.

Comentários

Observe que o contêiner não é necessário para dar suporte a essa propriedade.

COleControl::AmbientShowHatching

Determina se o contêiner permite que o controle se exiba com um padrão eclodido quando a interface do usuário está ativa.

BOOL AmbientShowHatching();

Valor de retorno

Não zero se o padrão hatched deve ser mostrado; caso contrário, 0. Se essa propriedade não tiver suporte, essa função retornará não zero.

Comentários

Observe que o contêiner não é necessário para dar suporte a essa propriedade.

COleControl::AmbientTextAlign

Determina o alinhamento de texto ambiente preferido pelo contêiner de controle.

short AmbientTextAlign();

Valor de retorno

O status da propriedade TextAlign ambiente do contêiner. Se essa propriedade não tiver suporte, essa função retornará 0.

O seguinte é uma lista de valores retornados válidos:

Valor retornado	Significado
0	Alinhamento geral (números à direita, texto à esquerda).
1	Justificar à esquerda
2	Centro
3	Justificar à direita

Comentários

Essa propriedade está disponível para todos os controles inseridos e é definida pelo contêiner. Observe que o contêiner não é necessário para dar suporte a essa propriedade.

COleControl::AmbientUIDead

Determina se o contêiner deseja que o controle responda às ações de interface do usuário.

BOOL AmbientUIDead();

Valor de retorno

Não zero se o controle deve responder a ações de interface do usuário; caso contrário, 0. Se essa propriedade não tiver suporte, essa função retornará 0.

Comentários

Por exemplo, um contêiner pode definir isso como TRUE no modo de design.

COleControl::AmbientUserMode

Determina se o contêiner está no modo de design ou no modo de usuário.

BOOL AmbientUserMode();

Valor de retorno

Não zero se o contêiner estiver no modo de usuário; caso contrário, 0 (no modo de design). Se essa propriedade não tiver suporte, essa função retornará TRUE.

Comentários

Por exemplo, um contêiner pode definir isso como FALSE no modo de design.

COleControl::BoundPropertyChanged

Sinaliza que o valor da propriedade associada foi alterado.

void BoundPropertyChanged(DISPID dispid);

Parâmetros

dispid
A ID de expedição de uma propriedade associada do controle.

Comentários

Isso deve ser chamado sempre que o valor da propriedade for alterado, mesmo nos casos em que a alteração não foi feita por meio do método conjunto de propriedades. Lembre-se particularmente das propriedades associadas mapeadas para variáveis membro. Sempre que uma variável de membro for alterada, BoundPropertyChanged deverá ser chamada.

COleControl::BoundPropertyRequestEdit

Solicita permissão da interface IPropertyNotifySink para alterar um valor de propriedade associado fornecido pelo controle.

BOOL BoundPropertyRequestEdit(DISPID dispid);

Parâmetros

dispid
A ID de expedição de uma propriedade associada do controle.

Valor de retorno

Não é zero se a alteração for permitida, caso contrário, 0. O valor padrão não é zero.

Comentários

Se a permissão for negada, o controle não deverá permitir que o valor da propriedade seja alterado. Isso pode ser feito ignorando ou falhando a ação que tentou alterar o valor da propriedade.

COleControl::ClientToParent

Converte as coordenadas do pPoint em coordenadas pai.

virtual void ClientToParent(
    LPCRECT lprcBounds,
    LPPOINT pPoint) const;

Parâmetros

lprcBounds
Ponteiro para os limites do controle OLE dentro do contêiner. Não a área do cliente, mas a área de todo o controle, incluindo bordas e barras de rolagem.

pPoint
Ponteiro para o ponto de área do cliente OLE a ser traduzido para as coordenadas do pai (contêiner).

Comentários

No pPoint de entrada é relativo à origem da área do cliente do controle OLE (canto superior esquerdo da área do cliente do controle). Na saída o pPoint é relativo à origem do pai (canto superior esquerdo do contêiner).

COleControl::ClipCaretRect

Ajusta um retângulo de ponto se ele estiver totalmente ou parcialmente coberto por objetos opacos sobrepostos.

BOOL ClipCaretRect(LPRECT lpRect);

Parâmetros

lpRect
Na entrada, um ponteiro para uma estrutura RECT que contém a área de cuidado a ser ajustada. Na saída, a área de careta ajustada ou NULL se o caret do retângulo está completamente coberto.

Valor de retorno

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

Comentários

Um caret é uma linha piscando, bloco ou bitmap que normalmente indica onde texto ou elementos gráficos serão inseridos.

Um objeto sem janelas não pode mostrar com segurança um caret sem primeiro verificar se o caret está parcial ou totalmente oculto por objetos sobrepostos. Para tornar isso possível, um objeto pode ser usado ClipCaretRect para ajustar o caret (reduzido) para garantir que ele se ajuste na região de recorte.

Os objetos que criam um caret devem enviar o retângulo de caret ClipCaretRecte usar o retângulo ajustado para o caret. Se o cursor estiver totalmente oculto, esse método retornará FALSE e o cuidado não deverá ser mostrado neste caso.

COleControl::COleControl

Constrói um objeto COleControl.

COleControl();

Comentários

Essa função normalmente não é chamada diretamente. Em vez disso, o controle OLE geralmente é criado por sua fábrica de classes.

COleControl::ControlInfoChanged

Chame essa função quando o conjunto de mnemônicos com suporte pelo controle for alterado.

void ControlInfoChanged();

Comentários

Ao receber essa notificação, o contêiner do controle obtém o novo conjunto de mnemônicos fazendo uma chamada para IOleControl::GetControlInfo. Observe que o contêiner não é necessário para responder a essa notificação.

COleControl::DisplayError

Chamado pela estrutura após o evento erro de estoque ter sido tratado (a menos que o manipulador de eventos tenha suprimido a exibição do erro).

virtual void DisplayError(
    SCODE scode,
    LPCTSTR lpszDescription,
    LPCTSTR lpszSource,
    LPCTSTR lpszHelpFile,
    UINT nHelpID);

Parâmetros

scode
O valor do código de status a ser relatado. Para obter uma lista completa de códigos possíveis, consulte o artigo Controles ActiveX: Tópicos Avançados.

lpszDescription
A descrição do erro que está sendo relatado.

lpszSource
O nome do módulo que gera o erro (normalmente, o nome do módulo de controle OLE).

lpszHelpFile
O nome do arquivo de ajuda que contém uma descrição do erro.

nHelpID
A ID de Contexto de Ajuda do erro que está sendo relatado.

Comentários

O comportamento padrão exibe uma caixa de mensagem que contém a descrição do erro, contida em lpszDescription.

Substitua essa função para personalizar como os erros são exibidos.

COleControl::DoClick

Simula uma ação de clique do mouse no controle.

void DoClick();

Comentários

A função de membro substituível COleControl::OnClick será chamada e um evento de clique de estoque será acionado, se houver suporte para o controle.

Essa função é compatível com a classe base COleControl como um método de estoque, chamado DoClick. Para obter mais informações, consulte o artigo Controles ActiveX: Métodos.

COleControl::DoPropExchange

Chamado pela estrutura ao carregar ou armazenar um controle de uma representação de armazenamento persistente, como um fluxo ou conjunto de propriedades.

virtual void DoPropExchange(CPropExchange* pPX);

Parâmetros

pPX
Um ponteiro para um objeto CPropExchange. A estrutura fornece esse objeto para estabelecer o contexto da troca de propriedades, incluindo sua direção.

Comentários

Essa função normalmente faz chamadas para a família de funções PX_ para carregar ou armazenar propriedades específicas definidas pelo usuário de um controle OLE.

Se o Assistente de Controle tiver sido usado para criar o projeto de controle OLE, a versão substituída dessa função serializará as propriedades de estoque com suporte COleControl com uma chamada para a função de classe base. COleControl::DoPropExchange À medida que você adiciona propriedades definidas pelo usuário ao controle OLE, será necessário modificar essa função para serializar suas novas propriedades. Para obter mais informações sobre serialização, consulte o artigo Controles ActiveX: Serialização.

COleControl::DoSuperclassPaint

Redesenha um controle OLE que foi subclasse de um controle do Windows.

void DoSuperclassPaint(
    CDC* pDC,
    const CRect& rcBounds);

Parâmetros

pDC
Um ponteiro para o contexto do dispositivo usado pelo contêiner.

rcBounds
A área na qual o controle deve ser desenhado.

Comentários

Chame essa função para manipular corretamente a pintura de um controle OLE não ativo. Essa função só deve ser usada se o controle OLE subclasse um controle do Windows e deve ser chamado na função OnDraw do controle.

Para obter mais informações sobre essa função e subclasse de um controle do Windows, consulte o artigo Controles ActiveX: Subclasse de um Controle do Windows.

COleControl::DrawContent

Chamado pela estrutura quando a aparência do controle precisa ser atualizada.

void DrawContent(
    CDC* pDC,
    CRect& rc);

Parâmetros

pDC
Ponteiro para o contexto do dispositivo.

rc
Área retangular a ser desenhada.

Comentários

Essa função chama diretamente a função substituível OnDraw.

COleControl::DrawMetafile

Chamado pela estrutura quando o contexto do dispositivo de metafile está sendo usado.

void DrawMetafile(
    CDC* pDC,
    CRect& rc);

Parâmetros

pDC
Ponteiro para o contexto do dispositivo de metafile.

rc
Área retangular a ser desenhada.

COleControl::EnableSimpleFrame

Habilita a característica de quadro simples para um controle OLE.

void EnableSimpleFrame();

Comentários

Essa característica permite que um controle dê suporte à contenção visual de outros controles, mas não à contenção OLE verdadeira. Um exemplo seria uma caixa de grupo com vários controles dentro. Esses controles não estão contidos no OLE, mas estão na mesma caixa de grupo.

COleControl::ExchangeExtent

Serializa ou inicializa o estado da extensão do controle (suas dimensões em unidades HIMETRIC).

BOOL ExchangeExtent(CPropExchange* pPX);

Parâmetros

pPX
Um ponteiro para um objeto CPropExchange. A estrutura fornece esse objeto para estabelecer o contexto da troca de propriedades, incluindo sua direção.

Valor de retorno

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

Comentários

Essa função normalmente é chamada pela implementação padrão de COleControl::DoPropExchange.

COleControl::ExchangeStockProps

Serializa ou inicializa o estado das propriedades de estoque do controle.

void ExchangeStockProps(CPropExchange* pPX);

Parâmetros

pPX
Um ponteiro para um objeto CPropExchange. A estrutura fornece esse objeto para estabelecer o contexto da troca de propriedades, incluindo sua direção.

Comentários

Essa função normalmente é chamada pela implementação padrão de COleControl::DoPropExchange.

COleControl::ExchangeVersion

Serializa ou inicializa o estado das informações de versão de um controle.

BOOL ExchangeVersion(
    CPropExchange* pPX,
    DWORD dwVersionDefault,
    BOOL bConvert = TRUE);

Parâmetros

pPX
Um ponteiro para um objeto CPropExchange. A estrutura fornece esse objeto para estabelecer o contexto da troca de propriedades, incluindo sua direção.

dwVersionDefault
O número de versão atual do controle.

bConvert
Indica se os dados persistentes devem ser convertidos no formato mais recente quando salvos ou mantidos no mesmo formato que foi carregado.

Valor de retorno

Não zero da função foi bem-sucedida; 0 caso contrário.

Comentários

Normalmente, essa será a primeira função chamada pela substituição de um controle de COleControl::DoPropExchange. Ao carregar, essa função lê o número de versão dos dados persistentes e define o atributo de versão do objeto CPropExchange adequadamente. Ao salvar, essa função grava o número de versão dos dados persistentes.

Para obter mais informações sobre persistência e controle de versão, consulte o artigo Controles ActiveX: Serialização.

COleControl::FireClick

Chamado pela estrutura quando o mouse é clicado sobre um controle ativo.

void FireClick();

Comentários

Se esse evento for definido como um evento personalizado, você determinará quando o evento é acionado.

Para que a ação automática de um evento Click ocorra, o mapa de Eventos do controle deve ter um evento de clique de estoque definido.

COleControl::FireDblClick

Chamado pela estrutura quando o mouse é clicado sobre um controle ativo.

void FireDblClick();

Comentários

Se esse evento for definido como um evento personalizado, você determinará quando o evento é acionado.

Para que o disparo automático de um evento DblClick ocorra, o mapa de eventos do controle deve ter um evento DblClick definido.

COleControl::FireError

Dispara o evento erro de estoque.

void FireError(
    SCODE scode,
    LPCTSTR lpszDescription,
    UINT nHelpID = 0);

Parâmetros

scode
O valor do código de status a ser relatado. Para obter uma lista completa de códigos possíveis, consulte o artigo Controles ActiveX: Tópicos Avançados.

lpszDescription
A descrição do erro que está sendo relatado.

nHelpID
A ID de Ajuda do erro que está sendo relatado.

Comentários

Esse evento fornece uma maneira de sinalizar, em locais apropriados em seu código, que ocorreu um erro no controle. Ao contrário de outros eventos de ações, como Clique ou MouseMove, o erro nunca é disparado pela estrutura.

Para relatar um erro que ocorre durante uma função de obtenção de propriedade, função de conjunto de propriedades ou método de automação, chame COleControl::ThrowError.

A implementação do evento Stock Error de um controle OLE usa um valor SCODE. Se o controle usar esse evento e se destinar a ser usado no Visual Basic 4.0, você receberá erros porque o valor SCODE não tem suporte no Visual Basic.

Para corrigir isso, altere manualmente o parâmetro SCODE no controle. Arquivo ODL para um long. Além disso, qualquer evento personalizado, método ou propriedade que usa um parâmetro SCODE também causa o mesmo problema.

COleControl::FireEvent

Aciona um evento definido pelo usuário do seu controle com qualquer número de argumentos opcionais,

void AFX_CDECL FireEvent(
    DISPID dispid,
    BYTE* pbParams,
...);

Parâmetros

dispid
A ID de expedição do evento a ser acionado.

pbParams
Um descritor para os tipos de parâmetro do evento.

Comentários

Normalmente, essa função não deve ser chamada diretamente. Em vez disso, você chamará as funções de disparo de evento na seção de mapa de eventos da declaração de classe do controle.

O argumento pbParams é uma lista separada por espaço de VTS_. Um ou mais desses valores, separados por espaços (não vírgulas), especifica a lista de parâmetros da função. Os valores possíveis são:

Símbolo	Tipo de parâmetro
VTS_COLOR	OLE_COLOR
VTS_FONT	IFontDisp*
VTS_HANDLE	HWND
VTS_PICTURE	IPictureDisp*
VTS_OPTEXCLUSIVE	OLE_OPTEXCLUSIVE*
VTS_TRISTATE	OLE_TRISTATE
VTS_XPOS_HIMETRIC	OLE_XPOS_HIMETRIC
VTS_YPOS_HIMETRIC	OLE_YPOS_HIMETRIC
VTS_XPOS_PIXELS	OLE_XPOS_PIXELS
VTS_YPOS_PIXELS	OLE_YPOS_PIXELS
VTS_XSIZE_PIXELS	OLE_XSIZE_PIXELS
VTS_YSIZE_PIXELS	OLE_XSIZE_PIXELS
VTS_XSIZE_HIMETRIC	OLE_XSIZE_HIMETRIC
VTS_YSIZE_HIMETRIC	OLE_XSIZE_HIMETRIC

Observação

Constantes variantes adicionais foram definidas para todos os tipos de variante, com exceção de VTS_FONT e VTS_PICTURE, que fornecem um ponteiro para a constante de dados variante. Essas constantes são nomeadas usando a convenção VTS_P<CONSTANT-NAME> . Por exemplo, VTS_PCOLOR é um ponteiro para uma constante VTS_COLOR.

COleControl::FireKeyDown

Chamado pela estrutura quando uma tecla é pressionada enquanto o controle está ativo na interface do usuário.

void FireKeyDown(
    USHORT* pnChar,
    short nShiftState);

Parâmetros

pnChar
Ponteiro para o valor do código da chave virtual da tecla pressionada. Para obter uma lista de códigos de tecla virtual padrão, consulte Winuser.h

nShiftState
Contém uma combinação dos seguintes sinalizadores:

• SHIFT_MASK a tecla SHIFT foi pressionada durante a ação.

• CTRL_MASK A tecla CTRL foi pressionada durante a ação.

• ALT_MASK A tecla ALT foi pressionada durante a ação.

Comentários

Se esse evento for definido como um evento personalizado, você determinará quando o evento é acionado.

Para que o disparo automático de um evento KeyDown ocorra, o mapa de eventos do controle deve ter um evento KeyDown de ações definido.

COleControl::FireKeyPress

Chamado pela estrutura quando uma tecla é pressionada e liberada enquanto o controle personalizado é ativo da interface do usuário dentro do contêiner.

void FireKeyPress(USHORT* pnChar);

Parâmetros

pnChar
Um ponteiro para o valor do caractere da tecla pressionada.

Comentários

Se esse evento for definido como um evento personalizado, você determinará quando o evento é acionado.

O destinatário do evento pode modificar pnChar, por exemplo, converter todos os caracteres minúsculos em letras maiúsculas. Se você quiser examinar o caractere modificado, substitua OnKeyPressEvent.

Para que o disparo automático de um evento KeyPress ocorra, o mapa de eventos do controle deve ter um evento KeyPress de estoque definido.

COleControl::FireKeyUp

Chamado pela estrutura quando uma tecla é pressionada e liberada enquanto o controle personalizado é ativo da interface do usuário dentro do contêiner.

void FireKeyUp(
    USHORT* pnChar,
    short nShiftState);

Parâmetros

pnChar
Ponteiro para o valor do código da chave virtual da tecla pressionada. Para obter uma lista de códigos de tecla virtual padrão, consulte Winuser.h

nShiftState
Contém uma combinação dos seguintes sinalizadores:

• SHIFT_MASK a tecla SHIFT foi pressionada durante a ação.

• CTRL_MASK A tecla CTRL foi pressionada durante a ação.

• ALT_MASK A tecla ALT foi pressionada durante a ação.

Comentários

Se esse evento for definido como um evento personalizado, você determinará quando o evento é acionado.

Para que o disparo automático de um evento KeyUp ocorra, o mapa de eventos do controle deve ter um evento KeyUp de estoque definido.

COleControl::FireMouseDown

Chamado pela estrutura quando um botão do mouse é pressionado sobre um controle personalizado ativo.

void FireMouseDown(
    short nButton,
    short nShiftState,
    OLE_XPOS_PIXELS x,
    OLE_YPOS_PIXELS y);

Parâmetros

nButton
O valor numérico do botão do mouse pressionado. Pode conter um dos seguintes valores:

• LEFT_BUTTON O botão esquerdo do mouse foi pressionado.

• MIDDLE_BUTTON O botão esquerdo do mouse foi pressionado.

• RIGHT_BUTTON O botão esquerdo do mouse foi pressionado.

nShiftState
Contém uma combinação dos seguintes sinalizadores:

• SHIFT_MASK a tecla SHIFT foi pressionada durante a ação.

• CTRL_MASK A tecla CTRL foi pressionada durante a ação.

• ALT_MASK A tecla ALT foi pressionada durante a ação.

x
A coordenada x do cursor quando um botão do mouse foi pressionado para baixo. A coordenada é relativa ao canto superior esquerdo da janela do controle.

y
A coordenada y do cursor quando um botão do mouse foi pressionado para baixo. A coordenada é relativa ao canto superior esquerdo da janela do controle.

Comentários

Se esse evento for definido como um evento personalizado, você determinará quando o evento é acionado.

Para que o disparo automático de um evento MouseDown ocorra, o mapa de eventos do controle deve ter um evento MouseDown de ações definido.

COleControl::FireMouseMove

Chamado pela estrutura quando o cursor é movido sobre um controle personalizado ativo.

void FireMouseMove(
    short nButton,
    short nShiftState,
    OLE_XPOS_PIXELS x,
    OLE_YPOS_PIXELS y);

Parâmetros

nButton
O valor numérico do botão do mouse pressionado. Contém uma combinação dos seguintes valores:

• LEFT_BUTTON O botão esquerdo do mouse foi pressionado para baixo durante a ação.

• MIDDLE_BUTTON O botão do mouse do meio foi pressionado para baixo durante a ação.

• RIGHT_BUTTON O botão direito do mouse foi pressionado para baixo durante a ação.

nShiftState
Contém uma combinação dos seguintes sinalizadores:

• SHIFT_MASK a tecla SHIFT foi pressionada durante a ação.

• CTRL_MASK A tecla CTRL foi pressionada durante a ação.

• ALT_MASK A tecla ALT foi pressionada durante a ação.

x
A coordenada X do cursor. A coordenada é relativa ao canto superior esquerdo da janela do controle.

y
A coordenada Y do cursor. A coordenada é relativa ao canto superior esquerdo da janela do controle.

Comentários

Se esse evento for definido como um evento personalizado, você determinará quando o evento é acionado.

Para que o disparo automático de um evento MouseMove ocorra, o mapa de eventos do controle deve ter um evento MouseMove de estoque definido.

COleControl::FireMouseUp

Chamado pela estrutura quando um botão do mouse é liberado por um controle personalizado ativo.

void FireMouseUp(
    short nButton,
    short nShiftState,
    OLE_XPOS_PIXELS x,
    OLE_YPOS_PIXELS y);

Parâmetros

nButton
O valor numérico do botão do mouse liberado. Ele pode ter um dos seguintes valores:

• LEFT_BUTTON o botão esquerdo do mouse foi liberado.

• MIDDLE_BUTTON O botão do meio do mouse foi liberado.

• RIGHT_BUTTON O botão esquerdo do mouse foi liberado.

nShiftState
Contém uma combinação dos seguintes sinalizadores:

• SHIFT_MASK a tecla SHIFT foi pressionada durante a ação.

• CTRL_MASK A tecla CTRL foi pressionada durante a ação.

• ALT_MASK A tecla ALT foi pressionada durante a ação.

x
A coordenada x do cursor quando um botão do mouse foi liberado. A coordenada é relativa ao canto superior esquerdo da janela do controle.

y
A coordenada y de um cursor quando um botão do mouse foi liberado. A coordenada é relativa ao canto superior esquerdo da janela do controle.

Comentários

Se esse evento for definido como um evento personalizado, você determinará quando o evento é acionado.

Para que o disparo automático de um evento MouseUp ocorra, o mapa de eventos do controle deve ter um evento MouseUp de estoque definido.

COleControl::FireReadyStateChange

Aciona um evento com o valor atual do estado pronto de controle.

void FireReadyStateChange();

Comentários

O estado de prontidão pode ser um dos valores a seguir:

Nome	Descrição
READYSTATE_UNINITIALIZED	Estado de inicialização padrão
READYSTATE_LOADING	No momento, o controle está carregando suas propriedades
READYSTATE_LOADED	O controle foi inicializado
READYSTATE_INTERACTIVE	O controle tem dados suficientes para serem interativos, mas nem todos os dados assíncronos ainda estão carregados
READYSTATE_COMPLETE	O controle tem todos os seus dados

Use GetReadyState para determinar a prontidão atual do controle.

InternalSetReadyState altera o estado pronto para o valor fornecido e, em seguida, chama FireReadyStateChange.

COleControl::GetActivationPolicy

Altera o comportamento de ativação padrão de um controle que dá suporte à interface IPointerInactive.

virtual DWORD GetActivationPolicy();

Valor de retorno

Uma combinação de sinalizadores da enumeração POINTERINACTIVE. Os possíveis sinalizadores são:

Nome	Descrição
POINTERINACTIVE_ACTIVATEONENTRY	O objeto deve ser ativado no local quando o mouse o insere durante uma operação de movimentação do mouse.
POINTERINACTIVE_DEACTIVATEONLEAVE	O objeto deve ser desativado quando o mouse sai do objeto durante uma operação de movimentação do mouse.
POINTERINACTIVE_ACTIVATEONDRAG	O objeto deve ser ativado no local quando o mouse é arrastado sobre ele durante uma operação de arrastar e soltar.

Comentários

Quando a interface IPointerInactive estiver habilitada, o contêiner delegará WM_SETCURSOR e WM_MOUSEMOVE mensagens a ele. COleControlA implementação dessa interface enviará essas mensagens por meio do mapa de mensagens do controle, depois de ajustar as coordenadas do mouse adequadamente.

Sempre que o contêiner recebe uma mensagem WM_SETCURSOR ou WM_MOUSEMOVE com o ponteiro do mouse sobre um objeto inativo com suporte IPointerInactive, ele deve chamar GetActivationPolicy na interface e retornar sinalizadores da enumeração POINTERINACTIVE.

Você pode processar essas mensagens como mensagens de janela comuns adicionando as entradas correspondentes ao mapa da mensagem. Em seus manipuladores, evite usar a variável membro m_hWnd (ou quaisquer funções de membro que a usem) sem primeiro verificar se seu valor não é NULL.

Qualquer objeto destinado a fazer mais do que definir o cursor do mouse e/ou disparar um evento de movimentação de mouse, como fornecer comentários visuais especiais, deve retornar o sinalizador POINTERINACTIVE_ACTIVATEONENTRY e desenhar os comentários somente quando ativo. Se o objeto retornar esse sinalizador, o contêiner deverá ativá-lo imediatamente no local e encaminhá-lo a mesma mensagem que disparou a chamada para GetActivationPolicy.

Se os sinalizadores POINTERINACTIVE_ACTIVATEONENTRY e POINTERINACTIVE_DEACTIVATEONLEAVE forem retornados, o objeto só será ativado quando o mouse estiver sobre o objeto. Se apenas o sinalizador POINTERINACTIVE_ACTIVATEONENTRY for retornado, o objeto só será ativado uma vez quando o mouse entrar primeiro no objeto.

Talvez você também queira que um controle inativo seja o destino de uma operação de arrastar e soltar OLE. Isso requer a ativação do controle no momento em que o usuário arrasta um objeto sobre ele, para que a janela do controle possa ser registrada como um destino suspenso. Para fazer com que a ativação ocorra durante um arrastão, retorne o sinalizador POINTERINACTIVE_ACTIVATEONDRAG:

DWORD CMyAxCtrl::GetActivationPolicy()
{
   return POINTERINACTIVE_ACTIVATEONDRAG;
}

As informações comunicadas por GetActivationPolicy não devem ser armazenadas em cache por um contêiner. Em vez disso, esse método deve ser chamado sempre que o mouse insere um objeto inativo.

Se um objeto inativo não solicitar a ativação in-loco quando o mouse entrar, seu contêiner deverá enviar mensagens WM_SETCURSOR subsequentes para esse objeto chamando OnInactiveSetCursor enquanto o ponteiro do mouse permanecer sobre o objeto.

Geralmente, habilitar a interface IPointerInactive significa que você deseja que o controle seja capaz de processar mensagens do mouse o tempo todo. Para obter esse comportamento em um contêiner que não dá suporte à interfaceIPointerInactive, você precisará ter seu controle sempre ativado quando visível, o que significa que o controle deve ter o sinalizador OLEMISC_ACTIVATEWHENVISIBLE entre seus sinalizadores diversos. No entanto, para evitar que esse sinalizador entre em vigor em um contêiner compatível com IPointerInactive, você também pode especificar o sinalizador OLEMISC_IGNOREACTIVATEWHENVISIBLE:

static const DWORD BASED_CODE _dwMyOleMisc =
    OLEMISC_ACTIVATEWHENVISIBLE |
    OLEMISC_IGNOREACTIVATEWHENVISIBLE |
    OLEMISC_SETCLIENTSITEFIRST |
    OLEMISC_INSIDEOUT |
    OLEMISC_CANTLINKINSIDE |
    OLEMISC_RECOMPOSEONRESIZE;

COleControl::GetAmbientProperty

Obtém o valor de uma propriedade ambiente do contêiner.

BOOL GetAmbientProperty(
    DISPID dispid,
    VARTYPE vtProp,
    void* pvProp);

Parâmetros

dwDispid
A ID de expedição da propriedade de ambiente desejada.

vtProp
Uma marca de tipo variante que especifica o tipo do valor a ser retornado em pvProp.

pvProp
Um ponteiro para o endereço da variável que receberá o valor da propriedade ou o valor retornado. O tipo real desse ponteiro deve corresponder ao tipo especificado por vtProp.

vtProp	Tipo de pvProp
VT_BOOL	BOOL*
VT_BSTR	CString*
VT_I2	short*
VT_I4	long*
VT_R4	float*
VT_R8	double*
VT_CY	CY*
VT_COLOR	OLE_COLOR*
VT_DISPATCH	LPDISPATCH*
VT_FONT	LPFONTDISP*

Valor de retorno

Não zero se a propriedade de ambiente tiver suporte; caso contrário, 0.

Comentários

Se você usar GetAmbientProperty para recuperar as propriedades ambiente DisplayName e ScaleUnits, defina vtProp como VT_BSTR e pvProp como CString*. Se você estiver recuperando a propriedade Fonte ambiente, defina vtProp como VT_FONT e pvProp como LPFONTDISP*.

Observe que as funções já foram fornecidas para propriedades de ambiente comuns, como AmbientBackColor e AmbientFont.

COleControl::GetAppearance

Implementa a função Get da propriedade Stock Appearance do controle.

short GetAppearance ();

Valor de retorno

O valor retornado especifica a configuração de aparência atual como um short valor (VT_I2), se bem-sucedido. Esse valor será zero se a aparência do controle for simples e 1 se a aparência do controle for 3D.

COleControl::GetBackColor

Implementa a função Get da propriedade BackColor de ações do controle.

OLE_COLOR GetBackColor();

Valor de retorno

O valor retornado especifica a cor da tela de fundo atual como um valor OLE_COLOR, se bem-sucedido. Esse valor pode ser convertido em um valor COLORREF com uma chamada para TranslateColor.

COleControl::GetBorderStyle

Implementa a função Get da propriedade BorderStyle do seu controle.

short GetBorderStyle();

Valor de retorno

1 se o controle tiver uma borda normal; 0 se o controle não tiver borda.

COleControl::GetCapture

Determina se o objeto COleControl tem a captura do mouse.

CWnd* GetCapture();

Valor de retorno

Se o controle estiver ativado e sem janelas, retornará this se o controle tiver atualmente a captura do mouse (conforme determinado pelo contêiner do controle) ou NULL se ele não tiver a captura.

Caso contrário, retorna o CWnd objeto que tem a captura do mouse (o mesmo que CWnd::GetCapture).

Comentários

Um controle ativado sem janelas recebe a captura do mouse quando SetCapture é chamado.

COleControl::GetClassID

Chamado pela estrutura para recuperar a ID da classe OLE do controle.

virtual HRESULT GetClassID(LPCLSID pclsid) = 0;

Parâmetros

pclsid
Ponteiro para o local da ID da classe.

Valor de retorno

Não zero se a chamada não tiver sido bem-sucedida; caso contrário, 0.

Comentários

Geralmente implementado pela IMPLEMENT_OLECREATE_EX.

COleControl::GetClientOffset

Recupera a diferença entre o canto superior esquerdo da área retangular do controle e o canto superior esquerdo da área de cliente.

virtual void GetClientOffset(long* pdxOffset, long* pdyOffset) const;

Parâmetros

pdxOffset
Ponteiro para o deslocamento horizontal da área de cliente do controle OLE.

pdyOffset
Ponteiro para o deslocamento vertical da área de cliente do controle OLE.

Comentários

O controle OLE tem uma área retangular dentro de seu contêiner. A área do cliente do controle é a área de controle, excluindo bordas e barras de rolagem. O deslocamento recuperado por GetClientOffset é a diferença entre o canto superior esquerdo da área retangular do controle e o canto superior esquerdo da área do cliente. Se o controle tiver elementos não cliente diferentes das bordas e barras de rolagem padrão, substitua essa função de membro para especificar o deslocamento.

COleControl::GetClientRect

Recupera o tamanho da área de cliente do controle.

virtual void GetClientRect(LPRECT lpRect) const;

Parâmetros

lpRect
Ponteiro para uma estrutura RECT que contém as dimensões da área de cliente do controle sem janelas; ou seja, o tamanho do controle menos bordas de janela, quadros, barras de rolagem e assim por diante. O parâmetro lpRect indica o tamanho do retângulo do cliente do controle, não sua posição.

COleControl::GetClientSite

Consulta um objeto para o ponteiro para seu site cliente atual dentro de seu contêiner.

LPOLECLIENTSITE GetClientSite();

Valor de retorno

Um ponteiro para o site cliente atual do controle em seu contêiner.

Comentários

O ponteiro retornado aponta para uma instância de IOleClientSite. A interface IOleClientSite, implementada por contêineres, é a exibição do objeto de seu contexto: onde ele está ancorado no documento, onde obtém seu armazenamento, interface do usuário e outros recursos.

COleControl::GetControlFlags

Recupera as configurações do sinalizador de controle.

virtual DWORD GetControlFlags();

Valor de retorno

Uma combinação ORed dos sinalizadores na enumeração ControlFlags:

enum ControlFlags {
    fastBeginPaint = 0x0001,
    clipPaintDC = 0x0002,
    pointerInactive = 0x0004,
    noFlickerActivate = 0x0008,
    windowlessActivate = 0x0010,
    canOptimizeDraw = 0x0020,
    };

Comentários

Por padrão, GetControlFlags retorna fastBeginPaint | clipPaintDC.

Nome	Descrição
fastBeginPaint	Se definido, usa uma função de pintura inicial personalizada para controles OLE em vez da API BeginPaint (definida por padrão).
clipPaintDC	Se não for definido, desabilita a chamada para IntersectClipRect feita por COleControl e obtém uma pequena vantagem de velocidade. Se você estiver usando a ativação sem janelas, o sinalizador não terá efeito.
pointerInactive	Se definido, fornece interação do mouse enquanto o controle está inativo, habilitando a implementação do COleControl da interface IPointerInactive, que está desabilitada por padrão.
noFlickerActivate	Se definido, elimina operações extras de desenho e a cintilação visual que acompanha. Use quando o controle se desenha de forma idêntica nos estados inativos e ativos. Se você estiver usando a ativação sem janelas, o sinalizador não terá efeito.
windowlessActivate	Se definido, indica que o controle usa ativação sem janelas.
canOptimizeDraw	Se definido, indica que o controle executará o desenho otimizado, se o contêiner der suporte a ele.

Para obter mais informações sobre GetControlFlags e outras otimizações de controles OLE, consulte Controles ActiveX: Otimização.

COleControl::GetControlSize

Recupera o tamanho da janela de controle OLE.

void GetControlSize(
    int* pcx,
    int* pcy);

Parâmetros

pcx
Especifica a largura do controle, em pixels.

pcy
Especifica a altura do controle em pixels.

Comentários

Observe que todas as coordenadas para janelas de controle são relativas ao canto superior esquerdo do controle.

COleControl::GetDC

Fornece um objeto sem janelas para obter um contexto de dispositivo de tela (ou compatível) de seu contêiner.

CDC* GetDC(
    LPCRECT lprcRect = NULL,
    DWORD dwFlags = OLEDC_PAINTBKGND);

Parâmetros

lprcRect
Um ponteiro para o retângulo que o controle sem janelas deseja redesenhar, nas coordenadas do cliente do controle. NULL significa a extensão do objeto completo.

dwFlags
Desenhando atributos do contexto do dispositivo. As opções são:

• OLEDC_NODRAW Indica que o objeto não usará o contexto do dispositivo para executar qualquer desenho, mas apenas para obter informações sobre o dispositivo de exibição. O contêiner deve simplesmente passar o DC da janela sem processamento adicional.

• OLEDC_PAINTBKGND Solicita que o contêiner pinte a tela de fundo antes de retornar o DC. Um objeto deverá usar esse sinalizador se ele estiver solicitando um DC para redesenhar uma área com plano de fundo transparente.

• OLEDC_OFFSCREEN Informa ao contêiner que o objeto deseja renderizar em um bitmap fora da tela que deve ser copiado para a tela. Um objeto deve usar esse sinalizador quando a operação de desenho que ele está prestes a executar gera muita cintilação. O contêiner é gratuito para atender a essa solicitação ou não. No entanto, se esse sinalizador não estiver definido, o contêiner deverá devolver um DC na tela. Isso permite que os objetos executem operações de tela direta, como mostrar uma seleção (por meio de uma operação XOR ).

Valor de retorno

Ponteiro para o contexto do dispositivo de exibição para a área do cliente do contêiner CWnd, se bem-sucedido; caso contrário, o valor retornado será NULL. O contexto do dispositivo de exibição pode ser usado em funções GDI subsequentes para desenhar na área do cliente da janela do contêiner.

Comentários

A função membro ReleaseDC deve ser chamada para liberar o contexto após a pintura. Ao chamar GetDC, os objetos passam o retângulo em que desejam desenhar em suas próprias coordenadas de cliente. GetDC converte-os em coordenadas da área do cliente do contêiner. O objeto não deve solicitar um retângulo de desenho desejado maior que seu próprio retângulo da área do cliente, do qual o tamanho pode ser recuperado com GetClientRect. Isso impede que objetos desenham inadvertidamente onde eles não deveriam.

COleControl::GetEnabled

Implementa a função Get da propriedade habilitada para ações do controle.

BOOL GetEnabled();

Valor de retorno

Diferente de zero se o controle estiver habilitado; caso contrário, 0.

COleControl::GetExtendedControl

Obtém um ponteiro para um objeto mantido pelo contêiner que representa o controle com um conjunto estendido de propriedades.

LPDISPATCH GetExtendedControl();

Valor de retorno

Um ponteiro para o objeto de controle estendido do contêiner. Se não houver nenhum objeto disponível, o valor será NULL.

Esse objeto pode ser manipulado por meio de sua IDispatch interface. Você também pode usar QueryInterface para obter outras interfaces disponíveis fornecidas pelo objeto. No entanto, o objeto não é necessário para dar suporte a um conjunto específico de interfaces. Observe que depender dos recursos específicos do objeto de controle estendido de um contêiner limita a portabilidade do controle a outros contêineres arbitrários.

Comentários

A função que chama essa função é responsável por liberar o ponteiro quando concluída com o objeto. Observe que o contêiner não é necessário para dar suporte a esse objeto.

COleControl::GetFocus

Determina se o objeto COleControl tem conteúdo.

CWnd* GetFocus();

Valor de retorno

Se o controle estiver ativado e sem janelas, retornará this se o controle tiver atualmente o foco do teclado (conforme determinado pelo contêiner do controle) ou NULL se ele não tiver o foco.

Caso contrário, retorna o CWnd objeto que tem o foco (o mesmo que CWnd::GetFocus).

Comentários

Um controle ativado sem janelas recebe o foco quando SetFocus é chamado.

COleControl::GetFont

Implementa a função Get da propriedade Fonte de estoque.

LPFONTDISP GetFont();

Valor de retorno

Um ponteiro para a interface de expedição de fonte da propriedade fonte de estoque do controle.

Comentários

Observe que o chamador deve liberar o objeto quando terminar. Na implementação do controle, use InternalGetFont para acessar o objeto fonte de estoque do controle. Para obter mais informações sobre como usar fontes em seu controle, consulte o artigo Controles ActiveX: Usando fontes em um controle ActiveX.

COleControl::GetFontTextMetrics

Mede as métricas de texto para qualquer CFontHolder objeto pertencente ao controle.

void GetFontTextMetrics(
    LPTEXTMETRIC lptm,
    CFontHolder& fontHolder);

Parâmetros

lptm
Um ponteiro para uma estrutura TEXTMETRIC .

fontHolder
Referência a um objeto CFontHolder .

Comentários

Essa fonte pode ser selecionada com a função COleControl::SelectFontObject. GetFontTextMetrics inicializará a TEXTMETRIC estrutura apontada pelo lptm com informações de métricas válidas sobre fontHoldera fonte se tiver êxito ou preencherá a estrutura com zeros, se não tiver êxito. Você deve usar essa função em vez de GetTextMetrics ao pintar seu controle porque os controles, como qualquer objeto OLE inserido, podem ser necessários para se renderizar em um metafile.

A estrutura TEXTMETRIC da fonte padrão é atualizada quando a função SelectFontObject é chamada. Você deve chamar GetFontTextMetrics somente depois de selecionar a propriedade fonte de estoque para garantir que as informações fornecidas sejam válidas.

COleControl::GetForeColor

Implementa a função Get da propriedade ForeColor de estoque.

OLE_COLOR GetForeColor();

Valor de retorno

O valor retornado especifica a cor do primeiro plano atual como um valor OLE_COLOR, se bem-sucedido. Esse valor pode ser convertido em um valor COLORREF com uma chamada para TranslateColor.

COleControl::GetHwnd

Implementa a função Get da propriedade stock hWnd.

OLE_HANDLE GetHwnd();

Valor de retorno

O identificador da janela do controle OLE, se houver; caso contrário, NULL.

COleControl::GetMessageString

Chamado pela estrutura para obter uma cadeia de caracteres curta que descreve a finalidade do item de menu identificado por nID.

virtual void GetMessageString(
    UINT nID,
    CString& rMessage) const;

Parâmetros

Nid
Uma ID de item de menu.

rMessage
Uma referência a um objeto CString por meio do qual uma cadeia de caracteres será retornada.

Comentários

Isso pode ser usado para obter uma mensagem para exibição em uma barra de status enquanto o item de menu está realçado. A implementação padrão tenta carregar um recurso de cadeia de caracteres identificado por nID.

COleControl::GetNotSupported

Impede o acesso ao valor da propriedade de um controle pelo usuário.

void GetNotSupported();

Comentários

Chame essa função no lugar da função Get de qualquer propriedade em que não há suporte para a recuperação da propriedade pelo usuário do controle. Um exemplo seria uma propriedade que é somente gravação.

COleControl::GetReadyState

Retorna o estado de preparação do controle.

long GetReadyState();

Valor de retorno

O estado de preparação do controle, um dos seguintes valores:

Nome	Descrição
READYSTATE_UNINITIALIZED	Estado de inicialização padrão
READYSTATE_LOADING	No momento, o controle está carregando suas propriedades
READYSTATE_LOADED	O controle foi inicializado
READYSTATE_INTERACTIVE	O controle tem dados suficientes para serem interativos, mas nem todos os dados assíncronos ainda estão carregados
READYSTATE_COMPLETE	O controle tem todos os seus dados

Comentários

A maioria dos controles simples nunca precisa diferenciar entre LOADED e INTERACTIVE. No entanto, os controles que dão suporte a propriedades de caminho de dados podem não estar prontos para serem interativos até que pelo menos alguns dados sejam recebidos de forma assíncrona. Um controle deve tentar se tornar interativo o mais rápido possível.

COleControl::GetRectInContainer

Obtém as coordenadas do retângulo do controle em relação ao contêiner, expressas em unidades de dispositivo.

BOOL GetRectInContainer(LPRECT lpRect);

Parâmetros

lpRect
Um ponteiro para a estrutura do retângulo na qual as coordenadas do controle serão copiadas.

Valor de retorno

Não zero se o controle estiver ativo in-loco; caso contrário, 0.

Comentários

O retângulo só será válido se o controle estiver ativo in-loco.

COleControl::GetStockTextMetrics

Mede as métricas de texto para a propriedade fonte de estoque do controle, que pode ser selecionada com a função SelectStockFont.

void GetStockTextMetrics(LPTEXTMETRIC lptm);

Parâmetros

lptm
Um ponteiro para uma estrutura TEXTMETRIC .

Comentários

A função GetStockTextMetrics inicializará a estrutura TEXTMETRIC apontada pelo lptm com informações de métricas válidas se tiver êxito ou preencherá a estrutura com zeros, se não for bem-sucedida. Use essa função em vez de GetTextMetrics ao pintar seu controle porque os controles, como qualquer objeto OLE inserido, podem ser necessários para se renderizar em um metafile.

A TEXTMETRIC estrutura da fonte padrão é atualizada quando a SelectStockFont função é chamada. Você deve chamar essa função somente depois de selecionar a fonte de estoque para garantir que as informações fornecidas sejam válidas.

COleControl::GetText

Implementa a função Get da propriedade Texto ou Legenda do estoque.

BSTR GetText();

Valor de retorno

O valor atual da cadeia de caracteres de texto de controle ou uma cadeia de caracteres de comprimento zero se nenhuma cadeia de caracteres estiver presente.

Observação

Para obter mais informações sobre o tipo de dados BSTR, consulte Tipos de Dados na seção Macros e Globais.

Comentários

Observe que o chamador dessa função deve chamar SysFreeString na cadeia de caracteres retornada para liberar o recurso. Dentro da implementação do controle, use InternalGetText para acessar a propriedade text ou caption do controle.

COleControl::GetWindowlessDropTarget

Substitua GetWindowlessDropTarget quando você quiser que um controle sem janelas seja o destino de uma operação de arrastar e soltar OLE.

virtual IDropTarget* GetWindowlessDropTarget();

Valor de retorno

Ponteiro para a interface do IDropTarget objeto. Como ele não tem uma janela, um objeto sem janelas não pode registrar uma interface IDropTarget. No entanto, para participar do arrastar e soltar, um objeto sem janelas ainda pode implementar a interface e devolvê-la emGetWindowlessDropTarget.

Comentários

Normalmente, isso exigiria que a janela do controle fosse registrada como um destino suspenso. Mas como o controle não tem nenhuma janela própria, o contêiner usará sua própria janela como um destino suspenso. O controle simplesmente precisa fornecer uma implementação da interface IDropTarget à qual o contêiner pode delegar chamadas no momento apropriado. Por exemplo:

IDropTarget *CMyAxCtrl::GetWindowlessDropTarget()
{
   m_xDropTarget.AddRef();
   return &m_xDropTarget;
}

COleControl::InitializeIIDs

Informa a classe base dos IIDs que o controle usará.

void InitializeIIDs(
    const IID* piidPrimary,
    const IID* piidEvents);

Parâmetros

piidPrimary
Ponteiro para a ID de interface da interface de expedição primária do controle.

piidEvents
Ponteiro para a ID de interface da interface de evento do controle.

Comentários

Chame essa função no construtor do controle para informar a classe base das IDs de interface que seu controle usará.

COleControl::InternalGetFont

Acessa a propriedade fonte de estoque do seu controle

CFontHolder& InternalGetFont();

Valor de retorno

Uma referência a um objeto CFontHolder que contém o objeto Stock Font.

COleControl::InternalGetText

Acessa a propriedade texto ou legenda de estoque do seu controle.

const CString& InternalGetText();

Valor de retorno

Uma referência à cadeia de caracteres de texto de controle.

COleControl::InternalSetReadyState

Define o estado de preparação do controle.

void InternalSetReadyState(long lNewReadyState);

Parâmetros

lNewReadyState
O estado de preparação a ser definido para o controle, um dos seguintes valores:

Nome	Descrição
READYSTATE_UNINITIALIZED	Estado de inicialização padrão
READYSTATE_LOADING	No momento, o controle está carregando suas propriedades
READYSTATE_LOADED	O controle foi inicializado
READYSTATE_INTERACTIVE	O controle tem dados suficientes para serem interativos, mas nem todos os dados assíncronos ainda estão carregados
READYSTATE_COMPLETE	O controle tem todos os seus dados

Comentários

A maioria dos controles simples nunca precisa diferenciar entre LOADED e INTERACTIVE. No entanto, os controles que dão suporte a propriedades de caminho de dados podem não estar prontos para serem interativos até que pelo menos alguns dados sejam recebidos de forma assíncrona. Um controle deve tentar se tornar interativo o mais rápido possível.

COleControl::InvalidateControl

Força que o controle se redesenhe.

void InvalidateControl(
    LPCRECT lpRect = NULL,
    BOOL bErase = TRUE);

Parâmetros

lpRect
Um ponteiro para a região do controle a ser invalidada.

bErase
Especifica se o plano de fundo dentro da região de atualização deve ser apagado quando a região de atualização é processada.

Comentários

Se lpRect tiver um valor NULL, todo o controle será redesenhado. Se lpRect não for NULL, isso indicará a parte do retângulo do controle que deve ser invalidada. Nos casos em que o controle não tem janela ou não está ativo no momento, o retângulo é ignorado e uma chamada é feita para a função de membro IAdviseSink::OnViewChange do site cliente. Use essa função em vez de CWnd::InvalidateRect ou InvalidateRect.

COleControl::InvalidateRgn

Invalida a área de cliente da janela de contêiner dentro da região fornecida.

void InvalidateRgn(CRgn* pRgn, BOOL bErase = TRUE);

Parâmetros

pRgn
Um ponteiro para um objeto CRgn que identifica a região de exibição do objeto OLE para invalidar, nas coordenadas do cliente da janela que contém. Se esse parâmetro for NULL, a extensão será o objeto inteiro.

bErase
Especifica se o plano de fundo dentro da região invalidada deve ser apagado. Se TRUE, o plano de fundo será apagado. Se FALSE, o plano de fundo permanecerá inalterado.

Comentários

Isso pode ser usado para redesenhar controles sem janelas dentro do contêiner. A região invalidada, juntamente com todas as outras áreas da região de atualização, é marcada para pintura quando a próxima WM_PAINT mensagem é enviada.

Se bErase for TRUE para qualquer parte da região de atualização, o plano de fundo em toda a região, não apenas na parte específica, será apagado.

COleControl::IsConvertingVBX

Permite o carregamento especializado de um controle OLE.

BOOL IsConvertingVBX();

Valor de retorno

Não zero se o controle estiver sendo convertido; caso contrário, 0.

Comentários

Ao converter um formulário que usa controles VBX em um que usa controles OLE, o código de carregamento especial para os controles OLE pode ser necessário. Por exemplo, se você estiver carregando uma instância do controle OLE, poderá ter uma chamada para PX_Font em seu DoPropExchange:

PX_Font(pPX, _T("Font"), *m_pMyFont, &DefaultFont);

No entanto, os controles VBX não tinham um objeto Font; cada propriedade de fonte foi salva individualmente. Nesse caso, você usaria IsConvertingVBX para distinguir entre esses dois casos:

if (!IsConvertingVBX())
{
   PX_Font(pPX, _T("Font"), *m_pMyFont, &DefaultFont);
}
else
{
   PX_String(pPX, _T("FontName"), tempString, DefaultName);
   m_pMyFont->m_pFont->put_Name(tempString.AllocSysString());
   PX_Bool(pPX, _T("FontUnderline"), tempBool, DefaultValue);
   m_pMyFont->m_pFont->put_Underline(tempBool);
}

Outro caso seria se o controle VBX salvasse dados binários proprietários (em seu manipulador de mensagens VBM_SAVEPROPERTY) e seu controle OLE salvasse seus dados binários em um formato diferente. Se você quiser que o controle OLE seja compatível com versões anteriores com o controle VBX, você poderá ler os formatos antigos e novos usando a função IsConvertingVBX, distinguindo se o controle VBX ou o controle OLE estava sendo carregado.

Na função DoPropExchange do controle, você pode verificar essa condição e, se for verdadeiro, executar código de carga específico para essa conversão (como os exemplos anteriores). Se o controle não estiver sendo convertido, você poderá executar o código de carga normal. Essa capacidade só é aplicável a controles que estão sendo convertidos de equivalentes VBX.

COleControl::IsInvokeAllowed

Habilita a invocação do método de automação.

BOOL IsInvokeAllowed(DISPID dispid);

Valor de retorno

Não zero se o controle tiver sido inicializado; caso contrário, 0.

Comentários

A implementação de IDispatch::Invoke chamadas IsInvokeAllowed da estrutura para determinar se uma determinada função (identificada por dispid) pode ser invocada. O comportamento padrão de um controle OLE é permitir que os métodos de automação sejam invocados somente se o controle tiver sido inicializado; no entanto, IsInvokeAllowed é uma função virtual e pode ser substituída se necessário (por exemplo, quando o controle está sendo usado como um servidor de automação).

COleControl::IsModified

Determina se o estado do controle foi modificado.

BOOL IsModified();

Valor de retorno

Não zero se o estado do controle tiver sido modificado desde que foi salvo pela última vez; caso contrário, 0.

Comentários

O estado de um controle é modificado quando uma propriedade altera o valor.

COleControl::IsOptimizedDraw

Determina se o contêiner dá suporte ao desenho otimizado para a operação de desenho atual.

BOOL IsOptimizedDraw();

Valor de retorno

TRUE se o contêiner der suporte ao desenho otimizado para a operação de desenho atual; caso contrário, FALSE.

Comentários

Se houver suporte para o desenho otimizado, o controle não precisará selecionar objetos antigos (canetas, pincéis, fontes etc.) no contexto do dispositivo quando o desenho for concluído.

COleControl::IsSubclassedControl

Chamado pela estrutura para determinar se o controle subclasse um controle do Windows.

virtual BOOL IsSubclassedControl();

Valor de retorno

Diferente de zero se o controle for subclasse; caso contrário, 0.

Comentários

Você deve substituir essa função e retornar TRUE se o controle OLE subclasse um controle do Windows.

COleControl::Load

Redefine os dados anteriores carregados de forma assíncrona e inicia um novo carregamento da propriedade assíncrona do controle.

void Load(LPCTSTR strNewPath, CDataPathProperty& prop);

Parâmetros

strNewPath
Um ponteiro para uma cadeia de caracteres que contém o caminho que faz referência ao local absoluto da propriedade de controle assíncrona.

prop
Um objeto CDataPathProperty que implementa uma propriedade de controle assíncrona.

COleControl::LockInPlaceActive

Impede que o contêiner desative seu controle.

BOOL LockInPlaceActive(BOOL bLock);

Parâmetros

bLock
TRUE se o estado ativo in-loco do controle deve ser bloqueado; FALSE se for para ser desbloqueado.

Valor de retorno

Diferente de zero se a operação de bloquear for bem-sucedida, caso contrário, 0.

Comentários

Observe que cada bloqueio do controle deve ser emparelhado com um desbloqueio do controle quando concluído. Você só deve bloquear seu controle por curtos períodos, como ao disparar um evento.

COleControl::OnAmbientPropertyChange

Chamado pela estrutura quando uma propriedade ambiente do contêiner tiver alterado o valor.

virtual void OnAmbientPropertyChange(DISPID dispid);

Parâmetros

dispID
A ID de expedição da propriedade ambiente que foi alterada ou DISPID_UNKNOWN se várias propriedades foram alteradas.

COleControl::OnAppearanceChanged

Chamado pela estrutura quando o valor da propriedade Aparência de estoque foi alterado.

virtual void OnAppearanceChanged ();

Comentários

Substitua essa função se você quiser notificação depois que essa propriedade for alterada. A implementação padrão chama InvalidateControl.

COleControl::OnBackColorChanged

Chamado pela estrutura quando o valor da propriedade BackColor de ações foi alterado.

virtual void OnBackColorChanged();

Comentários

Substitua essa função se você quiser notificação depois que essa propriedade for alterada. A implementação padrão chama InvalidateControl.

COleControl::OnBorderStyleChanged

Chamado pela estrutura quando o valor da propriedade BorderStyle de ações foi alterado.

virtual void OnBorderStyleChanged();

Comentários

A implementação padrão chama InvalidateControl.

Substitua essa função se você quiser notificação depois que essa propriedade for alterada.

COleControl::OnClick

Chamado pela estrutura quando um botão do mouse foi clicado ou o método de estoque do DoClick foi invocado.

virtual void OnClick(USHORT iButton);

Parâmetros

iButton
Índice de um botão do mouse. Pode ter um dos seguintes valores:

• LEFT_BUTTON O botão esquerdo do mouse foi clicado.

• MIDDLE_BUTTON O botão do mouse do meio foi clicado.

• RIGHT_BUTTON O botão direito do mouse foi clicado.

Comentários

A implementação padrão chama COleControl::FireClick.

Substitua essa função de membro para modificar ou estender o tratamento padrão.

COleControl::OnClose

Chamado pela estrutura quando o contêiner chamou a função IOleControl::Close do controle.

virtual void OnClose(DWORD dwSaveOption);

Parâmetros

dwSaveOption
Sinalizador que indica se o objeto deve ser salvo antes de carregar. Os valores válidos são:

• OLECLOSE_SAVEIFDIRTY

• OLECLOSE_NOSAVE

• OLECLOSE_PROMPTSAVE

Comentários

Por padrão, OnClose salva o objeto de controle se ele foi modificado e dwSaveOption é OLECLOSE_SAVEIFDIRTY ou OLECLOSE_PROMPTSAVE.

COleControl::OnDoVerb

Chamado pela estrutura quando o contêiner chama a função membro IOleObject::DoVerb.

virtual BOOL OnDoVerb(
    LONG iVerb,
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

Parâmetros

iVerb
O índice do verbo de controle a ser invocado.

lpMsg
Um ponteiro para a mensagem do Windows que fez com que o verbo fosse invocado.

hWndParent
O identificador para a janela pai do controle. Se a execução do verbo criar uma janela (ou janelas), hWndParent deverá ser usado como o pai.

lpRect
Um ponteiro para uma estrutura RECT na qual as coordenadas do controle, em relação ao contêiner, serão copiadas.

Valor de retorno

Não zero se a chamada foi bem-sucedida; caso contrário, 0.

Comentários

A implementação padrão usa as entradas do mapa de mensagens ON_OLEVERB e ON_STDOLEVERB para determinar a função adequada a ser invocada.

Substitua essa função para alterar o tratamento padrão do verbo.

COleControl::OnDraw

Chamado pela estrutura para desenhar o controle OLE no retângulo delimitador especificado usando o contexto do dispositivo especificado.

virtual void OnDraw(
    CDC* pDC,
    const CRect& rcBounds,
    const CRect& rcInvalid);

Parâmetros

pDC
O contexto do dispositivo no qual o desenho ocorre.

rcBounds
A área retangular do controle, incluindo a borda.

rcInvalid
A área retangular do controle que é inválida.

Comentários

OnDraw normalmente é chamado para exibição de tela, passando um contexto de dispositivo de tela como pDC. O parâmetro lpBounds identifica o retângulo no contexto do dispositivo de destino (em relação ao modo de mapeamento atual dele). O parâmetro rcInvalid é o retângulo real que é inválido. Em alguns casos, essa será uma área menor que rcBounds.

COleControl::OnDrawMetafile

Chamado pela estrutura para desenhar o controle OLE no retângulo delimitador especificado usando o contexto do dispositivo especificado.

virtual void OnDrawMetafile(
    CDC* pDC,
    const CRect& rcBounds);

Parâmetros

pDC
O contexto do dispositivo no qual o desenho ocorre.

rcBounds
A área retangular do controle, incluindo a borda.

Comentários

A implementação padrão chama a função OnDraw .

COleControl::OnEdit

Faz com que o controle seja ativado pela interface do usuário.

virtual BOOL OnEdit(
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

Parâmetros

lpMsg
Um ponteiro para a mensagem do Windows que invocou o verbo.

hWndParent
Um identificador para a janela pai do controle.

lpRect
Um ponteiro para o retângulo usado pelo controle no contêiner.

Valor de retorno

Diferente de zero se a chamada for bem-sucedida, caso contrário, retornará 0.

Comentários

Isso tem o mesmo efeito que invocar o verbo OLEIVERB_UIACTIVATE do controle.

Essa função normalmente é usada como a função de manipulador para uma entrada de mapa de mensagens ON_OLEVERB. Isso disponibiliza um verbo "Editar" no menu "Objeto" do controle. Por exemplo:

ON_OLEVERB(AFX_IDS_VERB_EDIT, OnEdit)

COleControl::OnEnabledChanged

Chamado pela estrutura quando o valor da propriedade de estoque habilitado foi alterado.

virtual void OnEnabledChanged();

Comentários

Substitua essa função se você quiser notificação depois que essa propriedade for alterada. A implementação padrão chama InvalidateControl.

COleControl::OnEnumVerbs

Chamado pela estrutura quando o contêiner chama a função membro IOleObject::EnumVerbs.

virtual BOOL OnEnumVerbs(LPENUMOLEVERB* ppenumOleVerb);

Parâmetros

ppenumOleVerb
Um ponteiro para o objeto IEnumOLEVERB que enumera os verbos do controle.

Valor de retorno

Não zero se os verbos estiverem disponíveis; caso contrário, 0.

Comentários

A implementação padrão enumera as entradas de ON_OLEVERB no mapa da mensagem.

Substitua essa função para alterar a maneira padrão de enumerar verbos.

COleControl::OnEventAdvise

Chamado pela estrutura quando um manipulador de eventos está conectado ou desconectado de um controle OLE.

virtual void OnEventAdvise(BOOL bAdvise);

Parâmetros

bAdvise
TRUE indica que um manipulador de eventos foi conectado ao controle. FALSE indica que um manipulador de eventos foi desconectado do controle.

COleControl::OnFontChanged

Chamado pela estrutura quando o valor da propriedade fonte de estoque foi alterado.

virtual void OnFontChanged();

Comentários

A implementação padrão chama COleControl::InvalidateControl. Se o controle estiver subclasse de um controle do Windows, a implementação padrão também enviará uma mensagem de WM_SETFONT para a janela do controle.

Substitua essa função se você quiser notificação depois que essa propriedade for alterada.

Exemplo

void CMyAxCtrl::OnFontChanged()
{
   // Always set it to the container's font
   if (m_MyEdit.m_hWnd != NULL)
   {
      IFontDisp *pFontDisp = NULL;
      IFont *pFont = NULL;
      HRESULT hr;

      // Get the container's FontDisp interface
      pFontDisp = AmbientFont();
      if (pFontDisp)
      {
         hr = pFontDisp->QueryInterface(IID_IFont, (LPVOID*)&pFont);
         if (FAILED(hr))
         {
            pFontDisp->Release();
            return;
         }
      }

      HFONT hFont = NULL;
      if (pFont)
      {
         pFont->get_hFont(&hFont);
         m_MyEdit.SendMessage(WM_SETFONT, (WPARAM)hFont, 0L);
      }

      pFontDisp->Release();
   }

   // Invalidate the control
   m_MyEdit.Invalidate();
   m_MyEdit.UpdateWindow();

   COleControl::OnFontChanged();
}

COleControl::OnForeColorChanged

Chamado pela estrutura quando o valor da propriedade ForeColor do estoque foi alterado.

virtual void OnForeColorChanged();

Comentários

A implementação padrão chama InvalidateControl.

Substitua essa função se você quiser notificação depois que essa propriedade for alterada.

COleControl::OnFreezeEvents

Chamado pela estrutura após as chamadas IOleControl::FreezeEventsde contêiner.

virtual void OnFreezeEvents(BOOL bFreeze);

Parâmetros

bFreeze
TRUE se a manipulação de eventos do controle estiver congelada; caso contrário, FALSE.

Comentários

A implementação padrão não tem ação.

Substitua essa função se você quiser um comportamento adicional quando o tratamento de eventos estiver congelado ou descongelado.

COleControl::OnGetColorSet

Chamado pela estrutura quando o contêiner chama a função membro IViewObject::GetColorSet.

virtual BOOL OnGetColorSet(
    DVTARGETDEVICE* ptd,
    HDC hicTargetDev,
    LPLOGPALETTE* ppColorSet);

Parâmetros

ptd
Aponta para o dispositivo de destino para o qual a imagem deve ser renderizada. Se esse valor for NULL, a imagem deverá ser renderizada para um dispositivo de destino padrão, geralmente um dispositivo de exibição.

hicTargetDev
Especifica o contexto de informações no dispositivo de destino indicado pelo ptd. Esse parâmetro pode ser um contexto de dispositivo, mas não é necessariamente um. Se ptd for NULL, hicTargetDev também deverá ser NULL.

ppColorSet
Um ponteiro para o local no qual o conjunto de cores que seria usado deve ser copiado. Se a função não retornar o conjunto de cores, NULL será retornado.

Valor de retorno

Diferente de zero se um conjunto de cores válido for retornado; caso contrário, 0.

Comentários

O contêiner chama essa função para obter todas as cores necessárias para desenhar o controle OLE. O contêiner pode usar os conjuntos de cores obtidos em conjunto com as cores necessárias para definir a paleta de cores geral. A implementação padrão retorna FALSE.

Substitua essa função para fazer qualquer processamento especial dessa solicitação.

COleControl::OnGetControlInfo

Chamado pela estrutura quando o contêiner do controle solicitou informações sobre o controle.

virtual void OnGetControlInfo(LPCONTROLINFO pControlInfo);

Parâmetros

pControlInfo
Ponteiro para a estrutura CONTROLINFO a ser preenchida.

Comentários

Essas informações consistem principalmente em uma descrição das chaves mnemônicas do controle. A implementação padrão preenche pControlInfo com informações padrão.

Substitua essa função se o controle precisar processar chaves mnemônicas.

COleControl::OnGetDisplayString

Chamado pela estrutura para obter uma cadeia de caracteres que representa o valor atual da propriedade identificada por dispid.

virtual BOOL OnGetDisplayString(
    DISPID dispid,
    CString& strValue);

Parâmetros

dispid
A ID de expedição de uma propriedade do controle.

strValue
Uma referência a um objeto CString por meio do qual uma cadeia de caracteres será retornada.

Valor de retorno

Não zero se uma cadeia de caracteres tiver sido retornada em strValue; caso contrário, 0.

Comentários

Substitua essa função se o controle tiver uma propriedade cujo valor não pode ser convertido diretamente em uma cadeia de caracteres e você quiser que o valor da propriedade seja exibido em um navegador de propriedades fornecido pelo contêiner.

COleControl::OnGetInPlaceMenu

Chamado pela estrutura quando o controle é ativado pela interface do usuário para obter o menu a ser mesclado no menu existente do contêiner.

virtual HMENU OnGetInPlaceMenu();

Valor de retorno

O identificador do menu do controle ou NULL se o controle não tiver nenhum. A implementação padrão retorna NULL.

Comentários

Para obter mais informações sobre como mesclar recursos OLE, consulte o artigo Menus e Recursos (OLE).

COleControl::OnGetNaturalExtent

Chamado pela estrutura em resposta à solicitação IViewObjectEx::GetNaturalExtent de um contêiner.

virtual BOOL OnGetNaturalExtent(
    DWORD dwAspect,
    LONG lindex,
    DVTARGETDEVICE* ptd,
    HDC hicTargetDev,
    DVEXTENTINFO* pExtentInfo,
    LPSIZEL psizel);

Parâmetros

dwAspect
Especifica como o objeto deve ser representado. As representações incluem conteúdo, um ícone, uma miniatura ou um documento impresso. Os valores válidos são obtidos da enumeração DVASPECT ou DVASPECT2.

lindex
A parte do objeto que é de interesse. Atualmente, somente -1 é válido.

ptd
Aponta para a estrutura DVTARGETDEVICE que define o dispositivo de destino para o qual o tamanho do objeto deve ser retornado.

hicTargetDev
Especifica o contexto de informações para o dispositivo de destino indicado pelo parâmetro ptd do qual o objeto pode extrair métricas do dispositivo e testar os recursos do dispositivo. Se ptd for NULL, o objeto deverá ignorar o valor no parâmetro hicTargetDev .

pExtentInfo
Aponta para a estrutura DVEXTENTINFO que especifica dados de dimensionamento. A estrutura DVEXTENTINFO é:

typedef struct tagExtentInfo
{
    UINT cb;
    DWORD dwExtentMode;
    SIZEL sizelProposed;
}   DVEXTENTINFO;

O membro da estrutura dwExtentMode pode usar um dos dois valores:

• DVEXTENT_CONTENT Perguntar qual deve ser o tamanho do controle para ajustar exatamente o conteúdo (snap-to-size)

• DVEXTENT_INTEGRAL Ao redimensionar, passe o tamanho proposto para controlar

psizel
Aponta para dados de dimensionamento retornados pelo controle. Os dados de dimensionamento retornados são definidos como -1 para qualquer dimensão que não foi ajustada.

Valor de retorno

Não zero se ele retornar ou ajustar o tamanho com êxito; caso contrário, 0.

Comentários

Substitua essa função para retornar o tamanho de exibição do objeto mais próximo do modo de tamanho e extensão propostos na estrutura DVEXTENTINFO. A implementação padrão retorna FALSE e não faz nenhum ajuste no tamanho.

COleControl::OnGetPredefinedStrings

Chamado pela estrutura para obter um conjunto de cadeias de caracteres predefinidas que representam os valores possíveis para uma propriedade.

virtual BOOL OnGetPredefinedStrings(
    DISPID dispid,
    CStringArray* pStringArray,
    CDWordArray* pCookieArray);

Parâmetros

dispid
A ID de expedição de uma propriedade do controle.

pStringArray
Uma matriz de cadeia de caracteres a ser preenchida com valores retornados.

pCookieArray
Uma matriz DWORD a ser preenchida com valores retornados.

Valor de retorno

Não zero se elementos tiverem sido adicionados a pStringArray e pCookieArray.

Comentários

Substitua essa função se o controle tiver uma propriedade com um conjunto de valores possíveis que podem ser representados por cadeias de caracteres. Para cada elemento adicionado ao pStringArray, você deve adicionar um elemento "cookie" correspondente ao pCookieArray. Esses valores de "cookie" podem ser passados posteriormente pela estrutura para a função COleControl::OnGetPredefinedValue.

COleControl::OnGetPredefinedValue

Chamado pela estrutura para obter o valor correspondente a uma das cadeias de caracteres predefinidas retornadas anteriormente por uma substituição de COleControl::OnGetPredefinedStrings.

virtual BOOL OnGetPredefinedValue(
    DISPID dispid,
    DWORD dwCookie,
    VARIANT* lpvarOut);

Parâmetros

dispid
A ID de expedição de uma propriedade do controle.

dwCookie
Um valor de cookie retornado anteriormente por uma substituição de COleControl::OnGetPredefinedStrings.

lpvarOut
Ponteiro para uma estrutura VARIANT por meio da qual um valor de propriedade será retornado.

Valor de retorno

Não zero se um valor tiver sido retornado em lpvarOut; caso contrário, 0.

COleControl::OnGetViewExtent

Chamado pela estrutura em resposta à solicitação IViewObject2::GetExtent de um contêiner.

virtual BOOL OnGetViewExtent(
    DWORD dwDrawAspect,
    LONG lindex,
    DVTARGETDEVICE* ptd,
    LPSIZEL lpsizel);

Parâmetros

dwDrawAspect
DWORD que descreve qual formulário, ou aspecto, de um objeto deve ser exibido. Os valores válidos são obtidos da enumeração DVASPECT ou DVASPECT2.

lindex
A parte do objeto que é de interesse. Atualmente, somente -1 é válido.

ptd
Aponta para a estrutura DVTARGETDEVICE que define o dispositivo de destino para o qual o tamanho do objeto deve ser retornado.

lpsizel
Aponta para o local em que o tamanho do objeto é retornado.

Valor de retorno

Não zero se as informações de extensão forem retornadas com êxito; caso contrário, 0.

Comentários

Substitua essa função se o controle usar desenho de duas etapas e suas partes opacas e transparentes tiverem dimensões diferentes.

COleControl::OnGetViewRect

Chamado pela estrutura em resposta à solicitação IViewObjectEx::GetRect de um contêiner.

virtual BOOL OnGetViewRect(DWORD dwAspect, LPRECTL pRect);

Parâmetros

dwAspect
DWORD que descreve qual formulário, ou aspecto, de um objeto deve ser exibido. Os valores válidos são obtidos da enumeração DVASPECT ou DVASPECT2.

• DVASPECT_CONTENT retângulo delimitador do objeto inteiro. Canto superior esquerdo na origem do objeto e tamanho igual à extensão retornada por GetViewExtent.

• DVASPECT_OPAQUE Objetos com uma região opaca retangular retornam esse retângulo. Outros falham.

• DVASPECT_TRANSPARENT Retângulo cobrindo todas as partes transparentes ou irregulares.

pRect
Aponta para a estrutura RECTL que especifica o retângulo no qual o objeto deve ser desenhado. Esse parâmetro controla o posicionamento e o alongamento do objeto.

Valor de retorno

Não zero se o retângulo dimensionado para o objeto for retornado com êxito; caso contrário, 0.

Comentários

O tamanho do objeto é convertido por OnGetViewRect em um retângulo começando em uma posição específica (o padrão é o canto superior esquerdo da exibição). Substitua essa função se o controle usar desenho de duas etapas e suas partes opacas e transparentes tiverem dimensões diferentes.

COleControl::OnGetViewStatus

Chamado pela estrutura em resposta à solicitação IViewObjectEx::GetViewStatus de um contêiner.

virtual DWORD OnGetViewStatus();

Valor de retorno

Um dos valores da enumeração VIEWSTATUS se tiver êxito; caso contrário, 0. Os valores possíveis são qualquer combinação do seguinte:

Nome	Descrição
VIEWSTATUS_OPAQUE	O objeto é completamente opaco. Se esse bit não estiver definido, o objeto conterá partes transparentes. Esse bit se aplica apenas a aspectos relacionados ao conteúdo e não a DVASPECT_ICON ou DVASPECT_DOCPRINT.
VIEWSTATUS_SOLIDBKGND	O objeto tem uma tela de fundo sólida (consistindo em uma cor sólida, não em um padrão de pincel). Esse bit só será significativo se VIEWSTATUS_OPAQUE estiver definido e se aplicar somente a aspectos relacionados ao conteúdo e não a DVASPECT_ICON ou DVASPECT_DOCPRINT.
VIEWSTATUS_DVASPECTOPAQUE	O objeto dá suporte a DVASPECT_OPAQUE. Todos os métodos IViewObjectEx que tomam um aspecto de desenho como um parâmetro podem ser chamados com esse aspecto.
VIEWSTATUS_DVASPECTTRANSPARENT	O objeto dá suporte a DVASPECT_TRANSPARENT. Todos os IViewObjectEx métodos que tomam um aspecto de desenho como parâmetro podem ser chamados com esse aspecto.

Comentários

Substitua essa função se o controle usar desenho de duas etapas. A implementação padrão retorna VIEWSTATUS_OPAQUE.

COleControl::OnHideToolBars

Chamado pela estrutura quando o controle é desativado pela interface do usuário.

virtual void OnHideToolBars();

Comentários

A implementação deve ocultar todas as barras de ferramentas exibidas por OnShowToolbars.

COleControl::OnInactiveMouseMove

Chamado pelo contêiner para o objeto inativo sob o ponteiro do mouse no recebimento de uma mensagem de WM_MOUSEMOVE.

virtual void OnInactiveMouseMove(
    LPCRECT lprcBounds,
    long x,
    long y,
    DWORD dwKeyState);

Parâmetros

lprcBounds
O retângulo delimitador de objeto, nas coordenadas do cliente da janela que contém. Informa ao objeto sua posição e tamanho exatos na tela quando a mensagem de WM_MOUSEMOVE foi recebida.

x
A coordenada x do local do mouse nas coordenadas do cliente da janela que contém.

y
A coordenada x do local do mouse nas coordenadas do cliente da janela que contém.

dwKeyState
Identifica o estado atual das teclas modificadoras de teclado no teclado. Os valores válidos podem ser uma combinação de qualquer um dos sinalizadores MK_CONTROL, MK_SHIFT, MK_ALT, MK_BUTTON, MK_LBUTTON, MK_MBUTTON e MK_RBUTTON.

Comentários

Observe que as coordenadas do cliente de janela (pixels) são usadas para passar a posição do cursor do mouse. Isso é possível passando também o retângulo delimitador do objeto no mesmo sistema de coordenadas.

COleControl::OnInactiveSetCursor

Chamado pelo contêiner para o objeto inativo sob o ponteiro do mouse no recebimento de uma mensagem de WM_MOUSEMOVE.

virtual BOOL OnInactiveSetCursor(
    LPCRECT lprcBounds,
    long x,
    long y,
    DWORD dwMouseMsg,
    BOOL bSetAlways);

Parâmetros

lprcBounds
O retângulo delimitador de objeto, nas coordenadas do cliente da janela que contém. Informa ao objeto sua posição e tamanho exatos na tela quando a mensagem de WM_SETCURSOR foi recebida.

x
A coordenada x do local do mouse nas coordenadas do cliente da janela que contém.

y
A coordenada x do local do mouse nas coordenadas do cliente da janela que contém.

dwMouseMsg
O identificador da mensagem do mouse para a qual ocorreu um WM_SETCURSOR.

bSetAlways
Especifica se o objeto deve ou não definir o cursor. Se TRUE, o objeto deverá definir o cursor; se FALSE, o cursor não será obrigado a definir o cursor e deverá retornar S_FALSE nesse caso.

Valor de retorno

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

Comentários

Observe que as coordenadas do cliente de janela (pixels) são usadas para passar a posição do cursor do mouse. Isso é possível passando também o retângulo delimitador do objeto no mesmo sistema de coordenadas.

COleControl::OnKeyDownEvent

Chamado pela estrutura após um evento KeyDown de ações ter sido processado.

virtual void OnKeyDownEvent(
    USHORT nChar,
    USHORT nShiftState);

Parâmetros

nChar
O valor do código da chave virtual da tecla pressionada. Para obter uma lista de códigos de tecla virtual padrão, consulte Winuser.h

nShiftState
Contém uma combinação dos seguintes sinalizadores:

• SHIFT_MASK a tecla SHIFT foi pressionada durante a ação.

• CTRL_MASK A tecla CTRL foi pressionada durante a ação.

• ALT_MASK A tecla ALT foi pressionada durante a ação.

Comentários

Substitua essa função se o controle precisar de acesso às informações de chave depois que o evento for acionado.

COleControl::OnKeyPressEvent

Chamado pela estrutura depois que o evento KeyPress de ações foi acionado.

virtual void OnKeyPressEvent(USHORT nChar);

Parâmetros

nChar
Contém o valor do código de chave virtual da tecla pressionada. Para obter uma lista de códigos de tecla virtual padrão, consulte Winuser.h

Comentários

Observe que o valor nChar pode ter sido modificado pelo contêiner.

Substitua essa função se você quiser notificação depois que esse evento ocorrer.

COleControl::OnKeyUpEvent

Chamado pela estrutura após um evento KeyDown de ações ter sido processado.

virtual void OnKeyUpEvent(
    USHORT nChar,
    USHORT nShiftState);

Parâmetros

nChar
O valor do código da chave virtual da tecla pressionada. Para obter uma lista de códigos de tecla virtual padrão, consulte Winuser.h

nShiftState
Contém uma combinação dos seguintes sinalizadores:

• SHIFT_MASK a tecla SHIFT foi pressionada durante a ação.

• CTRL_MASK A tecla CTRL foi pressionada durante a ação.

• ALT_MASK A tecla ALT foi pressionada durante a ação.

Comentários

Substitua essa função se o controle precisar de acesso às informações de chave depois que o evento for acionado.

COleControl::OnMapPropertyToPage

Chamado pela estrutura para obter a ID de classe de uma página de propriedade que implementa a edição da propriedade especificada.

virtual BOOL OnMapPropertyToPage(
    DISPID dispid,
    LPCLSID lpclsid,
    BOOL* pbPageOptional);

Parâmetros

dispid
A ID de expedição de uma propriedade do controle.

lpclsid
Ponteiro para uma estrutura CLSID por meio da qual uma ID de classe será retornada.

pbPageOptional
Retorna um indicador de se o uso da página de propriedade especificada é opcional.

Valor de retorno

Nonzero se uma ID de classe tiver sido retornada em lpclsid; caso contrário, 0.

Comentários

Substitua essa função para fornecer uma maneira de invocar as páginas de propriedades do controle do navegador de propriedades do contêiner.

COleControl::OnMnemonic

Chamado pela estrutura quando o contêiner detectou que uma chave mnemônica do controle OLE foi pressionada.

virtual void OnMnemonic(LPMSG pMsg);

Parâmetros

pMsg
Ponteiro para a mensagem do Windows gerada por uma tecla mnemônica.

COleControl::OnProperties

Chamado pela estrutura quando o verbo de propriedades do controle foi invocado pelo contêiner.

virtual BOOL OnProperties(
    LPMSG lpMsg,
    HWND hWndParent,
    LPCRECT lpRect);

Parâmetros

lpMsg
Um ponteiro para a mensagem do Windows que invocou o verbo.

hWndParent
Um identificador para a janela pai do controle.

lpRect
Um ponteiro para o retângulo usado pelo controle no contêiner.

Valor de retorno

Diferente de zero se a chamada for bem-sucedida, caso contrário, retornará 0.

Comentários

A implementação padrão exibe uma caixa de diálogo de propriedade modal.

Você também pode usar essa função para causar a exibição das páginas de propriedades do controle. Faça uma chamada para a função OnProperties, passando o identificador do pai do controle no parâmetro hWndParent. Nesse caso, os valores dos parâmetros lpMsg e lpRect são ignorados.

COleControl::OnQueryHitPoint

Chamado pela estrutura em resposta à solicitação IViewObjectEx::QueryHitPoint de um contêiner.

virtual BOOL OnQueryHitPoint(
    DWORD dwAspect,
    LPCRECT pRectBounds,
    POINT ptlLoc,
    LONG lCloseHint,
    DWORD* pHitResult);

Parâmetros

dwAspect
Especifica como o objeto é representado. Os valores válidos são obtidos da enumeração DVASPECT ou DVASPECT2.

pRectBounds
Ponteiro para uma RECT estrutura que especifica o retângulo delimitador da área do cliente de controle OLE.

ptlLoc
Ponteiro para a estrutura POINT que especifica o ponto a ser verificado para uma ocorrência. O ponto é especificado nas coordenadas da área do cliente OLE.

lCloseHint
A distância que define "close" ao ponto verificado para obter um hit.

pHitResult
Ponteiro para o resultado da consulta de acerto. Um dos seguintes valores:

• HITRESULT_OUTSIDE ptlLoc está fora do objeto OLE e não fecha.

• HITRESULT_TRANSPARENT ptlLoc está dentro dos limites do objeto OLE, mas não está perto da imagem. Por exemplo, um ponto no meio de um círculo transparente pode ser HITRESULT_TRANSPARENT.

• HITRESULT_CLOSE ptlLoc está dentro ou fora do objeto OLE, mas perto o suficiente do objeto a ser considerado dentro. Objetos pequenos, finos ou detalhados podem usar esse valor. Mesmo que um ponto esteja fora do retângulo delimitador de um objeto, ele ainda poderá estar próximo (isso é necessário para atingir objetos pequenos).

• HITRESULT_HIT ptlLoc está dentro da imagem do objeto.

Valor de retorno

Não zero se um resultado de ocorrência for retornado com êxito; caso contrário, 0. Um hit é uma sobreposição com a área de exibição do controle OLE.

Comentários

Consulta se o retângulo de exibição de um objeto se sobrepõe ao ponto determinado (atinge o ponto). QueryHitPoint pode ser substituído para testar acertos para objetos não retangulares.

COleControl::OnQueryHitRect

Chamado pela estrutura em resposta à solicitação IViewObjectEx::QueryHitRect de um contêiner.

virtual BOOL OnQueryHitRect(
    DWORD dwAspect,
    LPCRECT pRectBounds,
    LPCRECT prcLoc,
    LONG lCloseHint,
    DWORD* pHitResult);

Parâmetros

dwAspect
Especifica como o objeto deve ser representado. Os valores válidos são obtidos da enumeração DVASPECT ou DVASPECT2.

pRectBounds
Ponteiro para uma RECT estrutura que especifica o retângulo delimitador da área do cliente de controle OLE.

prcLoc
Ponteiro para a estrutura RECT que especifica o retângulo a ser verificado para um hit (sobreposição com o retângulo do objeto), em relação ao canto superior esquerdo do objeto.

lCloseHint
Não usado.

pHitResult
Ponteiro para o resultado da consulta de acerto. Um dos seguintes valores:

• HITRESULT_OUTSIDE nenhum ponto no retângulo é atingido pelo objeto OLE.

• HITRESULT_HIT pelo menos um ponto no retângulo seria um impacto no objeto.

Valor de retorno

Não zero se um resultado de ocorrência for retornado com êxito; caso contrário, 0.

Comentários

Consulta se o retângulo de exibição de um objeto se sobrepõe a qualquer ponto no retângulo fornecido (atinge o retângulo). QueryHitRect pode ser substituído para testar acertos para objetos não retangulares.

COleControl::OnRenderData

Chamado pela estrutura para recuperar dados no formato especificado.

virtual BOOL OnRenderData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium);

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC especificando o formato no qual as informações são solicitadas.

lpStgMedium
Aponta para uma estrutura STGMEDIUM na qual os dados devem ser retornados.

Valor de retorno

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

Comentários

O formato especificado é um colocado anteriormente no objeto de controle usando as funções de membro DelayRenderData ou DelayRenderFileData para renderização atrasada. A implementação padrão dessa função chama OnRenderFileData ou OnRenderGlobalData, respectivamente, se o meio de armazenamento fornecido for um arquivo ou memória. Se o formato solicitado for CF_METAFILEPICT ou o formato de conjunto de propriedades persistente, a implementação padrão renderizará os dados apropriados e retornará não zero. Caso contrário, ele retorna 0 e não faz nada.

Se lpStgMedium-tymed> for TYMED_NULL, o STGMEDIUM deverá ser alocado e preenchido conforme especificado por lpFormatEtc-tymed>. Se não for TYMED_NULL, STGMEDIUM deverá ser preenchido localmente com os dados.

Substitua essa função para fornecer seus dados no formato e no meio solicitados. Dependendo dos dados, talvez você queira substituir uma das outras versões dessa função. Se os dados forem pequenos e fixos em tamanho, substitua OnRenderGlobalData. Se os dados estiverem em um arquivo ou forem de tamanho variável, substitua OnRenderFileData.

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

COleControl::OnRenderFileData

Chamado pela estrutura para recuperar dados no formato especificado quando o meio de armazenamento for um arquivo.

virtual BOOL OnRenderFileData(
    LPFORMATETC lpFormatEtc,
    CFile* pFile);

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC especificando o formato no qual as informações são solicitadas.

pFile
Aponta para um objeto CFile no qual os dados devem ser renderizados.

Valor de retorno

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

Comentários

O formato especificado é um colocado anteriormente no objeto de controle usando a função de membro DelayRenderData para renderização atrasada. A implementação padrão dessa função simplesmente retorna FALSE.

Substitua essa função para fornecer seus dados no formato e no meio solicitados. Dependendo dos dados, talvez você queira substituir uma das outras versões dessa função. Se você quiser manipular vários meios de armazenamento, substitua OnRenderData. Se os dados estiverem em um arquivo ou forem de tamanho variável, substitua OnRenderFileData.

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

COleControl::OnRenderGlobalData

Chamado pela estrutura para recuperar dados no formato especificado quando o meio de armazenamento especificado for uma memória global.

virtual BOOL OnRenderGlobalData(
    LPFORMATETC lpFormatEtc,
    HGLOBAL* phGlobal);

Parâmetros

lpFormatEtc
Aponta para a estrutura FORMATETC especificando o formato no qual as informações são solicitadas.

phGlobal
Aponta para um identificador para a memória global na qual os dados devem ser retornados. Se nenhuma memória tiver sido alocada, esse parâmetro poderá ser NULL.

Valor de retorno

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

Comentários

O formato especificado é um colocado anteriormente no objeto de controle usando a função de membro DelayRenderData para renderização atrasada. A implementação padrão dessa função simplesmente retorna FALSE.

Se phGlobal for NULL, um novo HGLOBAL deverá ser alocado e retornado em phGlobal. Caso contrário, o HGLOBAL especificado pelo phGlobal deverá ser preenchido com os dados. A quantidade de dados colocados no HGLOBAL não pode exceder o tamanho atual do bloco de memória. Além disso, o bloco não pode ser realocado para um tamanho maior.

Substitua essa função para fornecer seus dados no formato e no meio solicitados. Dependendo dos dados, talvez você queira substituir uma das outras versões dessa função. Se você quiser manipular vários meios de armazenamento, substitua OnRenderData. Se os dados estiverem em um arquivo ou forem de tamanho variável, substitua OnRenderFileData.

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

COleControl::OnResetState

Chamado pela estrutura quando as propriedades do controle devem ser definidas como seus valores padrão.

virtual void OnResetState();

Comentários

A implementação padrão chama DoPropExchange, passando um CPropExchange objeto que faz com que as propriedades sejam definidas como seus valores padrão.

O gravador de controle pode inserir o código de inicialização para o controle OLE nesta substituição. Essa função é chamada quando IPersistStream::Load ou IPersistStorage::Load falha ou IPersistStreamInit::InitNew ou IPersistStorage::InitNew é chamado, sem chamar primeiro ou IPersistStream::LoadIPersistStorage::Load.

COleControl::OnSetClientSite

Chamado pela estrutura quando o contêiner chamou a função IOleControl::SetClientSite do controle.

virtual void OnSetClientSite();

Comentários

Por padrão, OnSetClientSite verifica se as propriedades do caminho de dados são carregadas e, se estiverem, as chamadas DoDataPathPropExchange.

Substitua essa função para fazer qualquer processamento especial desta notificação. Em particular, as substituições dessa função devem chamar a classe base.

COleControl::OnSetData

Chamado pela estrutura para substituir os dados do controle pelos dados especificados.

virtual BOOL OnSetData(
    LPFORMATETC lpFormatEtc,
    LPSTGMEDIUM lpStgMedium,
    BOOL bRelease);

Parâmetros

lpFormatEtc
Ponteiro para uma estrutura FORMATETC que especifica o formato dos dados.

lpStgMedium
Ponteiro para uma estrutura STGMEDIUM na qual os dados residem.

bRelease
TRUE se o controle deve liberar o meio de armazenamento; FALSE se o controle não deve liberar o meio de armazenamento.

Valor de retorno

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

Comentários

Se os dados estiverem no formato de conjunto de propriedades persistente, a implementação padrão modificará o estado do controle adequadamente. Caso contrário, a implementação padrão não fará nada. Se bRelease for TRUE, uma chamada para ReleaseStgMedium será feita; caso contrário, não.

Substitua essa função para substituir os dados do controle pelos dados especificados.

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

COleControl::OnSetExtent

Chamado pela estrutura quando a extensão do controle precisa ser alterada, como resultado de uma chamada para IOleObject::SetExtent.

virtual BOOL OnSetExtent(LPSIZEL lpSizeL);

Parâmetros

lpSizeL
Um ponteiro para a SIZEL estrutura que usa inteiros longos para representar a largura e a altura do controle, expressos em unidades HIMETRIC.

Valor de retorno

Não zero se a alteração de tamanho foi aceita; caso contrário, 0.

Comentários

A implementação padrão manipula o redimensionamento da extensão do controle. Se o controle estiver ativo in-loco, uma chamada para o contêiner OnPosRectChanged será feita.

Substitua essa função para alterar o redimensionamento padrão do controle.

COleControl::OnSetObjectRects

Chamado pela estrutura para implementar uma chamada para IOleInPlaceObject::SetObjectRects.

virtual BOOL OnSetObjectRects(
    LPCRECT lpRectPos,
    LPCRECT lpRectClip);

Parâmetros

lpRectPos
Um ponteiro para uma estrutura RECT que indica a nova posição e o tamanho do controle em relação ao contêiner.

lpRectClip
Um ponteiro para uma estrutura RECT que indica uma área retangular à qual o controle deve ser recortado.

Valor de retorno

Não zero se o repositório foi aceito; caso contrário, 0.

Comentários

A implementação padrão manipula automaticamente o reposicionamento e o redimensionamento da janela de controle e retorna TRUE.

Substitua essa função para alterar o comportamento padrão dessa função.

COleControl::OnShowToolBars

Chamado pela estrutura quando o controle foi ativado pela interface do usuário.

virtual void OnShowToolBars();

Comentários

A implementação padrão não tem ação.

COleControl::OnTextChanged

Chamado pela estrutura quando o valor da propriedade fonte de estoque foi alterado.

virtual void OnTextChanged();

Comentários

A implementação padrão chama InvalidateControl.

Substitua essa função se você quiser notificação depois que essa propriedade for alterada.

COleControl::OnWindowlessMessage

Chamado pela estrutura em resposta à solicitação IOleInPlaceObjectWindowless::OnWindowMessage de um contêiner.

virtual BOOL OnWindowlessMessage(
    UINT msg,
    WPARAM wParam,
    LPARAM lParam,
    LRESULT* plResult);

Parâmetros

msg
Identificador de mensagem conforme passado pelo Windows.

wParam
Conforme passado pelo Windows. Especifica informações adicionais específicas da mensagem. O conteúdo desse parâmetro depende do valor do parâmetro msg.

lParam
Conforme passado pelo Windows. Especifica informações adicionais específicas da mensagem. O conteúdo desse parâmetro depende do valor do parâmetro msg.

plResult
Código de resultado do Windows. Especifica o resultado do processamento da mensagem e depende da mensagem enviada.

Valor de retorno

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

Comentários

Processa as mensagens de janela para controles sem janelas. COleControl's OnWindowlessMessage devem ser usados para mensagens de janela que não sejam mensagens de mouse e mensagens de teclado. COleControl fornece SetCapture e SetFocus especificamente para obter a captura do mouse e o foco do teclado para objetos OLE sem janelas.

Como os objetos sem janela não têm uma janela, eles precisam de um mecanismo para permitir que o contêiner envie mensagens para eles. Um objeto OLE sem janelas obtém mensagens de seu contêiner, por meio do método OnWindowMessage na interface IOleInPlaceObjectWindowless (uma extensão de IOleInPlaceObject para suporte sem janelas). OnWindowMessage não assume um parâmetro HWND.

COleControl::ParentToClient

Converte as coordenadas do pPoint em coordenadas do cliente.

virtual UINT ParentToClient(
    LPCRECT lprcBounds,
    LPPOINT pPoint,
    BOOL bHitTest = FALSE) const;

Parâmetros

lprcBounds
Ponteiro para os limites do controle OLE dentro do contêiner. Não a área do cliente, mas a área de todo o controle, incluindo bordas e barras de rolagem.

pPoint
Ponteiro para o ponto pai (contêiner) a ser traduzido para as coordenadas da área do cliente do controle.

bHitTest
Especifica se o teste de ocorrência deve ou não ser feito no ponto.

Valor de retorno

Se bHitTest for FALSE, retornará HTNOWHERE. Se bHitTest for TRUE, retornará o local no qual o ponto pai (contêiner) pousou na área do cliente do controle OLE e será um dos seguintes valores de teste de ocorrência do mouse:

• HTBORDER Na borda de uma janela que não tem uma borda de dimensionamento.

• HTBOTTOM Na borda horizontal inferior da janela.

• HTBOTTOMLEFT No canto inferior esquerdo da borda da janela.

• HTBOTTOMRIGHT no canto inferior direito da borda da janela.

• HTCAPTION em uma área de barra de título.

• HTCLIENT em uma área de cliente.

• HTERROR na tela de fundo ou em uma linha divisória entre janelas (o mesmo que HTNOWHERE, exceto que a função Windows DefWndProc produz um bipe do sistema para indicar um erro).

• HTGROWBOX em uma caixa de tamanho.

• HTHSCROLL na barra de rolagem horizontal.

• HTLEFT na borda esquerda da janela.

• HTMAXBUTTON em um botão Maximizar.

• HTMENU em uma área de menu.

• HTMINBUTTON em um botão Minimizar.

• HTNOWHERE Na tela de fundo ou em uma linha divisória entre janelas.

• HTREDUCE em um botão Minimizar.

• HTRIGHT na borda direita da janela.

• HTSIZE em uma caixa de tamanho (o mesmo que HTGROWBOX).

• HTSYSMENU em um menu Controle ou em um botão Fechar em uma janela filho.

• HTTOP na borda horizontal superior da janela.

• HTTOPLEFT no canto superior esquerdo da borda da janela.

• HTTOPRIGHT no canto superior direito da borda da janela.

• HTTRANSPARENT Em uma janela atualmente coberta por outra janela.

• HTVSCROLL na barra de rolagem vertical.

• HTZOOM em um botão Maximizar.

Comentários

No pPoint de entrada é relativo à origem do pai (canto superior esquerdo do contêiner). Na saída pPoint é relativo à origem da área do cliente do controle OLE (canto superior esquerdo da área do cliente do controle).

COleControl::PostModalDialog

Notifica o contêiner de que uma caixa de diálogo modal foi fechada.

void PostModalDialog(HWND hWndParent = NULL);

Parâmetros

hWndParent
Manipule para a janela pai da caixa de diálogo modal.

Comentários

Chame essa função depois de exibir qualquer caixa de diálogo modal. Você deve chamar essa função para que o contêiner possa habilitar todas as janelas de nível superior desabilitadas por PreModalDialog. Essa função deve ser emparelhada com uma chamada para PreModalDialog.

COleControl::PreModalDialog

Notifica o contêiner de que uma caixa de diálogo modal está prestes a ser exibida.

void PreModalDialog(HWND hWndParent = NULL);

Parâmetros

hWndParent
Manipule para a janela pai da caixa de diálogo modal.

Comentários

Chame essa função antes de exibir qualquer caixa de diálogo modal. Você deve chamar essa função para que o contêiner possa desabilitar todas as janelas de nível superior. Depois que a caixa de diálogo modal for exibida, você deverá chamar PostModalDialog.

COleControl::RecreateControlWindow

Destrói e recria a janela do controle.

void RecreateControlWindow();

Comentários

Isso pode ser necessário se você precisar alterar os bits de estilo da janela.

COleControl::Refresh

Força uma repintação do controle OLE.

void Refresh();

Comentários

Essa função é compatível com a classe base COleControl como um método de estoque, chamado Refresh. Isso permite que os usuários do controle OLE repintem o controle em um momento específico. Para obter mais informações sobre esse método, consulte o artigo Controles ActiveX: Métodos.

COleControl::ReleaseCapture

Libera a captura do mouse.

BOOL ReleaseCapture();

Valor de retorno

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

Comentários

Se o controle tiver a captura do mouse no momento, a captura será liberada. Caso contrário, essa função não terá efeito.

COleControl::ReleaseDC

Libera o contexto do dispositivo de exibição de um contêiner de um controle sem janelas, liberando o contexto do dispositivo para uso por outros aplicativos.

int ReleaseDC(CDC* pDC);

Parâmetros

pDC
Identifica o contexto do dispositivo de contêiner a ser liberado.

Valor de retorno

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

Comentários

O aplicativo deve chamar ReleaseDC para cada chamada para GetDC.

COleControl::ReparentControlWindow

O pai deste controle.

virtual void ReparentControlWindow(
    HWND hWndOuter,
    HWND hWndParent);

Parâmetros

hWndOuter
O identificador da janela de controle.

hWndParent
O identificador da nova janela pai.

Comentários

Chame essa função para redefinir o pai da janela de controle.

COleControl::ResetStockProps

Inicializa o estado das propriedades de ações COleControl para seus valores padrão.

void ResetStockProps();

Comentários

As propriedades são: Appearance, BackColor, BorderStyle, Caption, Enabled, Font, ForeColor, hWnd e Text. Para obter uma descrição das propriedades de estoque, consulte Controles ActiveX: Adicionando propriedades de estoque.

Você pode melhorar o desempenho de inicialização binária de um controle usando ResetStockProps e ResetVersionsubstituindo COleControl::OnResetState. Veja o exemplo abaixo. Para obter mais informações sobre como otimizar a inicialização, consulte Controles ActiveX: Otimização.

Exemplo

void CMyAxCtrl::OnResetState()
{
   ResetVersion(MAKELONG(_wVerMinor, _wVerMajor));
   ResetStockProps();

   // initialize custom properties here
}

COleControl::ResetVersion

Inicializa o número de versão para o valor especificado.

void ResetVersion(DWORD dwVersionDefault);

Parâmetros

dwVersionDefault
O número de versão a ser atribuído ao controle.

Comentários

Você pode melhorar o desempenho de inicialização binária de um controle usando ResetVersion e ResetStockPropssubstituindo COleControl::OnResetState. Consulte o exemplo em ResetStockProps. Para obter mais informações sobre como otimizar a inicialização, consulte Controles ActiveX: Otimização.

COleControl::ScrollWindow

Permite que um objeto OLE sem janelas role uma área dentro de sua imagem ativa in-loco na tela.

void ScrollWindow(
    int xAmount,
    int yAmount,
    LPCRECT lpRect = NULL,
    LPCRECT lpClipRect = NULL);

Parâmetros

xAmount
Especifica a quantidade, em unidades de dispositivo, da rolagem horizontal. Esse parâmetro deve ser um valor negativo para rolar para a esquerda.

yAmount
Especifica a quantidade, em unidades de dispositivo, da rolagem horizontal. Esse parâmetro deve ser um valor negativo para rolar para cima.

lpRect
Aponta para um objeto CRect ou uma estrutura RECT que especifica a parte da área de cliente do objeto OLE a ser rolada, nas coordenadas do cliente da janela que contém. Se lpRect for NULL, toda a área de cliente do objeto OLE será rolada.

lpClipRect
Aponta para um objeto CRect ou estrutura RECT que especifica o retângulo de recorte a ser rolado. Somente pixels dentro do retângulo são rolados. Bits fora do retângulo não são afetados mesmo que estejam no retângulo lpRect . Se lpClipRect for NULL, nenhum recorte será executado no retângulo de rolagem.

COleControl::SelectFontObject

Seleciona uma fonte em um contexto de dispositivo.

CFont* SelectFontObject(
    CDC* pDC,
    CFontHolder& fontHolder);

Parâmetros

pDC
Ponteiro para um objeto de contexto de dispositivo.

fontHolder
Referência ao objeto CFontHolder que representa a fonte a ser selecionada.

Valor de retorno

Um ponteiro para a fonte selecionada anteriormente. Quando o chamador tiver terminado todas as operações de desenho que usam fontHolder, ele deverá reelecionar a fonte selecionada anteriormente passando-a como um parâmetro para CDC::SelectObject.

COleControl::SelectStockFont

Seleciona a propriedade fonte de estoque em um contexto de dispositivo.

CFont* SelectStockFont(CDC* pDC);

Parâmetros

pDC
O contexto do dispositivo no qual a fonte será selecionada.

Valor de retorno

Um ponteiro para o objeto CFont selecionado anteriormente. Você deve usar CDC::SelectObject para selecionar essa fonte novamente no contexto do dispositivo quando terminar.

COleControl::SerializeExtent

Serializa ou inicializa o estado do espaço de exibição alocado ao controle.

void SerializeExtent(CArchive& ar);

Parâmetros

ar
Um objeto CArchive do qual, ou para o qual serializar.

Comentários

Você pode melhorar o desempenho de persistência binária de um controle usando SerializeExtent, SerializeStockProps e SerializeVersion para substituir COleControl::Serialize. Veja o exemplo abaixo. Para obter mais informações sobre como otimizar a inicialização, consulte Controles ActiveX: Otimização.

Exemplo

void CMyAxCtrl::Serialize(CArchive &ar)
{
   SerializeVersion(ar, MAKELONG(_wVerMinor, _wVerMajor));
   SerializeExtent(ar);
   SerializeStockProps(ar);

   if (ar.IsStoring())
   { // storing code
   }
   else
   { // loading code
   }
}

COleControl::SerializeStockProps

Serializa ou inicializa o estado das propriedades de COleControl estoque: Aparência, BackColor, BorderStyle, Caption, Enabled, Font, ForeColor e Text.

void SerializeStockProps(CArchive& ar);

Parâmetros

ar
Um objeto CArchive do qual, ou para o qual serializar.

Comentários

Para obter uma descrição das propriedades de estoque, consulte Controles ActiveX: Adicionando propriedades de estoque.

Você pode melhorar o desempenho de persistência binária de um controle usando SerializeStockProps, SerializeExtent e SerializeVersion para substituir COleControl::Serialize. Para obter um exemplo, consulte o código em SerializeExtent. Para obter mais informações sobre como otimizar a inicialização, consulte Controles ActiveX: Otimização.

COleControl::SerializeVersion

Serializa ou inicializa o estado das informações de versão de um controle.

DWORD SerializeVersion(
    CArchive& ar,
    DWORD dwVersionDefault,
    BOOL bConvert = TRUE);

Parâmetros

ar
Um objeto CArchive do qual, ou para o qual serializar.

dwVersionDefault
O número de versão atual do controle.

bConvert
Indica se os dados persistentes devem ser convertidos no formato mais recente quando são salvos ou mantidos no mesmo formato que tinham quando foram carregados.

Valor de retorno

O número de versão do controle. Se o arquivo especificado estiver carregando, SerializeVersion retornará a versão carregada desse arquivo. Caso contrário, ele retornará a versão carregada no momento.

Comentários

Você pode melhorar o desempenho de persistência binária de um controle usando SerializeVersion, SerializeExtent e SerializeStockProps para substituir COleControl::Serialize. Para obter um exemplo, consulte o código em SerializeExtent. Para obter mais informações sobre como otimizar a inicialização, consulte Controles ActiveX: Otimização.

COleControl::SetAppearance

Define o valor da propriedade Aparência de estoque do seu controle.

void SetAppearance (short sAppearance);

Parâmetros

sAppearance
Um short valor (VT_I2) a ser usado para a aparência do controle. Um valor zero define a aparência do controle como simples e um valor de 1 define a aparência do controle como 3D.

Comentários

Para obter mais informações sobre propriedades de estoque, consulte Controles ActiveX: Propriedades.

COleControl::SetBackColor

Define o valor da propriedade BackColor do estoque do seu controle.

void SetBackColor(OLE_COLOR dwBackColor);

Parâmetros

dwBackColor
Um valor OLE_COLOR a ser usado para desenho em segundo plano do controle.

Comentários

Para obter mais informações sobre como usar essa propriedade e outras propriedades relacionadas, consulte o artigo Controles ActiveX: Propriedades.

COleControl::SetBorderStyle

Define o valor da propriedade BorderStyle de estoque do seu controle.

void SetBorderStyle(short sBorderStyle);

Parâmetros

sBorderStyle
O novo estilo de borda para o controle; 0 indica nenhuma borda e 1 indica uma borda normal.

Comentários

Em seguida, a janela de controle será recriada e OnBorderStyleChanged chamada.

COleControl::SetCapture

Faz com que a janela de contêiner do controle assuma a posse da captura do mouse em nome do controle.

CWnd* SetCapture();

Valor de retorno

Um ponteiro para o objeto de CWnd janela que recebeu anteriormente a entrada do mouse.

Comentários

Se o controle estiver ativado e sem janelas, essa função fará com que a janela do contêiner do controle assuma a posse da captura do mouse, em nome do controle. Caso contrário, essa função faz com que o próprio controle assuma a posse da captura do mouse (o mesmo que CWnd::SetCapture).

COleControl::SetControlSize

Define o tamanho da janela de controle OLE e notifica o contêiner que o site de controle está alterando.

BOOL SetControlSize(int cx, int cy);

Parâmetros

cx
Especifica a nova largura do controle em pixels.

Cy
Especifica a nova altura do controle em pixels.

Valor de retorno

Diferente de zero se a chamada foi bem-sucedida, caso contrário, retornará 0.

Comentários

Essa função não deve ser usada no construtor do controle.

Observe que todas as coordenadas para janelas de controle são relativas ao canto superior esquerdo do controle.

COleControl::SetEnabled

Define o valor da propriedade habilitada para ações do controle.

void SetEnabled(BOOL bEnabled);

Parâmetros

bEnabled
TRUE se o controle for habilitado; caso contrário, FALSE.

Comentários

Depois de definir essa propriedade, OnEnabledChange é chamado.

COleControl::SetFocus

Faz com que a janela de contêiner do controle assuma a posse do foco de entrada em nome do controle.

CWnd* SetFocus();

Valor de retorno

Um ponteiro para o objeto de janela CWnd que anteriormente tinha o foco de entrada ou NULL se não houver essa janela.

Comentários

Se o controle estiver ativado e sem janelas, essa função fará com que a janela de contêiner do controle assuma a posse do foco de entrada, em nome do controle. O foco de entrada direciona a entrada do teclado para a janela do contêiner e o contêiner envia todas as mensagens de teclado subsequentes para o objeto OLE que chama SetFocus. Qualquer janela que anteriormente tinha o foco de entrada a perde.

Se o controle não estiver sem janelas, essa função fará com que o próprio controle assuma a posse do foco de entrada (o mesmo que CWnd::SetFocus).

COleControl::SetFont

Define a propriedade fonte de estoque do controle.

void SetFont(LPFONTDISP pFontDisp);

Parâmetros

pFontDisp
Um ponteiro para uma interface de expedição de fonte.

COleControl::SetForeColor

Define o valor da propriedade ForeColor de estoque do seu controle.

void SetForeColor(OLE_COLOR dwForeColor);

Parâmetros

dwForeColor
Um valor OLE_COLOR a ser usado para desenho em primeiro plano do controle.

Comentários

Para obter mais informações sobre como usar essa propriedade e outras propriedades relacionadas, consulte o artigo Controles ActiveX: Propriedades.

COleControl::SetInitialDataFormats

Chamado pela estrutura para inicializar a lista de formatos de dados compatíveis com o controle.

virtual void SetInitialDataFormats();

Comentários

A implementação padrão especifica dois formatos: CF_METAFILEPICT e o conjunto de propriedades persistentes.

COleControl::SetInitialSize

Define o tamanho de um controle OLE quando exibido pela primeira vez em um contêiner.

void SetInitialSize(
    int cx,
    int cy);

Parâmetros

cx
A largura inicial do controle OLE em pixels.

Cy
A altura inicial do controle OLE em pixels.

Comentários

Chame essa função no construtor para definir o tamanho inicial do controle. O tamanho inicial é medido em unidades de dispositivo ou pixels. É recomendável que essa chamada seja feita no construtor do controle.

COleControl::SetModifiedFlag

Altera o estado modificado de um controle.

void SetModifiedFlag(BOOL bModified = TRUE);

Parâmetros

bModified
O novo valor para o sinalizador modificado do controle. TRUE indica que o estado do controle foi modificado; FALSE indica que o estado do controle acabou de ser salvo.

Comentários

Chame essa função sempre que ocorrer uma alteração que afete o estado persistente do controle. Por exemplo, se o valor de uma propriedade persistente for alterado, chame essa função com bModified TRUE.

COleControl::SetNotPermitted

Indica que uma solicitação de edição falhou.

void SetNotPermitted();

Comentários

Chame essa função quando BoundPropertyRequestEdit falhar. Essa função gera uma exceção de tipo COleDispScodeException para indicar que a operação de conjunto não foi permitida.

COleControl::SetNotSupported

Impede a modificação do valor da propriedade de um controle pelo usuário.

void SetNotSupported();

Comentários

Chame essa função no lugar da função Get de qualquer propriedade em que não há suporte para a recuperação da propriedade pelo usuário do controle. Um exemplo seria uma propriedade que é somente gravação.

COleControl::SetRectInContainer

Define as coordenadas do retângulo do controle em relação ao contêiner, expresso em unidades de dispositivo.

BOOL SetRectInContainer(LPCRECT lpRect);

Parâmetros

lpRect
Um ponteiro para um retângulo que contém as novas coordenadas do controle em relação ao contêiner.

Valor de retorno

Diferente de zero se a chamada foi bem-sucedida, caso contrário, retornará 0.

Comentários

Se o controle estiver aberto, ele será redimensionado; caso contrário, a função OnPosRectChanged do contêiner é chamada.

COleControl::SetText

Define o valor da propriedade Legenda ou Texto do seu controle.

void SetText(LPCTSTR pszText);

Parâmetros

pszText
Um ponteiro para uma cadeia de caracteres.

Comentários

Observe que as propriedades Legenda e Texto de ações são mapeadas para o mesmo valor. Isso significa que todas as alterações feitas em qualquer propriedade alterarão automaticamente ambas as propriedades. Em geral, um controle deve dar suporte à propriedade Legenda ou Texto de ações, mas não a ambos.

COleControl::ThrowError

Sinaliza a ocorrência de um erro em seu controle.

void ThrowError(
    SCODE sc,
    UINT nDescriptionID,
    UINT nHelpID = -1);

void ThrowError(
    SCODE sc,
    LPCTSTR pszDescription = NULL,
    UINT nHelpID = 0);

Parâmetros

sc
O valor do código de status a ser relatado. Para obter uma lista completa de códigos possíveis, consulte o artigo Controles ActiveX: Tópicos Avançados.

nDescriptionID
A ID do recurso de cadeia de caracteres da exceção a ser relatada.

nHelpID
A ID de ajuda do tópico a ser relatado.

pszDescription
Uma cadeia de caracteres que contém uma explicação da exceção a ser relatada.

Comentários

Essa função só deve ser chamada de dentro de uma função Get ou Set para uma propriedade OLE ou a implementação de um método de automação OLE. Se você precisar sinalizar erros que ocorrem em outras ocasiões, dispare o evento erro de estoque.

COleControl::TransformCoords

Transforma valores de coordenadas entre unidades HIMETRIC e as unidades nativas do contêiner.

void TransformCoords(
    POINTL* lpptlHimetric,
    POINTF* lpptfContainer,
    DWORD flags);

Parâmetros

lpptlHimetric
Ponteiro para uma estrutura POINTL que contém coordenadas em unidades HIMETRIC.

lpptfContainer
Ponteiro para uma estrutura POINTF que contém coordenadas no tamanho da unidade do contêiner.

sinalizadores
Uma combinação dos seguintes valores:

• XFORMCOORDS_POSITION Uma posição no contêiner.

• XFORMCOORDS_SIZE Um tamanho no contêiner.

• XFORMCOORDS_HIMETRICTOCONTAINER Transformar unidades HIMETRIC nas unidades do contêiner.

• XFORMCOORDS_CONTAINERTOHIMETRIC Transformar as unidades do contêiner em unidades HIMETRIC.

Comentários

Os dois primeiros sinalizadores, XFORMCOORDS_POSITION e XFORMCOORDS_SIZE, indicam se as coordenadas devem ser tratadas como uma posição ou um tamanho. Os dois sinalizadores restantes indicam a direção da transformação.

COleControl::TranslateColor

Converte um valor de cor do tipo de dados OLE_COLOR para o tipo de dados COLORREF.

COLORREF TranslateColor(
    OLE_COLOR clrColor,
    HPALETTE hpal = NULL);

Parâmetros

clrColor
Um tipo de dados OLE_COLOR. Para obter mais informações, confira a função OleTranslateColor do Windows.

hpal
Um identificador para uma paleta opcional; pode ser NULL.

Valor de retorno

Um valor de cor RGB (vermelho, verde, azul) de 32 bits que define a cor sólida mais próxima do valor clrColor que o dispositivo pode representar.

Comentários

Essa função é útil para traduzir as propriedades ForeColor e BackColor de estoque para tipos COLORREF usados pelas funções de membro CDC.

COleControl::WillAmbientsBeValidDuringLoad

Determina se o controle deve usar os valores das propriedades de ambiente como valores padrão, quando ele é carregado posteriormente de seu estado persistente.

BOOL WillAmbientsBeValidDuringLoad();

Valor de retorno

Nonzero indica que as propriedades de ambiente serão válidas; caso contrário, as propriedades de ambiente não serão válidas.

Comentários

Em alguns contêineres, o controle pode não ter acesso às suas propriedades de ambiente durante a chamada inicial para a substituição de COleControl::DoPropExchange. Esse é o caso se o contêiner chamar IPersistStreamInit::Load ou IPersistStorage::Load antes de chamar IOleObject::SetClientSite (ou seja, se ele não honrar o bit de status OLEMISC_SETCLIENTSITEFIRST).

COleControl::WindowProc

Fornece um procedimento do Windows para um objeto COleControl.

virtual LRESULT WindowProc(
    UINT message,
    WPARAM wParam,
    LPARAM lParam);

Parâmetros

message
Especifica a mensagem do Windows a ser processada.

wParam
Fornece informações adicionais usadas no processamento da mensagem. O valor desse parâmetro depende da mensagem.

lParam
Fornece informações adicionais usadas no processamento da mensagem. O valor desse parâmetro depende da mensagem.

Valor de retorno

O valor retornado da mensagem expedida.

Comentários

Chame essa função para despachar mensagens específicas por meio do mapa de mensagens do controle.

Confira também

Exemplo do MFC CIRC3
TESTHELP de exemplo do MFC
Classe COlePropertyPage
Classe CWnd
Gráfico da hierarquia
Classe CFontHolder
Classe CPictureHolder