Partilhar via


Mapas de evento

Sempre que um controle quiser notificar seu contêiner de que alguma ação (determinada pelo desenvolvedor de controle) ocorreu (como um pressionamento de teclas, um clique do mouse ou uma alteração no estado do controle), ele chama uma função de disparo de evento. Essa função notifica o contêiner de controle de que alguma ação importante ocorreu disparando o evento relacionado.

A Biblioteca Microsoft Foundation Class oferece um modelo de programação otimizado para disparar eventos. Nesse modelo, "mapas de eventos" são usados para designar quais funções disparam quais eventos para um controle específico. Os mapas de eventos contêm uma macro para cada evento. Por exemplo, um mapa de eventos que dispara um evento de clique de estoque pode ter esta aparência:

BEGIN_EVENT_MAP(CMyAxCtrl, COleControl)
EVENT_STOCK_CLICK()
END_EVENT_MAP()

A macro EVENT_STOCK_CLICK indica que o controle disparará um evento de clique de estoque sempre que detectar um clique do mouse. Para obter uma listagem mais detalhada de outros eventos de ações, consulte o artigo Controles ActiveX: eventos. As macros também estão disponíveis para indicar eventos personalizados.

Embora as macros de mapa de eventos sejam importantes, geralmente você não as insere diretamente. Isso ocorre porque a janela Propriedades (no Modo de Exibição de Classe) cria automaticamente entradas de mapa de eventos em seus arquivos de origem quando você a usa para associar funções de disparo de eventos a eventos. Sempre que quiser editar ou adicionar uma entrada de mapa de eventos, você pode usar a janela Propriedades.

Para dar suporte a mapas de eventos, o MFC fornece as seguintes macros:

Macros de mapa de eventos

Declaração e demarcação do mapa de eventos

Nome Descrição
DECLARE_EVENT_MAP Declara que um mapa de eventos será usado em uma classe para mapear eventos para funções de disparo de eventos (deve ser usado na declaração de classe).
BEGIN_EVENT_MAP Inicia a definição de um mapa de eventos (deve ser usado na implementação da classe).
END_EVENT_MAP Encerra a definição de um mapa de eventos (deve ser usado na implementação da classe).

Macros de mapeamento de eventos

Nome Descrição
EVENT_CUSTOM Indica qual função de disparo de evento disparará o evento especificado.
EVENT_CUSTOM_ID Indica qual função de disparo de evento disparará o evento especificado, com uma ID de expedição designada.

Macros de mapeamento de mensagem

Nome Descrição
ON_OLEVERB Indica um verbo personalizado manipulado pelo controle OLE.
ON_STDOLEVERB Substitui um mapeamento de verbo padrão do controle OLE.

DECLARE_EVENT_MAP

Cada classe derivada de COleControl em seu programa pode fornecer um mapa de eventos para especificar os eventos que seu controle será acionado.

DECLARE_EVENT_MAP()

Comentários

Use a macro DECLARE_EVENT_MAP no final da declaração de classe. Em seguida, no arquivo .cpp que define as funções de membro para a classe, use a macro BEGIN_EVENT_MAP, as entradas de macro para cada um dos eventos do controle e a macro END_EVENT_MAP para declarar o final da lista de eventos.

Para obter mais informações sobre mapas de eventos, consulte o artigo Controles ActiveX: eventos.

Requisitos

Cabeçalho afxctl.h

BEGIN_EVENT_MAP

Inicia a definição do mapa de eventos.

BEGIN_EVENT_MAP(theClass,  baseClass)

Parâmetros

theClass
Especifica o nome da classe de controle cujo mapa de eventos é esse.

baseClass
Especifica o nome da classe base de theClass.

Comentários

No arquivo de implementação (.cpp) que define as funções de membro para sua classe, inicie o mapa de eventos com a macro BEGIN_EVENT_MAP, adicione entradas de macro para cada um dos eventos e conclua o mapa de eventos com a macro END_EVENT_MAP.

Para obter mais informações sobre mapas de eventos e a macro BEGIN_EVENT_MAP, consulte o artigo Controles ActiveX: eventos.

Requisitos

Cabeçalho afxctl.h

END_EVENT_MAP

Use a macro END_EVENT_MAP para encerrar a definição do mapa de eventos.

END_EVENT_MAP()

Requisitos

Cabeçalho afxctl.h

EVENT_CUSTOM

Define uma entrada de mapa de eventos para um evento personalizado.

EVENT_CUSTOM(pszName, pfnFire,  vtsParams)

Parâmetros

pszName
O nome do evento.

pfnFire
O nome da função de disparo de evento.

vtsParams
Uma lista separada por espaço de uma ou mais constantes que especificam a lista de parâmetros da função.

Comentários

