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:

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>
  1. 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