Using the WixUI dialog library

The WixUI dialog library contains a set of "stock" dialogs providing the familiar wizard-style setup user interface. Several stock dialog sets are supported -- use one UIRef to add a user interface to your setup. WixUI is also customizable, from the bitmaps shown in the UI to adding and removing custom dialogs.

Using the stock dialog sets

The WixUI stock dialog sets support several common dialog sequences:

How to add a WixUI stock dialog set to a product installer

Assuming you have an existing installer that's functional but just lacking a user interface, here are the steps you need to follow to use a WixUI stock dialog set:

  1. Add a UIRef element to your installer source code, using an Id attribute of one of the above dialog sets. For example:
    <Product ...>
    <UIRef Id="WixUI_InstallDir" />
    </Product>
  2. Add the WixUIExtension extension with the appropriate culture switch to your light command line. For example:
    light -ext WixUIExtension -cultures:en-us Product.wixobj -out Product.msi

Specifying a license file

WixUIExtension.dll includes a default, placeholder license agreement. To specify your product's license, override the default by specifying a WiX variable named WixUILicenseRtf with the value of an RTF file that contains your license text. You can define the variable in your WiX authoring:

<WixVariable Id="WixUILicenseRtf" Value="bobpl.rtf" />
or at the light command line:
light -ext WixUIExtension -cultures:en-us -dWixUILicenseRtf=bobpl.rtf Product.wixobj -out Product.msi
The file you specify must be in a directory light is looking in for files. Use the -b switch to add directories.

Using translated error and progress text

By default, WixUI doesn't include any translated Error or ProgressText elements. You can include them by referencing the WixUI_ErrorProgressText UI element:

<UIRef Id="WixUI_ErrorProgressText" />

Replacing the stock bitmaps

The WixUI dialog library includes stock bitmaps for the background of the welcome and installation-complete dialogs and the top banner of the other dialogs. You can replace those graphics with your own for product-branding purposes. To replace stock bitmaps, specify WiX variable values with the file names of your bitmaps, as when replacing the default license text.

Variable name Description Dimensions
WixUIBannerBmp Top banner 493 × 58
WixUIDialogBmp Background bitmap used on welcome and install-complete dialogs 493 × 312
WixUIExclamationIco Exclamation icon on the wait-for-costing dialog 32 × 32
WixUIInfoIco Information icon on the cancel and error dialogs 32 × 32
WixUINewIco Button glyph on directory-browse dialog 16 × 16
WixUIUpIco Button glyph on directory-browse dialog 16 × 16

Customizing dialog sets

You can customize the stock dialog sets by adding and removing dialogs in the wizard sequence. Let's start with some background on how the stock sets are built. WixUIExtension includes a library of many WiX fragments containing dialog UIs. Each set is its own fragment that references the dialog fragments and publishes control events for them -- mostly the Back and Next buttons. Changing the Back/Next sequence requires replacing the stock control events with ones matching the dialogs you want to use. For example, the WixUI_InstallDir control events for the first two dialogs look like this:

<Publish Dialog="WelcomeDlg" Control="Next" Event="NewDialog" Value="LicenseAgreementDlg">1</Publish>
<Publish Dialog="LicenseAgreementDlg" Control="Back" Event="NewDialog" Value="WelcomeDlg">1</Publish>
<Publish Dialog="LicenseAgreementDlg" Control="Next" Event="NewDialog" Value="InstallDirDlg">LicenseAccepted = "1"</Publish>

You could insert a dialog between WelcomeDlg and LicenseAgreementDlg by changing the control events for the Back and Next buttons of the dialogs before and after the one you want to add. For example:

<Publish Dialog="WelcomeDlg" Control="Next" Event="NewDialog" Value="SpecialDlg">1</Publish>
<Publish Dialog="SpecialDlg" Control="Back" Event="NewDialog" Value="WelcomeDlg">1</Publish>
<Publish Dialog="SpecialDlg" Control="Next" Event="NewDialog" Value="LicenseAgreementDlg">1</Publish>
<Publish Dialog="LicenseAgreementDlg" Control="Back" Event="NewDialog" Value="SpecialDlg">1</Publish>
<Publish Dialog="LicenseAgreementDlg" Control="Next" Event="NewDialog" Value="InstallDirDlg">LicenseAccepted = "1"</Publish>

You don't need to rebuild WixUIExtension to customize the WixUI dialog sets. Compile your dialog fragment and your custom set fragment with the rest of your setup project. Continue using WixUIExtension so your fragments can find the stock dialog fragments.