Event Maps

 

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at Event Maps.

Whenever a control wishes to notify its container that some action (determined by the control developer) has happened (such as a keystroke, mouse click, or a change to the control's state) it calls an event-firing function. This function notifies the control container that some important action has occurred by firing the related event.

The Microsoft Foundation Class Library offers a programming model optimized for firing events. In this model, "event maps" are used to designate which functions fire which events for a particular control. Event maps contain one macro for each event. For example, an event map that fires a stock Click event might look like this:

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

The EVENT_STOCK_CLICK macro indicates that the control will fire a stock Click event every time it detects a mouse click. For a more detailed listing of other stock events, see the article ActiveX Controls: Events. Macros are also available to indicate custom events.

Although event-map macros are important, you generally do not insert them directly. This is because the Properties window automatically creates event-map entries in your source files when you use it to associate event-firing functions with events. Any time you want to edit or add an event-map entry, you can use the Properties window.

To support event maps, MFC provides the following macros:

Event Map Declaration and Demarcation

DECLARE_EVENT_MAPDeclares that an event map will be used in a class to map events to event-firing functions (must be used in the class declaration).
BEGIN_EVENT_MAPBegins the definition of an event map (must be used in the class implementation).
END_EVENT_MAPEnds the definition of an event map (must be used in the class implementation).

Event Mapping Macros

EVENT_CUSTOMIndicates which event-firing function will fire the specified event.
EVENT_CUSTOM_IDIndicates which event-firing function will fire the specified event, with a designated dispatch ID.

Message Mapping Macros

ON_OLEVERBIndicates a custom verb handled by the OLE control.
ON_STDOLEVERBOverrides a standard verb mapping of the OLE control.

Each COleControl-derived class in your program can provide an event map to specify the events your control will fire.

DECLARE_EVENT_MAP()   

Remarks

Use the DECLARE_EVENT_MAP macro at the end of your class declaration. Then, in the .cpp file that defines the member functions for the class, use the BEGIN_EVENT_MAP macro, macro entries for each of the control's events, and the END_EVENT_MAP macro to declare the end of the event list.

For more information on event maps, see the article ActiveX Controls: Events.

Begins the definition of your event map.

BEGIN_EVENT_MAP(theClass,  baseClass)  

Parameters

theClass
Specifies the name of the control class whose event map this is.

baseClass
Specifies the name of the base class of theClass.

Remarks

In the implementation (.cpp) file that defines the member functions for your class, start the event map with the BEGIN_EVENT_MAP macro, then add macro entries for each of your events, and complete the event map with the END_EVENT_MAP macro.

For more information on event maps and the BEGIN_EVENT_MAP macro, see the article ActiveX Controls: Events.

Use the END_EVENT_MAP macro to end the definition of your event map.

END_EVENT_MAP()   

Defines an event-map entry for a custom event.

EVENT_CUSTOM(pszName, pfnFire,  vtsParams) 

Parameters

pszName
The name of the event.

pfnFire
The name of the event firing function.

vtsParams
A space-separated list of one or more constants specifying the function's parameter list.

Remarks

The vtsParams parameter is a space-separated list of values from the VTS_ constants. One or more of these values separated by spaces (not commas) specifies the function's parameter list. For example:

      VTS_COLOR VTS_FONT

specifies a list containing a 32-bit integer representing an RGB color value, followed by a pointer to the IFontDisp interface of an OLE font object.

The VTS_ constants and their meanings are as follows:

SymbolParameter type
VTS_I2short
VTS_I4long
VTS_R4float
VTS_R8double
VTS_COLOROLE_COLOR
VTS_CYCURRENCY
VTS_DATEDATE
VTS_BSTRconst char*
VTS_DISPATCHLPDISPATCH
VTS_FONTIFontDispatch*
VTS_HANDLEHANDLE
VTS_SCODESCODE
VTS_BOOLBOOL
VTS_VARIANTconst VARIANT*
VTS_PVARIANTVARIANT*
VTS_UNKNOWNLPUNKNOWN
VTS_OPTEXCLUSIVEOLE_OPTEXCLUSIVE
VTS_PICTUREIPictureDisp*
VTS_TRISTATEOLE_TRISTATE
VTS_XPOS_PIXELSOLE_XPOS_PIXELS
VTS_YPOS_PIXELSOLE_YPOS_PIXELS
VTS_XSIZE_PIXELSOLE_XSIZE_PIXELS
VTS_YSIZE_PIXELSOLE_YSIZE_PIXELS
VTS_XPOS_HIMETRICOLE_XPOS_HIMETRIC
VTS_YPOS_HIMETRICOLE_YPOS_HIMETRIC
VTS_XSIZE_HIMETRICOLE_XSIZE_HIMETRIC
VTS_YSIZE_HIMETRICOLE_YSIZE_HIMETRIC
System_CAPS_ICON_note.jpg Note

Additional variant constants have been defined for all variant types, with the exception of VTS_FONT and VTS_PICTURE, that provide a pointer to the variant data constant. These constants are named using the VTS_Pconstantname convention. For example, VTS_PCOLOR is a pointer to a VTS_COLOR constant.

Defines an event firing function for a custom event belonging to the dispatch ID specified by dispid.

EVENT_CUSTOM_ID(
  pszName,   
  dispid,   
  pfnFire,
  vtsParams)  
 

Parameters

pszName
The name of the event.

dispid
The dispatch ID used by the control when firing the event.

pfnFire
The name of the event firing function.

vtsParams
A variable list of parameters passed to the control container when the event is fired.

Remarks

The vtsParams argument is a space-separated list of values from the VTS_ constants. One or more of these values separated by spaces, not commas, specifies the function's parameter list. For example:

      VTS_COLOR VTS_FONT

specifies a list containing a 32-bit integer representing an RGB color value, followed by a pointer to the IFontDisp interface of an OLE font object.

For a list of the VTS_ constants, see EVENT_CUSTOM.

This macro defines a message map entry that maps a custom verb to a specific member function of your control.

ON_OLEVERB(idsVerbName,  memberFxn)   

Parameters

idsVerbName
The string resource ID of the verb's name.

memberFxn
The function called by the framework when the verb is invoked.

Remarks

The resource editor can be used to create custom verb names that are added to your string table.

The function prototype for memberFxn is:

BOOL memberFxn(

LPMSG lpMsg ,

HWND hWndParent ,

LPCRECT lpRect

);

The values of the lpMsg, hWndParent, and lpRect parameters are taken from the corresponding parameters of the IOleObject::DoVerb member function.

Use this macro to override the default behavior of a standard verb.

ON_STDOLEVERB(iVerb,   memberFxn)   

Parameters

iVerb
The standard verb index for the verb being overridden.

memberFxn
The function called by the framework when the verb is invoked.

Remarks

The standard verb index is of the form OLEIVERB_, followed by an action. OLEIVERB_SHOW, OLEIVERB_HIDE, and OLEIVERB_UIACTIVATE are some examples of standard verbs.

See ON_OLEVERB for a description of the function prototype to be used as the memberFxn parameter.

Macros and Globals

Show: