Adding Property Pages
This topic discusses adding property pages to a snap-in using the interfaces and other constructs provided in the MMC SDK.
The MMC SDK defines three main interfaces for working with property pages. Two of these interfaces —IPropertySheetProvider and IPropertySheetCallback— are implemented by MMC and are used to create and maintain property sheet objects. The third interface, IExtendPropertySheet2, is implemented by the snap-in.
The IPropertySheetProvider interface implements property sheets as COM objects.
The following list contains methods included in this interface:
- CreatePropertySheet creates a property sheet frame.
- FindPropertySheet determines whether a property sheet already exists.
- AddPrimaryPages collects pages from a primary snap-in.
- AddExtensionPages collects pages from extension snap-ins.
- Show displays a specific property sheet frame.
MMC uses its own IPropertySheetProvider implementation when it initiates the display of the property sheet — for example, when the user activates the properties verb on an item. If the snap-in wishes to display property sheets at other times, it should call directly into MMC's IPropertySheetProvider. In both cases, the IPropertySheetProvider methods call into the snap-in's IExtendPropertySheet implementation and supply an IPropertySheetCallback interface pointer so that the snap-in can add property pages.
Be aware that MMC owns all property sheets created by its IPropertySheetProvider implementation. Snap-ins own property pages that they add to property sheets, but the property sheet objects themselves are created, maintained, and destroyed by MMC.
The IPropertySheetCallback interface contains two methods. AddPage enables a snap-in to add a single page to the MMC-owned property sheet of a scope or result item. RemovePage enables a snap-in to remove a page.
Generally, if a primary snap-in wants its extendable node types to be extended by property sheet extensions, it should enable the MMC_VERB_PROPERTIES verb for the extendable items, even if it does not add property pages of its own. In addition, the primary snap-in must implement IExtendPropertySheet2 and return S_OK in its implementation of the IExtendPropertySheet2 methods. This allows all property sheet extensions to the selected node type to add their own pages when the user activates the properties verb.
As previously stated, snap-ins can choose to display a property sheet independent of the properties verb. In this case, they must use the IPropertySheetProvider interface. A situation where this can occur is if an extension snap-in wants to display properties for an extendable node type that does not display its own property sheet (via the properties verb). Although this is not recommended (see previous paragraph), it may occur. Now, extension snap-ins cannot enable verbs (such as the properties verb) on the context menus owned by other snap-ins. Extension snap-ins must therefore use the IPropertySheetProvider interface to display a property sheet. See Using IPropertySheetProvider Directly for details.
Similarly, snap-ins must use IPropertySheetProvider to add a feature that has a property sheet as a user interface, but identifies the sheet as something else. An example of this is the Select Computer dialog box. This dialog box appears in the Event Viewer snap-in when the user selects the Event Viewer node and clicks the Connect to another computer context menu item.
Finally, snap-ins (primary and extension) must also use the IPropertySheetProvider interface to display wizards and add pages to them. For more information about adding wizard pages, see Adding Wizard Pages: Implementation Details.
Be aware that each property sheet is modeless and is created in its own thread. MMC does not support marshaling of its published interfaces, so snap-ins cannot call MMC interfaces from within their property page dialog procedure (which executes in the property sheet thread). However, snap-ins can use other techniques, such as posting messages to hidden windows.
Related topics