Taking a look at the example scripts will also help you to learn more about the Modern UI.
Syntax
-Most defines (i.e. MUI_COMPONENTSPAGE_SMALLDESC) don't need a value, they are true/false settings. - Others (i.e. MUI_FINISHPAGE_RUN) can be used to define a specific - value.
+Some defines (i.e. MUI_COMPONENTSPAGE_SMALLDESC) don't need a value, they are true/false settings. + Others (i.e. 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 for the define:
+You should put all parameters in one string.
!define MUI_STARTMENUPAGE_NODISABLE ;No value !define MUI_FINISHPAGE_RUN "$INSTDIR\Application.exe" ;Value -!define MUI_INSTALLCOLORS "FFFFFF 000000" ;Multiple settings !define MUI_LICENSEPAGE_TEXT '"Text"' ;Text !define MUI_LICENSEPAGE_TEXT '"Text" "Buttontext"' ;Multiple texts +!define MUI_INSTFILESPAGE_COLORS "FFFFFF 000000" ;Multiple settings
If you want a certain value (i.e. a text) to be language-specific, set a language string (using LangString) - and define $(LANGUAGESTRINGNAME) as value. Use a license language string (LicenseLangString) for the license text.
+ and define $(STRINGNAME) as value. Use a license language string (LicenseLangString) for the license text.When adding " to a Modern UI string, you should always escape it ($\"), because the Modern UI macros use " to separate parameters. If you want to set texts like above you have to escape both " and ' (using $\" and $\').
1. Include the header file
!include "MUI.nsh"-
MUI.nsh is in the Include directory, so you don't have +
MUI.nsh is in the Include directory, so you don't have to specify a path.
-2. Pages
+2. Interface Settings
+Page interface settings apply to all pages of a certain type.
+General Interface Settings
+For UI elements that are enabled by default, the default value will be used when a setting + has not been defined.
+MUI_UI ui_file
+ The interface file with the dialog resources. Change this if you have made your own customized UI.
+ Default: ${NSISDIR}\Contrib\UIs\modern.exe
MUI_UI_HEADERBITMAP ui_file
+ MUI_UI_HEADERBITMAP_RIGHT ui_file
+ The interface files with the dialog resource IDD_INST that contains a bitmap control and space for
+ the header bitmap.
Defaults: ${NSISDIR}\Contrib\UIs\modern-headerbmp.exe,
+ ${NSISDIR}\Contrib\UIs\modern-headerbmpr.exe
MUI_UI_SMALLDESCRIPTION
MUI_UI_NODESCRIPTION
+ The interface files with a customized dialog resource IDD_SELCOM for a small or no description area.
+ Defaults: {NSISDIR}\Contrib\UIs\modern-smalldesc.exe, {NSISDIR}\Contrib\UIs\modern-nodesc.exe
MUI_ICON icon_file
+ The icon of the installer.
Default: ${NSISDIR}\Contrib\Graphics\Icons\modern-install.ico
MUI_UNICON icon_file
+ The icon of the uninstaller.
Default: ${NSISDIR}\Contrib\Graphics\Icons\modern-uninstall.ico
MUI_CHECKBITMAP bitmap_file
+ The bitmap with images for the checks of the component select treeview.
+ Default: ${NSISDIR}\Contrib\Graphics\Checks\modern.bmp
MUI_HEADERBITMAP bmp_file
+ Bitmap to display in the white header (recommended size: 150x57 pixels). The NSIS Setup uses the bitmap
+ ${NSISDIR}\Contrib\Graphics\Header\nsis.bmp, but can also make one with your own logo.
MUI_HEADERBITMAP_RIGHT
+ Display the header image on the right side instead of the left side.
MUI_HEADERBITMAP_NOSTRETCH
+ Do not stretch the header bitmap to fit the size of the field. Use this option only if you have an
+ image that does not use the whole space. If you have a full size bitmap that fits exactly, you should
+ not use this option because the size of the field will be different if the user has a custom DPI setting.
MUI_SPECIALINI ini_file
+ InstallOptions INI file for the Welcome and Finish page.
+ Default: ${NSISDIR}\Contrib\Modern UI\ioSpecial.ini
MUI_SPECIALBITMAP bmp_file
+ Bitmap for the Welcome and Finish page (recommended size: 164x314 pixels).
+ Default: ${NSISDIR}\Contrib\Graphics\Wizard\win.bmp
MUI_SPECIALBITMAP_NOSTRETCH
+ Do not stretch the bitmap for the Welcome and Finish page to fit the size of the field.
+ Use this option only if you have an image that does not use the whole space. If you have a full size
+ bitmap that fits exactly, you should not use this option because the size of the field will be different
+ if the user has a custom DPI setting.
MUI_BGCOLOR (color: RRGGBBR hexadecimal)
+ Background color for the header, Welcome- and Finish page.
Default: FFFFFF
License Page Interface Settings
+MUI_LICENSEPAGE_BGCOLOR
+ (/windows | /grey | (color: RRGGBB hexadecimal))
+ The background color for the license textbox. Use /windows for the default text background (usually white).
+ Use the /grey for the standard window background (usually grey).
Default: /windows
Components Page Interface Settings
+MUI_COMPONENTSPAGE_SMALLDESC
+ A small description area on the bottom of the page. Use this layout
+ if you have a lot of sections and don't need large descriptions.
MUI_COMPONENTSPAGE_NODESC
+ No description area.
Installation Page Interface Settings
+MUI_INSTFILESPAGE_COLORS (/windows |
+ (foreground color: RRGGBB hexadecimal) (background color: RRGGBB hexadecimal))
+ The colors of the details screen. Use /windows for the default colors.
MUI_INSTFILESPAGE_PROGRESSBAR ("" | colored | smooth)
+ The style of the progress bar. Colored makes it use the MUI_INSTALLCOLORS.
Default: smooth
Finish Page Interface Settings
+MUI_FINISHPAGE_NOAUTOCLOSE
+ Do not automatically jump to the finish page, to allow the user to
+ check the log.
Abort Warning Message Settings
+MUI_ABORTWARNING
+ Show a message box with a warning when the user wants to close the installer.
MUI_ABORTWARNING_TEXT text
+ Texts to display next to the abort warning messagebox.
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. @@ -355,10 +441,9 @@ will also help you to learn more about the Modern UI.
MUI_FINISHPAGE_LINK_LOCATION file/url
Website or file which the user can select to view using the link.
You don't need to put quotes around the filename when it contains spaces.
MUI_FINISHPAGE_LINK_COLOR (color: 0xBBGGRR hexadecimal)
+ Text color for the link on the Finish page.
Default: 0x800000
MUI_FINISHPAGE_NOAUTOCLOSE
- Do not automatically jump to the finish page, to allow the user to
- check the log.
MUI_FINISHPAGE_NOREBOOTSUPPORT
Disables support for the page that allows the user to reboot the system.
Define this option to save some space if you are not using the /REBOOTOK
@@ -375,99 +460,20 @@ will also help you to learn more about the Modern UI.
3. Interface Settings
-Page interface settings apply to all pages of a certain type.
-General Interface Settings
-For UI elements that are enabled by default, the default value will be used when a setting - has not been defined.
-MUI_UI ui_file
- The interface file with the dialog resources. Change this if you have made your own customized UI.
- Default: ${NSISDIR}\Contrib\UIs\modern.exe
MUI_UI_HEADERBITMAP ui_file
- MUI_UI_HEADERBITMAP_RIGHT ui_file
- The interface files with the dialog resource IDD_INST that contains a bitmap control and space for
- the header bitmap.
Defaults: ${NSISDIR}\Contrib\UIs\modern-headerbmp.exe,
- ${NSISDIR}\Contrib\UIs\modern-headerbmpr.exe
MUI_UI_SMALLDESCRIPTION
MUI_UI_NODESCRIPTION
- The interface files with a customized dialog resource IDD_SELCOM for a small or no description area.
- Defaults: {NSISDIR}\Contrib\UIs\modern-smalldesc.exe, {NSISDIR}\Contrib\UIs\modern-nodesc.exe
MUI_ICON icon_file
- The icon of the installer.
Default: ${NSISDIR}\Contrib\Graphics\Icons\modern-install.ico
MUI_UNICON icon_file
- The icon of the uninstaller.
Default: ${NSISDIR}\Contrib\Graphics\Icons\modern-uninstall.ico
MUI_LICENSEBKCOLOR
- (/windows | /grey | (color: RRGGBB hexadecimal))
- The background color for the license textbox. Use /windows for the default text background (usually white).
- Use the /grey for the standard window background (usually grey).
Default: /windows
MUI_CHECKBITMAP bitmap_file
- The bitmap with images for the checks of the component select treeview.
- Default: ${NSISDIR}\Contrib\Graphics\Checks\modern.bmp
MUI_INSTALLCOLORS (/windows |
- (foreground color: RRGGBB hexadecimal) (background color: RRGGBB hexadecimal))
- The colors of the details screen. Use /windows for the default colors.
MUI_PROGRESSBAR ("" | colored | smooth)
- The style of the progress bar. Colored makes it use the MUI_INSTALLCOLORS.
Default: smooth
MUI_HEADERBITMAP bmp_file
- Bitmap to display in the white header (recommended size: 150x57 pixels). The NSIS Setup uses the bitmap
- ${NSISDIR}\Contrib\Graphics\Header\nsis.bmp, but can also make one with your own logo.
MUI_HEADERBITMAP_RIGHT
- Display the header image on the right side instead of the left side.
MUI_HEADERBITMAP_NOSTRETCH
- Do not stretch the header bitmap to fit the size of the field. Use this option only if you have an
- image that does not use the whole space. If you have a full size bitmap that fits exactly, you should
- not use this option because the size of the field will be different if the user has a custom DPI setting.
MUI_SPECIALINI ini_file
- InstallOptions INI file for the Welcome and Finish page.
- Default: ${NSISDIR}\Contrib\Modern UI\ioSpecial.ini
MUI_SPECIALBITMAP bmp_file
- Bitmap for the Welcome and Finish page (recommended size: 164x314 pixels).
- Default: ${NSISDIR}\Contrib\Graphics\Wizard\win.bmp
MUI_SPECIALBITMAP_NOSTRETCH
- Do not stretch the bitmap for the Welcome and Finish page to fit the size of the field.
- Use this option only if you have an image that does not use the whole space. If you have a full size
- bitmap that fits exactly, you should not use this option because the size of the field will be different
- if the user has a custom DPI setting.
MUI_BGCOLOR (color: RRGGBBR hexadecimal)
- Background color for the header, Welcome- and Finish page.
Default: FFFFFF
MUI_FINISHPAGE_LINK_COLOR (color: 0xBBGGRR hexadecimal)
- Text color for the link on the Finish page.
Default: 0x800000
MUI_RTL_UI
- Right-to-left interface.
Components Page Interface Settings
-MUI_COMPONENTSPAGE_SMALLDESC
- A small description area on the bottom of the page. Use this layout
- if you have a lot of sections and don't need large descriptions.
MUI_COMPONENTSPAGE_NODESC
- No description area.
Message Settings
-MUI_ABORTWARNING
- Show a message box with a warning when the user wants to close the installer.
MUI_ABORTWARNING_TEXT text
- Texts to display next to the abort warning messagebox.
4. Define custom functions
If you want add your own code to functions inserted by the Modern UI (i.e. the .onGUIInit function and the page functions), create your own function and let the Modern UI functions call them.
5. Insert language files
-Insert the Modern UI language files for the languages you are using:
+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.
Customize fonts
You can customize the fonts for a language using the following defines before inserting - a language:
+ a language.MUI_FONT_HEADER font_name
MUI_FONTSIZE_HEADER font_size
MUI_FONTSTYLE_HEADER weight [/ITALIC] [/UNDERLINE] [/STRIKE]
@@ -482,7 +488,7 @@ will also help you to learn more about the Modern UI.
If you want the installer to display a language selection dialog (have a look at the - MultiLanguage.nsi example), insert the MUI_LANGDLL_DISPLAY macro in .onInit:
+ MultiLanguage.nsi example), insert the MUI_LANGDLL_DISPLAY macro in .onInit.Function .onInit @@ -490,7 +496,7 @@ Function .onInit FunctionEnd-
To customize the language selection dialog, use these defines before inserting the macro:
+To customize the language selection dialog, use these defines before inserting the macro.
MUI_LANGDLL_WINDOWTITLE text
The window title of the language selection dialog.
MUI_LANGDLL_INFO text
@@ -502,7 +508,7 @@ FunctionEnd
You can also use it in the uninstaller to display the right language. Don't forget
to remove this key in the uninstaller.
In the uninstaller, insert the MUI_UNGETLANGUAGE macro in un.onInit to get the stored language - preference:
+ preference.Function un.onInit @@ -521,7 +527,7 @@ FunctionEnd 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:
+ that should contain the section number.Section "Section Name 1" Section1 ... @@ -540,19 +546,18 @@ LangString DESC_Section2 ${LANG_ENGLISH} "Description of section 2."For the uninstaller, use the MUI_UNFUNCTION_DESCRIPTION_BEGIN and MUI_UNFUNCTIONS_DESCRIPTION_END macros
7. Reserve Files
-If you are using BZIP2 compression, you might need to +
If you are using BZIP2 (solid) compression, you might need to insert ReserveFile commands. More info...
Custom page commands
If you want add custom pages to your installer, you should insert your -own page commands between the page macros:
+own page commands between the page macros.!insertmacro MUI_PAGE_WELCOME Page custom FunctionName ;Custom page !insertmacro MUI_PAGE_COMPONENTS --For the uninstaller:
-+ +;Uninstaller !insertmacro MUI_UNPAGE_CONFIRM UninstPage custom un.FunctionName ;Custom page !insertmacro MUI_UNPAGE_INSTFILES @@ -562,18 +567,16 @@ UninstPage custom un.FunctionName ;Custom page using INI files.Have a look at the InstallOptions documentation for info about creating InstallOptions INI files.
-First, you need to extract your InstallOptions INI -File in the .onInit function (un.onInit for the uninstaller) using -the MUI_INSTALLOPTIONS_EXTRACT macro:
+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 Plugins directory. Use this name when inserting the other InstallOptions -macros:
+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" @@ -581,7 +584,7 @@ FunctionEndYou 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:
+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" @@ -592,7 +595,7 @@ Function FunctionName ;FunctionName defined with Page command FunctionEndFor custom fonts and colors, macros for the initDialog and show -functions of InstallOptions are also available:
+functions of InstallOptions are also available.Var HWND Var DLGITEM @@ -621,7 +624,7 @@ FunctionEndIf 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.
-To read or write INI file values use these macros:
+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" @@ -637,7 +640,7 @@ to get the user input: files which are being extracted in init- or page functions functions are first in the data block, because this will make your installer start faster.If there are File commands in your script above Modern UI settings -or above your own init- or page functions, you have to reserve files:
+or above your own init- or page functions, you have to reserve files.ReserveFile "ioFile.ini" ;Your own InstallOptions INI files ReserveFile "${NSISDIR}\Contrib\Graphics\Header\nsis.bmp" ;Your header bitmap @@ -669,9 +672,10 @@ ReserveFile "${NSISDIR}\Contrib\Graphics\Wizard\win.bmp" ;Special bitmap dialog 111 of modern.exe.
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 need to edit this file and recompile NSIS. -To modify the Welcome and Finish dialog, edit the Install - Options INI File ioSpecial.ini in the 'Contrib\Modern UI' directory.
+ To change them, you have to edit this file and recompile NSIS. +To modify the Welcome and Finish dialog, use a custom + INI file (MUI_SPECIALINI setting) or write to the INI file in the + custom page functions.
If you want add your own code to functions inserted by the Modern UI, such as the .onGUIInit function and the Page functions, @@ -703,17 +707,18 @@ FunctionEnd
Version history