NSIS的Modern UI教程

来源 :http://hi.baidu.com/usemm/blog/item/28be0a4f72209d32aec3abcb.html

NSIS的Modern UI教程

2008-02-02 16:51

NSIS 2.0版本支持定制的用户界面。所谓的Modern
UI(下称MUI)就是一种模仿最新的Windows界面风格的界面系统。MUI改变了NSIS脚本的编写习惯，它使用NSIS的宏来表达，指定MUI的
属性需要使用宏。所以，诸如LicenseText, Icon, CheckBitmap, InstallColors在MUI中失去意义。
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
指定安装完成后要执行的nsi函数，在该函数中可以显示多个文件或网站。

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" or "Button".

"Label" 用来显示静态文本
"Text" and "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"控件的文件过滤器，模式如Text Files|*.txt|Programs|*.exe;*.com|All Files|*.*

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的源代码，加上需要的选项。