ActiveX Control Containers: Handling Events from an ActiveX Control
This article discusses using the Properties window to install event handlers for ActiveX controls in an ActiveX control container. The event handlers are used to receive notifications (from the control) of certain events and perform some action in response. This notification is called "firing" the event.
Note
This article uses a dialog-based ActiveX control container project named Container and an embedded control named Circ as examples in the procedures and code.
Using the Events button in the Properties window, you can create a map of events that can occur in your ActiveX control container application. This map, called an "event sink map,'' is created and maintained by Visual C++ when you add event handlers to the control container class. Each event handler, implemented with an event map entry, maps a specific event to a container event handler member function. This event handler function is called when the specified event is fired by the ActiveX control object.
For more information on event sink maps, see Event Sink Maps in the Class Library Reference.
Event Handler Modifications to the Project
When you use the Properties window to add event handlers, an event sink map is declared and defined in your project. The following statements are added to the control .CPP file the first time an event handler is added. This code declares an event sink map for the dialog box class (in this case, CContainerDlg):
BEGIN_EVENTSINK_MAP(CContainerDlg, CDialog)
...
END_EVENTSINK_MAP()
As you use the Properties window to add events, an event map entry (ON_EVENT) is added to the event sink map and an event handler function is added to the container's implementation (.CPP) file.
The following example declares an event handler, called OnClickInCircCtrl, for the Circ control's ClickIn event:
BEGIN_EVENTSINK_MAP(CContainerDlg, CDialog)
ON_EVENT(CContainerDlg, IDC_CIRCCTRL1, 1 /* ClickIn */, OnClickInCircctrl1,
VTS_I4 VTS_I4)
END_EVENTSINK_MAP()
In addition, the following template is added to the CContainerDlg class implementation (.CPP) file for the event handler member function:
BOOL CContainerDlg::OnClickInCircctrl1(OLE_XPOS_PIXELS nX, OLE_YPOS_PIXELS nY)
{
// use nX and nY here
TRACE(_T("nX = %d, nY = %d\n"), nX, nY);
return TRUE;
}
For more information on event sink macros, see Event Sink Maps in the Class Library Reference.
To create an event handler function
From Class View, select the dialog class that contains the ActiveX control. For this example, use CContainerDlg.
In the Properties window, click the Events button.
In the Properties window, select the control ID of the embedded ActiveX control. For this example, use IDC_CIRCCTRL1.
The Properties window displays a list of events that can be fired by the embedded ActiveX control. Any member function shown in bold already has handler functions assigned to it.
Select the event you want the dialog class to handle. For this example, select Click.
From the drop-down list box on the right, select <Add> ClickCircctrl1.
Double-click the new handler function from Class View to jump to the event handler code in the implementation (.CPP) file of CContainerDlg.