Introduction

NSIS 2 makes it is possible to create installers with a custom user interface. The Modern UI is an interface with a style like the wizards of recent Windows versions.

This new interface also features new pages (Welcome, Finish, Start Menu) and a description area on the components page. The interface and the graphics can be customized using the provided settings.

Using the Modern UI macros and language files, writing scripts with a modern interface is easy. This document contains information about writing Modern UI scripts and a reference of all settings.

Important: Because the Modern UI has its own macro system, its own default settings and a lot of new features, the interface configuration works differently. So you should not use commands like LicenseText, Icon, CheckBitmap, InstallColors etc.

Screenshots

How to use

The Modern UI has a macro system, so all the code to control the interface has already been written for you.

If you want to start a new Modern UI script or upgrade an older script with the Classic UI, follow the steps below.

Taking a look at the example scripts will also help you to learn more about the Modern UI.

Syntax

Some defines (e.g. MUI_COMPONENTSPAGE_SMALLDESC) don't need a value, they are true/false settings. Others (e.g. MUI_UI) can be used to define a specific value.

Parameters are specified in this format: required (option1 | option2) [optional]

You should put all parameters in one string.

!define MUI_COMPONENTSPAGE_SMALLDESC ;No value
!define MUI_UI "myUI.exe" ;Value
!define MUI_INSTFILESPAGE_COLORS "FFFFFF 000000" ;Multiple settings

If you want a certain value (e.g. a text) to be language-specific, set a language string (using LangString) and define $(STRINGNAME) as value. Use a license language string (LicenseLangString) for the license text.

If you want to add " to a Modern UI string, you should always escape it using $\" because the Modern UI macros use " separate parameters.

1. Header file

!include "MUI.nsh"

MUI.nsh is in the Include directory, so you don't have to specify a path.

2. Interface Settings

Interface settings should be set before inserting page macros. Page interface settings apply to all pages of a certain type.

General Interface Settings

Interface Resource Settings

Welcome/Finish Page Interface Settings

Welcome/Finish Page InstallOptions INI Settings

Uninstaller Welcome/Finish Page Settings

Uninstaller Welcome/Finish Page Interface INI Settings

License Page Interface Settings

Components Page Interface Settings

Installation Page Interface Settings

Installer Finish Page Interface Settings

Uninstaller Finish Page Interface Settings

Abort Warning Settings

Uninstaller Abort Warning Settings

3. Pages

Insert the following macros to set the pages you want to use. The pages will appear in the order you insert them in your script. You can also insert custom Page commands between the macros to add custom pages. More info about custom pages...

You can add multiple pages of certain types (for example, if you want the user to specify multiple folders).

Examples:

!insertmacro MUI_PAGE_LICENSE "License.rtf"
!insertmacro MUI_PAGE_COMPONENTS

Var STARTMENU_FOLDER
!insertmacro MUI_PAGE_STARTMENU "Application" $STARTMENU_FOLDER

You will need the page ID for the Start Menu Folder page when using the Start Menu Folder macros. The Start Menu Folder will be stored in the specified variable.

Installer Pages
MUI_PAGE_WELCOME
MUI_PAGE_LICENSE text/rtf_file
MUI_PAGE_COMPONENTS
MUI_PAGE_DIRECTORY
MUI_PAGE_STARTMENU page_id variable
MUI_PAGE_INSTFILES
MUI_PAGE_FINISH

Uninstaller Pages
MUI_UNPAGE_WELCOME
MUI_UNPAGE_CONFIRM
MUI_UNPAGE_LICENSE text/rtf_file
MUI_UNPAGE_COMPONENTS
MUI_UNPAGE_DIRECTORY
MUI_UNPAGE_INSTFILES
MUI_UNPAGE_FINISH

Page Settings apply to a single page and should be set before inserting a page macro. Example:

;Add a directory page to let the user specify a plug-ins folder
;Store the folder in $PLUGINS_FOLDER

Var PLUGINS_FOLDER
!define MUI_DIRECTORYPAGE_VARIABLE $PLUGINS_FOLDER
!insertmacro MUI_PAGE_DIRECTORY

Page Settings

!insertmacro MUI_STARTMENU_WRITE_BEGIN page_id
  ...create shortcuts...
!insertmacro MUI_STARTMENU_WRITE_END

!insertmacro MUI_STARTMENU_GETFOLDER page_id $R0
  Delete "$SMPROGRAMS\$R0\Your Shortcut.lnk"

4. Custom functions

If you want add your own code to functions inserted by the Modern UI (e.g. the .onGUIInit function and the page functions), create your own function and let the Modern UI functions call them.

