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.
The WixUI stock dialog sets support several common dialog sequences:
Note: WixUI_Mondo uses SetInstallLevel control events to set the install level when the user chooses Typical or Complete. For Typical, the install level is set to 3; for Complete, 1000. For details about feature levels and install levels, see INSTALLLEVEL Property.
Note: To use WixUI_InstallDir, you must set a property named WIXUI_INSTALLDIR with a value of the ID of the directory you want the user to be able to specify the location of. Note that the directory ID must be all uppercase characters, as it must be passed from the UI to the execute sequence to take effect. For example:
<Directory Id="TARGETDIR" Name="SourceDir"> <Directory Id="ProgramFilesFolder" Name="PFiles"> <Directory Id="TESTFILEPRODUCTDIR" Name="Test File"> ... </Directory> </Directory> </Directory> ... <Property Id="WIXUI_INSTALLDIR" Value="TESTFILEPRODUCTDIR" /> <UIRef Id="WixUI_InstallDir" />
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:
<Product ...> <UIRef Id="WixUI_InstallDir" /> </Product>
light -ext WixUIExtension -cultures:en-us Product.wixobj -out Product.msi
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.msiThe file you specify must be in a directory light is looking in for files. Use the -b switch to add directories.
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" />
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 |
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.