NSIS 2.0界面快速入门

NSIS 2.0 版本支持定制的用户界面。所谓的 Modern UI(下称 MUI) 就是一种模仿最新的 Windows 界面风格的界面系统。MUI 改变了 NSIS 脚本的编写习惯，它使用 NSIS 的宏来表达，指定 MUI 的属性需要使用宏。所以，诸如 LicenseText, Icon, CheckBitmap, InstallColors 在 MUI 中失去意义。
MUI 的内置向导页面
和安装程序有关的向导页面
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 该向导页面显示安装结束
和卸载程序有关的向导页面
MUI_UNPAGE_WELCOME
MUI_UNPAGE_CONFIRM
MUI_UNPAGE_LICENSE text/rtf_file
MUI_UNPAGE_COMPONENTS
MUI_UNPAGE_DIRECTORY
MUI_UNPAGE_INSTFILES
MUI_UNPAGE_FINISH
页面的属性设定需要放在插入页面的宏之前。比如:
Var PLUGINS_FOLDER
!define MUI_DIRECTORYPAGE_VARIABLE $PLUGINS_FOLDER
!insertmacro MUI_PAGE_DIRECTORY
这段 nsi 脚本表示，将目录选择页面中用户选择的目录位置存放到变量 $PLUGINS_FOLDER 中去。
以下是 MUI 各个内置向导页面属性说明：
所有页面适用的属性
MUI_PAGE_HEADER_TEXT text
显示在向导页头上的文字
MUI_PAGE_HEADER_SUBTEXT text
显示在向导页头上的文字，它是通常显示在 MUI_PAGE_HEADER_TEXT 之下，表示对 MUI_PAGE_HEADER_TEXT 的进一步解释。
对于使用 InstallOptions 的定制界面，使用宏 !insertmacro MUI_HEADER_TEXT "$(TEXT_IO_TITLE)" "$(TEXT_IO_SUBTITLE)" 实现类似功能。
欢迎页面属性
MUI_WELCOMEPAGE_TITLE title
显示在欢迎向导页上的标题
MUI_WELCOMEPAGE_TITLE_3LINES
标题区的空格
MUI_WELCOMEPAGE_TEXT text
显示在欢迎向导页上的文字。使用\r\n换行。
通常这些属性不需要制定，省缺的值已经足够。
软件授权页面属性
在软件授权页面中可以定制用户接受软件授权许可的三种方式，一是按钮，二是 checkbox，三是 radio。
MUI_LICENSEPAGE_TEXT_TOP text
显示在页面顶部的文字
MUI_LICENSEPAGE_TEXT_BOTTOM text
显示在页面底部的文字
MUI_LICENSEPAGE_BUTTON button_text
按钮方式时按钮上的文字
MUI_LICENSEPAGE_CHECKBOX
定义此宏表示用户需要钩选该 checkbox 来接受软件许可
MUI_LICENSEPAGE_CHECKBOX_TEXT text
在 checkbox 旁显示的文字
MUI_LICENSEPAGE_RADIOBUTTONS
定义此宏表示用户需要钩选相应的 radio box 来接受或拒绝软件许可
MUI_LICENSEPAGE_RADIOBUTTONS_TEXT_ACCEPT text
在 radio 旁显示的表示接受的文字
MUI_LICENSEPAGE_RADIOBUTTONS_TEXT_DECLINE text
在 radio 旁显示的表示拒绝的文字
安装组件选择页面属性
MUI_COMPONENTSPAGE_TEXT_TOP text
显示在页面顶部的文字
MUI_COMPONENTSPAGE_TEXT_COMPLIST text
显示在组件列表旁边的文字
MUI_COMPONENTSPAGE_TEXT_INSTTYPE text
显示在安转类型下拉框旁边的文字
MUI_COMPONENTSPAGE_TEXT_DESCRIPTION_TITLE text
显示在描述框顶部的文字
MUI_COMPONENTSPAGE_TEXT_DESCRIPTION_INFO text
当没有安装组件选中时，显示在描述框中的文字
安装目录选择页面属性
MUI_DIRECTORYPAGE_TEXT_TOP text
显示在页面顶部的文字
MUI_DIRECTORYPAGE_TEXT_DESTINATION text
显示在目地目录选择框上的文字
MUI_DIRECTORYPAGE_VARIABLE variable
存放用户选择的目录的变量，默认是 $INSTDIR
MUI_DIRECTORYPAGE_VERIFYONLEAVE
在离开该页面时验证目录的有效性，不禁用"下一步"这个按钮
开始菜单目录选择页面
创建快捷方式的代码应当放在 MUI_STARTMENU_WRITE_BEGIN 和 MUI_STARTMENU_WRITE_END 之间，示例如下:
!insertmacro MUI_STARTMENU_WRITE_BEGIN page_id
...create shortcuts...
!insertmacro MUI_STARTMENU_WRITE_END
这里的 page_id 是用户选择要创建快捷方式的页面。
MUI_STARTMENUPAGE_TEXT_TOP text
显示在页面顶部的文字
MUI_STARTMENUPAGE_TEXT_CHECKBOX text
显示在 checkbox 旁的表示禁止快捷方式创建的文字
MUI_STARTMENUPAGE_DEFAULTFOLDER folder
默认的开始菜单目录
MUI_STARTMENUPAGE_NODISABLE
不实现用于禁止快捷方式创建的 checkbox
MUI_STARTMENUPAGE_REGISTRY_ROOT root
MUI_STARTMENUPAGE_REGISTRY_KEY key
MUI_STARTMENUPAGE_REGISTRY_VALUENAME value_name
这三项用于指定开始菜单设定在注册表中的键和值，用于记录用户的偏好。在卸载时应当删除之。
卸载程序可以用宏MUI_STARTMENU_GETFOLDER获得开始菜单目录，下面的例子说明了如何删除快捷方式:
!insertmacro MUI_STARTMENU_GETFOLDER page_id $R0
Delete "$SMPROGRAMS\$R0\Your Shortcut.lnk"
安装进度页面属性
MUI_INSTFILESPAGE_FINISHHEADER_TEXT text
显示安装进度页面头上的文字，但对于结束页面不是MUI_(UN)FINISHPAGE_NOAUTOCLOSE)不显示。
MUI_INSTFILESPAGE_FINISHHEADER_SUBTEXT text
显示安装进度页面头上的，对MUI_INSTFILESPAGE_FINISHHEADER_TEXT的进一步说明。对于结束页面不是MUI_(UN)FINISHPAGE_NOAUTOCLOSE)不显示。
MUI_INSTFILESPAGE_ABORTHEADER_TEXT text
显示安装进度页面头上的表示安装过程非正常终止的文字
MUI_INSTFILESPAGE_ABORTHEADER_SUBTEXT text
对MUI_INSTFILESPAGE_ABORTHEADER_TEXT的进一步描述
完成页面属性
在完成页面中可以运行程序，打开文件或网站。
MUI_FINISHPAGE_TITLE title
页面标题
MUI_FINISHPAGE_TITLE_3LINES
页面标题区的额外空格
MUI_FINISHPAGE_TEXT text
显示在完成页面上文字，用\r\n换行
MUI_FINISHPAGE_TEXT_LARGE
如果使用了 checkbox 时，需要设定的文本区的额外空间
MUI_FINISHPAGE_BUTTON text
完成按钮的显示文字
MUI_FINISHPAGE_TEXT_REBOOT text
重启操作系统 checkbox 旁的文字，用\r\n换行
MUI_FINISHPAGE_TEXT_REBOOTNOW text
显示在'Reboot now'旁的文字
MUI_FINISHPAGE_TEXT_REBOOTLATER text
显示在'Reboot later'旁的文字
MUI_FINISHPAGE_RUN exe_file
指定用户可以用 checkbox 选择运行的应用程序，如果有空格无需引用。
MUI_FINISHPAGE_RUN_TEXT text
运行应用程序 checkbox 旁的文字
MUI_FINISHPAGE_RUN_PARAMETERS parameters
运行应用程序的参数，需要用$\"表示双引号
MUI_FINISHPAGE_RUN_NOTCHECKED
指定运行应用程序 checkbox 为非选中状态
MUI_FINISHPAGE_RUN_FUNCTION function_name
指定安装完成后要执行的nsi函数，在该函数中可以运行多个应用程序。
MUI_FINISHPAGE_SHOWREADME file/url
指定用户可以用 checkbox 选择是否查看的文件或网站，如果有空格无需引用。
MUI_FINISHPAGE_SHOWREADME_TEXT text
指定 'Show Readme' checkbox 旁的显示文字
MUI_FINISHPAGE_SHOWREADME_NOTCHECKED
指定 'Show Readme' checkbox 为非选中状态
MUI_FINISHPAGE_SHOWREADME_FUNCTION function_name
指定安装完成后要执行的 nsis 函数，在该函数中可以显示多个文件或网站。
MUI_FINISHPAGE_LINK link_text
用户可及点击的超链上的文字
MUI_FINISHPAGE_LINK_LOCATION file/url
指定用户是否可以用超链查看网站，如果有空格无需引用。
MUI_FINISHPAGE_LINK_COLOR (color: RRGGBB hexadecimal)
超链上文字的颜色，默认为 000080
MUI_FINISHPAGE_NOREBOOTSUPPORT
禁用重启操作系统的功能
卸载确认页面属性
MUI_UNCONFIRMPAGE_TEXT_TOP text
显示在页面顶部的文字
MUI_UNCONFIRMPAGE_TEXT_LOCATION text
显示在 uninstall location 旁的文字