More info...

5. Language files

Insert the Modern UI language files for the languages to want to include.

!insertmacro MUI_LANGUAGE "English"

The Modern UI language files load the NLF language files, so you should not use LoadLanguageFile.

Language Selection Dialog

Function .onInit

  !insertmacro MUI_LANGDLL_DISPLAY

FunctionEnd

Function un.onInit

  !insertmacro MUI_UNGETLANGUAGE

FunctionEnd

6. Reserve files

If you are using solid compression (by default, solid compression is enabled for BZip2 and LZMA), it's important that files which are being extracted in init- or page functions function are located before other files in the data block, because this will make your installer faster.

If there are File commands in your sections or functions above the init- or page functions, add the reserve file macros above your sections and functions.

ReserveFile "ioFile.ini" ;Your own InstallOptions INI files
!insertmacro MUI_RESERVEFILE_INSTALLOPTIONS ;InstallOptions plug-in
!insertmacro MUI_RESERVEFILE_LANGDLL ;Language selection dialog

7. Your own sections and functions

Add your installer sections and functions. See the NSIS Users Manual for details.

Information about section code and function code for Start Menu shortcut creation and language selection can be found above.

8. Descriptions for the sections

The descriptions of sections will be displayed on the components page, when the user hovers the mouse over a section. If you don't want to use descriptions, use the MUI_COMPONENTSPAGE_NODESC interface setting.

To set a description for a section, you have to add an additional parameter to the Section commmand with a name for the define that should contain the section number.

Section "Section Name 1" Section1
   ...
SectionEnd

Use these macros to set the descriptions:

LangString DESC_Section1 ${LANG_ENGLISH} "Description of section 1."
LangString DESC_Section2 ${LANG_ENGLISH} "Description of section 2."

!insertmacro MUI_FUNCTION_DESCRIPTION_BEGIN
  !insertmacro MUI_DESCRIPTION_TEXT ${Section1} $(DESC_Section1)
  !insertmacro MUI_DESCRIPTION_TEXT ${Section2} $(DESC_Section2)
!insertmacro MUI_FUNCTION_DESCRIPTION_END

For the uninstaller, use the MUI_UNFUNCTION_DESCRIPTION_BEGIN and MUI_UNFUNCTIONS_DESCRIPTION_END macros:

ReserveFile "ioFile.ini" ;Your own InstallOptions INI files
ReserveFile "${NSISDIR}\Contrib\Graphics\Header\nsis.bmp" ;Your header bitmap

!insertmacro MUI_RESERVEFILE_INSTALLOPTIONS ;InstallOptions
!insertmacro MUI_RESERVEFILE_LANGDLL ;LangDLL (language selection dialog)
!insertmacro MUI_RESERVEFILE_STARTMENU ;Start Menu Folder page

Custom pages

Custom page commands

If you want add custom pages to your installer, you should insert your own page commands between the page macros.

!insertmacro MUI_PAGE_WELCOME
Page custom FunctionName ;Custom page
!insertmacro MUI_PAGE_COMPONENTS

;Uninstaller
!insertmacro MUI_UNPAGE_CONFIRM
UninstPage custom un.FunctionName ;Custom page
!insertmacro MUI_UNPAGE_INSTFILES

Call InstallOptions

InstallOptions is a plug-in that displays custom pages that you can create using INI files.

Have a look at the InstallOptions documentation for info about creating InstallOptions INI files.

First, you have to extract your InstallOptions INI File in the .onInit function (un.onInit for the uninstaller) using the MUI_INSTALLOPTIONS_EXTRACT macro.

Function .onInit
  !insertmacro MUI_INSTALLOPTIONS_EXTRACT "ioFile.ini"
FunctionEnd

If your INI File is located in another directory, use MUI_INSTALLOPTIONS_EXTRACT_AS. The second parameter is the filename for the temporary plug-ins directory, use this filename as parameter for the other InstallOptions macros.

Function .onInit
  !insertmacro MUI_INSTALLOPTIONS_EXTRACT_AS "..\ioFile.ini" "ioFile.ini"
FunctionEnd

You can call Instal Options in the function defined with the Page or UninstPage command using the MUI_INSTALLOPTIONS_DISPLAY macro. Use the MUI_HEADER_TEXT macro to set the text in the white box.

LangString TEXT_IO_TITLE ${LANG_ENGLISH} "Install Options Page Title"
LangString TEXT_IO_SUBTITLE ${LANG_ENGLISH} "A subtitle"

