Implementing Property Pages

ATL COM Property Pages

Property pages are COM objects that implement the IPropertyPage or IPropertyPage2 interface. ATL provides support for implementing property pages through the Property Page item in the Controls category of the ATL Object Wizard.

To create a property page using ATL:

Create or open an ATL Dynamic Link Library (DLL) server project.
Run the ATL Object Wizard and select Property Page from the Controls category.
Give your property page class a name using the wizard's Names property page.
Make sure your property page is apartment threaded (since it has a user interface) using the wizard's Attributes property page.
Set the title, description (Doc String), and help file to be associated with your page using the wizard's Strings property page.
Add controls to the generated dialog resource to act as the user interface of your property page.
Respond to changes in your page's user interface to perform validation, update the page site, or update the objects associated with your page. In particular, call IPropertyPageImpl::SetDirty when the user makes changes to the property page.
Optionally override the IPropertyPageImpl methods using the guidelines below.

IPropertyPageImpl Method	Override When You Want To...	Notes
SetObjects	Perform basic sanity checks on the number of objects being passed to your page and the interfaces that they support.	Execute your own code before calling the base class implementation. If the objects being set don't conform to your expectations, you should fail the call as soon as possible.
Activate	Initialize your page's user interface (for example, set dialog controls with current property values from objects, create controls dynamically, or perform other initializations).	Call the base class implementation before your code so that the base class has a chance to create the dialog window and all the controls before you try to update them.
Apply	Validate the property settings and update the objects.	There is no need to call the base class implementation since it doesn't do anything apart from trace the call.
Deactivate	Clean up window related items.	The base class implementation destroys the dialog representing the property page. If you need to clean up before the dialog is destroyed, you should add your code before calling the base class.

For an example property page implementation, see Example: Implementing a Property Page.

Note If you want to host ActiveX controls in your property page, you will need to change the derivation of your wizard-generated class. Replace CDialogImpl<CYourClass> with CAxDialogImpl<CYourClass> in the list of base classes.