一个 NSIS 脚本文件 (.nsi) 就是一个包含了脚本代码的文本文件。
命令
命令行的格式为: ‘命令 [参数]’
File "myfile"
注释
以 ; 或 # 作为开始的行为注释。你可以在命令后面添加注释。你也可以使用 C 规范的注释来注释一行或多行。
; 注释 # 注释 # 注释 另一个注释行 (查看本节下面的 `长命令`) /* 注释 注释 */ Name /* 注释 */ mysetup File “我的文件” ; 注释
如果参数需要由 ; 或 # 开头,你可以用双引号把它括起来。
插件
要调用一个插件,使用 ‘插件::命令 [参数]’。更多的信息请查看 插件 DLLs。
nsExec::Exec "我的文件"
数字
对于数字参数,使用十进制 (数字) 或十六进制 (以 0x 开头的,比如: 0x12345AB), 或八进制 (以 0 开头且无 x)。
颜色被设置为十六进制 RGB 形式,像 HTML 那样但是没有 # 开头。
IntCmp 1 0x1 lbl_equal SetCtlColors $HWND CCCCCC
字符串
要使用一个包含空格的字符串,需要用引号括起来:
MessageBox MB_OK "Hi 您好!"
引号仅有的作用就是当他们开始时包含一个参数。他们可以是单引号、双引号或向后的单引号。
You can escape quotes using $:
MessageBox MB_OK "I'll be happy"
;把一个 ' 放在字符串里
MessageBox MB_OK 'And he said to me "Hi there!"'
;把一个 " 放在字符串里
MessageBox MB_OK `And he said to me "I'll be happy!"`
;这里把 ' 和 " 都放到了字符串里
MessageBox MB_OK "$"A quote from a wise man$" said the wise man"
;这里演示了跳过引号的解析
要在字符串里使用回车、换行、Tab 等,请使用 $r, $n, $t 等。 更多信息…
变量
变量以 $ 开头。用户变量应该 (不是必须) 事先被声明并且区分大小写。
Var MYVAR StrCpy $MYVAR "变量值"
更多的信息…
长命令
要把命令扩充为多行,需要在行尾使用反斜杠 () ,下一行会被自动连接到上一行的尾部。例如:
CreateShortCut "$SMPROGRAMSNSISZIP2EXE project workspace.lnk" "$INSTDIRsourcezip2exezip2exe.dsw" MessageBox MB_YESNO|MB_ICONQUESTION "是否要删除文件夹中的所有文件? (如果你想保留任何你自己创建的文件 请点击[否])" IDNO NoRemoveLabel
长命令多行扩充同样适用于注释,它可能会让人混淆,因此应该尽量避免。
# 一个注释 在这里仍然是注释…
4.2 变量
所有的变量都是全局的并且可以用于区段和函数。需要注意的是,在默认情况下变量被限制在 1024 字节。要扩大这个限制你需要使用一个更大 NSIS_MAX_STRLEN 值并重新 构建 NSIS 或者使用 特别版本。
4.2.1 用户变量
$VARNAME
用户变量可以用 Var 命令来声明。你可以使用这些变量来保存值,用于字符串操作等等。
4.2.1.1 Var
[/GLOBAL] 变量名
声明一个用户变量。变量名允许的字符: [a-z][A-Z][0-9] 和 ‘_’。 所有定义的变量都是全局的,即使在区段或函数内定义。 要使它表达更清楚一些,区段或函数内定义的变量必须使用 /GLOBAL 标记。在区段和函数之外不需要 /GLOBAL 标记。
Var example
Function testVar
Var /GLOBAL
example2
StrCpy $example "example value"
StrCpy $example2 "another example value"
FunctionEnd
4.2.2 其他可写的变量
$0, $1, $2, $3, $4, $5, $6, $7, $8, $9, $R0, $R1, $R2, $R3, $R4, $R5, $R6, $R7, $R8, $R9
寄存器。这些变量可以像用户变量一样使用,但常用于公用函数或宏。你不需要声明这些变量,所以当你在公用代码里使用他们的时候不能有任何名字冲突。当在公用代码里使用这些变量的时候,推荐你使用堆栈保存和恢复他们原来的数据。这些变量也可以在插件里传递,因为他们可以被 DLL 插件读取和写入。
$INSTDIR
安装目录 ($INSTDIR 可以使用 StrCpy、 ReadRegStr、 ReadINIStr 等等来更改。例如在 .onInit 函数里可以用来做高级的检测安装定位)。
注意在卸载程序代码里,$INSTDIR 为卸载程序所在的目录而不是在安装程序里所指定的目录。例如, 如果你把卸载程序放在 $WINDIR 里并且用户没有移动它,那么在卸载程序里 $INSTDIR 就等于 $WINDIR。如果你要把卸载程序放到另外的位置,那么你应该先把安装程序的 $INSTDIR 值写入注册表或者其它容易保存的地方,然后在卸载程序里读取该值并赋值给卸载程序里的 $INSTDIR。
$OUTDIR
当前输出目录 (通过 SetOutPath 或者通过 StrCpy、 ReadRegStr、 ReadINIStr 等等)
$CMDLINE
安装程序命令行。命令行的格式可以是下列之一:
- “完整路径安装程序.exe” 参数1 参数2 参数3
- 安装程序.exe 参数1 参数2 参数3
- 对于解析“参数”部分,参阅 GetParameters。如果在命令行里指定了 /D= (用来跳过安装路径的选择),那么 /D= 后面的参数将不会被保存在 $CMDLINE (前面的可以保存)。
$LANGUAGE
当前使用的语言标识符。例如,英语是 1033。你可以在 .onInit 里更改此变量。
4.2.3 常量
常量通常用在 InstallDir 属性里。
需要注意的是一些新的常量并不是在所有的 OS 上都是正常的。例如, $CDBURN_AREA 仅在 Windows XP 及以上系统中才正常。 如果在 Windows 98 中使用,将会得到空值。除非特别提示,否则该常量都是在所有 OS 上有效的。
$PROGRAMFILES, $PROGRAMFILES32, $PROGRAMFILES64
程序文件目录 (通常为 C:Program Files
但在运行时会检测)。在 Windows x64 操作系统中, $PROGRAMFILES 和 $PROGRAMFILES32 指向C:Program Files (x86)
同时 $PROGRAMFILES64 指向 C:Program Files
。当安装 64 位应用程序时,使用 $PROGRAMFILES64。
$COMMONFILES, $COMMONFILES32, $COMMONFILES64
公用文件目录。这是应用程序共享组件的目录 (通常为 C:Program FilesCommon Files
但在运行时会检测)。在 Windows x64 操作系统中, $COMMONFILES 和 $COMMONFILES32 指向 C:Program Files (x86)Common Files
同时 $COMMONFILES64 指向 C:Program FilesCommon Files
。当安装 64 位应用程序时,使用 $COMMONFILES64。
$DESKTOP
Windows 桌面目录 (通常为 C:WindowsDesktop
但在运行时会检测)。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。 默认为当前用户。
$EXEDIR
可执行安装程序运行时所在目录 (从技术上来说你可以修改改变量,但并不是一个好方法)。
$EXEFILE
可执行安装程序的基本名字。
$EXEPATH
可执行安装程序的完整路径。
${NSISDIR}
包含 NSIS 安装目录的符号定义标记。常用于在你想调用在 NSIS 目录下的资源时。图标、界面等等。
在 Windows 平台等于 makensis 所在的目录,而在其它平台则在编译时决定 (信息请看 INSTALL 文件)。你可以在编译前通过修改 NSISDIR 环境变量来改变默认的设置。更多信息请看 section 3.1.3。
$WINDIR
Windows 目录 (通常为 C:Windows
或者 C:WinNT
但在运行时会检测)。
$SYSDIR
Windows 系统目录 (通常为 C:WindowsSystem
or C:WinNTSystem32
但在运行时会检测)。
$TEMP
系统临时目录 (通常为 C:WindowsTemp
但在运行时会检测)。
$STARTMENU
开始菜单目录 (常用于添加一个开始菜单项,使用 CreateShortCut)。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。默认为当前用户。
$SMPROGRAMS
开始菜单程序目录 (当你想定位 $STARTMENU程序 时可以使用它)。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。默认为当前用户。
$SMSTARTUP
开始菜单程序/启动 目录。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。默认为当前用户。
$QUICKLAUNCH
在 IE4 活动桌面及以上的快速启动目录。如果快速启动不可用,仅仅返回和 $TEMP 一样。
$DOCUMENTS
文档目录。一个当前用户典型的路径形如 C:Documents and SettingsFooMy Documents
。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。默认为当前用户。
该常量在 Windows 95 且 Internet Explorer 4 没有安装时无效。
$SENDTO
该目录包含了“发送到”菜单快捷项。
$RECENT
该目录包含了指向用户最近文档的快捷方式。
$FAVORITES
该目录包含了指向用户网络收藏夹、文档等的快捷方式。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。默认为当前用户。
该常量在 Windows 95 且 Internet Explorer 4 没有安装时无效。
$MUSIC
用户的音乐文件目录。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。默认为当前用户。
该常量仅在 Windows XP, ME 及以上有效。
$PICTURES
用户的图片文件目录。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。 默认为当前用户。
该常量仅在 Windows 2000, XP, ME 及以上有效。
$VIDEOS
用户的视频文件目录。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。 默认为当前用户。
该常量仅在 Windows XP, ME 及以上有效。
$NETHOOD
该目录包含了可能存在于我的网络位置、网上邻居文件夹的链接对象。
该常量在 Windows 95 且 Internet Explorer 4 和活动桌面没有安装时无效。
$FONTS
系统字体目录。
$TEMPLATES
文档模板目录。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。 默认为当前用户。
$APPDATA
应用程序数据目录。当前用户路径的检测需要 Internet Explorer 4 及以上。所有用户路径的检测需要 Internet Explorer 5 及以上。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。 默认为当前用户。
该常量在 Windows 95 且 Internet Explorer 4 和活动桌面没有安装时无效。
$LOCALAPPDATA
本机应用程序数据目录。
该常量仅在 Windows 2000 及以上有效。
$PRINTHOOD
该目录包含了可能存在于打印机文件夹的链接对象。
该常量在 Windows 95 和 Windows 98 上无效。
$INTERNET_CACHE
Internet Explorer 的临时文件目录。
该常量在 Windows 95 和 Windows NT 且 Internet Explorer 4 和活动桌面没有安装时无效。
$COOKIES
Internet Explorer 的 Cookies 目录。
该常量在 Windows 95 和 Windows NT 且 Internet Explorer 4 和活动桌面没有安装时无效。
$HISTORY
Internet Explorer 的历史记录目录。
该常量在 Windows 95 和 Windows NT 且 Internet Explorer 4 和活动桌面没有安装时无效。
$PROFILE
用户的个人配置目录。一个典型的路径如 C:Documents and SettingsFoo
。
该常量仅在 Windows 2000 及以上有效。
$ADMINTOOLS
一个保存管理工具的目录。该常量的内容 (所有用户或者当前用户) 取决于 SetShellVarContext 设置。 默认为当前用户。
该常量仅在 Windows 2000, ME 及以上有效。
$RESOURCES
本地的资源目录保存了主题和其他 Windows 资源 (通常为 C:WindowsResources
但在运行时会检测)。
该常量仅在 Windows XP 及以上有效。
$RESOURCES_LOCALIZED
本地的资源目录保存了主题和其他 Windows 资源 (通常为 C:WindowsResources1033
但在运行时会检测)。
该常量仅在 Windows XP 及以上有效。
$CDBURN_AREA
一个在烧录 CD 时储存文件的目录。
该常量仅在 Windows XP 及以上有效。
$HWNDPARENT
父窗口的十进制窗口句柄。
$PLUGINSDIR
该路径是一个临时目录,当第一次使用一个插件或一个调用 InitPluginsDir 时被创建。该文件夹当安装程序退出时会被自动删除。 这个文件夹的用意是用来保存给 InstallOptions 使用的 INI 文件、启动画面位图或其他插件运行需要的文件。
4.2.4 在字符串里使用常量
$$
转义,用来表示 $。
$r
用来表示一个回车 (r)。
$n
用来表示新的一行 (n)。
$t
用来表示一个 Tab (t)。
4.3 标记
标记是 Goto 指令的目标,或各种分支指令 (例如 IfErrors、 MessageBox、 IfFileExists, 和 StrCmp) 的目标。标记必须存在于一个区段或函数里。标记是局限于该范围里的,这意味着这些指令只能访问和它们同处于一个区段或函数的标记。 要声明一个标记很简单:
MyLabel:
标记不能以 -, +, !, $, 或 0-9开头。 当给多个需要指定标记的指令指定了标记,不要忘了使用空字串 (“”) 或 0 来表示下一个指令(表示无 Goto 跳转)。一个标记以句点 (.) 开头时表示这是一个全局的标记,你可以从任何区段或函数直接跳转到它上面(但是你不能从一个安装程序跳转到一个卸载程序的全局标记,反之亦然)。
4.4 相对跳转
和标记不一样,相对跳转就如其名一样,相对于被调用的地方。在任何你可用到标记的地方你也都可以相对跳转。相对跳转由数字标定。+1 跳转到下一条指令(默认的步进),+2 会跳过一条指令也并且从当前指令转到第二条指令,-2 将往后跳两条指令,+10 将会跳过 9 条指令,从当前指令跳到第十条指令。
一条指令就是在安装程序运行时可以被执行的所有命令。 MessageBox、 Goto、 GetDLLVersion、 FileRead、 SetShellVarContext 都是指令。 AddSize、 Section、 SectionGroup、 SectionEnd、 SetOverwrite (和所有处于编译器标记)、 Name、 SetFont、 LangString 都不是指令,因为它们在编译时就被执行。
例子:
Goto +2
MessageBox MB_OK "你将看不到这个消息框"
MessageBox MB_OK "上一条信息被略过,这条信息才会被显示"
Goto +4
MessageBox MB_OK "随后的这条信息将会被略过"
Goto +3
MessageBox MB_OK "你将不会看到这个消息框"
Goto -3
MessageBox MB_OK "完成"
需要注意的是 宏指令 并不是真正意义上的一条指令,在编译时会被展开为若干条指令,所以你不能用相对跳转来跳过一条宏指令。下面的示例演示了相对跳转并没有真正跳过插入的宏 (仅仅是跳过了宏里的第一条指令),还是会显示一个消息框。
!macro relative_jump_test
MessageBox MB_OK "第一个宏行first macro line"
MessageBox MB_OK "第二个宏行second macro line"
!macroend
Goto +2
!insertmacro relative_jump_test
4.5 页面
每个(非静默安装) NSIS 安装程序都有一个页面设置。每个页面可以是一个 NSIS 内建页面或者一个由用户函数(查看 nsDialogs 或 InstallOptions 实例)创建的自定义页面。
使用脚本你可以控制这些页面的次序, 外观, 作用。你可以跳过页面, 颜色绘为白色, 强制用户停留在某个页面直到特定条件成立, 显示一个自述文件页面, 给输入显示一个自定义页面或者更多的功能。在本节中,你将学会如何控制上述提到的功能。
关于页面有两个基本的命令, Page 和 UninstPage。前一个为添加一个页面到安装程序,后一个为添加一个页面到卸载程序。在他们两个命令的前面你可以用 PageEx 命令给他们添加一个页面且包括一些选项。 PageEx 可以使你给添加的指定页面设置选项而不是使用 PageEx 之外设置的默认设置。
4.5.1 次序关系
页面的次序由 Page, UninstPage 和 PageEx 出现在脚本里的次序决定。例如:
Page license
Page components
Page directory
Page instfiles
UninstPage uninstConfirm
UninstPage instfiles
该代码告诉 NSIS 第一个显示的是许可页面,然后是组件选择页面,然后是目录选择页面,最后是区段被执行的安装记录页面,就像老式的安装程序那样。卸载程序将首先显示卸载确认页面然后是卸载执行记录。
你可以把同一个页面类型多次指定。
由于需要向下兼容旧 NSIS 脚本,如果没有使用到安装程序页面命令,那么随后的这些安装程序页面将会被添加: 许可 (如果指定了 LicenseText 和 LicenseData), 组件选择 (如果指定了 ComponentText 并且有一个以上非隐藏的区段), directory (如果指定了 DirText) 和安装记录。当没有使用到卸载程序页面命令,那么随后的卸载程序页面将会被添加:卸载确认页面 (如果指定了 UninstallText) 和卸载记录。不推荐这种方法,强烈推荐的是把脚本转换为使用页面命令,因为你可以使用新的标准语言字符串。
4.5.2 页面选项
每个页面都有它自己唯一的数据设置来定义外观和作用。这一段叙述了每种页面使用的数据和怎么样来设置。 回调函数 将在下节中说明而本节中处理。
下面的这个列表列出了某个页面类型受什么样的命令影响。除非特别提及,否则这些命令都可以在 PageEx 区块内外使用。如果在一个 PageEx 区块内部使用那么他们仅仅对由 PageEx 设置的当前页面产生影响,否则他们将被设为其他所有页面的默认值。
许可页面
- LicenseText
- LicenseData
- LicenseForceSelection
组件选择页面
- ComponentText
目录选择页面
- DirText
- DirVar – 仅能在 PageEx 里使用
- DirVerify
卸载、安装记录页面
- DetailsButtonText
- CompletedText
卸载确认页面
- DirVar – 仅能在 PageEx 里使用
- UninstallText
要设置页面标题请使用 Caption 。
4.5.3 回调
每个内建的页面都有三个回调函数: 一个预置函数,一个显示创建函数和一个离开函数。预置函数在页面被创建之前被直接的调用,显示函数在页面被创建后且在显示之前被直接调用,离开函数在用户按下下一页按钮之后并且在页面离开之前被直接调用。
- 预置函数允许你使用 Abort 来跳过该页面。
- 显示函数允许你使用 CreateFont, SetCtlColors, SendMessage 和其他来调整页面的用户界面。
- 离开函数允许你使用 Abort 来强制用户停留在当前页面。
一个自定义的页面仅有两个回调函数,一个是必须的创建页面,另一个离开函数的作用就和内建页面的离开函数一样。
实例:
Page license skipLicense "" stayInLicense
Page custom customPage "" ": 自定义页面"
Page instfiles
Function skipLicense
MessageBox MB_YESNO "你想跳过许可页面吗?" IDNO no Abort no:
FunctionEnd
Function stayInLicense
MessageBox MB_YESNO "你想停留在许可页面吗?" IDNO no Abort no:
FunctionEnd
Function customPage
GetTempFileName $R0
File /oname=$R0 customPage.ini
InstallOptions::dialog $R0
Pop $R1
StrCmp $R1 "cancel" done
StrCmp $R1 "back" done
StrCmp $R1 "success" done
error: MessageBox MB_OK|MB_ICONSTOP "InstallOptions 错误:$r$n$R1" done:
FunctionEnd
4.5.4 Page
custom [创建函数] [离开函数] [标题] [/ENABLECANCEL] 或 internal_page_type [预置函数] [显示函数] [离开函数] [/ENABLECANCEL]
要添加一个安装程序页面,见上述章节,了解更多关于相对于自定义页面的内置页面和回调函数信息。
内置的页面类型:
- license – 许可协议页面
- components – 组件选择页面
- directory – 安装目录选择页面
- instfiles – 安装执行页面
- uninstConfirm – 卸载确认页面
最后一个页面的取消按钮会被禁用来防止混乱。要允许这种行为请使用 /ENABLECANCEL 。
4.5.5 UninstPage
custom [创建函数] [离开函数] [标题] [/ENABLECANCEL] 或 internal_page_type [预置函数] [显示函数] [离开函数] [/ENABLECANCEL]
要添加一个卸载程序页面,见上述章节,了解更多关于相对于自定义页面的内置页面和回调函数信息。
内置的页面类型 请参考 Page 。
4.5.6 PageEx
[un.](custom|uninstConfirm|license|components|directory|instfiles)
添加一个安装程序页面或一个卸载程序页面(如果使用了 un. 前缀)。每一个 PageEx 必须和 PageExEnd 配合使用。在一个 PageEx 区块你可以对这个页面进行特殊的设置,这些设置不会被其他页面使用。没有被设置的选项将使用 PageEx 外部区块的的设置或者当什么都没有指定时使用默认设置。要对页面设置子标题使用 Caption 或 SubCaption 。要对一个使用 PageEx 的页面设置回调函数请使用 PageCallbacks。 见上述章节,了解更多关于相对于自定义页面的内置页面的信息。
使用实例:
PageEx license
LicenseText "自述文件"
LicenseData readme.rtf
PageExEnd
PageEx license
LicenseData license.txt
LicenseForceSelection checkbox
PageExEnd
4.5.7 PageExEnd
结束一个 PageEx 区块。
4.5.8 PageCallbacks
([创建函数] [离开函数]) | ([预置函数] [显示函数] [离开函数])
对一个使用 PageEx 定义的页面设置回调函数。仅能在 PageEx 区块里使用。见上述章节,了解更多关于回调函数信息。
PageEx license
PageCallbacks licensePre
licenseShow licenseLeave
PageExEnd
4.6 区段
每一个 NSIS 安装程序包含一个或多个区段。所有的这些区段都使用下面的这些命令来创建、修改和结束。
- 每一个区段包含零个或多个指令。
- 区段是安装程序执行的实体,并且如果设置了 ComponentText ,那么用户就可以选择禁止或允许每一个可见的区段。
- 如果一个区段名为 ‘Uninstall’ 或以 ‘un.’ 为前缀,那么它就是一个卸载程序区段。
4.6.1 区段命令
4.6.1.1 AddSize
大小(单位为:KB)
告诉安装程序当前的区段需要一个额外的 “大小” KB 磁盘空间。仅在一个区段里有效(在区段外或函数里无效)。
Section AddSize 500 SectionEnd
4.6.1.2 Section
[/o] [([!]|[-])区段名] [区段索引输出]
开始并且打开一个新的区段。如果区段名为空、遗漏或者以一个 – 开头,那么它将是一个隐藏的区段,用户也不能选择禁止它。如果一个区段名为 ‘Uninstall’ 或以 ‘un.’ 为前缀,那么它就是一个卸载程序区段。如果指定了区段索引输出,该参数将被 !defined 为区段索引 (然后可以对它使用 SectionSetText 等)。如果区段名以一个 ! 开头,那么该区段的显示名称将以粗体字显示。如果指定了 /o 开关,则该区段默认为不选。
Section "-隐藏区段"
SectionEnd
Section # 隐藏区段
SectionEnd
Section "!描黑区段"
SectionEnd
Section /o "可选区段"
SectionEnd
Section "某些安装"
SEC_IDX SectionEnd
若需访问区段索引,必需使用花括号括起来且区段索引代码必需在区段之后。
Section test1 sec1_id
SectionEnd
Section test2 sec2_id
SectionEnd
Function .onInit
SectionGetText ${sec2_id} $0
MessageBox MB_OK "索引 ${sec2_id} 的名称:$n$0" # 将正确显示 '索引 1 的名称: test2'
FunctionEnd
Function .onInit
SectionGetText ${sec2_id} $0
MessageBox MB_OK "索引 ${sec2_id} 的名称:$n$0" # 将错误显示 '索引 ${sec2_id} 的名称: test1'
# 加上一个警告说明:# 未知 变量/常量 "{sec2_id}" 查看, 忽略
FunctionEnd
Section test1 sec1_id
SectionEnd
Section test2 sec2_id
SectionEnd
4.6.1.3 SectionEnd
该命令关闭当前打开的区段。
4.6.1.4 SectionIn
安装类型索引 [安装类型索引] [RO]
该命令指定当前区段默认为哪一种安装类型 (详细信息查看 InstType) 允许的状态入口。可以指定多个 (它们会被组合起来)。如果指定 RO 作为一个参数,则该区段将被设为只读区段,意味着用户不能去改变它的状态。使用 InstType 可知第一种安装类型是索引 1,下一个是编号 2,以此类推。
InstType "完全"
InstType "最小化"
Section "区段 1"
SectionIn 1 2
SectionEnd
Section "区段 2"
SectionIn 1
SectionEnd
4.6.1.5 SectionGroup
[/e] section_group_name [index_output]
该命令插入一个区段组。区段组必须以 SectionGroupEnd 来关闭,并且可以包含一个或多个区段。如果区段组名称以一个 ! 开头,则区段组名称以粗体字显示。如果指定了 /e ,该区段组的所有区段默认将被展开。如果指定区段组索引输出,该参数将被 !defined 为区段索引 (然后可以对它使用 SectionSetText 等)。如果名字以 ‘un.’ 为前缀,则该区段组为卸载程序区段组。
SectionGroup "区段组"
Section "区段 1"
SectionEnd
Section "区段 2"
SectionEnd
SectionGroupEnd
4.6.1.6 SectionGroupEnd
关闭一个以 SectionGroup 打开的区段组。
4.6.2 卸载区段
一个特别的名为 “Uninstall” 的区段只能是被创建用于产生一个卸载程序。该区段应该用来从系统里移除由安装程序安装的所有文件、注册表健等等。下面是一个简单的卸载区段例子:
Section "Uninstall"
Delete $INSTDIRUninst.exe ; 删除自我 (看下面的解释为什么可以这样)
Delete $INSTDIRmyApp.exe
RMDir $INSTDIR
DeleteRegKey HKLM SOFTWAREmyApp
SectionEnd
第一个 Delete 指令是可以正常执行的 (删除卸载程序本身),因为执行卸载程序的时候它会复制一个副本到系统临时目录并执行副本来完成卸载。
需要注意的是在卸载程序的代码里, $INSTDIR 包含了卸载程序所在的位置。你不需要在安装程序里给该变量重复赋值。
4.7 函数
函数类似于区段因为他们可以包含零个或多个指令。用户函数不会被安装程序直接调用,而必须在区段里使用 Call 指令来调用。而当一个必然事件发生时回调函数将由安装程序调用。
函数声明必须在区段或是其他函数之外。
4.7.1 函数命令
4.7.1.1 Function
[函数名称]
开始并打开一个新的函数。 一般函数名称以 “.” 开头的函数(例如 “.Whatever”) 都是作为回调函数而保留。函数名称以 “un.” 开头的函数将会被创建在卸载程序里。因此,普通安装区段和函数不能调用卸载函数,而卸载区段和卸载函数也不能调用普通安装程序的函数。
Function func
# 一些命令
FunctionEnd
Section
Call func
SectionEnd
4.7.1.2 FunctionEnd
该命令关闭当前打开的函数。
4.7.2 回调函数
你可以创建特殊名称的回调函数。这些函数将会由安装程序在安装时需要某些用途时调用。下面是当前可用的回调函数列表:
4.7.2.1 安装回调
4.7.2.1.1 .onGUIInit
该回调将会在第一个页面被载入并且显示安装程序对话框前被调用,允许你来调整用户界面。
例子:
!include "WinMessages.nsh"
Function .onGUIInit
# 1028 是标志文本控件的 ID
GetDlgItem $R0 $HWNDPARENT 1028
CreateFont $R1 "Tahoma" 10 700
SendMessage $R0 ${WM_SETFONT} $R1 0
# 设置背景颜色为白色,文本颜色为红色
SetCtlColors $R0 FFFFFF FF0000
FunctionEnd
4.7.2.1.2 .onInit
该回调将会在当安装程序接近完成初始化时调用。如果在 ‘.onInit’ 函数调用了 Abort ,则安装程序立即退出。
这里有两个例子说明了怎么使用:
Function .onInit
MessageBox MB_YESNO "即将安装。继续?" IDYES NoAbort Abort ; 使得安装程序退出。
NoAbort:
FunctionEnd
或:
Function .onInit
ReadINIStr $INSTDIR $WINDIRwincmd.ini
Configuration InstallDir
StrCmp $INSTDIR "" 0 NoAbort
MessageBox MB_OK "未找到 Windows Commander 。未能取得安装路径。"
Abort ; 使得安装程序退出。
NoAbort:
FunctionEnd
4.7.2.1.3 .onInstFailed
该回调函数当在安装失败后用户点击 ‘取消’ 按钮时被调用 (如果安装程序不能释放任何文件,或安装脚本使用了 Abort 命令)。
例子:
Function .onInstFailed
MessageBox MB_OK "祝您下次好运。"
FunctionEnd
4.7.2.1.4 .onInstSuccess
该回调当安装成功且正当安装窗口关闭前 (如果 AutoCloseWindow 或 SetAutoClose 被设为 false 时可能在用户点击 ‘关闭’ 之后) 调用。
例子:
Function .onInstSuccess
MessageBox MB_YESNO "恭喜,运行正常。查看自述文件?" IDNO NoReadme
Exec notepad.exe ; 查看自述文件或其他。
NoReadme:
FunctionEnd
4.7.2.1.5 .onGUIEnd
该回调正当安装程序窗口关闭之后被调用。需要时用来释放任何与用户界面有关的插件。
4.7.2.1.6 .onMouseOverSection
该回调只要鼠标在树形区段选择框上移动时就被调用。这可以使你给每个区段设置一个样本描述。鼠标停留所在的当前区段 ID 已被临时的保存,为 $0 。
例子:
Function .onMouseOverSection
FindWindow $R0 "#32770" "" $HWNDPARENT
GetDlgItem $R0 $R0 1043 ; 描述项 (必须添加到界面)
StrCmp $0 0 "" +2
SendMessage $R0 ${WM_SETTEXT} 0 "STR:第一个区段描述"
StrCmp $0 1 "" +2
SendMessage $R0 ${WM_SETTEXT} 0 "STR:第二个区段描述"
FunctionEnd
4.7.2.1.7 .onRebootFailed
该回调函数当 Reboot 指令失败时被调用。 WriteUninstaller, 插件, File 和 WriteRegBin 不能用于该回调函数。
例子:
Function .onRebootFailed
MessageBox MB_OK|MB_ICONSTOP "重启失败,请手动重启。" /SD IDOK
FunctionEnd
4.7.2.1.8 .onSelChange
当在 组件选择页面 选项被改变时被调用。常用于使用 SectionSetFlags 和 SectionGetFlags 。
组件选项被改变包括组件和安装类型被改变。
4.7.2.1.9 .onUserAbort
该回调当用户点击 ‘取消’ 按钮且安装尚未失败时被调用。如果该函数调用 Abort ,则安装将不退出。
例子:
Function .onUserAbort
MessageBox MB_YESNO "中止安装?" IDYES NoCancelAbort
Abort ; 使得安装程序不退出。
NoCancelAbort:
FunctionEnd
4.7.2.1.10 .onVerifyInstDir
该回调对于你的安装程序来说可以允许代为控制安装路径是否有效。每次用户更改安装路径的时候这段代码都会被调用一次,所以不要在这里使用 MessageBox 等指令。如果该函数调用 Abort ,则 $INSTDIR 的路径被认为无效。
例子:
Function .onVerifyInstDir
IfFileExists $INSTDIRWinamp.exe PathGood
Abort ; 如果 $INSTDIR 不是 winamp 文件夹路径,则不让用户安装在这里
PathGood:
FunctionEnd
4.7.2.2 卸载回调
4.7.2.2.1 un.onGUIInit
该回调将会在第一个页面被载入并且显示卸载程序对话框前被调用,允许你来调整卸载程序的界面。
例子请看 .onGUIInit 。
4.7.2.2.2 un.onInit
该回调将会在当卸载程序接近完成初始化时调用。如果 ‘un.onInit’ 函数使用了 Abort ,则卸载程序立即退出。注意如果需要时该函数可以验证和(或)修改 $INSTDIR 。
这里有两个例子说明了怎么使用:
Function un.onInit
MessageBox MB_YESNO "即将卸载。继续?" IDYES NoAbort
Abort ;使得卸载程序退出。
NoAbort:
FunctionEnd
或:
Function un.onInit
IfFileExists $INSTDIRmyfile.exe found
Messagebox MB_OK "卸载路径不正确"
Abort
found:
FunctionEnd
4.7.2.2.3 un.onUninstFailed
该回调当卸载成功且正当卸载程序窗口关闭前 ‘取消’ 按钮时被调用 (如果使用了 Abort 命令或其它失败的命令) 。
例子:
Function un.onUninstFailed
MessageBox MB_OK "祝你下次好运。"
FunctionEnd
4.7.2.2.4 un.onUninstSuccess
该回调当卸载成功且正当卸载程序窗口关闭前 (如果 SetAutoClose 被设为 false 时可能在用户点击 ‘关闭’) 调用。
例子:
Function un.onUninstSuccess
MessageBox MB_OK "恭喜,已经移除。"
FunctionEnd
4.7.2.2.5 un.onGUIEnd
该回调正当卸载程序窗口关闭之后被调用。需要时用来释放任何与用户界面有关的插件。
4.7.2.2.6 un.onRebootFailed
该回调函数当 Reboot 指令失败时被调用。 WriteUninstaller, 插件, File 和 WriteRegBin 不能用于该回调函数。
例子:
Function un.onRebootFailed
MessageBox MB_OK|MB_ICONSTOP "重启失败,请手动重启。" /SD IDOK
FunctionEnd
4.7.2.2.7 un.onSelChange
该回调函数当 组件选择页面 选项被改变时被调用。常用于使用 SectionSetFlags 和 SectionGetFlags 。
组件选项被改变包括组件和安装类型被改变。
4.7.2.2.8 un.onUserAbort
该回调当用户点击 ‘取消’ 按钮且卸载尚未失败时被调用。如果该函数调用 Abort ,则卸载程序将不退出。
例子:
Function un.onUserAbort
MessageBox MB_YESNO "中止卸载?" IDYES NoCancelAbort
Abort ; 使得卸载程序不能退出。
NoCancelAbort:
FunctionEnd
4.8 安装程序属性
4.8.1 常规属性
这些属性控制安装程序的外观和函数、包括哪个页面出现在安装程序里、在每个页面的每个部分显示什么文本、安装程序的名称、使用什么样的图标、默认安装目录、写入什么样的文件还有更多。注意这些属性可以在除了区段和函数以外的任何地方设置。
黑体并加下划线的为默认值
4.8.1.1 AddBrandingImage
(left|right|top|bottom) (width|height) [padding]
在安装程序顶部、底部、左边、右边添加一个标志图像。它的大小将由指定的宽/高、安装程序的宽/高和安装程序字体确定。最终的大小不一定就是你需要的,请看输出命令来得到实际大小。 因为这取决于安装程序字体,所以你应该在 AddBrandingImage 前使用 SetFont 。默认的填充值为 2 。
AddBrandingImage 仅增加图像到标识的位置,若要使图像以标志图像显示请使用 SetBrandingImage 命令。
AddBrandingImage left 100
AddBrandingImage right 50
AddBrandingImage top 20
AddBrandingImage bottom 35
AddBrandingImage left 100 5
4.8.1.2 AllowRootDirInstall
true|false
控制是否允许安装在驱动器根目录,或者共享网络。把它设为 ‘true’ 可以改变这个安全行为,此安全行为可以防止用户选择 C:或 ServerShare 来作为安装 (或卸载) 目录。对于另外的可定制的目录选择页面,请看 .onVerifyInstDir 。
4.8.1.3 AutoCloseWindow
true|false
设置当安装完成的时候窗口是否自动关闭。该属性可以不理会一个使用了 SetAutoClose 的区段。
4.8.1.4 BGFont
[font_face [height [weight] [/ITALIC] [/UNDERLINE] [/STRIKE]]]
指定用于背景渐变显示文本的字体。要设置颜色请使用 BGGradient 。如果没有指定参数,则使用默认的字体。默认字体为粗斜体的 Times New Roman 。
4.8.1.5 BGGradient
[off|(顶部颜色 底部颜色 [文本颜色|notext])]
指定是否使用一个渐变的背景窗口。如果为 ‘off’ ,安装程序将不显示背景窗口,如果无指定参数,则使用默认的黑蓝渐变,或者指定顶部颜色或底部颜色来得到一个渐变的背景。顶部颜色和底部颜色使用 RRGGBB (十六进制,就像 HTML, 但略去了 ‘#’,因为 # 用于注释)。你也可以指定 ‘文本颜色’”,该颜色会显示 ‘Name’ 所指定的名称在左上角,或者你不需要文本时使用 ‘notext’ 来关闭文本显示。
4.8.1.6 BrandingText
/TRIM(LEFT|RIGHT|CENTER) 文本
设置显示在安装程序窗口底部的文本(默认为 ‘Nullsoft Install System vX.XX’)。如果设为空字符串(“”) 则使用默认值;设为 ” ” (一个空格)则显示空白。如果你不知道哪个适合你,那就保留默认值吧,这样可以使每个人知道你使用的 NSIS 版本。使用 /TRIMLEFT, /TRIMRIGHT 或 /TRIMCENTER 来裁剪控制大小到字符串大小。
接受变量。如果使用了变量,使用的变量应该在 .onInit 里被初始化。
4.8.1.7 Caption
标题
当使用一个外部的 PageEx 区块:设置安装程序标题条文本。当使用了 Name 指令指定了名称时默认为 ‘$(^Name) 安装’。你可以把它替换为 ‘我的安装程序’ 或其他。如果你指定为空字符串 (“”),则使用默认值(你也可以指定为 ” ” 来使用一个空白字符串)。
当使用一个内部的 PageEx 区块:设置当前页面的子标题。
接受变量。如果使用了变量,使用的变量应该在 .onInit 里被初始化。
4.8.1.8 ChangeUI
对话框 ui_file.exe
使用 ui_file.exe 里相同资源 ID 的一个对话框替换对话框 (IDD_LICENSE, IDD_DIR, IDD_SELCOM, IDD_INST, IDD_INSTFILES, IDD_UNINST或 IDD_VERIFY)。你也可以指定 ‘all’ 作为一个对话框,当你想从同一个 UI 文件里一次载入替换全部 7 个对话框时。 一些 UI 实例请看位于 NSIS 目录下的 ContribUIs 。
- IDD_LICENSE 必须包含 IDC_EDIT1 (RICHEDIT 控件)。
- IDD_DIR 必须包含 IDC_DIR (编辑框), IDC_BROWSE (按钮) 和 IDC_CHECK1 (选择框)。
- IDD_SELCOM 必须包含 IDC_TREE1 (SysTreeView32 控件), 和 IDC_COMBO1 (组合框)。
- IDD_INST 必须包含 IDC_BACK (按钮), IDC_CHILDRECT (静态控制其他所有对话大小), IDC_VERSTR (静态文本框), IDOK (按钮), andIDCANCEL (按钮)。如果该对话框有一个图象控件(静态 SS_BITMAP 样式),那么它将被用于 SetBrandingImage 作为默认值。
- IDD_INSTFILES 必须包含 IDC_LIST1 (SysListView32 控件), IDC_PROGRESS (msctls_progress32 控件), 和 IDC_SHOWDETAILS (按钮)。
- IDD_UNINST 必须包含 IDC_EDIT1 (编辑框)。
- IDD_VERIFY 必须包含 IDC_STR (静态文本框)。
-
ChangeUI all "${NSISDIR}ContribUIssdbarker_tiny.exe"
4.8.1.9 CheckBitmap
bitmap.bmp
指定一个位图为用于组件选择页面树形列表选择框的图像。
该位图应该为 96×16 像素大小,不能多于 8位位深(bpp) (256 色)且包括六个用于不同状态(次序为: 鼠标点击反白边缘、未选时、已选时、子区段未选时、未选且只读、已选且只读)的 16×16 图像。使用粉红色为覆盖颜色(该区域实际时为透明)。
4.8.1.10 CompletedText
文本
指定了参数时替换在安装结束时的默认文本 (“完成”)。否则,使用默认值。
接受变量。如果使用了变量,使用的变量必须在文本输出之前初始化。
4.8.1.11 ComponentText
[文本 [子文本] [子文本2]]
用来更改组件选择页面的默认文本。
文本: 控件上的文本,到安装图标的右边。
子文本: 安装类型选择控件的文本。
子文本2: 安装类型选择控件下面、组件列表左边的文本。
如果字符串为空(“”)则使用默认文本。
接受变量。如果使用了变量,使用的变量必须在创建组件选择页面之前被初始化。
4.8.1.12 CRCCheck
on|off|force
指定安装前安装程序是否对自身执行一个 CRC 。注意,如果用户使用了 /NCRC 命令行参数,且你没有指定 ‘force’ 参数时,不会执行 CRC ,这样有可能导致用户安装一个损坏的安装程序。
4.8.1.13 DetailsButtonText
show details text
指定参数时替换默认详细信息按钮文本 “显示详细信息”,未指定参数时使用默认值。
接受变量。如果使用了变量,使用的变量必须在安装页面 (instfiles) 之前被初始化。
4.8.1.14 DirText
[文本] [子文本] [浏览按钮文本] [浏览对话框文本]
用来更改目录选择页面的默认文本。
文本: 控件上面的文本,右延至安装图标。
子文本: 在目录选择框架上的文本。
浏览按钮文本: 浏览按钮上的文本。
浏览对话框文本: 在点击 “浏览” 按钮后 “浏览目录” 对话框上的文本。
如果字符串为空(“”)则使用默认文本。
接受变量。如果使用了变量,使用的变量必须在创建目录选择页面之前被初始化。
4.8.1.15 DirVar
用户变量(目录输入输出)
指定用哪个变量来保存所选的目录。该变量也会保存默认值。这样可以很方便的建立两个不同的目录选择页面而不需要频繁的读取、写入 $INSTDIR 。默认的变量为 $INSTDIR 。它只能用于 PageEx 来确定目录变量和 uninstConfirm 页面。
Var ANOTHER_DIR
PageEx directory
DirVar $ANOTHER_DIR
PageExEnd
Section
SetOutPath $INSTDIR
File "a file.dat"
SetOutPath $ANOTHER_DIR
File "another file.dat"
SectionEnd
4.8.1.16 DirVerify
auto|leave
如果使用了 `DirVerify leave’ ,则当安装目录无效或磁盘空间不够用时下一步按钮将会被禁止并且你可以在离开函数里使用 GetInstDirError 来读取被设置的标记。
PageEx directory
DirVerify leave
PageCallbacks "" "" dirLeave
PageExEnd
4.8.1.17 FileErrorText
文件错误文本
替换当文件不能写入时显示的默认文本。该文本可以包含一个代表文件名的 $0 ($0 会被临时更改为该值)。例如: “文件 $r$n$0 不能写入$r$n祝你下次好运。”。
接受变量。如果使用了变量,使用的变量必须在使用 File 指令之前被初始化。
4.8.1.18 Icon
[路径]图标文件.ico
设置安装程序的图标。在图标文件里的每一个图标将会被包含在安装程序里。使用 UninstallIcon 指定卸载程序的图标。[译者注: 注意,如果你添加了卸载程序,那么图标文件里的和卸载程序图标文件对应的每一个图标必须有相同的尺寸大小和颜色位深。图标文件里的次序也要匹配。例如,如果安装程序图标文件有三个图标,第一个图标为 32×32 像素 8bpp,第二个图标为 16×16 像素 8bpp,第三个图标为 8×8 像素 8bpp,那么卸载程序图标文件必须也有三个图标,且这三个图标的大小、颜色位深和次序都要相同。]
4.8.1.19 InstallButtonText
安装按钮文本
如果指定了参数,则会把默认的 (“安装”) 按钮文本替换为你指定的文本。
接受变量。如果使用了变量,使用的变量必须在安装按钮显示之前被初始化。
4.8.1.20 InstallColors
/windows | (前景色 背景色)
设置安装信息屏幕颜色 (默认为 00FF00 000000)。使用 RRGGBB (十六进制,就像 HTML 那样,但略去了 ‘#’,因为 # 用于注释)。注意如果指定了 “/windows” 作为唯一的参数,将使用默认的 Windows 颜色。
4.8.1.21 InstallDir
默认安装目录
设定默认的安装目录。查看 变量 章节得到可用于该字符串的变量 (尤其是 $PROGRAMFILES)。注意该字符串中最后一个 后面的部分会被保留,当用户在安装时选择 ‘浏览’ 并取得新的目录字符串时,该部分会自动附加在后面(要禁止该行为你需要在目录字串后面添加一个额外的 ,但是你要使用引号把目录字符串括起来以避免被认为是断行处理)。如果没有起作用的话,还是使用浏览按钮吧。
4.8.1.22 InstallDirRegKey
根键 子键 键名
该属性让安装程序去检测注册表里的一个字符串,如果该字符串可用那么把它用来作为安装目录。如果预置了该属性,当指定的注册表键可用时它会越过 InstallDir 指定的字符串,否则使用默认的 InstallDir 指定值。查询注册表时,该命令将自动截去引号。如果该字符串以 “.exe” ,它还会自动移去字串里的文件名部分 (即如果字符串是 “C:program filespooppoop.exe” ,它会知道使用 “C:program filespoop”))。对于更多高级的安装目录配置,可在 .onInit 函数里设定 $INSTDIR 。[译者注: 事实上它还可以自动截取如 “C:program filespooppoop.exe” “%1” 而得到 C:program filespoop ,这样你只要知道了某个程序关联的文件类型,就可以直接用它获得该程序的安装目录。比如 InstallDirRegKey HKCR “FlashGet.Documentshellopencommand” “” 即可获得网际快车的安装目录]
语言字串和变量不能用于 InstallDirRegKey 。
InstallDirRegKey HKLM SoftwareNSIS ""
InstallDirRegKey HKLM "SoftwareACMEThingy InstallLocation"
4.8.1.23 InstProgressFlags
[标记 […]]
有效的标记值为 “smooth” (平滑进度条) 或 “colored” (把进度条着色为 InstallColors 指令设定的颜色)。例如: “InstProgressFlags” (默认 Windows 经典样式外观),”InstProgressFlags smooth” (新式平滑外观),”InstProgressFlags smooth colored” (新式平滑外观并着色)。注意:当安装程序运行在 Windows XP 且使用了新式主题时 “smooth” 或 “colored” 都不能与 XPStyle 共用。
4.8.1.24 InstType
安装类型名称 | /NOCUSTOM | /CUSTOMSTRING=字符串 | /COMPONENTSONLYONCUSTOM
把一个安装类型添加到安装类型列表里,或禁止自定义安装类型。最多可以增加到 32 类,每一个类型都需要指定安装类型名称。如果以 ‘un.’ 作前缀那么它就是一个卸载程序安装类型。在组件页面显示之前,你可以使用在运行时需要处理的用户变量而不是难以改变的代码来作为安装类型名称,这样你可以动态的改变安装类型的名称。另一个在运行时更改 InstType 名称的方法是 InstTypeSetText 命令。 所不同的是使用 InstTypeSetText 你可以保留你自己宝贵的用户变量。第一个类型为默认类型 (通常为 ‘典型安装’)。如果指定了 /NOCUSTOM 开关,那么 “自定义” 安装类型就会被禁止,那么用户就必须选择一个已经定义的安装类型。做为选择,如果指定了 /CUSTOMSTRING 开关,那么该开关的参数将会替代 “自定义” 安装类型文本。做为选择,如果指定了 /COMPONENTSONLYONCUSTOM 标记,那么组件列表仅在选择了 “自定义” 安装类型的时候才显示。
安装类型名称接受变量。如果使用了变量,使用的变量必须在创建组件页面之前被初始化。
4.8.1.25 LicenseBkColor
颜色 | /gray | /windows
设置许可协议数据的背景颜色。颜色使用 RRGGBB 格式(十六进制,就像 HTML 那样,但略去了 ‘#’ ,因为 # 用于注释)。默认为 ‘/gray’。你也可以使用 ‘/windows’ 来使用 Windows 操作系统定义的颜色。
4.8.1.26 LicenseData
许可文件.(txt|rtf)
指定一个用户读取许可协议的文本文件或 RTF 文件。如果没有许可协议需要显示那么可以忽略它。注意该文件必须是 DOS 文本格式 (rn, yeah!)。要定义多语言许可协议请使用 LicenseLangString 。
如果你使用 RTF 文件来显示许可协议推荐使用写字板(WordPad)来编辑而不是使用微软的 Word。使用写字板(WordPad)可以得到更小的文件。
你可以使用 LicenseLangString 来给每一种语言显示一个许可协议。
4.8.1.27 LicenseForceSelection
(checkbox [接受文本] | radiobuttons [接受文本] [拒绝文本] | off)
指定显示的许可协议是否必须被接受。可以使用单选框或互斥按钮的形式。默认情况下 “下一步” 按钮是禁止的并且只能在钩选了单选框选择了正确的互斥按钮后才可以进入下一步。如果指定了 off 则默认情况下 “下一步” 按钮是可用的。
LicenseForceSelection checkbox
LicenseForceSelection checkbox "我接受"
LicenseForceSelection radiobuttons
LicenseForceSelection radiobuttons "我接受"
LicenseForceSelection radiobuttons "我接受" "我不接受"
LicenseForceSelection radiobuttons "" "我不接受"
LicenseForceSelection off
4.8.1.28 LicenseText
[文本 [按钮文本]]
用来更改许可协议页面的默认文本。
文本: 控件上方的文本,右延至安装图标。
按钮文本: “我同意” 按钮上的文本。
如果字符串为空(“”)则使用默认文本。
接受变量。如果使用了变量,使用的变量必须在创建许可协议页面之前被初始化。
4.8.1.29 MiscButtonText
[上一步文本 [下一步文本] [取消按钮文本] [关闭按钮文本]]
替换这四个 (> 上一步、下一步 <、取消、关闭)。如果留空参数,将使用默认值代替。
接受变量。如果使用了变量,使用的变量必须在 un.onInit 里被初始化。
4.8.1.30 Name
名称 [双与名称]
设置安装程序的名称。名称通常用来显示产品的名称比如 ‘我的程序’ 或 ‘CrapSoft 我的程序’。如果在名称里有一个或多个与符号(&),把第二个参数设为与第一个相同,有 & 的地方使用两个 & 来表示。例如你的产品名称为 “Foo & Bar”,那么使用:
Name "Foo & Bar" "Foo && Bar"
如果你的安装程序名称里有 & 符号并且对名称使用了一个 LangString ,那么你还需要创建另一个含有双& 字符的名称作为第二个参数。
接受变量。如果使用了变量,使用的变量必须在 un.onInit 里被初始化。
4.8.1.31 OutFile
[路径]安装程序.exe
指定 MakeNSIS 要写入安装程序的输出文件。仅仅是 MakeNSIS 要写入的文件,它不会对安装程序的内容有任何影响。
4.8.1.32 RequestExecutionLevel
none|user|highest|admin
指定在 Windows Vista 下安装程序需要的执行级别。设定的级别值将被内嵌到安装/卸载程序的 XML manifest 中,告诉 Vista (或以后其他合适版本的 Windows)安装程序需要什么样的权限级别来执行。 user 只要求普通用户权限级别(不需要管理员组权限)。 highest 要求当前用户可用的最高权限级别,Windows 可能会提示输入用户密码来核实权限提升。 admin 要求管理员权限级别,同时 Windows 也会提示用户。设定为 none (缺省值),将会保持 manifest 为空并由 Windows 来判断所需执行级别。 Windows Vista 能自动识别 NSIS 安装程序并要求管理员权限来执行。因此, none and admin实际上具有相同效果。
建议使用 RequestExecutionLevel,至少微软要求所有应用程序都应标明执行级别。未标明级别的安装程序将运行于兼容模式,(兼容模式下执行环境所在的)当前用户 “开始菜单” 文件夹中该程序的快捷方式会被自动转移到所有用户 “开始菜单” 文件夹中。如果你的安装程序不需要向系统目录安装文件或向注册表 HKLM 主键下写入键值,那么应该指定为 user 执行级别。
更多相关信息可以在 MSDN 上找到,关键字包括 “UAC”, “requested execution level”, “vista manifest” 和 “vista security” 。
4.8.1.33 SetFont
[/LANG=语言 ID] 字体名 字体大小
设置安装程序字体大小。请记住你选择的字体在用户的机器上也要有,不要使用只有你自己有的字体。
如果你想对每一个语言设置不同的字体,使用 /LANG 开关。例如:
SetFont /LANG=${LANG_ENGLISH} "English Font" 9
SetFont /LANG=${LANG_FRENCH} "French Font" 10
有两个名称为 ^Font 和 ^FontSize 的 常量语言字串包含了每种语言对应的字体和字体大小。
4.8.1.34 ShowInstDetails
hide|show|nevershow
设置是否显示安装详细信息。你可以设为 ‘hide’ 来隐藏详细信息但用户可以查看,’show’ 用来默认显示详细信息,或 ‘nevershow’ 可以阻止用户查看任何信息。注意区段里可以使用 SetDetailsView 来更改它的设置。
4.8.1.35 ShowUninstDetails
hide|show|nevershow
设置是否显示卸载详细信息。你可以设为 ‘hide’ 来隐藏详细信息但用户可以查看,’show’ 用来默认显示详细信息,或 ‘nevershow’ 可以阻止用户查看任何信息。注意区段里可以使用 SetDetailsView 来更改它的设置。
4.8.1.36 SilentInstall
normal|silent|silentlog
指定安装程序是否静默安装。如果它为 ‘silent’ 或 ‘silentlog’ ,所有标记为 SF_SELECTED 的区段都会被安装而不做提示(你可以使用 SectionSetFlags 来设定区段的标记),安装程序本身没有任何屏幕输出(而脚本仍可以显示某些特定的输出,使用 MessageBox 的 /SD 参数来指定静默安装时默认的返回值)。注意如果设置为 ‘normal’ 且用户运行时使用了 /S (区分大小写)命令行参数时就相当于 SilentInstall 设置为 ‘silent’ 一样。注意: 也可以看 LogSet 。
欲了解更多信息查看 section 4.12 。
4.8.1.37 SilentUnInstall
normal|silent
指定卸载程序是否静默安装。如果它为 ‘silent’ ,卸载区段会被运行而不做提示,卸载程序本身没有任何屏幕输出 (而脚本仍可以显示某些特定的输出,使用 MessageBox 的 /SD 参数来指定静默安装时默认的返回值)。注意如果设置为 ‘normal’ 且用户运行时使用了 /S (区分大小写)命令行参数时就相当于 SilentUnInstall 设置为 ‘silent’ 一样。注意: 也可以看 LogSet 。
欲了解更多信息查看 section 4.12 。
4.8.1.38 SpaceTexts
[req text [avail text]]
如果指定了参数,将会取代安装所需空间和可用空间文本 (默认为 “所需空间: ” 和 “可用空间: “)。如果指定为 ‘none’ 则不会显示空间提示文本。
接受变量。如果使用了变量,使用的变量必须在创建组件选择页面之前被初始化。
4.8.1.39 SubCaption
[page_number subcaption]
取代每一个安装程序页面 (0=”: 许可协议”,1=”: 安装选项”,2=”: 安装目录”, 3=”: 正在安装”, 4=”: 安装完成”)的子标题。如果指定了空字符串 (“”),将使用默认值(你也可以指定 ” ” 来使用一个空白字符串)。
你也可以在一个 PageEx 区块内部使用 Caption 来设置一个子标题(或取代默认值)。
接受变量。如果使用了变量,使用的变量必须在相关页面创建之前被初始化。
4.8.1.40 UninstallButtonText
文本
替换卸载程序上默认为 “卸载” 的按钮文本。如果无指定参数,将使用默认的文本。也可以差看 WriteUninstaller (替换 UninstallEXEName) 。
接受变量。如果使用了变量,使用的变量必须在卸载按钮显示之前被初始化。
4.8.1.41 UninstallCaption
标题
设置卸载程序标题条上显示的文本。 默认情况下,它为由 Name 命令指定的 ‘卸载名称’ 。你可以取代它为 ‘的应用程序卸载’ 或其他。 如果指定了空字符串 (“”),将使用默认值(你也可以指定 ” ” 来使用一个空白字符串)。
接受变量。如果使用了变量,使用的变量必须在 un.onInit 里被初始化。
4.8.1.42 UninstallIcon
[路径]图标.ico
设置卸载程序的图标。
4.8.1.43 UninstallSubCaption
页面代号 子标题
设置卸载程序页面的默认子标题 (0=”: 卸载确认”,1=”: 正在卸载文件”,2=”: 卸载完成”)。如果指定了空字符串 (“”)(“”),将使用默认值 (你也可以指定 ” ” 来使用一个空白字符串)。
你也可以在一个 PageEx 区块内部使用 Caption 来设置一个子标题(或替换默认值)。
接受变量,如果使用了变量,使用的变量必须在相关的页面创建之前被初始化。
4.8.1.44 UninstallText
文本 [子文本]
指定卸载程序确认页面上的文本。
文本: 控件上方的文本
子文本: 卸载定位旁边的文本
接受变量,如果使用了变量,使用的变量必须在创建卸载确认页面之前被初始化。
4.8.1.45 WindowIcon
on|off
设置是否显示安装程序的图标。.
4.8.1.46 XPStyle
on|off
设置是否把 XP 外观添加到安装程序里。当运行在 Windows XP 时一个 XP 外观使得安装程序控件使用新的 XP 样式。这个设定也会影响卸载程序。
4.8.2 编译器标记
下面的命令可以告诉编译器如何去创建代码和压缩数据。除非另有说明,否则这些命令在脚本的任何地方都有效,并且影响着该命令下的每一行(直到被另一个命令覆盖)。不能使用 流程控制指令 跳过。
例如,在下面的脚本,blah.dat 文件不会被覆盖。
${If} $0 == 0
SetOverwrite on
${Else}
SetOverwrite off
${EndIf}
File blah.dat # 在这 overwrite 覆盖标记总为 off !
而下面的例子才是正确覆盖。
${If} $0 == 0
SetOverwrite on
File blah.dat
${Else}
SetOverwrite off
File blah.dat
${EndIf}
4.8.2.1 AllowSkipFiles
on|off
该命令指定用户是否可以跳过文件。如果 SetOverwrite 设为 on (默认)且当安装程序打开一个文件往里边写入东西失败时一个用户可以选择跳过文件。如果使用了 off 则不会显示允许用户跳过文件的忽略按钮,这样用户只能选择退出安装程序(取消按钮)或重试打开该文件写入(重试按钮) 。如果使用了 on 则用户可以选择跳过文件(同时置一个错误标记 – 查看 SetOverwrite)。
4.8.2.2 FileBufSize
缓冲大小(单位:MB)
该命令设置编译器内部文件缓冲大小。该命令允许你通过限制一个所给的文件一次性读入内存的多少来控制编译器的内存的使用。因为编译器需要输入和输出,所以文件缓冲时需要使用两倍指定的内存大小。该命令不会限制需要另一组内存大小的压缩器缓冲,也不会限制编译器另外的内部缓冲,因为这两个缓冲正常情况下无论如何也不能达到 1MB 。指定一个很小的数字可能会降低执行效率。指定过大的数字可能会耗尽系统的资源并迫使编译器退出编译处理。该默认值为 32MB 。
4.8.2.3 SetCompress
auto|force|off
该命令设置由安装程序使用来决定数据是否应该被压缩的压缩标记。典型的 SetCompress 标记将影响它后面的命令,并且脚本文件中的最后一个 SetCompress 命令也决定了是否压缩安装信息区段和卸载数据。如果压缩标记为 ‘auto’ ,那么仅当压缩后大小小于未压缩时文件才会被压缩。如果压缩标记为 ‘force’ ,则始终使用压缩。如果压缩标记为 ‘off’ ,则不使用压缩 (这样可以加快编译速度)。
注意该选项当使用了固实压缩方式后无效。
4.8.2.4 SetCompressor
[/SOLID] [/FINAL] zlib|bzip2|lzma
该命令设置了安装程序压缩文件、数据使用的压缩算法。该命令只能在区段、函数之外或在任何数据被压缩之前使用。不同的压缩方式不能在同一个安装程序里用来压缩不同的文件。建议在脚本的开始处使用这个命令来尽可能避免编译错误。
支持三种压缩方式: ZLIB, BZIP2 和 LZMA 。
ZLIB (默认) 使用压缩算法,是一个快速简单的方法。默认的压缩级别它消耗大约 300 KB 内存。
BZIP2 通常比 ZLIB 的压缩率好,但是稍微慢了一点并且内存的使用也多一点。默认的压缩级别它消耗大约 4 MB 内存。
LZMA 是一个压缩率比较理想的新式压缩方式。它的解压速度非常快(在 2 GHz 的 CPU 上能达到 10-20 MB/s 的速度),但是压缩速度很慢。解压时内存的使用量是字典的大小加上一些 KB ,默认值为 8 MB 。
如果使用了 /FINAL ,则 SetCompressor 后来的调用都会被忽略。
如果使用了 /SOLID 的话,所有的数据将被压缩在一个区块里,这样可以提高压缩率。
4.8.2.5 SetCompressorDictSize
字典大小(单位:MB)
设置使用 LZMA 压缩器时的字典大小(单位:MB) (默认为 8 MB)。
4.8.2.6 SetDatablockOptimize
on|off
该命令决定编译器是否优化数据区块。数据区块的优化首先由编译器检查要添加到数据区块的数据是否已经存在了,如果已存在,只需要简单的作为引用来添加(可以节省一点点大小)。非常强烈的推荐保留该选项为 on 。
4.8.2.7 SetDateSave
on|off
该命令设置了由 File 命令使用的文件保存日期、时间标记来决定是否保留最后上次写入文件的日期和时间,它可以在安装时储存下来。有效的开关为 ‘on’ 和 ‘off’。默认为 ‘on’ 。
4.8.2.8 SetOverwrite
on|off|try|ifnewer|ifdiff|lastused
该命令设置了由 File 命令使用的覆盖标记来决定目标文件已存在时是否覆盖。如果覆盖标记为 ‘on’ ,则目标文件被覆盖(这个是默认值))。如果覆盖标记为 ‘off’ ,则已存在的文件不会被覆盖。如果覆盖标记为 ‘try’ ,文件仅当可以被覆盖时(就是说假如文件不能写入,它会自动略过而不需要用户决定)才会覆盖目标文件。如果覆盖标记为 ‘ifnewer’ ,则仅当已存在的文件比新文件旧时才会覆盖目标文件。如果覆盖标记为 ‘ifdiff’ 则仅当已存在的文件比新文件旧或新时才会覆盖目标文件。注意在 ‘ifnewer’ 或 ‘ifdiff’ 模式下,目标文件的日期都会被设为新文件的日期,而不管 SetDateSave 是怎么设置的。
SetOverwrite off
File program.cfg # 配置文件将不会被覆盖
SetOverwrite on
4.8.3 版本信息
4.8.3.1 VIAddVersionKey
4.8.3.1 VIAddVersionKey
在文件属性的版本表格里添加一个字段。既可以是由系统提供的一个字段也可以是一个用户定义的字段。 以下的这些字段由系统提供:
- ProductName
- Comments
- CompanyName
- LegalCopyright
- FileDescription
- FileVersion
- ProductVersion
- InternalName
- LegalTrademarks
- OriginalFilename
- PrivateBuild
- SpecialBuild
这些字段名称由目标系统翻译,而用户自定义的字段则无翻译。
VIAddVersionKey /LANG=${LANG_ENGLISH}
"ProductName" "Test Application"
VIAddVersionKey /LANG=${LANG_ENGLISH} "Comments" "A test comment"
VIAddVersionKey /LANG=${LANG_ENGLISH} "CompanyName" "Fake company"
VIAddVersionKey /LANG=${LANG_ENGLISH} "LegalTrademarks" "Test Application is a trademark of Fake company"
VIAddVersionKey /LANG=${LANG_ENGLISH} "LegalCopyright" "� Fake company"
VIAddVersionKey /LANG=${LANG_ENGLISH} "FileDescription" "Test Application"
VIAddVersionKey /LANG=${LANG_ENGLISH} "FileVersion" "1.2.3"
4.8.3.2 VIProductVersion
[版本字串_X.X.X.X]
在文件属性版本表格的顶部添加产品版本号。
VIProductVersion "1.2.3.4"
4.9 指令
4.9.1 基本指令
NSIS 用于脚本的这些指令稍微的近似于 PHP 和汇编。它们没有真正的高级语言结构,但是他们的指令(大多数情况下)却是高级的,并且你可以很容易的掌握(比如你不用担心字串的连接等等)。基本上你有 25 寄存器 (20 个常规用途, 5个特殊用途),和一个堆栈。
4.9.1.1 Delete
[/REBOOTOK] 文件
从目标系统删除文件文件(可以是文件或通配符,但必须指定一个完整的路径)。如果指定了 /REBOOTOK 并且该文件当前不可删除,则会在系统重启时删除该文件 — 如果该文件要在系统重启时删除,你还要设置一个重启的标记。如果找到的文件不能被删除则会置一个错误标记。但该错误标记不是为尝试删除一个不存在的文件设置的。
Delete $INSTDIRsomefile.dat
4.9.1.2 Exec
命令
执行一个指定的程序并且立即继续安装。注意指定的文件必须存在于目标系统而不是编译的系统。 $OUTDIR 用于指定工作路径。如果该命令不能被运行则会置一个错误标记。注意,如果该命令包含空格,你要用引号来把他们包括起来。例如: Exec ‘”$INSTDIRcommand.exe” 参数’ 。如果你不用引号括起来则在 Windows 9x下不正常或丢失参数。
Exec '"$INSTDIRsomeprogram.exe"' Exec '"$INSTDIRsomeprogram.exe" 某些参数'
4.9.1.3 ExecShell
动作 命令 [参数] [SW_SHOWNORMAL | SW_SHOWMAXIMIZED | SW_SHOWMINIMIZED | SW_HIDE]
使用 ShellExecute [译者注: Windows 的外壳关联] 执行指定的程序。注意: “动作” 通常为 “open”, “print” 等等,也可以是一个空字符串来使用默认动作。参数和显示类型是可选项。 $OUTDIR 用于指定工作路径。如果该命令不能被运行则会置一个错误标记。
ExecShell "open" "http://nsis.sf.net/" ExecShell "open" "$INSTDIRreadme.txt" ExecShell "print" "$INSTDIRreadme.txt"
4.9.1.4 ExecWait
命令 [用户变量(退出代码)]
执行一个指定的程序并且等待运行处理结束。更多信息请查看 Exec 。当程序执行返回一个非零错误代码或者当产生错误时,如果没有指定 “用户变量(返回代码)” 则 ExecWait 会放置一个错误标记。如果指定了 “用户变量(返回代码)” 则 ExecWait 会把变量设为返回代码(并且仅当产生错误时放置一个错误标记;如果产生错误则该用户变量的内容为未指定)。注意:如果该命令包含空格,你要用引号来把他们包括起来。例如: ExecWait ‘”$INSTDIRcommand.exe” 参数’ 。如果你不用引号括起来则在 Windows 9x 下 不 正常或丢失参数。
ExecWait '"$INSTDIRsomeprogram.exe"' ExecWait '"$INSTDIRsomeprogram.exe"' $0 DetailPrint "程序返回了 $0"
4.9.1.5 File
[/nonfatal] [/a] ([/r] [/x 文件|通配符 […]] (文件|通配符) […] | /oname=输出路径文件名 输入路径文件名)
释放文件到当前输出路径 ($OUTDIR)。
- 注意输出文件名是 $OUTDIR文件名 。
- 如果使用了 /oname=X 开关将改变输出名称。X 可以包含变量,它可以是一个完整的路径或一个相对路径(在这种情况下,由 SetOutPath 被附加到 $OUTDIR)。当使用了 /oname= 开关时只能指定一个文件。如果输出名称包含了空格,你需要用双引号把参数括起来,包括 /oname,就像下面例子显示的那样。
- 支持通配符。
- 如果使用了 /r 开关,匹配的文件和目录会在子目录里被递归的搜索。如果不确切说明是一个路径 (例如
File /r something
),那么当前目录将被递归搜索。如果确切说明是一个路径 (例如File /r something*.*
),路径最后部分将被作为符合条件匹配的目录而剩余部分由目录递归搜索。如果目录名匹配则所有包含的内容都会被递归添加,目录结构也会被保持。 - 使用 /x 开关可以用来排除文件或目录。
- 如果使用了 /a 开关,则被添加的文件的属性将会保持。
- 如果覆盖模式被设定为 ‘try’ 并且文件不能覆盖,那么 File 命令将会置一个错误标记,或者如果覆盖模式被设定为 ‘on’ 并且文件不能覆盖并用户选择了忽略时,也会放置一个错误标记。
- 如果使用了 /nonfatal 开关且当文件未找到时使用警告来代替错误。
-
File something.exe File /a something.exe File *.exe File /r *.dat File /r data File /oname=temp.dat somefile.ext File /oname=$TEMPtemp.dat somefile.ext File "/oname=$TEMPname with spaces.dat" somefile.ext File /nonfatal "一个可能不存在的文件" File /r /x CVS myproject*.* File /r /x *.res /x *.obj /x *.pch source*.*
注意: 在使用了 /r 开关后,所有匹配的目录和文件都会被搜索。不管是否使用通配符它都会执行,即使所给的路径与一个目录完全符合。也就是说,以下的目录结构:
something file.dat another.dat
dir something
dir2 file2.dat
another
something readme.txt
File /r something
会在根目录下匹配名为 something 的目录,以及 dir 目录中的 something 文件和 another 目录中的 something 目录。只在根目录中匹配名为something 的目录时,应该这样:
File /r something*.*
当添加了 *.* 时,会将它作为匹配条件,并且 something 会被当成文件夹进行搜索。当仅指定 something 时,当前目录会被递归搜索所有的something 目录,这样 anothersomething 目录就会匹配。
4.9.1.6 Rename
[/REBOOTOK] 源文件 目标文件
移动时(比如,目标文件已存在),则该文件在系统重启后才被移动到目标。如果文件在重启后才被移动,则会放置一个重启的标记。当文件不能被重命名时(并且没有使用 /REBOOTOK)或者原文件不存在时,会放置一个错误标记。
如果没有指定绝对路径则使用当前路径代替。当前路径可以由上一个 SetOutPath 指令来设置。[译者注:即使用 SetOutPath 设置当前路径,默认使用上一个 SetOutPath 指令设置当前路径。在创建快捷方式时需要注意这个问题,涉及到快捷方式的起始位置。]如果你没有使用 SetOutPath 那么当前路径为 $EXEDIR 。
Rename $INSTDIRfile.ext $INSTDIRfile.dat
4.9.1.7 ReserveFile
[/nonfatal] [/r] [/x file|通配符 […]] 文件 [文件…]
把文件保存在稍后使用的数据区块。文件将按照在脚本里出现的次序依次添加到压缩的数据区块。因为函数不必要按照它们出现在脚本里的次序调用,因此如果你把文件添加到一个早期就调用但却放在脚本最后的函数的时候,早期需要的文件需要解压出来,那么当文件很多的时候就需要很长的时间去解压这些文件。.onInit 就是这样的一个函数。它总是在安装程序初始化的时候被调用,如果你把这个函数放在了脚本的最后,这个函数所需要的文件之前还有很多文件,那么当你解压这些需要的文件的时候安装程序就需要大量的时间才能载入。这就是为什么这个命令很有用的原因,这个命令能加快安装程序的载入,使用这个命令后它可以把早期需要的文件添加到数据区块的顶端而不是让 NSIS 把压缩的数据区块从顶端搜索到底部后才把这些文件解压出来。
欲了解更多关于参数的信息,请查看 File 。
4.9.1.8 RMDir
[/r] [/REBOOTOK] 目录名
删除指定的目录(没有通配符的完整路径)。没有 /r 参数时只有在目录为空时才会被删除。如果指定了 /r ,则目录会被递归删除,所以在指定目录下的所有文件和目录均被删除。如果指定了 /REBOOTOK ,任何当前不能删除的文件或目录将会在重启后被删除 — 如果文件或目录需要在重启时被删除,会放置一个重启的标记。当文件或目录不能被删除时放置一个错误的标记。
RMDir $INSTDI
RMDir $INSTDIRdata
RMDir /r /REBOOTOK $INSTDIR
RMDir /REBOOTOK $INSTDIRDLLs
需要注意的是当前的工作目录不能删除。当前的工作目录由 SetOutPath 设定。例如,下面的例子将不能删除该目录。
SetOutPath $TEMPdir RMDir $TEMPdir
而下面的例子将成功地删除该目录。
SetOutPath $TEMPdir SetOutPath $TEMP RMDir $TEMPdir
警告: 在卸载程序中使用 RMDir /r $INSTDIR 是不安全的。虽然用户不太可能会选择将程序安装到 Program Files 文件夹中,但假如这样的话,这个命令将会递归删除整个 Program Files 文件夹,包括其他和卸载程序没有任何关系的程序(目录)。用户还可以安装除了程序文件之外的其他文件并希望它们能被卸载程序删除。可用的 解决方案 可以轻松地实现只卸载由安装程序释放的唯一文件。
4.9.1.9 SetOutPath
输出路径
设置输出路径 ($OUTDIR) 且当路径不存在时创建(需要时会递归创建)。必须为全路径名,通常都使用 $INSTDIR 。
SetOutPath $INSTDIR File program.exe
4.9.2 注册表、INI 文件指令
在下面所有的注册表指令里你可以使用一个空字符串 (“”) 来作为某个子健默认项,该默认项在注册表编辑器里显示为 “(默认)” 。
如果要处理的 INI 文件的路径没有指定,则使用 Windows 目录来代替。
4.9.2.1 DeleteINISec
文件 区段名
从 “INI文件” 里删除整个区段 “区段名” 。如果该区段不能被删除,会放置一个错误的标记。但是如果该区段找不到时则不会放置错误标记。
WriteINIStr $TEMPsomething.ini section1 something 123
WriteINIStr $TEMPsomething.ini section1 somethingelse 1234
WriteINIStr $TEMPsomething.ini section2 nsis true
DeleteINISec $TEMPsomething.ini section1
4.9.2.2 DeleteINIStr
INI文件 区段名 字符串
从 “INI文件” 里的 “区段名” 区段删除 “字符串” 字符串。如果该字符串不能被删除,会放置一个错误的标记。但是如果该字串找不到时,则不会放置错误标记。
WriteINIStr $TEMPsomething.ini section1 something 123
WriteINIStr $TEMPsomething.ini section1 somethingelse 1234
DeleteINIStr $TEMPsomething.ini section1 somethingelse
4.9.2.3 DeleteRegKey
[/ifempty] 根键 子键
删除一个注册表键。如果指定了 /ifempty ,则该注册表键仅当它无子键时才会被删除(否则,整个注册表键将被删除)。有效的根键值在后面的 WriteRegStr 列出。如果该键不能被删除(或如果它不存在) 则会放置一个错误的标记。
DeleteRegKey HKLM "SoftwareMy CompanyMy Software"
DeleteRegKey /ifempty HKLM "SoftwareA key that might have subkeys"
4.9.2.4 DeleteRegValue
根键 子键 键名
删除一个注册表键值。有效的根键值在后面的 WriteRegStr 列出。如果该键值不能被删除(或如果它不存在)则会放置一个错误的标记。
DeleteRegValue HKLM "SoftwareMy CompanyMy Software" "some value"
4.9.2.5 EnumRegKey
用户变量(输出) 根键 子键 索引
查询 “根键子键” 第 ‘索引’ 号注册表的键并输出到用户变量 $x 。有效的根键值在后面的 WriteRegStr 列出。当指定的 “根键子键” ,没有任何键时会返回一个空字符串,当产生一个错误时会返回空符字串并放置一个错误标记。
StrCpy $0 0 loop:
EnumRegKey $1 HKLM Software $0
StrCmp $1 "" done
IntOp $0 $0 + 1
MessageBox MB_YESNO|MB_ICONQUESTION "$1$n$n更多?" IDYES loop done:
4.9.2.6 EnumRegValue
用户变量(输出) 根键 子键 索引
查询 “根键子键” 第 ‘索引’ 号注册表的键并输出到用户变量 $x 。有效的根键值在后面的 WriteRegStr 列出。当指定的 “根键子键” ,没有任何键时会返回一个空字符串,当产生一个错误时会返回空符字串并放置一个错误标记。
StrCpy $0 0 loop:
ClearErrors
EnumRegValue $1 HKLM SoftwareMicrosoftWindowsCurrentVersion $0
IfErrors done
IntOp $0 $0 + 1
ReadRegStr $2 HKLM SoftwareMicrosoftWindowsCurrentVersion $1
MessageBox MB_YESNO|MB_ICONQUESTION "$1 = $2$n$n更多?" IDYES loop done:
4.9.2.7 ExpandEnvStrings
用户变量(输出) 字符串
把 字符串 里的环境变量展开到用户变量 $x 。如果环境变量不存在,则字串不会被替换。例如,你使用 “%var%” 而 var 不存在,输出还是 “%var” 。如果发生错误,该变量会被设为空值并放置一个错误标记。
ExpandEnvStrings $0 "WINDIR=%WINDIR%$nTEMP=%TEMP%"
4.9.2.8 FlushINI
INI文件名
刷新 INI 文件缓冲。 Windows 9x 会保持 INI 文件在内存里。该命令强制更改立即写入磁盘。当你自己编辑一个 INI 文件的时候可以使用它,删除、移动、复制,直到你使用 WriteINIStr, DeleteINISec 或 DeleteINStr 来更改它。
WriteINIStr $TEMPsomething.ini test test test
FlushINI $TEMPsomething.ini
Delete $TEMPsomething.ini
4.9.2.9 ReadEnvStr
用户变量(输出) 名称
从环境字串里读取 “名称” 并把值赋给用户变量 $x 。如果读取字串时有错误发生,该用户变量被设为空,并放置一个错误标记。
ReadEnvStr $0 WINDIR ReadEnvStr $1 TEMP
4.9.2.10 ReadINIStr
用户变量(输出) INI文件 区段名 项
从 “INI文件” 的 “区段名” 区段读取 “项” 的值并把该值输出到用户变量。如果该项未找到时.会放置一个错误标记且该用户变量被赋为空值。
ReadINIStr $0 $INSTDIRwinamp.ini winamp outname
4.9.2.11 ReadRegDWORD
用户变量(输出) 根键 子键 项
从注册表读取一个 32 位 DWORD 并输出到用户变量 $x 。有效的根键值在后面的 WriteRegStr 列出。如果字串不存在时会放置一个错误标记并把 $x 设为空字符串。如果该值存在但是 DWORD,则会转换为字串类型并放置一个错误标记。
ReadRegDWORD $0 HKLM SoftwareNSIS VersionBuild
4.9.2.12 ReadRegStr
用户变量(输出) 根键 子键 项
从注册表读取一个字符串值并输出到用户变量 $x 。有效的根键值在后面的 WriteRegStr 列出。如果字符串不存在时,会放置一个错误标记并把 $x 设为空字符串 (“”) 。如果该值存在且为 REG_DWORD ,则会转换为字符串类型并放置一个错误标记。
ReadRegStr $0 HKLM SoftwareNSIS ""
DetailPrint "NSIS is installed at: $0"
4.9.2.13 WriteINIStr
INI文件 区段名 项 值
把 “项 ” = “值” 写入 “INI文件” 的 “区段名” 。 如果 INI 文件不能写入则放置一个错误的标记。
WriteINIStr $TEMPsomething.ini section1 something 123
WriteINIStr $TEMPsomething.ini section1 somethingelse 1234
WriteINIStr $TEMPsomething.ini section2 nsis true
4.9.2.14 WriteRegBin
根键 子键 项 值数据
该命令将会写一个区块的二进制数据到注册表。有效的根键值在后面的 WriteRegStr 列出。值数据为十六进制格式 (例如 DEADBEEF01223211151)。如果该二进制数据不能写入注册表则放置一个错误的标记。如果注册表键不存在则会自动创建。“
WriteRegBin HKLM "SoftwareMy CompanyMy Software" "Binary Value" DEADBEEF01223211151
4.9.2.15 WriteRegDWORD
根键 子键 项 值
该命令写一个 Dword (32 位整数) 到注册表 (以使用变量)。有效的根键值在后面的 WriteRegStr 列出。如果该 Dword 不能写入注册表则会放置一个错误的标记。如果注册表键不存在则会自动创建。
WriteRegDWORD HKLM "SoftwareMy CompanyMy Software" "DWORD Value" 0xDEADBEEF
4.9.2.16 WriteRegStr
根键 子键 项 值
把字符串写入注册表。详细信息请查看 WriteRegExpandStr 。
WriteRegStr HKLM "SoftwareMy CompanyMy Software" "String Value" "dead beef"
4.9.2.17 WriteRegExpandStr
根键 子键 项 值
把字符串写入注册表。 root_key 必须为下面列表之一:
- HKCR 或 HKEY_CLASSES_ROOT
- HKLM 或 HKEY_LOCAL_MACHINE
- HKCU 或 HKEY_CURRENT_USER
- HKU 或 HKEY_USERS
- HKCC 或 HKEY_CURRENT_CONFIG
- HKDD 或 HKEY_DYN_DATA
- HKPD 或 HKEY_PERFORMANCE_DATA
- SHCTX 或 SHELL_CONTEXT
如果 根键 是 SHCTX 或 SHELL_CONTEXT, 当 SetShellVarContext 设置为 all 时,它将被替换成HKLM ;当 SetShellVarContext 设置为 current时,它将被替换成 HKCU 。
如果字符串不能写入注册表,则放置一个错误的标记。字符串的类型为 REG_SZ 对应 WriteRegStr ,或 REG_EXPAND_STR 对应 WriteRegExpandStr 。如果注册表键不存在,则会自动创建。
WriteRegExpandStr HKLM "SoftwareMy CompanyMy Software" "Expand String Value" "%WINDIR%notepad.exe"
4.9.3 常规用途指令
4.9.3.1 CallInstDLL
DLL文件 函数
从一个 NSIS 扩展动态链接库里调用一个 函数 。查看 实例插件 的例子可以知道如何来创建。扩展动态链接库可以访问堆栈和变量。注意: 要自动释放并调用 DLL 插件请使用插件命令而不是 CallInstDLL 。
Push "参数"
Push "另一个参数"
CallInstDLL $INSTDIRsomedll.dll somefunction
要想更简单地使用插件,可使用新的 插件调用语法 。
4.9.3.2 CopyFiles
[/SILENT] [/FILESONLY] 目标系统文件(规范) 目标路径 [文件大小(单位:KB)]
在正在安装的系统中把 “目标系统文件(规范)” 复制到 “目标路径” 。如果你想从安装媒体里复制,或从系统的一个地方复制到另一个地方,你可以使用 $EXEDIR 变量来代替安装程序目录。如果复制操作需要很长时间的话你可以看到 Windows 的复制文件窗口 (要禁止出现复制文件窗口使用 /SILENT) 。最后的参数用来指定要复制的文件的大小(单位: KB ),使安装程序可以估计所需磁盘空间。当出错,或用户退出 (仅当忽略了 /SILENT)时,会放置一个错误标记。 如果指定了 /FILESONLY 则仅复制文件。
这个指令应该使用完整的路径,使用相对路径将得到不可预料的结果。
CreateDirectory $INSTDIRbackup CopyFiles $INSTDIR*.dat $INSTDIRbackup
4.9.3.3 CreateDirectory
要创建的路径
创建(递归创建)指定的目录。当目录不能创建时会放置一个错误标记。
你也可以指定一个绝对路径。
CreateDirectory $INSTDIRsomedirectory
4.9.3.4 CreateShortCut
快捷文件.lnk 目标文件 [参数 [图标文件 [图标索引号 [启动选项 [键盘快捷键 [描述]]]]]]
创建一个指向 ‘目标文件’ 的快捷方式 ‘快捷文件.lnk’ ,可以带 ‘参数’ 参数。 用于快捷方式的图标为 “图标文件,图标索引号” ;要使用默认图标的话把 “图标文件” 和 “图标索引号” 设为空字符串。 “启动选项” 可以是它们之一: SW_SHOWNORMAL, SW_SHOWMAXIMIZED, SW_SHOWMINIMIZED, 或一个空字符串。 “键盘快捷键” 应该为 ‘flag|c’ 格式且 flag 可以联合使用 (使用 |) : ALT, CONTROL, EXT, 或 SHIFT 。c 为要使用的字符 (a-z, A-Z, 0-9, F1-F24, 等等)。注意在这些字串里不能含有空格。一个典型的例子为 “ALT|CONTROL|F8” 。$OUTDIR 被用来作为工作目录。你可以在创建快捷方式之前使用 SetOutPath 来指定或更改。 “描述” 为快捷方式的描述,或在 XP 下作为注释调用。 当快捷方式不能创建的时会放置一个错误标记(例如: 路径 (链接路径或目标路径) 不存在或一些其它错误)。
CreateDirectory "$SMPROGRAMSMy Company"
CreateShortCut "$SMPROGRAMSMy CompanyMy Program.lnk" "$INSTDIRMy Program.exe" "some command line parameters" "$INSTDIRMy Program.exe" 2 SW_SHOWNORMAL ALT|CONTROL|SHIFT|F5 "a description"
4.9.3.5 GetDLLVersion
文件名 用户变量(高位 DWORD 输出) 用户变量(低位 DWORD 输出)
从 “文件名” DLL (或其他包含版本信息的可执行文件) 取得版本信息。成功时把版本信息高位 Dwords 和低位 DWORD 设为用户输出变量;失败时输出为空且置错误标记。下面的例子演示了读取一个 DLL 版本并可读的版本到 $0 :
GetDllVersion "$INSTDIRMyDLL.dll" $R0 $R1
IntOp $R2 $R0 / 0x00010000
IntOp $R3 $R0 & 0x0000FFFF IntOp $R4 $R1 / 0x00010000
IntOp $R5 $R1 & 0x0000FFFF
StrCpy $0 "$R2.$R3.$R4.$R5"
4.9.3.6 GetDLLVersionLocal
localfilename 用户变量(高位 DWORD 输出) 用户变量(低位 DWORD 输出)
类似于 GetDLLVersion ,但它仅用于获取安装程序内部文件的信息(它实际上编译为两个 StrCpy 命令)。成功时把内部文件的版本信息高位 DWORD 和低位 DWORD 设为用户输出变量。
4.9.3.7 GetFileTime
文件名 用户变量(高位 DWORD 输出) 用户变量(低位 DWORD 输出)
获取 “文件名” 的最后写入时间。成功时把时间戳信息高位 DWORD 和低位 DWORD 输出到用户输出变量;失败时输出为空且置一个错误标记。
4.9.3.8 GetFileTimeLocal
内部文件 用户变量(高位 DWORD 输出) 用户变量(低位 DWORD 输出)
类似于 GetFileTime ,但它仅用于获取安装程序内部文件的信息 (它实际上编译为两个 StrCpy 命令) 。成功时把时间戳信息高位 DWORD 和低位 DWORD 输出到用户输出变量。
4.9.3.9 GetFullPathName
[/SHORT] 用户变量(输出) 路径或文件
把指定的文件完整路径信息输出到用户变量。如果参数的部分路径未找到,则会放置一个错误位标记并清空输出变量。如果指定了 /SHORT ,路径将会被转换为短文件名格式。如果没有指定 /SHORT ,路径不会被转换为短文件名格式。要获得长文件名,使用 System 插件调用 GetLongPathName 函数。请注意,GetLongPathName 仅适用于 Windows 98, Windows 2000 及以上。
StrCpy $INSTDIR $PROGRAMFILESNSIS
SetOutPath $INSTDIR
GetFullPathName $0 ..
DetailPrint $0 # will print C:Program Files
GetFullPathName /SHORT $0 $INSTDIR
DetailPrint $0 # will print C:Progra~1NSIS
StrCpy $0 C:Progra~1NSIS
System::Call 'kernel32::GetLongPathName(t r0, t .r1, i ${NSIS_MAX_STRLEN}) i .r2'
StrCmp $2 error +2 StrCpy $0 $1
DetailPrint $0 # will print C:Program FilesNSIS, where supported
4.9.3.10 GetTempFileName
用户变量(输出) 基本路径
把一个临时文件的名称输出到用户变量。该文件会自动创建,所以你可以随时的覆盖它。该临时文件的名称唯一。如果你希望这个临时文件创建在另一个目录而不是 Windows 临时目录的话指定一个 “基本路径” 给它。该临时文件需要在完成之后手动删除。
GetTempFileName $0 File /oname=$0 something.dat # 其它一些关于 something.dat 的操作
Delete $0
4.9.3.11 SearchPath
用户变量(输出) 文件名
由第二个参数指定的文件名的全路径输出到用户变量。如果该文件不存在则会置一个错误位标记并清空输出的变量。使用 SearchPath() 来在系统目录里搜索文件。
4.9.3.12 SetFileAttributes
文件名 属性1|属性2|…
设置文件的属性。多从属性可用 ‘ | ‘ 隔开,有效的属性为:
- NORMAL 或 FILE_ATTRIBUTE_NORMAL (你可以把该项缩写为 0 )
- ARCHIVE 或 FILE_ATTRIBUTE_ARCHIVE
- HIDDEN 或 FILE_ATTRIBUTE_HIDDEN
- OFFLINE 或 FILE_ATTRIBUTE_OFFLINE
- READONLY 或 FILE_ATTRIBUTE_READONLY
- SYSTEM 或 FILE_ATTRIBUTE_SYSTEM
- TEMPORARY 或 FILE_ATTRIBUTE_TEMPORARY
如果文件的属性不能被设置则置一个错误的标记 (例如: 文件不存在,或者你没有足够的权限)。你只能进行属性设置,而不能移除属性,如果你想移除的话请使用 NORMAL 。这样所有的属性都会被擦除,该命令不支持通配符。
4.9.3.13 RegDLL
DLL文件 [入口点名称]
载入指定的 DLL 并且调用 DllRegisterServer (或入口点名称,当指定之后) 。当产生一个错误的时候会置一个错误标记 (例如: 不能载入 DLL, 不能初始化 OLE, 不能找到入口点, 或者函数返回任何其它错误 ERROR_SUCCESS (=0)) 。
当某些要注册的 DLL 要依靠其它的位于同目录或 Windows 目录下的 DLL 时请用 SetOutPath 来设定当前目录。例如,如果 foo.dll 依靠位于 $INSTDIR 的 bar.dll:
SetOutPath $INSTDIR
RegDLL $INSTDIRfoo.dll
4.9.3.14 UnRegDLL
Dll文件
载入指定的 DLL 并且调用 DllUnregisterServer 。当产生一个错误的时候会置一个错误标记 (例如:不能载入 DLL, 不能初始化 OLE, 不能找到入口点, 或者函数返回任何其它错误 ERROR_SUCCESS (=0)) 。
4.9.4 流程控制指令
4.9.4.1 Abort
[用户信息]
取消安装,停止执行脚本,并且在状态显示里显示用户信息。注意: 你可以用于 回调函数 来实现一些特殊功能。 页面回调 也可以用 Abort 来实现特殊目的。
Abort Abort “不能安装”
4.9.4.2 Call
函数名 | :标记名 | 用户变量(输入)
调用 函数名 函数或调用 标记名 的标记,或者包含地址的一个变量。地址值可以由 GetCurrentAddress, GetFunctionAddress 或 GetLabelAddress 返回。当使用了 Return 指令后调用将返回。区段和函数可以自动结束于 Return 指令。卸载函数不能由安装区段或函数调用,反之亦然。
Function func
Call :label
DetailPrint "#1: This will only appear 1 time."
label:
DetailPrint "#2: This will appear before and after message #1."
Call :.global_label
FunctionEnd
Section
Call func
Return
.global_label:
DetailPrint "#3: The global label was called"
SectionEnd
4.9.4.3 ClearErrors
清除错误位标记。
ClearErrors
IfErrors 0 +2
MessageBox MB_OK "此消息框将永远不会显示"
4.9.4.4 GetCurrentAddress
用户变量(输出)
获取当前指令的地址 (GetCurrentAddress) 并且把它保存到用户输出变量。该用户变量可以传递到 Call或 Goto 。
Function func
DetailPrint "function"
IntOp $0 $0 + 2
Call $0
DetailPrint "function end"
FunctionEnd
Section
DetailPrint "section"
DetailPrint "section"
GetCurrentAddress $0
Goto callFunc
DetailPrint "back to section"
Return
callFunc:
Call func
DetailPrint "section end"
SectionEnd
4.9.4.5 GetFunctionAddress
用户变量(输出) 函数名
获取函数地址并且把它保存到用户输出变量。该用户变量可以传递到 Call 或 Goto 。注意如果你 Goto 一个由 GetFunctionAddress 输出的地址,你的函数将不能返回 (当你 Goto 的函数要返回时,你应该立即返回)。
Function func
DetailPrint "function"
FunctionEnd
Section
GetFunctionAddress $0 func
Call $0
SectionEnd
4.9.4.6 GetLabelAddress
用户变量(输出) 标记
获取标记地址并且把它保存到用户输出变量。该用户变量可以传递到 Call 或 Goto 。需要注意的是你可能仅能从你的函数里随标记调用该指令,但是你可以从任何地方调用它(可能存在不稳定因素)。需要注意的是如果你调用(Call)了 GetLabelAddress 的输出,那么直到它返回时才会被执行(明确或隐含在一个函数的结尾),然后你将回到 Call 指令的状态。
label:
DetailPrint "label"
GetLabelAddress $0 label
IntOp $0 $0 + 4
Goto $0
DetailPrint "done"
4.9.4.7 Goto
要跳转的标记 | +偏移| -偏移| 用户变量(目标地址)
如果指定了标记,则跳转到 ‘要跳转的标记:’ 。
如果指定了 “+偏移” 或 “-偏移” ,跳转会根据偏移指令相对的跳转。 Goto +1 跳转到下一条指令,Goto -1 跳转到上一条指令,等等。
如果指定了用户变量,则跳转到绝对地址(通常你可以从一个函数,比如 GetLabelAddress)。编译器标记命令和 SectionIn 不是指令,所以跳转对它们无效。
Goto label
Goto +2
Goto -2
Goto $0
4.9.4.8 IfAbort
取消时要跳转的标记 [不是取消时要跳转的标记]
如果调用退出时它将 “返回” true 。这种情况可能发生在当一个文件不能创建(或覆盖)失败而用户选择退出时或者当用户手动退出时。该函数仅能在 instfiles 页面 的离开函数里调用。
Page instfiles "" ""
instfilesLeave
Function instfilesLeave
IfAbort 0 +2
MessageBox MB_OK "用户取消"
FunctionEnd
4.9.4.9 IfErrors
错误时跳转的标记 [没有错误时跳转的标记]
检测并清除错误标记,如果设了错误标记,则跳转到 “错误时跳转的标记” ,否则跳转到 “没有错误时跳转的标记” 。错误标记由其它指令在产生一个错误时设置的(比如试图去删除一个正在使用的文件)。
ClearErrors
File file.dat
IfErrors 0 +2
Call ErrorHandler
4.9.4.10 IfFileExists
要检测的文件 文件存在时跳转的标记 [文件不存在时跳转的标记]
检测 “要检测的文件” 是否存在(可以用通配符,或目录),并当文件存在时跳转到 “文件存在时跳转” ,否则跳转到”文件不存在时跳转” 。如果你要检测目标是文件还是目录,请使用 IfFileExists “目录*.*” 。
IfFileExists $WINDIRnotepad.exe 0 +2
MessageBox MB_OK "记事本已安装"
4.9.4.11 IfRebootFlag
已设置重启时跳转的标记 [未设置重启时跳转的标记]
至少需要一个参数。检测重启标记,如果设置了重启标记则跳转到 “已设置重启时跳转的标记” ,否则跳转到 “未设置重启时跳转的标记” 。重启标记可以在 Delete和 Rename,或手动设定的 SetRebootFlag 指令里设置。
IfRebootFlag 0 noreboot
MessageBox MB_YESNO "完成安装需要重新启动计算机,是否现在重启?" IDNO noreboot
Reboot
noreboot:
4.9.4.12 IfSilent
静默安装时跳转的标记 [非静默安装时跳转的标记]
至少需要一个参数。检测静默安装标记,如果安装程序是静默安装时跳转到 “静默安装时跳转” ,否则跳转到 “非静默安装时跳转” 。 静默安装标记可以由 SilentInstall, SilentUninstall, SetSilent 和 用户使用 /S on 命令行启动来设置。
IfSilent +2
ExecWait '"$INSTDIRnonsilentprogram.exe"'
4.9.4.13 IntCmp
值1 值2 值1与值2相等时跳转的标记 [值1小与值2时跳转的标记] [值1大与值2时跳转的标记]
比较两个整数 “值1” 和 “值2” 。如果 “值1” 和 “值2” 相等,则跳转到 “值1与值2相等时跳转的标记” ,否则如果 “值1” < “值2” ,跳转到 “值1小与值2时跳转的标记” ,否则如果 “值1” > “值2” ,跳转到 “值1大与值2时跳转的标记” 。
IntCmp $0 5 is5 lessthan5 morethan5
is5:
DetailPrint "$0 == 5"
Goto done
lessthan5:
DetailPrint "$0 < 5"
Goto done
morethan5:
DetailPrint "$0 > 5"
Goto done
done:
4.9.4.14 IntCmpU
值1 值2 值1与值2相等时跳转的标记 [值1小与值2时跳转的标记] [值1大与值2时跳转的标记]
比较两个无符号整数 “值1” 和 “值2” 。如果 “值1” 和 “值2” 相等,则跳转到 “值1与值2相等时跳转的标记” ,否则如果 “值1” < “值2” ,跳转到 “值1小与值2时跳转的标记” ,否则如果 “值1” > “值2” ,跳转到 “值1大与值2时跳转的标记” 。比较时作为无符号整数来比较。
4.9.4.15 MessageBox
消息框选项列表 消息框文本 [/SD 返回] [检测返回值 跳转到标记] [检测返回值2 跳转到标记2]
显示一个包含 “消息框文本” 的消息框。”消息框选项列表” 必须为下面的一个或多个,多个使用 ‘|’ 来隔开 (例如 MB_YESNO|MB_ICONSTOP)。
- MB_OK – 显示 OK 按钮
- MB_OKCANCEL – 显示 OK 和取消按钮
- MB_ABORTRETRYIGNORE – 显示退出、重试、忽略按钮
- MB_RETRYCANCEL – 显示重试和取消按钮
- MB_YESNO – 显示是和否按钮
- MB_YESNOCANCEL – 显示是、否、取消按钮
- MB_ICONEXCLAMATION – 显示惊叹号图标
- MB_ICONINFORMATION – 显示信息图标
- MB_ICONQUESTION – 显示问号图标
- MB_ICONSTOP – 显示终止图标
- MB_USERICON – 显示安装程序图标
- MB_TOPMOST – 使消息框在最前端显示
- MB_SETFOREGROUND – 设置前景
- MB_RIGHT – 右对齐文本
- MB_RTLREADING – RTL 阅读次序
- MB_DEFBUTTON1 – 默认为按钮 1
- MB_DEFBUTTON2 – 默认为按钮 2
- MB_DEFBUTTON3 – 默认为按钮 3
- MB_DEFBUTTON4 – 默认为按钮 4
Return_check 可以为 0 (或空,或保留关闭),或下列之一:
- IDABORT – 中止按钮
- IDCANCEL – 取消按钮
- IDIGNORE – 忽略按钮
- IDNO – 否按钮
- IDOK – OK 按钮
- IDRETRY – 重试按钮
- IDYES – 是按钮
如果消息框的返回值为 “检测返回值” ,则安装程序执行跳转。
Use the 用 /SD 来指定一个上面列出的返回值当在安装程序静默安装时作为返回值。欲了解更多信息,请查看 section 4.12 。
MessageBox MB_OK "简单消息框"
MessageBox MB_YESNO "真的吗?" IDYES true IDNO false
true:
DetailPrint "是真的!"
Goto next
false:
DetailPrint "是假的"
next:
MessageBox MB_YESNO "真的吗?(静默安装时默认为是)" /SD IDYES IDNO false2
DetailPrint "是真的 (或静默)!"
Goto next2
false2:
DetailPrint "是假的"
next2:
4.9.4.16 Return
从一个函数或区段返回。
Function func
StrCmp $0 "return now" 0 +2
Return # do stuff
FunctionEnd
Section
Call func ;"Return" will return here
SectionEnd
4.9.4.17 Quit
使得安装程序立即退出。在调用 Quit 后,安装程序将退出 (且没有回调函数可以运行)。
4.9.4.18 SetErrors
设置错误标记。
SetErrors IfErrors 0 +2
MessageBox MB_OK "此消息框将始终显示"
4.9.4.19 StrCmp
字符串1 字符串2 相同时跳转的标记 [不相同时跳转的标记]
比较(不区分大小写) “字符串1” 和 “字符串2” 。如果两者相等,跳转到 “相同时跳转的标记” ,否则跳转到 “不相同时跳转的标记”。
StrCmp $0 "a string" 0 +3
DetailPrint '$0 == "a string"'
Goto +2
DetailPrint '$0 != "a string"'
4.9.4.20 StrCmpS
字符串1 字符串2 相同时跳转的标记 [不相同时跳转的标记]
和 StrCmp 类似,不过区分大小写。
4.9.5 文件指令
4.9.5.1 FileClose
句柄
关闭一个由 FileOpen 打开的文件句柄。
4.9.5.2 FileOpen
用户变量(句柄输出) 文件名 打开模式
打开一个 “文件名” 的文件,并且把句柄设置为句柄输出变量。”打开模式” 为 “r” (只读) “w” (写入,文件的所有内容将被清空) 或 “a” (附加,保持文件内容并附加写入)其中之一。在所有的打开模式里,文件指针都置于文件起始位置。如果文件不能被打开,则句柄输出变量为空,并放置一个错误标记。
如果没有指定绝对路径则使用当前路径。当前路径由 SetOutPath 设置。如果之前没有使用 SetOutPath 则当前路径为 $EXEDIR 。
FileOpen $0 $INSTDIRfile.dat r
FileClose $0
4.9.5.3 FileRead
句柄 用户变量(输出) [最大长度]
读取一个由 FileOpen 打开的文件的字符串。该字符串一直读取到新的一行为止(或回车新行) ,或直到读取到空的字节为止,或者直到读取的字符串满足了 “最大长度” (如果指定了的话)。字符串默认的最大长度被限定在 1024 字节之内。(可以下载或重新编译一个使用较大 NSIS_MAX_STRLEN 值的特别构建版本)。如果读取到了文件的结尾却没有得到有效的数据则输出字串被清空,并放置一个错误标记。
ClearErrors
FileOpen $0 $INSTDIRfile.dat r
IfErrors done
FileRead $0 $1
DetailPrint $1
FileClose $0
done:
4.9.5.4 FileReadByte
句柄 用户变量(输出)
读取一个由 FileOpen 打开的文件的字节。读取的字节作为一个整数(0-255) 保存在输出变量里。如果读取到了文件的结尾却没有得到有效的数据则输出字符串被清空,并放置一个错误标记。
ClearErrors
FileOpen $0 $INSTDIRfile.dat r
IfErrors done
FileReadByte $0 $1
FileReadByte $0 $2
DetailPrint "$1 $2"
FileClose $0
done:
4.9.5.5 FileSeek
句柄 偏移 [模式] [用户变量(新位置)]
定位一个由 FileOpen 打开的文件。如果 “模式” 被忽略或指定为 SET ,则文件指针定位到 “偏移” 。如果 “模式” 指定为 CUR ,则文件指针向后移动 “偏移” 。如果 “模式” 指定为 END ,则指针定位到相对于文件结尾 EOF(End of file) 处。如果指定了最后一个参数 “用户变量(新位置)” ,则新文件位置将保存在该变量中。
ClearErrors
FileOpen $0 $INSTDIRfile.dat r
IfErrors done
FileSeek $0 -5
END
FileRead $0 $1
DetailPrint $1
FileClose $0
done:
4.9.5.6 FileWrite
句柄 字符串
写入一个字符串到 FileOpen 打开的文件。如果写入时产生了错误,则放置一个错误标记。
ClearErrors
FileOpen $0 $INSTDIRfile.dat w
IfErrors done
FileWrite $0 "some text"
FileClose $0
done:
4.9.5.7 FileWriteByte
句柄 字符串
写入 解析为整数值的 ‘字符串’ 到 FileOpen 打开的文件。当然你也可以直接输入整数值。下面的代码写入一个 “回车 / 换行” – 输入到文件。
FileWriteByte 文件句柄 “13” ;[译者注:回车,相当于 $r] FileWriteByte 文件句柄 “10” ;[译者注:换行,相当于 $n]
果写入时产生了错误,则置一个错误标记。需要注意的是低字节的整数已经被使用,例如: 写入 256 和写入 0 一样,等等。
4.9.5.8 FindClose
句柄
关闭一个由 FindFirst 打开的搜索。
4.9.5.9 FindFirst
用户变量(句柄输出) 用户变量(文件输出) 文件规范
对 ‘文件规范’ 执行一个搜索,把第一个查找到的文件放置到 “用户变量(文件输出)” 。也可以把搜索的句柄放到 “用户变量(句柄输出)” 如果未找到任何文件,则输出都被设为空,并且放置一个错误标记。最好的用法是使用 FindNext 和 FindClose 。需要注意的是 “用户变量(文件输出)” 不带路径。
FindFirst $0 $1 $INSTDIR*.txt
loop:
StrCmp $1 "" done
DetailPrint $1
FindNext $0 $1
Goto loop
done:
4.9.5.10 FindNext
句柄 用户变量(文件输出)
继续一个由 FindFirst 开始的搜索。句柄应该为 FindFirst 返回的值。如果搜索已完成(没有更多的文件),”用户变量(文件输出)” 将被设为空,并且置一个错误标记。需要注意的是 “用户变量(文件输出)” 不带路径。
4.9.6 卸载程序指令
4.9.6.1 WriteUninstaller
[路径]可执行文件名.exe
由指定的文件名(路径为可选项)写入卸载程序。仅在一个安装区段或函数里有效,并且你的脚本里必须有一个卸载区段。也可以参考卸载配置。你可以调用一次或多次来写入一个或多个卸载程序(副本)。
WriteUninstaller $INSTDIRuninstaller.exe
4.9.7 混合指令
4.9.7.1 GetErrorLevel
用户变量(错误级别输出)
返回由 SetErrorLevel 设置的最后错误级别或者没有使用过时返回 -1 。
GetErrorLevel $0
IntOp $0 $0 + 1
SetErrorLevel $0
4.9.7.2 GetInstDirError
用户变量(错误输出)
用于目录选择页面的离开函数。读取标记设置看 ‘DirVerify leave’ 是否已使用。可能的值:
0: 无错误
1: 无效的安装目录
2: 目标驱动器没有足够的空间
!include LogicLib.nsh
PageEx directory
DirVerify leave
PageCallbacks "" ""
dirLeave
PageExEnd
Function dirLeave
GetInstDirError $0
${Switch} $0
${Case} 0
MessageBox MB_OK "有效的安装目录"
${Break} ${Case} 1
MessageBox MB_OK "无效的安装目录!"
Abort
${Break} ${Case} 2
MessageBox MB_OK "没有足够的可用空间!"
Abort
${Break} ${EndSwitch}
FunctionEnd
4.9.7.3 InitPluginsDir
初始化插件目录 ($PLUGINSDIR) 当之前没有初始化时,可以多次使用。
InitPluginsDir File /oname=$PLUGINSDIRimage.bmp image.bmp
4.9.7.4 Nop
空操作(什么也不做)。
4.9.7.5 SetErrorLevel
错误级别
把安装程序或卸载程序的错误级别设为 错误级别。更多信息请查看 Error Levels 。
IfRebootFlag 0 +2
SetErrorLevel 4
4.9.7.6 SetRegView
32|64|lastused
设置作用于 注册表命令 的注册表查看。在 Windows x64 上共有2种查看方式。一种用于 32-bit 应用程序,另一种用于 x64 应用程序。默认情况下,32-bit 应用程序运行在 x64 系统的 WOW64 模式下时,只允许使用 32-bit 查看方式。使用 SetRegView 64 将允许安装程序在 x64 中访问注册表键值。
它将影响 DeleteRegKey, DeleteRegValue, EnumRegKey, EnumRegValue, ReadRegDWORD, ReadRegStr, WriteRegBin, WriteRegDWORD, WriteRegStr 和 WriteRegExpandStr。
它不会影响 InstallDirRegKey。另外,在函数 .onInit 中也可使用 ReadRegStr 读取注册表。
SetRegView 32
ReadRegStr $0 HKLM SoftwareMicrosoftWindowsCurrentVersion ProgramFilesDir
DetailPrint $0 # prints C:Program Files (x86)
SetRegView 64
ReadRegStr $0 HKLM SoftwareMicrosoftWindowsCurrentVersion ProgramFilesDir
DetailPrint $0 # prints C:Program Files
Function .onInit
SetRegView 64
ReadRegStr $INSTDIR HKLM SoftwareNSIS ""
SetRegView 32
FunctionEnd
4.9.7.7 SetShellVarContext
current|all
设置 $SMPROGRAMS 的内容或其他命令解释程序目录。如果设为 ‘current’ (默认值),则使用当前用户的命令解释程序目录。如果设为 ‘all’,则使用所有用户的命令解释程序目录。所有用户目录可能不能被所有的操作系统支持。如果所有用户的目录找不到则使用当前用户代替。 请考虑一个普通用户或游客是否有正确的权限在所有用户目录里操作。仅仅管理员才有完全的权限访问所有用户目录。你可以用 UserInfo 插件来查看用户身份。详细信息请查看 ContribUserInfoUserInfo.nsi 例子。
注意事项: 如果该指令用于安装程序,那么它只对安装程序有效,而如果它用于卸载程序,那么它仅对卸载程序有效,如果要两者都有效,你必须在安装程序和卸载程序里都使用。
SetShellVarContext current StrCpy $0 $DESKTOP
SetShellVarContext all StrCpy $1 $DESKTOP
MessageBox MB_OK $0$n$1
4.9.7.8 Sleep
休眠时间(单位为:ms)
在安装程序里暂停执行 “休眠时间(单位为:ms)” 毫秒。”休眠时间(单位为:ms)” 可以是一个变量, 例如 “$0” 或一个数字,例如 “666”。
DetailPrint "正在睡觉...^_^"
Sleep 3000
DetailPrint "返回继续运行"
4.9.8 字符串操作指令
4.9.8.1 StrCpy
用户变量(目标) 字符串 [最大长度] [起始偏移]
字符串复制指令。“字符串” 可以包含另一个变量,或该用户变量会被设置(可以用来连接字符串等等)。如果指定了 “最大长度” 则限定了要复制字串的最大长度 (如果 “最大长度” 是负数,则会从字串尾部截去 “最大长度” 的绝对值个字符)。如果指定了起始偏移,则字串偏移到该处作为起始(如果“起始偏移”是负数,则会从尾部开始偏移)。
StrCpy $0 "a string" ;$0 = "a string"
StrCpy $0 "a string" 3 ;$0 = "a s"
StrCpy $0 "a string" -1 ;$0 = "a strin"
StrCpy $0 "a string" "" 2 ;$0 = "string"
StrCpy $0 "a string" "" -3 ;$0 = "ing"
StrCpy $0 "a string" 3 -4 ;$0 = "rin";连接字串StrCpy $0 "字串1"StrCpy $0 "$0 + 字串2" ;$0 = "字串1 + 字串2"
4.9.8.2 StrLen
用户变量(length output) 字符串
获取字符串的长度。
StrLen $0 "123456" # = 6
4.9.9 堆栈支持
4.9.9.1 Exch
[用户变量 | 堆栈索引]
当不指定参数时,交换堆栈顶部的两个单元。当指定了一个参数并且是一个用户变量时,交换堆栈顶部的单元和该变量的值。当指定了一个参数并且是正整数时,Exch 将会交换堆栈顶部单元和根据参数从堆栈顶部偏移到指定单元的值。如果堆栈里没有足够的单元来完成交换时,会产生一个致命的错误(来帮助你调试你的代码)。
Push 1
Push 2
Exch
Pop $0 # = 1
Push 1
Push 2
Push 3
Exch 2
Pop $0 # = 1
StrCpy $0 1
Push 2
Exch $0 # = 2
Pop $1 # = 1
4.9.9.2 Pop
用户变量(输出)
从堆栈里弹出一个字串到用户变量 $x。如果堆栈是空的,则会置一个错误标记。
Push 1
Pop $0 # = 1
4.9.9.3 Push
字符串
把一个字串压入堆栈。该字串可随后从堆栈里弹出。
Push "a string"
4.9.10 整数支持
4.9.10.1 IntFmt
用户变量(输出) 格式 数字字符串
用 “格式” 格式格式化 “数字字符串” 中的数字,并把输出设为用户变量 $x。例如格式化字符串包含 “%08X” “%u”。 (这个指令其实就是 C++ 里的 wsprintf 函数,常用的格式为 %x – 十六进制数(小写)、%X – 十六进制数(大写) 、%d – 十进制数、%u – 无符号整数、%c 单个字符。)
IntFmt $0 "0x%08X" 195948557
IntFmt $0 "%c" 0x41
4.9.10.2 IntOp
用户变量(输出) 值1 操作 [值2]
数字运算,将结果输出到用户变量 $x。操作定义为下列之一:
- + 值1 加 值2
- – 值1 减 值2
- * 值1 乘 值2
- / 值1 除 值2
- % 由 值2 取 值1 的模
- | 值1 和 值2 二进制“或”
- & 值1 和 值2 二进制“与”
- ^ 值1 和 值2 二进制“异或”
- >> 值1 按位右移 值2 个位
- << 值1 按位左移 值2 个位
- ~ 按位取反 值1 (例如 7 变为 4294967288)
- ! 逻辑取反 值1 (例如 7 变为 0)
- || 值1 和 值2 逻辑“或”
- && 值1 和 值2 逻辑“与”
-
IntOp $0 1 + 1 IntOp $0 $0 + 1 IntOp $0 $0 << 2 IntOp $0 $0 ~ IntOp $0 $0 & 0xF
4.9.11 重新启动指令
4.9.11.1 Reboot
重新启动计算机。请小心使用该指令。如果失败,则 .onRebootFailed 函数会被调用。 在任何情况下,该指令都不会返回,跟 Quit 一样。
MessageBox MB_YESNO|MB_ICONQUESTION "你希望重启系统吗?" IDNO +2
Reboot
4.9.11.2 SetRebootFlag
true|false
设置重启标记为 true 或 false。该标记值可以由 IfRebootFlag 读取并作判断。
SetRebootFlag true
IfRebootFlag 0 +2
MessageBox MB_OK "这个消息框将始终显示。"
4.9.12 安装记录指令
4.9.12.1 LogSet
on|off
设置是否将即将发生的安装,记录到 $INSTDIRinstall.log 中。在你调用该函数之前 $INSTDIR 必须有一个值否则该指令将无效。需要注意的是在编译的时候编译配置文件 NSIS_CONFIG_LOG 必须设置 (scons NSIS_CONFIG_LOG=yes
) (默认未设置) 来支持该指令。关于重新编译 NSIS 的详细信息请查看构建 NSIS 。
4.9.12.2 LogText
文本
如果启用了安装程序记录,插入文本“文本”将被写入到日志文件中。
IfFileExists $WINDIR\notepad.exe 0 +2
LogText "$WINDIR\notepad.exe exists"
4.9.13 区段管理
4.9.13.1 SectionSetFlags
区段索引 区段标记
设置区段标记。标记为 32 位整数。第一位(低位)代表该区段当前是否选中,第二位代表该区段是否是一个区段组 (请不要修改这里除非你真的很了解), 第三位代表该区段是否是一个区段组的结尾 (同样,请不要修改),第四位代表该区段文字是否描黑显示,第五位代表该区段是否是只读,第六位代表区段组是否自动展开,第七位代表区段组是部分选定的,第八位是部分选定区段组切换内部使用,第九位是用来反映区段名称更改。如果指定了超出范围的区段则会放置一个错误的标记。
每个标记名称都以 `SF_` 开头:
!define SF_SELECTED 1
!define SF_SECGRP 2
!define SF_SECGRPEND 4
!define SF_BOLD 8
!define SF_RO 16
!define SF_EXPAND 32
!define SF_PSELECTED 64
对于一个使用范例,请参阅 one-section.nsi 实例。
对于常用的宏和定义,请参阅 IncludeSections.nsh 。
Section test
test_section_id
SectionEnd
Function .onInit
#设置区段 'test' 为选定和只读
IntOp $0 ${SF_SELECTED} | ${SF_RO} SectionSetFlags ${test_section_id} $0
FunctionEnd
4.9.13.2 SectionGetFlags
区段索引 用户变量(输出)
获取该区段的标记。标记的描述请看上面。如果指定了超出范围的区段则会放置一个错误的标记。
Section test
test_section_id
SectionEnd
Function .onSelChange
# 保持区段 'test' 为选定
SectionGetFlags ${test_section_id} $0
IntOp $0 $0 | ${SF_SELECTED}
SectionSetFlags ${test_section_id} $0
FunctionEnd
4.9.13.3 SectionSetText
区段索引 区段文本
设置 “区段索引” 区段的描述。如果文本设为 “” 则该区段将会隐藏。如果指定了超出范围的区段则会置一个错误的标记。
Section ""
test_section_id
SectionEnd
Function .onInit
# 把 区段名 改为 $WINDIR
SectionSetText ${test_section_id} $WINDIR
FunctionEnd
4.9.13.4 SectionGetText
区段索引 用户变量(输出)
把 “区段索引” 区段的描述保存在输出变量。如果区段为隐藏,则保存的变量为空。如果指定了超出范围的区段则会置一个错误的标记。
Section test
test_section_id
SectionEnd
Function .onInit
# 把 $WINDIR 附加到区段名中
SectionGetText ${test_section_id} $0
StrCpy $0 "$0 - $WINDIR"
SectionSetText ${test_section_id} $0
FunctionEnd
4.9.13.5 SectionSetInstTypes
区段索引 安装类型
设置区段在安装类型中的默认启用状态。需要注意的是区段索引从零开始。”安装类型” 的每一位都是一个告诉该区段是否属于这个安装类型的标记。例如, 如果你有 3 个安装类型并且你希望第一个区段包含在类型 1 和 3 ,则命令如下:
SectionSetInstTypes 0 5
因为 5 的二进制值为 “00000101” 。如果指定了超出范围的区段则会放置一个错误的标记。
Section test
test_section_id
SectionEnd
Function .onInit
# 使用安装类型 3 和 4 关联区段 'test'
SectionSetInstTypes ${test_section_id} 12
FunctionEnd
4.9.13.6 SectionGetInstTypes
区段索引 用户变量(输出)
获取一个区段的安装类型标记。如何处理输出的描述请看上面关于 SectionSetInstTypes 的解释。如果指定了超出范围的区段则会放置一个错误的标记。
Section test
test_section_id
SectionEnd
Function .onInit
# 使用安装类型 5 关联区段 'test' ,优先于它已存在的关联
SectionGetInstTypes ${test_section_id} $0
IntOp $0 $0 | 16
SectionSetInstTypes ${test_section_id} $0
FunctionEnd
4.9.13.7 SectionSetSize
区段索引 新大小
设置某个区段的大小。需要注意的是索引从零开始。”新大小” 容量的单位为 KB 且仅支持整数。
Section test
test_section_id
SectionEnd
Function .onInit
# 设置区段 'test' 所需大小为 100 字节
SectionSetSize ${test_section_id} 100
FunctionEnd
4.9.13.8 SectionGetSize
区段索引 用户变量
获取区段的大小并把值保存在指定的用户变量里。需要注意的是索引从零开始。
Section test
test_section_id
SectionEnd
Function .onInit
#增加区段 'test' 所需大小 100 字节
SectionGetSize ${test_section_id} $0
IntOp $0 $0 + 100
SectionSetSize ${test_section_id} $0
FunctionEnd
4.9.13.9 SetCurInstType
安装类型索引
设置当前安装类型。”安装类型索引” 介于 0 和 31 之间。如果使用了一个超出范围的安装类型,则 不 会放置一个错误标记。
4.9.13.10 GetCurInstType
用户变量
获取当前的安装类型并保存到 “用户变量” 里。如果选择了第一个类型,则 “用户变量 ” 值为 0 ,如果选择了第二个类型,则 “用户变量 ” 值为 1 ,依次类推。 ${NSIS_MAX_INST_TYPES} (默认为 32) 的值则意味着选择了自定义安装类型。
4.9.13.11 InstTypeSetText
安装类型索引 文本
设置指定的安装类型的文本。如果设置的文本为空则移除该安装类型。通过使用一个以前未使用的 “安装类型索引” 序号你可以创建一个新的安装类型。要在新的安装类型里添加、删除区段请看 SectionSetInstTypes 。与 SectionIn 不同的是该索引从零开始,这意味着第一个安装类型索引为 0 。
InstType a
InstType b
Function .onInit
# 设置第一个安装类型的名字 $WINDIR
InstTypeSetText 0 $WINDIR
# 设置第二个安装类型的名字 $TEMP
InstTypeSetText 1 $TEMP
FunctionEnd
4.9.13.12 InstTypeGetText
安装类型索引 用户变量
获取指定的安装类型的文本。
InstType a
InstType b
Function .onInit
InstTypeGetText 0 $0
DetailPrint $0 # prints 'a'
InstTypeGetText 1 $0
DetailPrint $0 # prints 'b'
FunctionEnd
4.9.14 用户界面指令
4.9.14.1 BringToFront
使安装程序窗口可见并把它带到其它窗口的最前端。如果一个应用程序已经执行且显示在安装程序的前面,BringToFront 将把安装程序带回到焦点。
近期的 Windows 版本限制了前景窗口的设置。如果在安装的时候用户正在运行其他的应用程序,也许会通知该用户使用一种不同的方式。
4.9.14.2 CreateFont
user_var(handle output) face_name [height] [weight] [/ITALIC] [/UNDERLINE] [/STRIKE]
创建一个字体并把句柄保存在用户变量里。欲了解更多关于不同参数的信息,请查看 MSDN 关于 Win32 API 函数 CreateFont() 。
你可以通过 ^Font 和 ^FontSize LangStrings 来获取当前使用的字体。
!include WinMessages.nsh
GetDlgItem $0 $HWNDPARENT 1
CreateFont $1 "Times New Roman" "7" "700" /UNDERLINE
SendMessage $0 ${WM_SETFONT} $1 1
4.9.14.3 DetailPrint
用户信息
添加 “用户信息” 字符串到安装程序的安装信息查看窗口。
DeteailPrint "这个消息将显示在安装窗口"
4.9.14.4 EnableWindow
窗口句柄 (1|0)
对指定的窗口或控件允许或禁止鼠标和键盘输入。可用的状态为 0 (禁止) 或 1 (允许)。
GetDlgItem $0 $HWNDPARENT 1
EnableWindow $0 0
Sleep 1000
EnableWindow $0 1
4.9.14.5 FindWindow
用户变量(窗口句柄输出) 窗口类名 [窗口标题] [父窗口句柄] [childafter]
查找一个窗口。类似于 Win32 FindWindowEx() 。由窗口类名来查找 (和[或]窗口标题,如果指定的话). 如果指定了 “父窗口句柄” 或 childafter ,则查找会受到限制。如果窗口类名或窗口标题指定为 “” ,则它们将不能用于查找。如果窗口未找到,用户变量将返回 0 值。要实现旧式 FindWindow 行为,请和 SendMessage 一起使用。
FindWindow $0 "#32770" "" $HWNDPARENT
FIndWindow $0 "我的窗口类" "我的窗口标题"
4.9.14.6 GetDlgItem
用户变量(输出) 窗口句柄 控件ID
在指定的对话框上根据控件ID获得控件句柄。如果你想获得安装程序内部的控件句柄,请先使用 FindWindow 用户变量(窗口句柄输出) “#32770” “” $HWNDPARENT 来获取窗口句柄。
GetDlgItem $0 $HWNDPARENT 1 # 下一步、安装按钮
4.9.14.7 HideWindow
隐藏安装程序。
4.9.14.8 IsWindow
窗口句柄 是窗口时跳转的标记 [不是窗口时跳转的标记]
如果 “窗口句柄” 是一个窗口,则跳转到 “是窗口时跳转的标记” ,否则跳转到 “不是窗口时跳转的标记” (如果指定了的话) 。
GetDlgItem $0 $HWNDPARENT 1
IsWindow 0 +3
MessageBox MB_OK "找到窗口"
Goto +2
MessageBox MB_OK "无窗口"
4.9.14.9 LockWindow
on|off
LockWindow on 会阻止主窗口在更改或更新时自动重绘。使用了 LockWindow off 之后使得应用了 LockWindow on 的窗口的所有控件可以自动重绘。这可以有效的避免页面的闪烁,因为现在是一组控件同时重绘而不是一个控件一个控件的重绘。个别的控件在老的电脑上也会闪烁。如果你在区段里使用了循环,你也可以用来阻止进度条来回闪动。
4.9.14.10 SendMessage
窗口句柄 消息 第一个消息参数 第二个消息参数 [用户变量(返回值)] [/TIMEOUT=时间(单位为:毫秒)]
发送消息到 “窗口句柄” 。如果指定了一个用户变量 $x 作为最后一个参数 (或在 /TIMEOUT 之前的最后一个参数) ,SendMessage 的返回值将保存在该变量里。需要注意的是当指定 ‘消息’ 时你只能用消息的整数值。如果你需要发送字串请使用 “STR:字符串” 作为 “第一个消息参数” 或 “第二个消息参数” 。
- WM_CLOSE 16
- WM_COMMAND 273
- WM_USER 1024
Include WinMessages.nsh 来获得所有 Windows 消息定义。
要发送一个字串参数的话,在参数前面加入 STR: , 例如: “STR:一些字符串” 。
使用 /TIMEOUT=时间(单位为:毫秒) 来指定持续时间,单位为毫秒。
!include WinMessages.nsh
FindWindow $0 "Winamp v1.x"
SendMessage $0 ${WM_CLOSE} 0 0
4.9.14.11 SetAutoClose
true|false
取代默认的窗口自动关闭标记 (由 AutoCloseWindow 指定,且对于写在程序为 false) 。指定 ‘true’ 将使得安装程序在安装完成时立即关闭窗口,或者 ‘false’ 来使它需要手动关闭。
4.9.14.12 SetBrandingImage
[/IMGID=对话里的 ID 项] [/RESIZETOFIT] 路径位图.bmp
把当前位图作为标志图像显示。如果没有指定 IMGID ,则使用第一个找到的图像控件,或由 AddBrandingImage 建立的图像控件。需要注意的是位图必须预先存在于当前用户的机器上。可以先使用 File 指令把它释放。如果指定了 /RESIZETOFIT 则图像会自动改变尺寸到图像控件的大小。如果你使用了 AddBrandingImage 你可以得到它的大小,通过编译你的脚本并察看 AddBrandingImage 的输出,它会告诉你控件的大小。 SetBrandingImage 在 .onInit 或 .onInit 调用的函数里无效。
4.9.14.13 SetDetailsView
show|hide
显示或隐藏详细信息,取决于你使用什么样的参数。它可以覆盖默认的由 ShowInstDetails 设定的详细信息察看属性。
4.9.14.14 SetDetailsPrint
none|listonly|textonly|both|lastused
为命令输出的状态信息设置一个显示模式。 None 为不输出,listonly 仅在列表框显示, textonly 仅在状态条显示, both 则两者都显示(默认)。对于释放很多小的文件,推荐使用 textonly (特别在 Win9x 下启用了平滑卷动) 。
SetDetailsPrint none
File "secret file.dat"
SetDetailsPrint both
4.9.14.15 SetCtlColors
句柄 [/BRANDING] [文本颜色] [transparent|背景颜色]
对一个静态控件、编辑控件、按钮或一个对话框设置一个背景颜色和文本颜色。 文本颜色 和 背景颜色 不能使用变量。使用 GetDlgItem 来获取控件的句柄 (HWND) 。如果要使得控件透明你可以指定 “transparent” 作为背景颜色值。你也可以指定 /BRANDING 并带或不带文本颜色和背景颜色来使得控件完全灰白 (或其他你选择的颜色)。下面是在 MUI 里用来显示标志牌颜色的实例:
FindWindow $0 "#32770" "" $HWNDPARENT
GetDlgItem $0 $0 1006
SetCtlColors $0 0xFF0000 0x00FF00
警告: 当
XPStlye on 时,勾选按钮 (Check Boxes) 背景颜色设置为 “transparent” 可能无效。当使用某些 Windows 主题时,它的背景可能完全是黑色而不是透明的。
4.9.14.16 SetSilent
silent | normal
设置安装程序为静默模式或普通模式。欲了解更多关于静默安装的信息,请查看 SilentInstall 。仅能在 .onInit 里使用。
4.9.14.17 ShowWindow
窗口句柄 显示状态
设置一个窗口的显示程度。可用的显示状态和 Windows ShowWindow 函数相同。 SW_* 常量定义于 IncludeWinMessages.nsh 。
!include WinMessages.nsh
GetDlgItem $0 $HWNDPARENT 1
ShowWindow $0 ${SW_HIDE}
Sleep 1000
ShowWindow $0 ${SW_SHOW}
4.9.15 多语言指令
4.9.15.1 LoadLanguageFile
语言文件.nlf
给一个语言表的结构载入一个语言文件。NSIS 所有的语言文件在 ContribLanguage Files 。
在你插入一个语言文件后 ${LANG_langfile} 将会被定义为语言 ID (例如, ${LANG_ENGLISH} 将会被定义为 1033)。你可以把它用于 LangString, LicenseLangString, LangDLL 和 VIAddVersionKey 。
4.9.15.2 LangString
名称 语言ID 字符串
定义一个使用多语言的字符串。这意味着对每种语言来说他们的值可能不同(或者相同, 由你决定)。这允许你容易的使你的安装程序多语言化为不需要再脚本里使用大量的开关语句。
每一个语言字符串都有一个特定的名字和一个用于安装程序分配给每一种语言的值。 他们可以在脚本里用于任何运行时字符串。使用一个语言字符串你所需要做的就是把 $(LangString_name_here) 插入到你想插入字串的地方。
注意:
- 不像定义使用花括号 – {} 一样,语言字符串使用圆括号 – () 。
- 如果你想在 .onInit 函数里更改语言,需要注意的是在 .onInit 里的语言字符串将仍旧使用基于用户的默认 Windows 语言检测到的语言,因为语言的初始化在 .onInit 之后。
- 总是在你的脚本里为所有语言设置语言字串。
- 如果你把语言 ID 设为 0 则使用 LangString 或 LoadLanguageFile 最后使用的语言。
使用范例:
LangString message ${LANG_ENGLISH} "英语信息"
LangString message ${LANG_SIMPCHINESE} "简体中文信息"
LangString message ${LANG_TRADCHINESE} "繁体中文信息"
4.9.15.3 LicenseLangString
名称 语言ID 许可文件路径
用法和 LangString 一样,但它仅从一个文本、RTF 文件载入字符串并且定义一个特殊且仅能用于 LicenseData 的 LangString 。
LicenseLangString license ${LANG_ENGLISH} license-english.txt
LicenseLangString license ${LANG_SIMPCHINESE} license-simpchinese.txt
LicenseLangString license ${LANG_TRADCHINESE} license-tradchinese.txt
LicenseData $(license)
4.10 多语言
截至第 2 版 NSIS 已经完全支持多国语言。一个安装程序的界面可以支持多语言。
对所有的语言使用 LoadLanguageFile 来载入默认的界面文本和语言属性。
默认的界面文本可以很容易的使用指令(比如 ComponentText 等)来更改。
你也可以在你自己的字符串里使用标准语言字符串的内容(例如, $(^Name) 包含了使用 Name 指令设置的安装程序名称)。在语言文件中,所有标准语言字符串的名称作为注释列表于语言文件字符串的上方。语言文件位于 ContribLanguage Files 。
要创建你自己的语言的字符串,请使用 LangString 。
使用多语言的一个安装程序例子,请看 languages.nsi 。
4.10.1 语言选择
当安装程序启动时通过以下步骤选择界面语言:
- 获取用户的默认 Windows 用户界面语言
- 查找一个最佳匹配的语言
- 如果没有最佳匹配的,则查找第一个匹配的语言
- 如果没有匹配的,使用脚本里定义的第一个语言(确认你的第一个语言是一个通用的语言,比如英语)
- 如果语言变量 $LANGUAGE 在 .onInit 里被改变, NSIS 将重新进行步骤 2 到步骤4 。
4.10.2 LangDLL 插件
LangDLL 插件允许用户为安装程序选择语言。只需要把语言 ID (${LANG_langfile}) 和他它在所有语言中的名称压入堆栈,然后再压入语言的数量,窗口标题和要提示用户选择语言的文本,调用插件的 LangDialog 函数,弹出返回值到 $LANGUAGE ,然后你便可以继续。如果用户点击了取消按钮,则返回值就是 “cancel” 。
使用多语言的一个安装程序例子,请看 languages.nsi 。
4.10.3 RTL 语言
RTL 语言是从右至左书写的语言(例如 Arabic[阿拉伯语] 和 Hebrew[希伯来语])。 NSIS 完整支持 RTL 语言。在语言文件里有一个地方来指定该语言是否 RTL 语言。要在运行时检测当前是否是 RTL 语言,需要检测 $(^RTL) 语言字串的值。如果语言是 RTL 则为 1 ,否则为 0 。这在使用插件来创建对话时非常有用,他们通常也有 RTL 设置。
4.11 插件 DLLs
脚本语言允许你通过一个 DLL 文件的函数扩展它的能力。可能最好的例子就是在每个 NSIS 发布的版本里附带的 InstallOptions.dll。
当 NSIS 编译器开始时它会扫描插件目录的 DLL 并且列出找到的插件和输出的函数。在编译时如果遇到有序的冒号如 fred::flintstone 编译器将会作为关键字在该列表中查找。如果列表项列入了 fred.dll 并输出 flintstone 则 NSIS 将会把 fred.dll 文件打包到安装程序里。
当插件命令执行时 NSIS 将会解压所需的插件 DLL 文件到一个临时目录 ($PLUGINSDIR),把指定的参数全部压入(从右到左次序),然后执行 DLL 函数。
4.11.1 使用插件命令
一般插件的调用像下面这样:
InstallOptions::dialog "ini_file_location.ini"
所有的参数都压入堆栈 (在这个例子中,该插件函数仅需要一个参数).还有一些插件不需要在堆栈里有任何参数,而其他的有可能需要几个或更多。要使用插件命令你首先需要阅读插件附带的文档以了解该插件函数需要什么样的参数。
4.11.2 手动调用插件
如果你想调用一个用户硬盘或其他地方里的插件,你可以使用 CallInstDLL。几乎所有插件都提供了安装程序的泛函数,所以使用插件命令是一个简易的方法。使用 CallInstDLL 对于你创建了插件并包含在你的应用程序里并被复制到安装目录里的情况来说非常有用。
4.12 静默安装程序、卸载程序
静默安装在安装过程中不需要用户参与而且不显示用户界面。用户不会看到任何对话且不会被询问任何问题。这对于网络管理员希望不需要用户参与的安装或卸载一些程序,这样可以快速的对多台电脑执行操作。对于其他的开发者来说,把其他的安装程序整合到自己的安装程序并且把所有需要的信息收集到自己的安装程序而不是显示两个安装程序时非常有用的。
NSIS 安装程序和卸载程序都可以静默或非静默。当一个安装程序或卸载程序静默时,不是所有的回调函数都被调用。 .onGUIInit, .onGUIEnd,它们对应的卸载程序函数和任何涉及到特殊页面或页面类型的回调将不会被调用。
有几种方法来使得安装或卸载程序静默:
- SilentInstall 和 SilentUninstall
- SetSilent
- 在程序命令行里加 /S 参数 (区分大小写)
要判断安装、卸载程序是否静默请使用 IfSilent。
首先你需要确认你的安装程序是否真的需要静默模式,在每一个需要用户参与的命令或创建一个窗口命令之前你应该使用 IfSilent 来判断。 MessageBox 命令是在静默安装程序最常犯的,应该使用 /SD 开关来为静默安装程序指定一个默认的回答。如果你希望你的安装程序可以完全的静默你就应该使用这个开关。使所有内部的 NSIS 信息对话框都有一个静默安装的默认值。 silent.nsi 实例 演示了这个主题所有方面的问题。
因为安装目录选择页面在静默安装的时候不会显示,所以用户可以添加一个命令行选项来指定安装程序安装目录(也可以在非静默安装、卸载程序里使用)。要做到这一点,用户只需要使用 /D 开关象下面这样的例子:
foo.exe /S /D=C:Program FilesFoo
如果你的安装程序在静默模式时需要更多的信息,你可以让你的用户在命令行里指定并在 .onInit 函数里进行处理。你可以使用 GetOptions 。
!include FileFunc.nsh
!insertmacro GetParameters
!insertmacro GetOptions
Function .onInit
${GetParameters} $R0
ClearErrors
${GetOptions} $R0 /USERNAME= $0
FunctionEnd
上面的例子将会把 /USERNAME= 后面的值复制到 $0。这样可以让用户在命令行指定必须的参数信息而不需要用户参与的用户界面。用户可以使用:
foo.exe /S /USERNAME=Bar /D=C:Program FilesFoo
或:
foo.exe /S /USERNAME=带空格的字符串 /D=C:Program FilesFoo
或:
foo.exe /S /USERNAME="带空格的字符串" /D=C:Program FilesFoo
如果你的安装程序、卸载程序需要大量的信息并且你希望能静默安装,你应该允许用户建立一个应答文件,把需要的信息都写在里面。这样比把所有的信息都写到命令行里更好一些。
暂无评论内容