Function FunctionName ;FunctionName defined with Page command
  !insertmacro MUI_HEADER_TEXT "$(TEXT_IO_TITLE)" "$(TEXT_IO_SUBTITLE)"
  !insertmacro MUI_INSTALLOPTIONS_DISPLAY "ioFile.ini"
FunctionEnd

For custom fonts and colors, macros for the initDialog and show functions of InstallOptions are also available.

Var HWND
Var DLGITEM
Var FONT

LangString TEXT_IO_TITLE ${LANG_ENGLISH} "Install Options Page Title"
LangString TEXT_IO_SUBTITLE ${LANG_ENGLISH} "A subtitle"

Function FunctionName ;FunctionName defined with Page command

  !insertmacro MUI_HEADER_TEXT "$(TEXT_IO_TITLE)" "$(TEXT_IO_SUBTITLE)"

  !insertmacro MUI_INSTALLOPTIONS_INITDIALOG "ioFile.ini"
  Pop $HWND ;HWND of dialog
    
  GetDlgItem $DLGITEM $HWND 1200 ;1200 + Field number - 1
    
  ;$DLGITEM contains the HWND of the first field
  CreateFont $FONT "Tahoma" 10 700 
  SendMessage $DLGITEM ${WM_SETFONT} $FONT 0
        
  !insertmacro MUI_INSTALLOPTIONS_SHOW

FunctionEnd

If you need the InstallOptions return value (success, back, cancel, error), use the MUI_INSTALLOPTIONS_DISPLAY_RETURN or MUI_INSTALLOPTIONS_SHOW_RETURN macro. The return value will be added to the stack, so you can use the Pop command to get it.

Use these macros to read or write INI file values:

!insertmacro MUI_INSTALLOPTIONS_READ $VAR "ioFile.ini" "Field #" "Value Name"
!insertmacro MUI_INSTALLOPTIONS_WRITE "ioFile.ini" "Field #" "Value Name" "Value"

For example, you can use the MUI_INSTALLOPTIONS_READ macro in a section to get the user input:

!insertmacro MUI_INSTALLOPTIONS_READ $R0 "ioFile.ini" "Field 1" "State"

For more details about InstallOptions, validation of user input etc., check the InstallOptions documentation.

Examples

Basic: Basic.nsi
Welcome/Finish page: WelcomeFinish.nsi
Multiple languages: MultiLanguage.nsi
Header image: HeaderBitmap.nsi
Custom pages: InstallOptions.nsi
Start Menu Folder page: StartMenu.nsi

Customize the dialogs

To change elements on the dialogs, use customized UI resource files (see Interface settings). You can change your copies of the original files (in the Contrib\UIs folder) by using an application such as Resource Hacker.

The 'Please wait while Setup is loading...' text on the splash screen that is being displayed while the installer is starting (Verifying installer, Unpacking data) can be changed by using a customized UI resource file (MUI_UI setting) with a modified dialog 111.
The 'Verifying installer' and 'Unpacking data' texts are defined in the language header file of the NSIS exehead (Source\exehead\lang.h). To change them, you have to edit this file and recompile NSIS.

To modify the Welcome dialog and Finish dialog, use a custom INI file (MUI_SPECIALINI setting) or write to the INI file in the custom page functions.

Customize Modern UI Functions

If you want add your own code to functions inserted by the Modern UI, such as the .onGUIInit function and the Page functions, create your own function and let the Modern UI functions call them. Use the defines to define the name of your functions.

Example:

!define MUI_CUSTOMFUNCTION_GUIINIT myGuiInit

Function myGUIInit
  ...your own code...
FunctionEnd

General Custom Functions

Page Custom Functions

Version history

• 1.68 - November 24, 2003
  • New settings for extra space for title and text on Welcome page and Finish page
  • Improved handling of verbose settings. Define MUI_VERBOSE the set the Modern UI verbose level (1-4).
  • Language file string for uninstaller reboot information
  • Setting for folder validation in leave function
  • Fixed finish page text settings for multiple pages

Complete version history

Credits

Made by Joost Verburg.
Icons designed by Nikos Adamamas, aka adni18.
Thanks to Amir Szekely, aka KiCHiK, for his work on NSIS to make this possible.

Help

Please post questions at the NSIS Forum.

License

Copyright © 2002-2003 Joost Verburg

This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute
it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; 
   you must not claim that you wrote the original software.
   If you use this software in a product, an acknowledgment in the
   product documentation would be appreciated but is not required.
2. Altered versions must be plainly marked as such,
   and must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any distribution.