Event Sink 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 Sink Maps.
When an embedded OLE control fires an event, the control's container receives the event using a mechanism, called an "event sink map," supplied by MFC. This event sink map designates handler functions for each specific event, as well as parameters of those events. For more information on event sink maps, see the article ActiveX Control Containers.
Event Sink Maps
| BEGIN_EVENTSINK_MAP | Starts the definition of an event sink map. |
| DECLARE_EVENTSINK_MAP | Declares an event sink map. |
| END_EVENTSINK_MAP | Ends the definition of an event sink map. |
| ON_EVENT | Defines an event handler for a specific event. |
| ON_EVENT_RANGE | Defines an event handler for a specific event fired from a set of OLE controls. |
| ON_EVENT_REFLECT | Receives events fired by the control before they are handled by the control's container. |
| ON_PROPNOTIFY | Defines a handler for handling property notifications from an OLE control. |
| ON_PROPNOTIFY_RANGE | Defines a handler for handling property notifications from a set of OLE controls. |
| ON_PROPNOTIFY_REFLECT | Receives property notifications sent by the control before they are handled by the control's container. |
BEGIN_EVENTSINK_MAP
Begins the definition of your event sink map.
BEGIN_EVENTSINK_MAP
(theClass, baseClass)
Parameters
theClass
Specifies the name of the control class whose event sink 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 sink map with the BEGIN_EVENTSINK_MAP macro, then add macro entries for each event to be notified of, and complete the event sink map with the END_EVENTSINK_MAP macro.
For more information on event sink maps and OLE control containers, see the article ActiveX Control Containers.
DECLARE_EVENTSINK_MAP
An OLE container can provide an event sink map to specify the events your container will be notified of.
DECLARE_EVENTSINK_MAP
()
Remarks
Use the DECLARE_EVENTSINK_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_EVENTSINK_MAP macro, macro entries for each of the events to be notified of, and the END_EVENTSINK_MAP macro to declare the end of the event sink list.
For more information on event sink maps, see the article ActiveX Control Containers.
END_EVENTSINK_MAP
Ends the definition of your event sink map.
END_EVENTSINK_MAP
()
ON_EVENT
Use the ON_EVENT macro to define an event handler function for an event fired by an OLE control.
ON_EVENT
(theClass, id, dispid, pfnHandler, vtsParams)
Parameters
theClass
The class to which this event sink map belongs.
id
The control ID of the OLE control.
dispid
The dispatch ID of the event fired by the control.
pfnHandler
Pointer to a member function that handles the event. This function should have a BOOL return type, and parameter types that match the event's parameters (see vtsParams). The function should return TRUE to indicate the event was handled; otherwise FALSE.
vtsParams
A sequence of VTS_ constants that specifies the types of the parameters for the event. These are the same constants that are used in dispatch map entries such as DISP_FUNCTION.
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_I2 VTS_BOOL
specifies a list containing a short integer followed by a BOOL.
For a list of the VTS_ constants, see [EVENT_CUSTOM]--brokenlink--(../Topic/not%20found.md#event_custom).
ON_EVENT_RANGE
Use the ON_EVENT_RANGE macro to define an event handler function for an event fired by any OLE control having a control ID within a contiguous range of IDs.
ON_EVENT_RANGE
(theClass, idFirst, idLast, dispid, pfnHandler, vtsParams)
Parameters
theClass
The class to which this event sink map belongs.
idFirst
The control ID of the first OLE control in the range.
idLast
The control ID of the last OLE control in the range.
dispid
The dispatch ID of the event fired by the control.
pfnHandler
Pointer to a member function that handles the event. This function should have a BOOL return type, a first parameter of type UINT (for the control ID), and additional parameter types that match the event's parameters (see vtsParams). The function should return TRUE to indicate the event was handled; otherwise FALSE.
vtsParams
A sequence of VTS_ constants that specifies the types of the parameters for the event. The first constant should be of type VTS_I4, for the control ID. These are the same constants that are used in dispatch map entries such as DISP_FUNCTION.
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_I2 VTS_BOOL
specifies a list containing a short integer followed by a BOOL.
For a list of the VTS_ constants, see [EVENT_CUSTOM]--brokenlink--(../Topic/not%20found.md#event_custom).
Example
The following example demonstrates an event handler, for the MouseDown event, implemented for three controls ( IDC_MYCTRL1 through IDC_MYCTRL3). The event handler function, OnRangeMouseDown, is declared in the header file of the dialog class ( CMyDlg) as:
BOOL OnRangeMouseDown(UINT CtlID, short MouseButton, short Shift,
long x, long y);
The code below is defined in the implementation file of the dialog class.
BEGIN_EVENTSINK_MAP(CMyDlg, CDialog)
ON_EVENT_RANGE(CMyDlg, IDC_MYCTRL1, IDC_MYCTRL3, -605, OnRangeMouseDown,
VTS_I4 VTS_I2 VTS_I2 VTS_I4 VTS_I4)
END_EVENTSINK_MAP()
ON_EVENT_REFLECT
The ON_EVENT_REFLECT macro, when used in the event sink map of an OLE control's wrapper class, receives events fired by the control before they are handled by the control's container.
ON_EVENT_REFLECT
(theClass, dispid, pfnHandler, vtsParams)
Parameters
theClass
The class to which this event sink map belongs.
dispid
The dispatch ID of the event fired by the control.
pfnHandler
Pointer to a member function that handles the event. This function should have a BOOL return type and parameter types that match the event's parameters (see vtsParams). The function should return TRUE to indicate the event was handled; otherwise FALSE.
vtsParams
A sequence of VTS_ constants that specifies the types of the parameters for the event. These are the same constants that are used in dispatch map entries such as DISP_FUNCTION.
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_I2 VTS_BOOL
specifies a list containing a short integer followed by a BOOL.
For a list of the VTS_ constants, see [EVENT_CUSTOM]--brokenlink--(../Topic/not%20found.md#event_custom).
ON_PROPNOTIFY
Use the ON_PROPNOTIFY macro to define an event sink map entry for handling property notifications from an OLE control.
ON_PROPNOTIFY
(theClass, id, dispid, pfnRequest, pfnChanged)
Parameters
theClass
The class to which this event sink map belongs.
id
The control ID of the OLE control.
dispid
The dispatch ID of the property involved in the notification.
pfnRequest
Pointer to a member function that handles the OnRequestEdit notification for this property. This function should have a BOOL return type and a BOOL* parameter. This function should set the parameter to TRUE to allow the property to change and FALSE to disallow. The function should return TRUE to indicate the notification was handled; otherwise FALSE.
pfnChanged
Pointer to a member function that handles the OnChanged notification for this property. The function should have a BOOL return type and a UINT parameter. The function should return TRUE to indicate that notification was handled; otherwise FALSE.
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_I2 VTS_BOOL
specifies a list containing a short integer followed by a BOOL.
For a list of the VTS_ constants, see [EVENT_CUSTOM]--brokenlink--(../Topic/not%20found.md#event_custom).
ON_PROPNOTIFY_RANGE
Use the ON_PROPNOTIFY_RANGE macro to define an event sink map entry for handling property notifications from any OLE control having a control ID within a contiguous range of IDs.
ON_PROPNOTIFY_RANGE
(theClass, idFirst, idLast, dispid, pfnRequest, pfnChanged)
Parameters
theClass
The class to which this event sink map belongs.
idFirst
The control ID of the first OLE control in the range.
idLast
The control ID of the last OLE control in the range.
dispid
The dispatch ID of the property involved in the notification.
pfnRequest
Pointer to a member function that handles the OnRequestEdit notification for this property. This function should have a BOOL return type and UINT and BOOL* parameters. The function should set the parameter to TRUE to allow the property to change and FALSE to disallow. The function should return TRUE to indicate that notification was handled; otherwise FALSE.
pfnChanged
Pointer to a member function that handles the OnChanged notification for this property. The function should have a BOOL return type and a UINT parameter. The function should return TRUE to indicate that notification was handled; otherwise FALSE.
ON_PROPNOTIFY_REFLECT
The ON_PROPNOTIFY_REFLECT macro, when used in the event sink map of an OLE control's wrapper class, receives property notifications sent by the control before they are handled by the control's container.
ON_PROPNOTIFY_REFLECT
(theClass, dispid, pfnRequest, pfnChanged)
Parameters
theClass
The class to which this event sink map belongs.
dispid
The dispatch ID of the property involved in the notification.
pfnRequest
Pointer to a member function that handles the OnRequestEdit notification for this property. This function should have a BOOL return type and a BOOL* parameter. This function should set the parameter to TRUE to allow the property to change and FALSE to disallow. The function should return TRUE to indicate the notification was handled; otherwise FALSE.
pfnChanged
Pointer to a member function that handles the OnChanged notification for this property. The function should have a BOOL return type and no parameters. The function should return TRUE to indicate the notification was handled; otherwise FALSE.