ActiveX Controls: Adding Custom Properties

Custom properties differ from stock properties in that custom properties are not already implemented by the COleControl class. A custom property is used to expose a certain state or appearance of an ActiveX control to a programmer using the control.

This article describes how to add a custom property to the ActiveX control using ClassWizard and explains the resulting code modifications. Topics include:

Using ClassWizard to add a custom property
ClassWizard changes for custom properties

Custom properties come in four varieties of implementation: Member Variable, Member Variable with Notification, Get/Set Methods, and Parameterized.

Member Variable Implementation
This implementation represents the property’s state as a member variable in the control class. Use the Member Variable implementation when it is not important to know when the property value changes. Of the three types, this implementation creates the least amount of support code for the property. The dispatch map entry macro for member variable implementation is DISP_PROPERTY. For a detailed example of this implementation, see Adding Special Effects, in Tutorials.
Member Variable with Notification Implementation
This implementation consists of a member variable and a notification function created by ClassWizard. The notification function is automatically called by the framework after the property value changes. Use the Member Variable with Notification implementation when you need to be notified after a property value has changed. This implementation requires more time because it requires a function call. The dispatch map entry macro for this implementation is DISP_PROPERTY_NOTIFY. For a detailed example of this implementation, see Adding a Custom Notification Property in Tutorials.
Get/Set Methods Implementation
This implementation consists of a pair of member functions in the control class. The Get/Set Methods implementation automatically calls the Get member function when the control’s user requests the current value of the property and the Set member function when the control’s user requests that the property be changed. Use this implementation when you need to compute the value of a property during run time, validate a value passed by the control’s user before changing the actual property, or implement a read- or write-only property type. The dispatch map entry macro for this implementation is DISP_PROPERTY_EX. The following section, Using ClassWizard to Add a Custom Property, uses the CircleOffset custom property to demonstrate this implementation.
Parameterized Implementation
Parameterized implementation is supported by ClassWizard. A parameterized property (sometimes called a property array) can be used to access a set of values through a single property of your control. The dispatch map entry macro for this implementation is DISP_PROPERTY_PARAM. For more information on implementing this type, see Implementing a Parameterized Property in the article “ActiveX Controls: Advanced Topics”.

Using ClassWizard to Add a Custom Property

The following procedure demonstrates adding a custom property, CircleOffset, which uses the Get/Set Methods implementation. The CircleOffset custom property allows the control’s user to offset the circle from the center of the control’s bounding rectangle. The procedure for adding custom properties with an implementation other than Get/Set Methods is very similar.

This same procedure can also be used to add other custom properties you desire. Simply substitute your custom property name for the CircleOffset property name and parameters.

To add the CircleOffset custom 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, type CircleOffset.
In the Implementation box, click Get/Set Methods.
In the Type box, select short for the property’s type.
Type unique names for your Get and Set Functions, or accept the default names.
Click OK to close the Add Property dialog box.
Click OK to confirm your choices and close ClassWizard.

ClassWizard Changes for Custom Properties

When you add the CircleOffset custom property, ClassWizard makes changes to the header (.H) and the implementation (.CPP) files of the control class.

The following lines are added to the .H file to declare two functions called GetCircleOffset and SetCircleOffset:

afx_msg short GetCircleOffset( );
afx_msg void SetCircleOffset(short nNewValue);

The following line is added to your control’s .ODL file:

[id(1)] short CircleOffset;

This line assigns the CircleOffset property a specific ID number, taken from the method’s position in the methods and properties list of ClassWizard.

In addition, the following line is added to the dispatch map (in the .CPP file of the control class) to map the CircleOffset property to the control’s two handler functions:

DISP_PROPERTY_EX(CSampleCtrl,"CircleOffset", 
   GetCircleOffset, SetCircleOffset, VT_I2)

Finally, the implementations of the GetCircleOffset and SetCircleOffset functions are added to the end of the control’s .CPP file. In most cases, you will modify the Get function to return the value of the property. The Set function will usually contain code that should be executed either before or after the property changes.

void CFooCtrl::SetCircleOffset(short nNewValue) 
{
   // TODO: Add your property handler here
   SetModifiedFlag();
}

Note that ClassWizard automatically adds a call, to SetModifiedFlag, to the body of the Set function. Calling this function marks the control as modified. If a control has been modified, its new state will be saved when the container is saved. This function should be called whenever a property, saved as part of the control’s persistent state, changes value.

For a detailed implementation of the CircleOffset property, see Adding a Custom Get/Set Property in Tutorials.