InstallOptions 和定制页面
InstallOptions 是一个 NSIS 插件，他能让安装程序开发人员创建定制的向导页面来获得内置向导页面不能提供的用户输入。
InstallOptions 会创建内嵌在 NSIS 窗体中的对话框。InstallOptions 的控件用 INI 文件描述。该文件可以用可视化工具生成。HM NIS EDIT 就是这样的一个工具。
InstallOptions 控件 INI 文件的结构
InstallOptions INI 文件包含一个必须的段。它包含了控件的数量、窗体的属性等。该文还可包含描述具体空间的段。
必须的段是 Settings，它可以包含以下内容：
NumFields(必须的) 该对话框包含的控件数目
Title (可选的) Windows窗体的标题
CancelEnabled (可选的) 是否启用Cancel按钮，1:是，0:否
CancelShow (可选的) 是否显示Cancel按钮，1:是，0:否
BackEnabled (可选的) 是否启用Back按钮，1:是，0:否
CancelButtonText (可选的) Cancel按钮的显示文字
NextButtonText (可选的) Next按钮的显示文字
BackButtonText (可选的) Back按钮的显示文字
Rect (可选的)
RTL (可选的)
State (output) This is not something you have to supply yourself but is set by InstallOptions, before calling your custom page validation function, to the field number of the custom Button control (or other control having the Notify flag) the user pressed, if any.
每个控件段以"Field #"模式命名，井号表示数字，从1开始。控件有以下属性：
Type (required) 控件的类型，有"Label", "Text", "Password", "Combobox", "DropList", "Listbox", "CheckBox", "RadioButton", "FileRequest" , "DirRequest" "Icon", "Bitmap", "GroupBox", "Link" 或 "Button"。
"Label" 用来显示静态文本
"Text" 和 "Password" 和 HTML 中的类似，用来接受用户输入。
"Combobox"允许用户输入列表中不存在的项， "Droplist" 则只能选择列表中规定的项。
"Listbox" 显示多个选项(不用下拉即可看到)，并允许多选
"CheckBox" "RadioButton" 和 Windows中的相应控件类似。
"FileRequest" 显示一个输入框和浏览按钮，允许用户用文件选择对话框选取文件。
"DirRequest" 和 "FileRequest" 类似，但只选取到目录。
"Icon" 显示图标
"Bitmap" 显示位图
"GroupBox" 显示组合框
"Link" 显示超链
"Button" 按钮
Text (可选的) 对 checkbox,radio button 控件是 caption；对 DirRequest 控件是浏览对话框的标题；对图标，位图控件是图像文件的的路径。
State (可选的) 控件状态，该状态可以在 nsi 脚本读取。对于文本类型的控件，state 的值是用户输入的字符串。对于 radio button 和 check boxes state 为'0'或'1'。对 list boxes, combo boxes 和 drop lists 状态值是选中的选项，如果有多个则用管道符号'|'分割。 对于超链和按钮 State 是可以用 ShellExecute 执行的字符串。
ListItems (可选的) combobox, droplist, 或 listbox的选项，选项之间用管道符号'|'分割
MaxLen (可选的) 最大输入长度
MinLen (可选的) 最小输入长度
ValidateText (可选的) 校验文本
Left
Right
Top
Bottom (required) 控件坐标，在可视化环境中不重要。
Filter (可选的) 指定 "FileRequest" 控件的文件过滤器，模式如 文本文件|*.txt|程序文件|*.exe;*.com|所有文件|*.*
Root (可选的) 指定"DirRequest" 控件的根目录
Flags (可选的) 指定控件的修饰。多个值用管道符号'|'分割且不能有空格。有效的值如下：
Value Meaning
REQ_SAVE 将 "FileRequest" 控件变成 "另存为" 对话框
FILE_MUST_EXIST 用于 "FileRequest" 控件，规定所选文件是否必须存在
FILE_EXPLORER 用于 "FileRequest" 控件
FILE_HIDEREADONLY 用于 "FileRequest" 控件，隐藏 "open read only"checkbox
WARN_IF_EXIST 用于 "FileRequest" 控件，显示警告如果文件已存在
PATH_MUST_EXIST 用于 "FileRequest" 控件，规定输入的路径必须存在
PROMPT_CREATE 用于 "FileRequest" 控件，在创建之前显示警告如果文件或路径不存在
RIGHT 用于"Checkbox"和Radiobutton"控件，规定文字出现在左边，很少用
MULTISELECT 用于"Listbox"控件允许多选
EXTENDEDSELCT 用于"Listbox"控件允许多选
RESIZETOFIT 用于"Bitmap"控件，将图片扩大到控件的大小
GROUP 多个控件分组，该标志放在同组的第一个控件上。
NOTABSTOP 禁止tab键焦点落在该控件上
DISABLED 禁用控件
ONLY_NUMBERS 用于"Text"控件，Forces the user to enter only numbers into the edit box.
MULTILINE 用于"Text"控件，允许多行输入
WANTRETURN 用于"Text"控件，允许多行输入，规定按下Enter键时插入回车
NOWORDWRAP 用于"Text"控件，允许多行输入禁用word-wrap
HSCROLL 显示水平方向的滚动条
VSCROLL 显示垂直方向的滚动条
READONLY 用于"Text"控件，使文本输入框变成只读
NOTIFY 用于"Button", "Link", "CheckBox", "RadioButton", "ListBox"和"DropList"控件。使InstallOptions触发事件，调用定制页面的validation/leave方法。
TxtColor (可选的) 用于"Link"控件，指定文本的前景色，格式为: 0xBBRRGG (十六进制)
使用定制向导页的步骤：
1. 设计定制向导页界面，产生界面描述ini文件，可以使用HM NIS Edit的可视化工具简化开发
2. 编写nsi脚本：
首先，如果使用了lzma,gzip等压缩算法，需要在所有File指令前reserve定制界面的ini文件：ReserveFile ".ini"。
然后，在.onInit方法中使用宏!insertmacro MUI_INSTALLOPTIONS_EXTRACT ".ini"。
接着，编写定制对话框的显示函数。
最后，用Page指令在合适的位置插入该向导页面。
定制对话框显示函数的示例：
Function setChooseBuildArea
!insertmacro MUI_HEADER_TEXT "请选择构建目录" "请选择构建目录"
!insertmacro MUI_INSTALLOPTIONS_WRITE "buildarea.ini" "Field 2" "State" "$INSTDIR\buildarea"
!insertmacro MUI_INSTALLOPTIONS_DISPLAY "buildarea.ini"
FunctionEnd
该函数的第一行代码设置向导页面的头上的文字；第二行代码设置向导页面第二个控件的State为"$INSTDIR\buildarea"，也就是设置该控件的默认值；第三行代码显示对话框。
用Page指令插入向导页的代码如下：
Page custom setChooseBuildArea "" "--选择构建目录"
该指令接受三个参数，前两个是该页面的显示函数和离开函数，第三个是显示在标题栏的文字。
nsi的变量如果存放字符串的话，默认只能保存1024。对于复杂的Java应用，由于需要设置Classpath其命令行的长度往往会超过1024。此时，必须让nsi的变量支持大于1024的字符串长度。有两种方法解决此问题，一个是到http: //nsis.sourceforge.net/download/specialbuilds/处下载Special Builds，目前一个称为Large strings的build支持可以存放8192个字符的变量；另外一个就是手工编译NSIS的源代码，加上需要的选项。
（完了）