The WiX toolset ships with several User Interface wizards that are ready to use out of the box. We’ll briefly discuss each of the available sets and then move on to learning how to create your own from scratch. In this article by Nick Ramirez, author of the book WiX: A Developer’s Guide to Windows Installer XML, you’ll learn about:

• Adding dialogs into the InstallUISequence
• Linking one dialog to another to form a complete wizard
• Getting basic text and window styling working
• Including necessary dialogs like those needed to display errors

(For more resources on WiX, see here.)

WiX standard dialog sets

The wizards that come prebuilt with WiX won’t fit every need, but they’re a good place to get your feet wet. To add any one of them, you first have to add a project reference to WixUIExtension.dll, which can be found in the bin directory of your WiX program files.

Adding this reference is sort of like adding a new source file. This one contains dialogs. To use one, you’ll need to use a UIRef element to pull the dialog into the scope of your project. For example, this line, anywhere inside the Product element, will add the “Minimal” wizard to your installer:

<UIRef Id=”WixUI_Minimal” />

It’s definitely minimal, containing just one screen.

It gives you a license agreement, which you can change by adding a WixVariable element with an Id of WixUILicenseRtf and a Value attribute that points to a Rich Text Format (.rtf) file containing your new license agreement:

<WixVariable Id=”WixUILicenseRtf”
Value=”newLicense.rtf” />

You can also override the background image (red wheel on the left, white box on the right) by setting another WixVariable called WixUIDialogBmp to a new image. The dimensions used are 493×312. The other available wizards offer more and we’ll cover them in the following sections.

WixUI_Advanced

The “Advanced” dialog set offers more: It has a screen that lets the user choose to install for just the current user or for all users, another where the end user can change the folder that files are installed to and a screen with a feature tree where features can be turned on or off. As in the following screenshot:

You’ll need to change your UIRef element to use WixUI_Advanced. This can be done by adding the following line:

<UIRef Id=”WixUI_Advanced” />

You’ll also have to make sure that your install directory has an Id of APPLICATIONFOLDER, as in this example:

<Directory Id=”TARGETDIR”
Name=”SourceDir”>
<Directory Id=”ProgramFilesFolder”>
<Directory Id=”APPLICATIONFOLDER”
Name=”My Program” />
</Directory>
</Directory>

Next, set two properties: ApplicationFolderName and WixAppFolder. The first sets the name of the install directory as it will be displayed in the UI. The second sets whether this install should default to being per user or per machine. It can be either WixPerMachineFolder or WixPerUserFolder.

<Property Id=”ApplicationFolderName”
Value=”My Program” />
<Property Id=”WixAppFolder”
Value=”WixPerMachineFolder” />

This dialog uses a bitmap that the Minimal installer doesn’t: the white banner at the top. You can replace it with your own image by setting the WixUIBannerBmp variable. Its dimensions are 493×58. It would look something like this:

<WixVariable Id=”WixUIBannerBmp”
Value=”myBanner.bmp” />

WixUI_FeatureTree

The WixUI_FeatureTree wizard shows a feature tree like the Advanced wizard, but it doesn’t have a dialog that lets the user change the install path. To use it, you only need to set the UIRef to WixUI_FeatureTree, like so:

<UIRef Id=”WixUI_FeatureTree” />

This would produce a window that would allow you to choose features as show in the following screenshot:

Notice that in the image, the Browse button is disabled. If any of your Feature elements have the ConfigurableDirectory attribute set to the Id of a Directory element, then this button will allow you to change where that feature is installed to. The Directory element’s Id must be all uppercase.

WixUI_InstallDir

WixUI_InstallDir shows a dialog where the user can change the installation path. Change the UIRef to WixUI_InstallDir. Like so:

<UIRef Id=”WixUI_InstallDir” />

Here, the user can chose the installation path. This is seen in the following screenshot:

You’ll have to set a property called WIXUI_INSTALLDIR to the Id you gave your install directory. So, if your directory structure used INSTALLLDIR for the Id of the main install folder, use that as the value of the property.

<Directory Id=”TARGETDIR”
Name=”SourceDir”>
<Directory Id=”ProgramFilesFolder”>
<Directory Id=”INSTALLDIR”
Name=”My Program” />
</Directory>
</Directory>

<Property Id=”WIXUI_INSTALLDIR”
Value=”INSTALLDIR” />

WixUI_Mondo

The WixUI_Mondo wizard gives the user the option of installing a “Typical”, “Complete” or “Custom” install. Typical sets the INSTALLLEVEL property to 3 while Complete sets it to 1000. You can set the Level attribute of your Feature elements accordingly to include them in one group or the other. Selecting a Custom install will display a feature tree dialog where the user can choose exactly what they want. To use this wizard, change your UIRef element to WixUI_Mondo.

<UIRef Id=”WixUI_Mondo” />

This would result in a window like the following: