ActiveX Controls: Property Pages

Home |  Overview |  How Do I |  FAQ |  Tutorial |  Sample

Property pages allow an ActiveX control user to view and change ActiveX control properties. These properties are accessed by invoking a control properties dialog box, which contains one or more property pages that provide a customized, graphical interface for viewing and editing the control properties.

ActiveX control property pages are displayed in two ways:

• When the control’s Properties verb (OLEIVERB_PROPERTIES) is invoked, the control opens a modal property dialog box that contains the control’s property pages.
  
  
• The container can display its own modeless dialog box that shows the property pages of the selected control.

The properties dialog box (illustrated in the figure below) consists of an area for displaying the current property page, tabs for switching between property pages, and a collection of buttons that perform common tasks such as closing the property page dialog, canceling any changes made, or immediately applying any changes to the ActiveX control.

A Properties Dialog Box

This article covers topics related to using property pages in an ActiveX control. These include:

• Implementing the default property page for an ActiveX control
  
  
• Adding controls to a property page
  
  
• Adding a Help button to a property page
  
  
• Customizing the DoDataExchange function

For more information on using property pages in an ActiveX control, see the following articles:

• ActiveX Controls: Adding Another Custom Property Page
  
  
• ActiveX Controls: Using Stock Property Pages

For information on using property sheets in an MFC application other than an ActiveX control, see the article Property Sheets: Overview.

Implementing the Default Property Page

If you use ControlWizard to create your control project, ControlWizard provides a default property page class for the control derived from COlePropertyPage. Initially, this property page is blank, but you can add any dialog box control or set of controls to it. Because ControlWizard creates only one property page class by default, additional property page classes (also derived from COlePropertyPage) must be created using ClassWizard. For more information on this procedure, see ActiveX Controls: Adding Another Custom Property Page.

Implementing a property page (in this case, the default) is a three step process:

To implement a property page

1. Add a COlePropertyPage-derived class to the control project. If the project was created using ControlWizard (as in this case), the default property page class already exists.
   
   
2. Use the dialog editor to add any controls to the property page template.
   
   
3. Customize the DoDataExchange function of the control to exchange values between the property page control and the ActiveX control.

For example purposes, the following procedures use a simple control (named “Sample”). Sample was created using ControlWizard and contains only the stock Caption property.

Adding Controls to a Property Page

To add controls to a property page

1. With your control project open, click the ResourceView tab in the Project Workspace window.
   
   
2. Double-click the Dialog directory icon.
   
   
3. Open the IDD_PROPPAGE_SAMPLE dialog box.

   ControlWizard appends the name of the project to the end of the dialog ID, in this case, Sample.

4. Click the desired control on the Control Palette and drag and drop it into the dialog box area.

   For this example, a text label control “Caption :” and an edit box control with an IDC_CAPTION identifier are sufficient.

5. Click Save on the Toolbar to save your changes.

Now that the user interface has been modified, you need to link the edit box with the Caption property. This is done in the following section by editing the CSamplePropPage::DoDataExchange function.

Adding a Help Button to a Property Page

To enable help in your ActiveX control, call SetHelpInfo from your property page's constructor, and override the property page's OnHelp function to invoke WinHelp.

Here is an example of changing the default property page generated by ControlWizard:

CMyPropPage::CMyPropPage() :
        COlePropertyPage(IDD, IDS_MY_PPG_CAPTION)
{
        //{{AFX_DATA_INIT(CMyPropPage)
        // NOTE: ClassWizard will add member initialization here
        //    DO NOT EDIT what you see in these blocks of generated code !
        //}}AFX_DATA_INIT

        SetHelpInfo("Custom Help String goes here!!!","My.hlp",0);  
}

BOOL CMyPropPage::OnHelp(LPCTSTR lpszHelpDir)
{
        AfxGetApp()->WinHelp(0,HELP_CONTENTS);
        return TRUE;
}

The sample TESTHELP demonstrates how to create an ActiveX control with tooltips and Help.

Customizing the DoDataExchange Function

Your property page DoDataExchange function allows you to link property page values with the actual values of properties in the control. To establish links, you must map the appropriate property page fields to their respective control properties.

These mappings are implemented using the property page DDP_ functions. The DDP_ functions work like the DDX_ functions used in standard MFC dialogs, with one exception. In addition to the reference to a member variable, DDP_ functions take the name of the control property. The following is a typical entry in the DoDataExchange function for a property page.

DDP_Text(pDX, IDC_CAPTION, m_caption, _T("Caption"));

This function associates the property page’s m_caption member variable with the Caption property of the control.

Once you have the property page control inserted, you need to establish a link between the property page control, IDC_CAPTION, and the actual control property, Caption.

For more information on this procedure, see Linking Controls with Properties in Tutorials.

DDP functions are available for other dialog control types, such as check boxes, radio buttons, and list boxes. The table below lists the entire set of property page DDP_ functions and their purposes:

Property Page Functions

See Also   COlePropertyPage