MFC ActiveX Controls: Adding Stock Properties
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 the Add Property Wizard 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 the Add Property Wizard and explains the resulting code modifications. Topics include:
Using the Add Property Wizard to add a stock property
Add Property Wizard changes for stock properties
Stock properties supported by the Add Property Wizard
Stock properties and notification
Color properties
Notes
Visual Basic custom 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 the Add Property Wizard 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 and can also be used to add other stock properties. Substitute the selected stock property name for Caption.
To add the stock Caption property using the Add Property Wizard
Load your control's project.
In Class View, expand the library node of your control.
Right-click the interface node for your control (the second node of the library node) to open the shortcut menu.
From the shortcut menu, click Add and then click Add Property.
This opens the Add Property Wizard.
In the Property Name box, click Caption.
Click Finish.
Add Property Wizard Changes for Stock Properties
Because COleControl supports stock properties, the Add Property Wizard does not change the class declaration in any way; it adds the property to the dispatch map. The Add Property Wizard 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 interface description (.IDL) file:
[id(DISPID_CAPTION), helpstring("property Caption")] 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 the next section, Stock Properties Supported by the Add Property Wizard.
Stock Properties Supported by the Add Property Wizard
The COleControl class provides nine stock properties. You can add the properties you want by using the Add Property Wizard.
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 MFC ActiveX Controls: Using Fonts 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. |
ReadyState |
DISP_STOCKPROP_READYSTATE() |
Value accessible as m_lReadyState or GetReadyState |
Stock Properties and Notification
Most 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 COleControl::TranslateColor 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);