Mapas de eventos

  • Artículo

Cada vez que un control desea notificar a su contenedor que se ha producido alguna acción (determinada por el desarrollador del control) (como una pulsación de tecla, un clic del mouse o un cambio en el estado del control), llama a una función de activación de eventos. Esta función notifica al contenedor de control que se ha producido alguna acción importante activando el evento relacionado.

La biblioteca de clases de Microsoft Foundation ofrece un modelo de programación optimizado para el lanzamiento de eventos. En este modelo, se usan «asignaciones de eventos» para designar qué funciones se activan qué eventos para un control determinado. Los mapas de eventos contienen una macro para cada evento. Por ejemplo, un mapa de eventos que activa un evento Click de stock podría tener este aspecto:

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

La macro EVENT_STOCK_CLICK indica que el control activará un evento Click de stock cada vez que detecte un clic del mouse. Para obtener una lista más detallada de otros eventos de existencias, consulta el artículo Controles ActiveX: Eventos. Las macros también están disponibles para indicar eventos personalizados.

Aunque las macros de mapa de eventos son importantes, por lo general no las inserta directamente. Esto se debe a que la ventana de propiedades (en la Vista de clase) crea automáticamente entradas de asignación de eventos en tus archivos fuente cuando la utilizas para asociar funciones de disparo de eventos con eventos. Siempre que desees editar o agregar una entrada de mapa de mensajes, puedes utilizar la ventana Propiedades.

Para admitir mapas de eventos, MFC proporciona las siguientes macros:

Macros de asignación de eventos

Declaración y demarcación de la asignación de eventos

Nombre Descripción
DECLARE_EVENT_MAP Declara que se usará un mapa de eventos en una clase para asignar eventos a funciones de activación de eventos (se deben usar en la declaración de clase).
BEGIN_EVENT_MAP Comienza la definición de una asignación de mensajes (debe usarse en la implementación de la clase).
END_EVENT_MAP Finaliza la definición de una asignación de mensajes (debe usarse en la implementación de la clase).

Macros de asignación de eventos

Nombre Descripción
EVENT_CUSTOM Indica qué función de activación de eventos activará el evento especificado.
EVENT_CUSTOM_ID Indica qué función de activación de eventos activará el evento especificado, con un identificador de envío designado.

Macros de asignación de mensajes

Nombre Descripción
ON_OLEVERB Indica un verbo personalizado controlado por el control OLE.
ON_STDOLEVERB Invalida una asignación de verbos estándar del control OLE.

DECLARE_EVENT_MAP

Cada clase COleControl derivada del programa puede proporcionar una asignación de eventos para especificar los eventos que desencadenará tu control.

DECLARE_EVENT_MAP()

Comentarios

Usa la macro DECLARE_DISPATCH_MAP al final de tu declaración de clase. A continuación, en el archivo .cpp que define las funciones miembro de la clase, usa la macro BEGIN_EVENT_MAP, las entradas de macro para cada uno de los eventos del control y la macro END_EVENT_MAP para declarar el final de la lista de eventos.

Para obtener más información sobre los mapas de eventos, consulta el artículo Controles ActiveX: Eventos.

Requisitos

Encabezado: afxctl.h

BEGIN_EVENT_MAP

Comienza la definición de la asignación de eventos de mensajes.

BEGIN_EVENT_MAP(theClass,  baseClass)

Parámetros

theClass
Especifica el nombre de la clase de control cuyo mapa de eventos es.

baseClass
Especifica el nombre de clase base de theClass.

Comentarios

En el archivo de implementación (.cpp) que define las funciones miembro de la clase, inicia el mapa de eventos con la macro BEGIN_EVENT_MAP, agrega entradas de macro para cada uno de los eventos y complete el mapa de eventos con la macro END_EVENT_MAP.

Para obtener más información sobre las asignaciones de eventos y la macro BEGIN_EVENT_MAP, consulte el artículo Controles ActiveX: Eventos.

Requisitos

Encabezado: afxctl.h

END_EVENT_MAP

Usa la macro END_EVENT_MAP para finalizar la definición de la asignación de eventos.

END_EVENT_MAP()

Requisitos

