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