O parâmetro vtsParams é uma lista de valores separados por espaço das constantes VTS_. Um ou mais desses valores separados por espaços (não vírgulas) especifica a lista de parâmetros da função. Por exemplo:

VTS_COLOR VTS_FONT

especifica uma lista que contém um inteiro de 32 bits que representa um valor de cor RGB, seguido por um ponteiro para a interface IFontDisp de um objeto de fonte OLE.

As constantes VTS_ e seus significados são os seguintes:

Símbolo Tipo de parâmetro
VTS_I2 short
VTS_I4 long
VTS_R4 float
VTS_R8 double
VTS_COLOR OLE_COLOR
VTS_CY MOEDA
VTS_DATE DATE
VTS_BSTR constqueimar*
VTS_DISPATCH LPDISPATCH
VTS_FONT IFontDispatch*
VTS_HANDLE HANDLE
VTS_SCODE SCODE
VTS_BOOL BOOL
VTS_VARIANT const VARIANT*
VTS_PVARIANT VARIANT*
VTS_UNKNOWN LPUNKNOWN
VTS_OPTEXCLUSIVE OLE_OPTEXCLUSIVE
VTS_PICTURE IPictureDisp*
VTS_TRISTATE OLE_TRISTATE
VTS_XPOS_PIXELS OLE_XPOS_PIXELS
VTS_YPOS_PIXELS OLE_YPOS_PIXELS
VTS_XSIZE_PIXELS OLE_XSIZE_PIXELS
VTS_YSIZE_PIXELS OLE_YSIZE_PIXELS
TS_XPOS_HIMETRIC OLE_XPOS_HIMETRIC
VTS_YPOS_HIMETRIC OLE_YPOS_HIMETRIC
VTS_XSIZE_HIMETRIC OLE_XSIZE_HIMETRIC
VTS_YSIZE_HIMETRIC OLE_YSIZE_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_Pconstantname. Por exemplo, VTS_PCOLOR é um ponteiro para uma constante VTS_COLOR.

Requisitos

Cabeçalho afxctl.h

EVENT_CUSTOM_ID

Define uma função de disparo de evento para um evento personalizado que pertence à ID de expedição especificada por dispid.

EVENT_CUSTOM_ID(
    pszName,
    dispid,
    pfnFire,
    vtsParams)

Parâmetros

pszName
O nome do evento.

dispid
A ID de expedição usada pelo controle ao disparar o evento.

pfnFire
O nome da função de disparo de evento.

vtsParams
Uma lista variável de parâmetros passados para o contêiner de controle quando o evento é acionado.

Comentários

O argumento vtsParams é uma lista de valores separados por espaço das constantes VTS_. Um ou mais desses valores separados por espaços, não vírgulas, especifica a lista de parâmetros da função. Por exemplo:

VTS_COLOR VTS_FONT

especifica uma lista que contém um inteiro de 32 bits que representa um valor de cor RGB, seguido por um ponteiro para a interface IFontDisp de um objeto de fonte OLE.

Para obter uma lista das constantes VTS_, consulte EVENT_CUSTOM.

Requisitos

Cabeçalho afxctl.h

ON_OLEVERB

Essa macro define uma entrada de mapa de mensagem que mapeia um verbo personalizado para uma função de membro específica do controle.

ON_OLEVERB(idsVerbName,  memberFxn)

Parâmetros

idsVerbName
A ID do recurso de cadeia de caracteres do nome do verbo.

memberFxn
A função chamada pela estrutura quando o verbo é invocado.

Comentários

O editor de recursos pode ser usado para criar nomes de verbo personalizados adicionados à tabela de cadeia de caracteres.

O protótipo de função para memberFxn é:

BOOL memberFxn(
   LPMSG    lpMsg,
   HWND     hWndParent,
   LPCRECT  lpRect);

Os valores dos parâmetros lpMsg, hWndParent e lpRect são obtidos dos parâmetros correspondentes da função de membro IOleObject::DoVerb.

Requisitos

Cabeçalho: afxole.h

ON_STDOLEVERB

Use essa macro para substituir o comportamento padrão de um verbo padrão.

ON_STDOLEVERB(iVerb, memberFxn)

Parâmetros

iVerb
O índice de verbo padrão para o verbo que está sendo substituído.

memberFxn
A função chamada pela estrutura quando o verbo é invocado.

Comentários

O índice de verbo padrão é do formulário OLEIVERB_, seguido por uma ação. OLEIVERB_SHOW, OLEIVERB_HIDE e OLEIVERB_UIACTIVATE são alguns exemplos de verbos padrão.

Consulte ON_OLEVERB para obter uma descrição do protótipo de função a ser usado como o parâmetro memberFxn.

Requisitos

Cabeçalho: afxole.h

Confira também

Macros e Globais