ActiveX Controls: Adding Stock Properties

Article
09/15/2006

Stock properties differ from custom properties in that they are already implemented by the class COleControl. COleControl contains predefined member functions that support common properties for the control. Some common properties include the control’s caption and the foreground and background colors. For information on other stock properties, see Stock Properties Supported by ClassWizard later in this article. The dispatch map entries for stock properties are always prefixed by DISP_STOCKPROP.

This article describes how to add a stock property (in this case, Caption) to an ActiveX control using ClassWizard and explains the resulting code modifications. Topics include:

Using ClassWizard to add a stock property
ClassWizard changes for stock properties
Stock properties supported by ClassWizard
Stock properties and notification
Color properties

Note Visual Basic custom (VBX) controls typically have properties such as Top, Left, Width, Height, Align, Tag, Name, TabIndex, TabStop, and Parent. ActiveX control containers, however, are responsible for implementing these control properties and therefore ActiveX controls should not support these properties.

Using ClassWizard to Add a Stock Property

Adding stock properties requires less code than adding custom properties because support for the property is handled automatically by COleControl. The following procedure demonstrates adding the stock Caption property to an ActiveX control framework. This same procedure can also be used to add other stock properties. Simply substitute the desired stock property name for Caption.

To add the stock Caption property using ClassWizard

Load your control’s project.
On the View menu, click ClassWizard.
Click the Automation tab.
Select the control’s class from the Class name box.
Click Add Property.
In the External name box, click Caption.

Note that in the Implementation group, Stock is automatically selected.
Click OK to close the Add Property box.
Click OK to confirm your choices and close ClassWizard.

ClassWizard Changes for Stock Properties

Because COleControl supports stock properties, ClassWizard does not change the class declaration in any way; it simply adds the property to the dispatch map. ClassWizard adds the following line to the dispatch map of the control, which is located in the implementation (.CPP) file:

DISP_STOCKPROP_CAPTION( )

The following line is added to your control’s Object Description (.ODL) file:

[id(DISPID_CAPTION), bindable, requestedit] BSTR Caption;

This line assigns the Caption property a specific ID. Notice that the property is bindable and will request permission from the database before modifying the value.

This makes the Caption property available to users of your control. To use the value of a stock property, access a member variable or member function of the COleControl base class. For more information on these member variables and member functions, see Stock Properties Supported by ClassWizard.

Stock Properties Supported by ClassWizard

The COleControl class provides nine stock properties. You can specify the properties you want in the control in the Automation tab of the MFC ClassWizard dialog box.

Property	Dispatch map entry	How to access value
Appearance	DISP_STOCKPROP_APPEARANCE( )	Value accessible as m_sAppearance.
BackColor	DISP_STOCKPROP_BACKCOLOR( )	Value accessible by calling GetBackColor.
BorderStyle	DISP_STOCKPROP_BORDERSTYLE( )	Value accessible as m_sBorderStyle.
Caption	DISP_STOCKPROP_CAPTION( )	Value accessible by calling InternalGetText.
Enabled	DISP_STOCKPROP_ENABLED( )	Value accessible as m_bEnabled.
Font	DISP_STOCKPROP_FONT( )	See the article ActiveX Controls: Using Fonts in an ActiveX Control for usage.
ForeColor	DISP_STOCKPROP_FORECOLOR( )	Value accessible by calling GetForeColor.
hWnd	DISP_STOCKPROP_HWND( )	Value accessible as m_hWnd.
Text	DISP_STOCKPROP_TEXT( )	Value accessible by calling InternalGetText. This property is the same as Caption, except for the property name.

Stock Properties and Notification

Most of the stock properties have notification functions that can be overridden. For example, whenever the BackColor property is changed, the OnBackColorChanged function (a member function of the control class) is called. The default implementation (in COleControl) calls InvalidateControl. Override this function if you want to take additional actions in response to this situation.

Color Properties

You can use the stock ForeColor and BackColor properties, or your own custom color properties, when painting the control. To use a color property, call the member function. The parameters of this function are the value of the color property and an optional palette handle. The return value is a COLORREF value that can be passed to GDI functions, such as SetTextColor and CreateSolidBrush.

The color values for the stock ForeColor and BackColor properties are accessed by calling either the GetForeColor or the GetBackColor function, respectively.

The following example demonstrates using these two color properties when painting a control. It initializes a temporary COLORREF variable and a CBrush object with calls to TranslateColor: one using the ForeColor property and the other using the BackColor property. A temporary CBrush object is then used to paint the control’s rectangle, and the text color is set using the ForeColor property.

   CBrush bkBrush(TranslateColor(GetBackColor()));
   COLORREF clrFore = TranslateColor(GetForeColor());
   pdc->FillRect( rcBounds, &bkbrush );
   pdc->SetTextColor( clrFore );
   pdc->DrawText( InternalGetText(), -1, rcBounds, DT_SINGLELINE | DT_CENTER | DT_VCENTER );