Encabezado: afxctl.h

EVENT_CUSTOM

Define una entrada de asignación de eventos para un evento personalizado.

EVENT_CUSTOM(pszName, pfnFire,  vtsParams)

Parámetros

pszName
El nombre del evento.

pfnFire
Nombre de la función de activación de eventos.

vtsParams
Lista separada por espacios de una o varias constantes que especifican la lista de parámetros de la función.

Comentarios

El parámetro vtsParams es una lista separada por espacios de valores de las constantes VTS_. Uno o varios de estos valores, separados por espacios (no por comas), especifican la lista de parámetros de la función. Por ejemplo:

VTS_COLOR VTS_FONT

especifica una lista que contiene un entero de 32 bits que representa un valor de color RGB, seguido de un puntero a la interfaz IFontDisp de un objeto de fuente OLE.

A continuación se indican las constantes VTS_ y el significado de cada una de ellas:

Símbolo Parameter type (Tipo de parámetro)
VTS_I2 short
VTS_I4 long
VTS_R4 float
VTS_R8 double
VTS_COLOR OLE_COLOR
VTS_CY DIVISA
VTS_DATE DATE
VTS_BSTR constchar*
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

Nota:

Se han definido constantes variant adicionales para todos los tipos de variante, excepto VTS_FONT y VTS_PICTURE, que proporcionan un puntero a la constante de datos variant. A estas constantes se les asigna un nombre mediante la convención VTS_Pconstantname. Por ejemplo, VTS_PCOLOR es un puntero a una constante VTS_COLOR.

Requisitos

Encabezado: afxctl.h

EVENT_CUSTOM_ID

Define una función de activación de eventos para un evento personalizado que pertenece al identificador de envío especificado por dispid.

EVENT_CUSTOM_ID(
    pszName,
    dispid,
    pfnFire,
    vtsParams)

Parámetros

pszName
El nombre del evento.

dispid
Identificador de distribución utilizado por el control al activar el evento.

pfnFire
Nombre de la función de activación de eventos.

vtsParams
Lista variable de parámetros pasados al contenedor de control cuando se desencadena el evento.

Comentarios

El argumento vtsParams es una lista separada por espacios de valores de las constantes VTS_. Uno o varios de estos valores, separados por espacios (no por comas), especifican la lista de parámetros de la función. Por ejemplo:

VTS_COLOR VTS_FONT

especifica una lista que contiene un entero de 32 bits que representa un valor de color RGB, seguido de un puntero a la interfaz IFontDisp de un objeto de fuente OLE.

Para obtener una lista de las VTS_ constantes, consulte EVENT_CUSTOM.

Requisitos

Encabezado: afxctl.h

ON_OLEVERB

Esta macro define una entrada de mapa de mensajes que asigna un verbo personalizado a una función miembro específica del control.

ON_OLEVERB(idsVerbName,  memberFxn)

Parámetros

idsVerbName
Identificador de recurso de cadena del nombre del verbo.

memberFxn
Función a la que llama el marco cuando se invoca el verbo.

Comentarios

El editor de recursos se puede usar para crear nombres de verbo personalizados que se agregan a la tabla de cadenas.

El prototipo de función para memberFxn es:

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

Los valores de los parámetros lpMsg, hWndParent y lpRect se toman de los parámetros correspondientes de la IOleObject::DoVerb función miembro.

Requisitos

Encabezado afxole.h

ON_STDOLEVERB

Usa esta macro para invalidar el comportamiento predeterminado de un verbo estándar.

ON_STDOLEVERB(iVerb, memberFxn)

Parámetros

iVerb
Índice de verbo estándar para el verbo que se va a invalidar.

memberFxn
Función a la que llama el marco cuando se invoca el verbo.

Comentarios

El índice de verbo estándar tiene el formato OLEIVERB_, seguido de una acción. OLEIVERB_SHOW, OLEIVERB_HIDE y OLEIVERB_UIACTIVATE son algunos ejemplos de verbos estándar.

Consulta ON_OLEVERB para obtener una descripción del prototipo de función que se va a usar como parámetro memberFxn.

Requisitos

Encabezado afxole.h

Consulte también

Macros y globales