Event Maps
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_MAP | Declares 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_MAP | Begins the definition of an event map (must be used in the class implementation). |
| END_EVENT_MAP | Ends the definition of an event map (must be used in the class implementation). |
Event Mapping Macros
| EVENT_CUSTOM | Indicates which event-firing function will fire the specified event. |
| EVENT_CUSTOM_ID | Indicates which event-firing function will fire the specified event, with a designated dispatch ID. |
Message Mapping Macros
| ON_OLEVERB | Indicates a custom verb handled by the OLE control. |
| ON_STDOLEVERB | Overrides a standard verb mapping of the OLE control. |
DECLARE_EVENT_MAP
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.
BEGIN_EVENT_MAP
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.
END_EVENT_MAP
Use the END_EVENT_MAP macro to end the definition of your event map.
END_EVENT_MAP
()
EVENT_CUSTOM
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:
| Symbol | Parameter type |
|---|---|
| VTS_I2 | short |
| VTS_I4 | long |
| VTS_R4 | float |
| VTS_R8 | double |
| VTS_COLOR | OLE_COLOR |
| VTS_CY | CURRENCY |
| VTS_DATE | DATE |
| VTS_BSTR | const char* |
| 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 |
| VTS_XPOS_HIMETRIC | OLE_XPOS_HIMETRIC |
| VTS_YPOS_HIMETRIC | OLE_YPOS_HIMETRIC |
| VTS_XSIZE_HIMETRIC | OLE_XSIZE_HIMETRIC |
| VTS_YSIZE_HIMETRIC | OLE_YSIZE_HIMETRIC |
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.
EVENT_CUSTOM_ID
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.
ON_OLEVERB
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.
ON_STDOLEVERB
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.