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.

Note: The WixUI dialog library is currently at technical preview status. Please provide feedback on the WiX-devs mailing list. Are the provided stock dialog sets useful? Do you have suggestions for others? Hate the UI? Need another dialog? Based on feedback, the WixUI library might change in incompatible ways.

Using the stock dialog sets

The WixUI stock dialog sets support several common dialog sequences:

• WixUI_Mondo includes the full set of dialogs (hence "Mondo"): welcome, license agreement, setup type (typical, custom, and complete), feature customization, directory browse, and disk cost. Maintenance-mode dialogs are also included. Use WixUI_Mondo when you have some of your product's features aren't installed by default and there's a meaningful difference between typical and complete installs.

  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.

• WixUI_FeatureTree is a simpler version of WixUI_Mondo that omits the setup type dialog. Instead, the user goes directly from the license agreement dialog to the feature customization dialog. WixUI_FeatureTree is more appropriate than WixUI_Mondo when your product installs all features by default.
• WixUI_InstallDir doesn't allow the user to choose features but adds a dialog to let the user choose a directory where the product will be installed.

  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. For example:

  <Directory Id="TARGETDIR" Name="SourceDir">
    <Directory Id="ProgramFilesFolder" Name="PFiles">
      <Directory Id="TESTFILEPRODUCTDIR" ShortName="WIXTEST" Name="Test File">
        ...
      </Directory>
     </Directory>
  </Directory>
  ...
  <Property Id="WIXUI_INSTALLDIR" Value="TESTFILEPRODUCTDIR" />
  <UIRef Id="WixUI_InstallDir" />

• WixUI_Minimal is the most spartan of the WixUI stock dialog sets. Its sole dialog combines the welcome and license-agreement dialogs and omits the feature customization dialog. WixUI_Minimal is appropriate when your product has no optional features.

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 wixui.wixlib and the appropriate WixUI localization file to your light command line. For example:

   light Mondo.wixobj %WIXUI_PATH%\WixUI.wixlib -loc %WIXUI_PATH%\WixUI_en-us.wxl -out Mondo.msi

For examples, see the .wxs files in the doc/examples/wixui directory.

Specifying a license file

The stock dialog sets have a dialog that displays an end-user license agreement (EULA). To specify your product's license, include a License.rtf file in the current directory when you run light. If there isn't such a file, light uses the License.rtf file in the ui directory.

Using translated error and progress text

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

<UIRef Id="WixUI_Minimal" />
<UIRef Id="WixUI_ErrorProgressText" />

Customizing dialog sets

You can most easily add and remove dialogs from the stock dialog sets by copying one of the existing sets and modifying it. For an example, see the project in the doc/examples/wixui/custom directory. The following table describes the files:

File name	Description
CustomDialogSet.build	NAnt build file to build the custom dialog set. Builds the WixUI common dialog elements if needed, then builds CustomDialogSet.wxs and CustomDlg.wxs to create CustomDialogSet.wixlib.
CustomDialogSet.wxs	Custom dialog set definition. Copied from WixUI_FeatureTree set and modified to add CustomDlg after the initial WelcomeDlg.
CustomDlg.wxs	Simple custom dialog.
TestCustom.wxs	WiX source code that consumes CustomDialogSet.wixlib.

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 "override" those graphics with your own for product-branding purposes. To replace stock bitmaps, add the files from the table below to a subdirectory named Bitmaps under your WiX source file.

File name	Description	Dimensions
bannrbmp.bmp	Top banner	500 × 63
dlgbmp.bmp	Background bitmap used on welcome and install-complete dialogs	503 × 314
exclamic.ico	Exclamation icon on the wait-for-costing dialog	32 × 32
info.ico	Information icon on the cancel and error dialogs	32 × 32
New.ico	Button glyph on directory-browse dialog	16 × 16
Up.ico	Button glyph on directory-browse dialog	16 × 16