The built-in WixUI dialog sets can be customized in order to provide product-specific license agreement files and bitmaps. In addition, dialogs can be inserted into the wizard sequences for any of the built-in dialog sets.
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" />Alternatively, you can define the variable using the -d switch when running light:
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.
There is a known issue with the rich text control used to display the text of the license file that can cause the text to appear blank until the user scrolls down in the control. This is typically caused by complex RTF content (such as the RTF generated when saving an RTF file in Microsoft Word). If you run into this behavior in your setup UI, one of the following workarounds will fix it in most cases:
The WixUI dialog library includes default bitmaps for the background of the welcome and installation complete dialogs and the top banner of the other dialogs. You can replace those bitmaps with your own for product branding purposes. To replace default bitmaps, specify WiX variable values with the file names of your bitmaps, just like 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 built-in WixUI dialog sets by adding and removing dialogs in the wizard sequence. Let's start with some background on how the default dialog sets are built. WixUIExtension includes a library of many WiX fragments containing dialog UIs. Each set is defined in 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 built-in 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 do not need to rebuild WixUIExtension to customize the WixUI dialog sets in this manner. All you need to do is compile your dialog fragment and your custom set fragment with the rest of your setup project. As long as you continue using the WixUIExtension, your custom fragments will be able to find the built-in dialog fragments.
The final page used in the standard dialog sets supports an optional checkbox. For an example of using this checkbox see How To: Run the Installed Application After Setup.