How-To Add Property Pages
Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista
A property page is a window that allows the user to view and edit the properties of an item. An item can have one or more property pages attached to it. A property sheet is a collection of property pages. Each property page typically contains window controls for setting a group of related properties. Property pages are displayed as overlapping child windows in the property sheet. Each page has a tab that the user can click to bring the page to the foreground of the property sheet.
MMC allows primary and extension snap-ins to add property pages to a property sheet. To access the property page of an item the user selects a scope node or a result node, and then clicks the Properties standard verb. Property pages are initiated by MMC by using the Properties standard verb. Another way to initiate a property sheet is by defining a specific action in the snap-in. This action requests MMC to present a property sheet when it is invoked. Property sheets that are initiated by actions are referred to as snap-in initiated property pages. It is common for snap-ins to show property sheets and enable the Properties standard verb. MMC manages the property sheet overhead, thus allowing developers to focus on creating the logic of their property pages.
Each property page is inherited from the PropertyPage class and is the container for a control that represents the actual user interface to be shown. In the implementation of the OnAddPropertyPages method, the developer can composite the property pages and the controls that they contain, and add them to the PropertyPageCollection object that is passed into the method.
MMC compares the SelectionObject to the existing property sheets to see if a property sheet is already open for the selection. If a property sheet is already open, MMC brings the existing property sheet to the front instead of creating a new one.
Property sheet events
Each property page must load its own information, track its own state, and be able to respond to the following virtual events at the property sheet level that are passed to every property page in the property sheet:
OnApply
Sent to every page in the property sheet to indicate that the user has clicked the Apply button and wants all changes to take effect.OnCancel
Indicates that the user has clicked the Cancel button, and the property sheet is about to be destroyed.OnDestroy
Notifies a page that the property sheet is getting destroyed. The snap-in can use this notification message as an opportunity to perform clean-up operations.OnInitialize
Notifies the page for initialization. The default implementation is empty.OnKillActive
Notifies a page that it is about to lose activation either because another page is being activated, or the user has clicked the OK button. The default implementation allows page to be deactivated.OnOK
Sent to every page in the property sheet to indicate that the user has clicked the OK or Close button and wants all changes to take effect.OnSetActive
Notifies a page that it is about to be activated. The default implementation allows a page to be activated.QueryCancel
Indicates that the user wants to cancel the property sheet. The default implementation allows a Cancel operation.
Notes for Implementers
MMC creates property sheets as modeless dialogs. The window owner of a property sheet is the desktop and the z-order on the screen is not managed by MMC, but managed by Windows instead. Property sheets do not have a presence on the taskbar and do not show up in the MMC open windows list. Unfortunately, property sheets are easily hidden behind other windows. Selecting another results pane item in MMC can bring the MMC console window in front of an open property sheet. Because of this behavior, as the snap-in developer, you should design your user interface in such a way that a user is encouraged to close a property sheet before clicking anywhere else.