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.
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. 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" />
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 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.
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.
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" />
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. |
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 |