Framework Support: Stock Properties and CStockPropImpl

---

Framework Support: Stock Properties and CStockPropImpl<>

Just like a custom property you might add to a COM interface, a stock property has a get_ and put_ function to allow the container to obtain and alter the value represented by the property itself. ATL provides a default implementation for each stock property using the CStockPropertyImpl<> template. As soon as you add support for a stock property using the ATL Object Wizard, this template is added to your class derivation:

// If you select any stock properties from the ATL Object Wizard, you will be // derived from CStockPropImpl<>. class ATL_NO_VTABLE CShapesControl :      public CComObjectRootEx<CComSingleThreadModel>,      public CStockPropImpl<CShapesControl, IShapesControl,                &IID_IShapesControl,&LIBID_AXSHAPESSERVERLib>, ... {...};

CStockPropImpl<> provides accessor and mutator methods for each stock property. The parameters to this template should be obvious by now. What may not be obvious is that CStockPropImpl<> expects the [default] interface to be IDispatch savvy in order to work correctly. Therefore, be sure your primary default interface has been declared as a [dual].

CStockPropImpl<> implements a given stock property by providing boilerplate code which notifies the container a property has been changed (for every put_ method) or returns the current value of the property (for each get_ method). To define the member variables used for each stock property, CComControlBase establishes a union of all stock property member variables:

// These member variables of CComControlBase are used by CStockPropImpl<>'s // implementation of the [propput] and [propget] methods. union {      IPictureDisp* m_pMouseIcon;      IPictureDisp* m_pPicture;      IFontDisp* m_pFont;      OLE_COLOR m_clrBackColor;      OLE_COLOR m_clrBorderColor;      OLE_COLOR m_clrFillColor;      OLE_COLOR m_clrForeColor;      BSTR m_bstrText;      BSTR m_bstrCaption;      BOOL m_bValid;      BOOL m_bTabStop;      BOOL m_bBorderVisible;      BOOL m_bEnabled;      LONG m_nBackStyle;      LONG m_nBorderStyle;      LONG m_nBorderWidth;      LONG m_nDrawMode;      LONG m_nDrawStyle;      LONG m_nDrawWidth;      LONG m_nFillStyle;      SHORT m_nAppearance;      LONG m_nMousePointer;      LONG m_nReadyState; }; 

Given the name of each variable, I think you can gather which stock property each one represents. Your derived class needs to provide the actual storage for the stock properties you have selected from the ATL Object Wizard. If you examine the header file for CShapesControl, you will see the wizard has inserted the correct data members into your class:

// Your class will contain member variables for the stock properties you selected. OLE_COLOR m_clrBackColor; CComBSTR m_bstrCaption; CComPtr<IFontDisp> m_pFont;

When you wish to set or get the property, you will call the CStockPropImpl<> method (e.g., put_BackColor(), get_BackColor()). Exactly how CStockPropImpl<> actually implements these [propget] and [propput] functions depends on the underlying data type.

ATL's Stock Property Macros

For complex data types (meaning any COM interface, such as IFontDisp), CStock- PropImpl<> implements the accessor and mutator using some more elaborate COM code, taking care of interface reference counting and necessary memory management. For the remaining simple data types, CStockPropImpl<> makes use of three ATL macros. While you will most likely never need to directly use (or pay mind to) these macros, here is a brief description of each:

ATL Stock Property Macro	Meaning in Life
IMPLEMENT_STOCKPROP	Defines a [propput] and [propget] method for any stock property that is not a BSTR, BOOL, or COM interface. The implementation code informs the container of the new change.
IMPLEMENT_BOOL_STOCKPROP	A special case of the previous macro, which provides [propput] and [propget] methods for BOOLs.
IMPLEMENT_BSTR_STOCKPROP	Another special case to handle the manipulation of a BSTR property.

To get a feeling as to what these macros do, consider ATL's implementation of the BackColor stock property:

// CStockPropImpl<> code. IMPLEMENT_STOCKPROP(OLE_COLOR, BackColor, clrBackColor, DISPID_BACKCOLOR)

The parameters to this macro are the name of the data type of the property, the friendly name of the property, the member variable defined by CComControlBase (without the "m_" prefix), and the DISPID. When this macro expands, we are provided with the actual code that sets or retrieves the value. Note that the "dirty flag" is automatically set. Also note that FireOnEditRequest() and FireOnChanged() are called when the template expands.

Note 

Given this, you should always augment the wizard-generated IDL code with the [bindable, requestedit] attributes for any stock property supported by your control!

// Defining accessors and mutators for a basic stock property. #define IMPLEMENT_STOCKPROP(type, fname, pname, dispid) \      HRESULT STDMETHODCALLTYPE put_##fname(type pname) \      { \           ATLTRACE2(atlTraceControls,2,_T("CStockPropImpl::put_%s\n"), #fname); \           T* pT = (T*) this; \           if (pT->FireOnRequestEdit(dispid) == S_FALSE) \                return S_FALSE; \           pT->m_##pname = pname; \           pT->m_bRequiresSave = TRUE; \           pT->FireOnChanged(dispid); \           pT->FireViewChange(); \           pT->SendOnDataChange(NULL); \           return S_OK; \      } \      HRESULT STDMETHODCALLTYPE get_##fname(type* p##pname) \      { \           ATLTRACE2(atlTraceControls,2,_T("CStockPropImpl::get_%s\n"), \                      #fname); \           T* pT = (T*) this; \           *p##pname = pT->m_##pname; \           return S_OK; \      }

The basic functionality of the [propget] method is to simply return to the container the value of the data member representing the stock property. The [propput] method sets the new value and informs the container of the changes. The remaining stock property macros build similar implementation, with the net result being that ATL has established all the code required, allowing your ActiveX control to support stock properties—without requiring you to write the code.

---