Implementing a Property Sheet

A property sheet is a dialog box for displaying the properties of an object. The properties can be read-only, enabling the user only to view them, or read/write, enabling the user to make changes. A property sheet contains one or more overlapping child windows called pages, each page contains control windows for setting a group of related properties. Users navigate from page to page by selecting a tab that brings the corresponding page to the foreground of the property sheet.

Service providers are required to implement a property sheet that displays a minimal set of properties related to configuration in the message service. If you allow these message service properties to be changed, you can either allow users of client applications such as the Control Panel applet to make the changes or implement the changes programmatically. Implementing property sheets to display and edit other types of properties is optional.

Typically, you will need to display a property sheet:

• When a client calls your status object's IMAPIStatus::SettingsDialog method.
• When MAPI calls your provider object's logon method.
• When MAPI calls the entry point function for your provider's message service.

Transport providers also implement property sheets to display properties related to message options, and address book providers implement property sheets to view and edit detailed information about messaging users and distribution lists, advanced search criteria, and templates for entering new users.

There are three techniques for creating a property sheet:

• Manually, as you would any dialog box.
• Using the property sheet common control provided in the Platform SDK.
• Using a MAPI display table.

MAPI recommends that providers choose the third option; create a property sheet using a display table. This is the simplest option because it eliminates the need to work with the Windows user interface.

    To implement a property sheet built from a display table for your message service properties

1. Call IMAPISupport::OpenProfileSection to open a section in the current profile. Pass your MAPIUID or NULL to open your provider's profile section.
2. Call CreateIProp to create a property data object.
3. Call the profile section's IMAPIProp::CopyTo method to copy all of the section's properties to the property data object.
4. Create a display table either by building one or more DTPAGE structures that describe the controls to appear on the property sheet and calling the BuildDisplayTable function or by implementing custom code.
5. Call IMAPISupport::DoConfigPropSheet to display a property sheet with the copied properties. Pass a pointer to the property data object as the lpConfigData parameter and a pointer to the display table as the lpDisplayTable parameter. If you want to override the default access mode for this property sheet, do not set the DT_EDITABLE flag for each control in the display table that represents a read-only property.
6. When all of the changes have been made in the property sheet, call the property data object's IMAPIProp::CopyTo method to copy the changed properties back to the profile section.

For an overview of display tables, see Display Tables.

For detailed information about display tables, see Implementing a Display Table.

For information about implementing a control, see Implementing a Control Object.

To retrieve the index of a control selected by a user in a display table list box, wait until the user clicks OK or Apply Now. At this point, the entry identifier of the selected item is written back to the IMAPIProp interface as the value of the property specified by the ulPRSetProperty member in the DTBLLBX structure.

If you need to be able to add or remove items from your list box, using a display table and IMAPISupport::DoConfigPropsheet will not work. Instead, consider implementing a property sheet with the Win32 property sheet API contained in COMDLG32.DLL.