ActiveX Controls with MFC

Analogy categoryAnalogies

Anatomy of an MFC ActiveX Control

An ActiveX control authored with MFC is a CWnd-derived class that also derives from COleControl, which layers in the COM interfaces a control host expects: IOleObject for embedding, IOleInPlaceObject for in-place activation, IViewObject for drawing, and IDispatch for its scriptable properties and methods. The MFC ActiveX Control Wizard scaffolds a project containing the control class itself, a COleControlModule-derived CWinApp replacement (since a control DLL has no normal application object), and a class factory registered under a control-specific CLSID, all packaged into an OCX (a DLL with a .ocx extension signaling it's a control). Stock properties such as BackColor, ForeColor, Enabled, and Font are wired in automatically by the wizard through OLE_COLOR-typed dispatch entries and the DoPropExchange mechanism, while custom properties the developer adds go through the same DDP_ (dialog data property) style exchange used for persistence.

🏏

Cricket analogy: COleControl layering IOleObject, IOleInPlaceObject, IViewObject, and IDispatch onto CWnd is like a franchise player who must simultaneously satisfy the roles of opener, vice-captain, and fielding-drills lead - one person, several formally required responsibilities.

Events and Property Pages

A control communicates back to its host through events, declared with an event map (DECLARE_EVENT_MAP/BEGIN_EVENT_MAP) and fired with FireEvent or the wizard-generated helper functions like FireClick(), which under the hood calls IPropertyNotifySink or the connection points established via IConnectionPointContainer so the host (an MFC dialog, a web page, or a VB6 form) can wire up an event handler. Property pages, implemented as COlePropertyPage-derived classes and associated with the control through the property page's CLSID in the control's implementation, give designers a tabbed UI (shown at design time in the host's Properties dialog) for editing complex properties that don't map neatly onto the generic grid, such as picking a font or a set of chart series colors. A control's stock property BorderStyle or a custom property like GridLineColor is exposed to both the property grid and property pages through the same dispatch map entries used for scripting, so changing a value in the designer and changing it from VBA code go through identical code paths.

🏏

Cricket analogy: Events fired via connection points are like a fielder's signal to the bowler after taking a catch - the underlying action (control state change) triggers a notification that a specific subscribed party (the host) reacts to.

Hosting Controls in an MFC Dialog

To host an ActiveX control inside an MFC dialog, the application must first call AfxEnableControlContainer() in InitInstance so the framework's control-container support (COleControlContainer and friends) is compiled in and initialized, then place the control on the dialog template (either by inserting it in the resource editor's control palette after adding the OCX via 'Insert ActiveX Control', or by handling it purely at runtime with CWnd::CreateControl) and bind a member variable to it with DDX_Control. Once bound, the generated wrapper class - produced by 'Add Class > From ActiveX Control' at design time - exposes the control's dispatch methods and properties as ordinary C++ member functions with the correct parameter types, so calling a method on a hosted Adobe Reader or Windows Media Player control from an MFC dialog looks like calling any other C++ member function even though it's routed through IDispatch::Invoke underneath. Licensing must also be considered: a control marked with a machine license (a .lic file at design time) requires the host to supply IClassFactory2::CreateInstanceLic with a valid runtime license key, or CreateInstance calls fail on machines without a design-time license installed.

🏏

Cricket analogy: AfxEnableControlContainer being required before hosting any ActiveX control is like a ground needing its DRS technology formally switched on before any review can be requested during the match.

cpp

// Control class declaration (from the ActiveX Control Wizard)
class CGaugeCtrl : public COleControl
{
    DECLARE_DYNCREATE(CGaugeCtrl)
    DECLARE_OLECREATE_EX(CGaugeCtrl)
    DECLARE_OLETYPELIB(CGaugeCtrl)
    DECLARE_PROPPAGEIDS(CGaugeCtrl)
    DECLARE_DISPATCH_MAP()
    DECLARE_EVENT_MAP()

    void OnDraw(CDC* pdc, const CRect& rcBounds, const CRect& rcInvalid) override;
    afx_msg long GetValue();
    afx_msg void SetValue(long nNewValue);
};

BEGIN_DISPATCH_MAP(CGaugeCtrl, COleControl)
    DISP_PROPERTY_EX(CGaugeCtrl, "Value", GetValue, SetValue, VT_I4)
END_DISPATCH_MAP()

BEGIN_EVENT_MAP(CGaugeCtrl, COleControl)
    EVENT_STOCK_CLICK()
    EVENT_CUSTOM("ThresholdExceeded", FireThresholdExceeded, VTS_I4)
END_EVENT_MAP()

// Hosting the control in an MFC dialog after AfxEnableControlContainer()
void CMonitorDlg::OnGaugeUpdate()
{
    m_gauge.SetValue(m_currentReading); // m_gauge bound via DDX_Control
}

'Add Class > From ActiveX Control' (or the older MFC ClassWizard 'Add Class... From a Control' dialog) parses the target OCX's type library and generates a CWnd-derived wrapper class whose member functions call InvokeHelper against the correct DISPID, so hosted-control calls read like ordinary C++ even though they cross a COM boundary.

If AfxEnableControlContainer() is omitted from InitInstance, an MFC dialog containing an ActiveX control will typically fail to create the control at runtime (or assert in debug builds), because the container-side COM plumbing that ActiveX controls require was never initialized.

An MFC ActiveX control derives from COleControl, which layers IOleObject, IOleInPlaceObject, IViewObject, and IDispatch onto a CWnd.
The ActiveX Control Wizard generates the control class, a COleControlModule-based app object, and a registered class factory packaged as an OCX.
Events are declared with an event map and fired via FireEvent/wizard-generated helpers, delivered to hosts through connection points.
COlePropertyPage-derived classes provide tabbed design-time UI for editing complex properties beyond the generic property grid.
AfxEnableControlContainer() must be called before an MFC dialog can host ActiveX controls.
DDX_Control binds a hosted control to a wrapper class generated from its type library, exposing dispatch calls as ordinary member functions.
Licensed controls require IClassFactory2::CreateInstanceLic with a valid runtime license key on machines without the design-time license.