Adding Wizard Pages: Implementation Details

  • Article

The procedures in this topic describe how to create and add wizard pages to your snap-in. To add standard property pages, see Adding Property Pages: Implementation Details.

To add Wizard pages

  1. Implement a procedure, for example a function called InvokeWizardSheet, that is called when the user performs an action that causes the snap-in to invoke the wizard.

  2. In InvokeWizardSheet, call the IPropertySheetProvider::CreatePropertySheet method to create a wizard. Ensure that the type parameter passed in the call is set to FALSE (for wizard).

  3. In InvokeWizardSheet, call the IPropertySheetProvider::AddPrimaryPages method. In the call to AddPrimaryPages:

    • If the wizard sheet is for a scope item, set bScopePane to TRUE. Otherwise, set this parameter to FALSE.
    • If the snap-in should receive notifications via the MMCN_PROPERTY_CHANGE notification when the user changes any wizard properties, set the bCreateHandle parameter to TRUE.
    • If bCreateHandle is set to TRUE, the snap-in must implement either IComponent (if bScopePane == FALSE) or IComponentData (if bScopePane == TRUE) and handle the MMCN_PROPERTY_CHANGE notification in its IComponent::Notify (or IComponentData::Notify) implementation. The lpUnknown parameter should be a pointer to the IComponent (or IComponentData) object that receives the MMCN_PROPERTY_CHANGE notification.

    In the MMC AddPrimaryPages implementation, MMC calls back to the snap-in IExtendPropertySheet2::CreatePropertyPages method.

  4. In InvokeWizardSheet, call IPropertySheetProvider::Show to display the wizard.

  5. Implement the IExtendPropertySheet2::CreatePropertyPages method in the appropriate IComponentData or IComponent implementation to add pages to the wizard.

    In the implementation of CreatePropertyPages:

    • If you set bCreateA handle to TRUE in the call to IPropertySheetProvider::AddPrimaryPages in Step 3, the handle parameter holds the handle value that the snap-in requires to specify in any future calls to MMCPropertyChangeNotify. The snap-in should cache this value for future use.
    • Define one or more wizard pages by filling the PROPSHEETPAGE structure for each of the pages with information about the page. Be aware that the standard size for a property page in an MMC console is 252 dialog units horizontally and 218 dialog units vertically.
    • For each PROPSHEETPAGE structure, call the API function CreatePropertySheetPage to create a page. The function returns a handle to the HPROPSHEETPAGE type that uniquely identifies the page.
    • Using the pointer to the IPropertySheetCallback interface passed to the snap-in in the call to the CreatePropertyPages method, call the IPropertySheetCallback::AddPage method to add each page to the wizard.

  6. Implement a dialog box procedure for each page. The pfnDlgProc member of each page's PROPSHEETPAGE structure should be set to the address of this procedure.

  7. The snap-in should call the MMCPropertyChangeNotify function if the user has changed any wizard properties. As a result of this method call, an MMCN_PROPERTY_CHANGE notification is sent to the appropriate IComponent or IComponentData object. The snap-in should be prepared to handle this notification.

To add wizard pages with the Wizard 97 style, follow the previous procedure for adding wizard pages. In addition to the Steps in that procedure:

To add wizard pages with the Wizard 97 style

  1. In the call to the IPropertySheetProvider::CreatePropertySheet method, set the dwOptions parameter to MMC_PSO_NEWWIZARDTYPE. This specifies the Wizard 97 style.
  2. Implement the IExtendPropertySheet2::GetWatermarks method to specify the watermark and header bitmaps for the wizard.
  3. By setting the pszHeaderTitle and pszHeaderSubTitle members of the PROPSHEETPAGE structure, you can specify the header title and subtitle text for interior Wizard 97 pages.

To add Wizard 97 style pages without watermarks and header bitmaps, follow the instructions in "To add wizard pages with the Wizard 97 style". In the snap-in's implementation of IExtendPropertySheet2::GetWatermarks, return a success code (for example, S_OK or S_FALSE) without providing any bitmaps.

Be aware that if GetWatermarks is not implemented or returns a failure code, MMC reverts the wizard requested by the snap-in in the call to IPropertySheetProvider::CreatePropertySheet to the non-Wizard 97 style. This is to maintain compatibility with MMC 1.1.

Adding Wizard Pages: Interfaces

Adding Watermarks to Wizard 97 Pages

Adding Wizard Pages