上一页 | 目录 | 下一页

4.9 指令

4.9.1 基本指令

NSIS 用于脚本的这些指令稍微的近似于 PHP 和汇编。它们没有真正的高级语言结构,但是他们的指令(大多数情况下)却是高级的,并且你可以很容易的掌握(比如你不用担心字串的连接等等)。基本上你有 25 寄存器 (20 个常规用途, 5个特殊用途),和一个堆栈。

4.9.1.1 Delete

[/REBOOTOK] 文件

从目标系统删除文件文件(可以是文件或通配符,但必须指定一个完整的路径)。如果指定了 /REBOOTOK 并且该文件当前不可删除,则会在系统重启时删除该文件 -- 如果该文件要在系统重启时删除,你还要设置一个重启的标记。如果找到的文件不能被删除则会置一个错误标记。但该错误标记不是为尝试删除一个不存在的文件设置的。

Delete $INSTDIR\somefile.dat

4.9.1.2 Exec

命令

执行一个指定的程序并且立即继续安装。注意指定的文件必须存在于目标系统而不是编译的系统。 $OUTDIR 用于指定工作路径。如果该命令不能被运行则会置一个错误标记。注意,如果该命令包含空格,你要用引号来把他们包括起来。例如: Exec '"$INSTDIR\command.exe" 参数' 。如果你不用引号括起来则在 Windows 9x下正常或丢失参数。

Exec '"$INSTDIR\someprogram.exe"'
Exec '"$INSTDIR\someprogram.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" "$INSTDIR\readme.txt"
ExecShell "print" "$INSTDIR\readme.txt"

4.9.1.4 ExecWait

命令 [用户变量(退出代码)]

执行一个指定的程序并且等待运行处理结束。更多信息请查看 Exec 。当程序执行返回一个非零错误代码或者当产生错误时,如果没有指定 "用户变量(返回代码)" 则 ExecWait 会放置一个错误标记。如果指定了 "用户变量(返回代码)" 则 ExecWait 会把变量设为返回代码(并且仅当产生错误时放置一个错误标记;如果产生错误则该用户变量的内容为未指定)。注意:如果该命令包含空格,你要用引号来把他们包括起来。例如: ExecWait '"$INSTDIR\command.exe" 参数' 。如果你不用引号括起来则在 Windows 9x 下 正常或丢失参数。

ExecWait '"$INSTDIR\someprogram.exe"'
ExecWait '"$INSTDIR\someprogram.exe"' $0
DetailPrint "程序返回了 $0"

4.9.1.5 File

[/nonfatal] [/a] ([/r] [/x 文件|通配符 [...]] (文件|通配符) [...] | /oname=输出路径\文件名 输入路径\文件名)

释放文件到当前输出路径 ($OUTDIR)。

File something.exe
File /a something.exe
File *.exe
File /r *.dat
File /r data
File /oname=temp.dat somefile.ext
File /oname=$TEMP\temp.dat somefile.ext
File "/oname=$TEMP\name 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 用法时:

File /r something

会在根目录下匹配名为 something 的目录,以及 dir 目录中的 something 文件和 another 目录中的 something 目录。只在根目录中匹配名为 something 的目录时,应该这样:

File /r something\*.*

当添加了 \*.* 时,会将它作为匹配条件,并且 something 会被当成文件夹进行搜索。当仅指定 something 时,当前目录会被递归搜索所有的 something 目录,这样 another\something 目录就会匹配。

4.9.1.6 Rename

[/REBOOTOK] 源文件 目标文件

移动时(比如,目标文件已存在),则该文件在系统重启后才被移动到目标。如果文件在重启后才被移动,则会放置一个重启的标记。当文件不能被重命名时(并且没有使用 /REBOOTOK)或者原文件不存在时,会放置一个错误标记。

如果没有指定绝对路径则使用当前路径代替。当前路径可以由上一个 SetOutPath 指令来设置。[译者注:即使用 SetOutPath 设置当前路径,默认使用上一个 SetOutPath 指令设置当前路径。在创建快捷方式时需要注意这个问题,涉及到快捷方式的起始位置。]如果你没有使用 SetOutPath 那么当前路径为 $EXEDIR

Rename $INSTDIR\file.ext $INSTDIR\file.dat

4.9.1.7 ReserveFile

[/nonfatal] [/r] [/x file|通配符 [...]] 文件 [文件...]

把文件保存在稍后使用的数据区块。文件将按照在脚本里出现的次序依次添加到压缩的数据区块。因为函数不必要按照它们出现在脚本里的次序调用,因此如果你把文件添加到一个早期就调用但却放在脚本最后的函数的时候,早期需要的文件需要解压出来,那么当文件很多的时候就需要很长的时间去解压这些文件。.onInit 就是这样的一个函数。它总是在安装程序初始化的时候被调用,如果你把这个函数放在了脚本的最后,这个函数所需要的文件之前还有很多文件,那么当你解压这些需要的文件的时候安装程序就需要大量的时间才能载入。这就是为什么这个命令很有用的原因,这个命令能加快安装程序的载入,使用这个命令后它可以把早期需要的文件添加到数据区块的顶端而不是让 NSIS 把压缩的数据区块从顶端搜索到底部后才把这些文件解压出来。

欲了解更多关于参数的信息,请查看 File

4.9.1.8 RMDir

[/r] [/REBOOTOK] 目录名

删除指定的目录(没有通配符的完整路径)。没有 /r 参数时只有在目录为空时才会被删除。如果指定了 /r ,则目录会被递归删除,所以在指定目录下的所有文件和目录均被删除。如果指定了 /REBOOTOK ,任何当前不能删除的文件或目录将会在重启后被删除 -- 如果文件或目录需要在重启时被删除,会放置一个重启的标记。当文件或目录不能被删除时放置一个错误的标记。

RMDir $INSTDIR
RMDir $INSTDIR\data
RMDir /r /REBOOTOK $INSTDIR
RMDir /REBOOTOK $INSTDIR\DLLs

需要注意的是当前的工作目录不能删除。当前的工作目录由 SetOutPath 设定。例如,下面的例子将不能删除该目录。

SetOutPath $TEMP\dir
RMDir $TEMP\dir

而下面的例子将成功地删除该目录。

SetOutPath $TEMP\dir
SetOutPath $TEMP
RMDir $TEMP\dir

警告: 在卸载程序中使用 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 $TEMP\something.ini section1 something 123
WriteINIStr $TEMP\something.ini section1 somethingelse 1234
WriteINIStr $TEMP\something.ini section2 nsis true
DeleteINISec $TEMP\something.ini section1

4.9.2.2 DeleteINIStr

INI文件 区段名 字符串

从 "INI文件" 里的 "区段名" 区段删除 "字符串" 字符串。如果该字符串不能被删除,会放置一个错误的标记。但是如果该字串找不到时,则不会放置错误标记。

WriteINIStr $TEMP\something.ini section1 something 123
WriteINIStr $TEMP\something.ini section1 somethingelse 1234
DeleteINIStr $TEMP\something.ini section1 somethingelse

4.9.2.3 DeleteRegKey

[/ifempty] 根键 子键

删除一个注册表键。如果指定了 /ifempty ,则该注册表键仅当它无子键时才会被删除(否则,整个注册表键将被删除)。有效的根键值在后面的 WriteRegStr 列出。如果该键不能被删除(或如果它不存在) 则会放置一个错误的标记。

DeleteRegKey HKLM "Software\My Company\My Software"
DeleteRegKey /ifempty HKLM "Software\A key that might have subkeys"

4.9.2.4 DeleteRegValue

根键 子键 键名

删除一个注册表键值。有效的根键值在后面的 WriteRegStr 列出。如果该键值不能被删除(或如果它不存在)则会放置一个错误的标记。

DeleteRegValue HKLM "Software\My Company\My 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 Software\Microsoft\Windows\CurrentVersion $0
  IfErrors done
  IntOp $0 $0 + 1
  ReadRegStr $2 HKLM Software\Microsoft\Windows\CurrentVersion $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, DeleteINISecDeleteINStr 来更改它。

WriteINIStr $TEMP\something.ini test test test
FlushINI $TEMP\something.ini
Delete $TEMP\something.ini

4.9.2.9 ReadEnvStr

用户变量(输出) 名称

从环境字串里读取 "名称" 并把值赋给用户变量 $x 。如果读取字串时有错误发生,该用户变量被设为空,并放置一个错误标记。

ReadEnvStr $0 WINDIR
ReadEnvStr $1 TEMP

4.9.2.10 ReadINIStr

用户变量(输出) INI文件 区段名 项

从 "INI文件" 的 "区段名" 区段读取 "项" 的值并把该值输出到用户变量。如果该项未找到时.会放置一个错误标记且该用户变量被赋为空值。

ReadINIStr $0 $INSTDIR\winamp.ini winamp outname

4.9.2.11 ReadRegDWORD

用户变量(输出) 根键 子键 项

从注册表读取一个 32 位 DWORD 并输出到用户变量 $x 。有效的根键值在后面的 WriteRegStr 列出。如果字串不存在时会放置一个错误标记并把 $x 设为空字符串。如果该值存在但是 DWORD,则会转换为字串类型并放置一个错误标记。

ReadRegDWORD $0 HKLM Software\NSIS VersionBuild

4.9.2.12 ReadRegStr

用户变量(输出) 根键 子键 项

从注册表读取一个字符串值并输出到用户变量 $x 。有效的根键值在后面的 WriteRegStr 列出。如果字符串不存在时,会放置一个错误标记并把 $x 设为空字符串 ("") 。如果该值存在且为 REG_DWORD ,则会转换为字符串类型并放置一个错误标记。

ReadRegStr $0 HKLM Software\NSIS ""
DetailPrint "NSIS is installed at: $0"

4.9.2.13 WriteINIStr

INI文件 区段名 项 值

把 "项 " = "值" 写入 "INI文件" 的 "区段名" 。 如果 INI 文件不能写入则放置一个错误的标记。

WriteINIStr $TEMP\something.ini section1 something 123
WriteINIStr $TEMP\something.ini section1 somethingelse 1234
WriteINIStr $TEMP\something.ini section2 nsis true

4.9.2.14 WriteRegBin

根键 子键 项 值数据

该命令将会写一个区块的二进制数据到注册表。有效的根键值在后面的 WriteRegStr 列出。值数据为十六进制格式 (例如 DEADBEEF01223211151)。如果该二进制数据不能写入注册表则放置一个错误的标记。如果注册表键不存在则会自动创建。“

WriteRegBin HKLM "Software\My Company\My Software" "Binary Value" DEADBEEF01223211151

4.9.2.15 WriteRegDWORD

根键 子键 项 值

该命令写一个 Dword (32 位整数) 到注册表 (以使用变量)。有效的根键值在后面的 WriteRegStr 列出。如果该 Dword 不能写入注册表则会放置一个错误的标记。如果注册表键不存在则会自动创建。

WriteRegDWORD HKLM "Software\My Company\My Software" "DWORD Value" 0xDEADBEEF

4.9.2.16 WriteRegStr

根键 子键 项 值

把字符串写入注册表。详细信息请查看 WriteRegExpandStr

WriteRegStr HKLM "Software\My Company\My Software" "String Value" "dead beef"

4.9.2.17 WriteRegExpandStr

根键 子键 项 值

把字符串写入注册表。 root_key 必须为下面列表之一:

如果 根键SHCTXSHELL_CONTEXT, 当 SetShellVarContext 设置为 all 时,它将被替换成HKLM ;当 SetShellVarContext 设置为 current 时,它将被替换成 HKCU

如果字符串不能写入注册表,则放置一个错误的标记。字符串的类型为 REG_SZ 对应 WriteRegStr ,或 REG_EXPAND_STR 对应 WriteRegExpandStr 。如果注册表键不存在,则会自动创建。

WriteRegExpandStr HKLM "Software\My Company\My Software" "Expand String Value" "%WINDIR%\notepad.exe"

4.9.3 常规用途指令

4.9.3.1 CallInstDLL

DLL文件 函数

从一个 NSIS 扩展动态链接库里调用一个 函数 。查看 实例插件 的例子可以知道如何来创建。扩展动态链接库可以访问堆栈和变量。注意: 要自动释放并调用 DLL 插件请使用插件命令而不是 CallInstDLL 。

Push "参数"
Push "另一个参数"
CallInstDLL $INSTDIR\somedll.dll somefunction

要想更简单地使用插件,可使用新的 插件调用语法

4.9.3.2 CopyFiles

[/SILENT] [/FILESONLY] 目标系统文件(规范) 目标路径 [文件大小(单位:KB)]

在正在安装的系统中把 "目标系统文件(规范)" 复制到 "目标路径" 。如果你想从安装媒体里复制,或从系统的一个地方复制到另一个地方,你可以使用 $EXEDIR 变量来代替安装程序目录。如果复制操作需要很长时间的话你可以看到 Windows 的复制文件窗口 (要禁止出现复制文件窗口使用 /SILENT) 。最后的参数用来指定要复制的文件的大小(单位: KB ),使安装程序可以估计所需磁盘空间。当出错,或用户退出 (仅当忽略了 /SILENT)时,会放置一个错误标记。 如果指定了 /FILESONLY 则仅复制文件。

这个指令应该使用完整的路径,使用相对路径将得到不可预料的结果。

CreateDirectory $INSTDIR\backup
CopyFiles $INSTDIR\*.dat $INSTDIR\backup

4.9.3.3 CreateDirectory

要创建的路径

创建(递归创建)指定的目录。当目录不能创建时会放置一个错误标记。

你也可以指定一个绝对路径。

CreateDirectory $INSTDIR\some\directory

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 "$SMPROGRAMS\My Company"
CreateShortCut "$SMPROGRAMS\My Company\My Program.lnk" "$INSTDIR\My Program.exe" \
  "some command line parameters" "$INSTDIR\My Program.exe" 2 SW_SHOWNORMAL \
  ALT|CONTROL|SHIFT|F5 "a description"

4.9.3.5 GetDLLVersion

文件名 用户变量(高位 DWORD 输出) 用户变量(低位 DWORD 输出)

从 "文件名" DLL (或其他包含版本信息的可执行文件) 取得版本信息。成功时把版本信息高位 Dwords 和低位 DWORD 设为用户输出变量;失败时输出为空且置错误标记。下面的例子演示了读取一个 DLL 版本并可读的版本到 $0 :

GetDllVersion "$INSTDIR\MyDLL.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 $PROGRAMFILES\NSIS
SetOutPath $INSTDIR
GetFullPathName $0 ..
DetailPrint $0 # will print C:\Program Files
GetFullPathName /SHORT $0 $INSTDIR
DetailPrint $0 # will print C:\Progra~1\NSIS
StrCpy $0 C:\Progra~1\NSIS
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 Files\NSIS, 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 。这样所有的属性都会被擦除,该命令不支持通配符。

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 $INSTDIR\foo.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, GetFunctionAddressGetLabelAddress 返回。当使用了 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 $WINDIR\notepad.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 '"$INSTDIR\nonsilentprogram.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)。

Return_check 可以为 0 (或空,或保留关闭),或下列之一:

如果消息框的返回值为 "检测返回值" ,则安装程序执行跳转。

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 $INSTDIR\file.dat r
FileClose $0

4.9.5.3 FileRead

句柄 用户变量(输出) [最大长度]

读取一个由 FileOpen 打开的文件的字符串。该字符串一直读取到新的一行为止(或回车新行) ,或直到读取到空的字节为止,或者直到读取的字符串满足了 "最大长度" (如果指定了的话)。字符串默认的最大长度被限定在 1024 字节之内。(可以下载或重新编译一个使用较大 NSIS_MAX_STRLEN 值的特别构建版本)。如果读取到了文件的结尾却没有得到有效的数据则输出字串被清空,并放置一个错误标记。

ClearErrors
FileOpen $0 $INSTDIR\file.dat r
IfErrors done
FileRead $0 $1
DetailPrint $1
FileClose $0
done:

4.9.5.4 FileReadByte

句柄 用户变量(输出)

读取一个由 FileOpen 打开的文件的字节。读取的字节作为一个整数(0-255) 保存在输出变量里。如果读取到了文件的结尾却没有得到有效的数据则输出字符串被清空,并放置一个错误标记。

ClearErrors
FileOpen $0 $INSTDIR\file.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 $INSTDIR\file.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 $INSTDIR\file.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 $INSTDIR\uninstaller.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=$PLUGINSDIR\image.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, WriteRegStrWriteRegExpandStr

它不会影响 InstallDirRegKey。另外,在函数 .onInit 中也可使用 ReadRegStr 读取注册表。

SetRegView 32
ReadRegStr $0 HKLM Software\Microsoft\Windows\CurrentVersion ProgramFilesDir
DetailPrint $0 # prints C:\Program Files (x86)
SetRegView 64
ReadRegStr $0 HKLM Software\Microsoft\Windows\CurrentVersion ProgramFilesDir
DetailPrint $0 # prints C:\Program Files
Function .onInit
  SetRegView 64
  ReadRegStr $INSTDIR HKLM Software\NSIS ""
  SetRegView 32
FunctionEnd

4.9.7.7 SetShellVarContext

\\current\\|all

设置 $SMPROGRAMS 的内容或其他命令解释程序目录。如果设为 'current' (默认值),则使用当前用户的命令解释程序目录。如果设为 'all',则使用所有用户的命令解释程序目录。所有用户目录可能不能被所有的操作系统支持。如果所有用户的目录找不到则使用当前用户代替。 请考虑一个普通用户或游客是否有正确的权限在所有用户目录里操作。仅仅管理员才有完全的权限访问所有用户目录。你可以用 UserInfo 插件来查看用户身份。详细信息请查看 Contrib\UserInfo\UserInfo.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" # = "a string"
StrCpy $0 "a string" 3 # = "a s"
StrCpy $0 "a string" -1 # = "a strin"
StrCpy $0 "a string" "" 2 # = "string"
StrCpy $0 "a string" "" -3 # = "ing"
StrCpy $0 "a string" 3 -4 # = "rin"

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 "一个字符串"

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。操作定义为下列之一:

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\\

设置是否将即将发生的安装,记录到 $INSTDIR\install.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 实例。

对于常用的宏和定义,请参阅 Include\Sections.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

用户信息

添加 "用户信息" 字符串到安装程序的安装信息查看窗口。

DetailPrint "this message will show on the installation window"

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 "my window class" "my window title"

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 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:字符串" 作为 "第一个消息参数" 或 "第二个消息参数" 。

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_* 常量定义于 Include\WinMessages.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 所有的语言文件在 Contrib\Language Files

在你插入一个语言文件后 ${LANG_langfile} 将会被定义为语言 ID (例如, ${LANG_ENGLISH} 将会被定义为 1033)。你可以把它用于 LangString, LicenseLangString, LangDLL 和 VIAddVersionKey

4.9.15.2 LangString

名称 语言ID 字符串

定义一个使用多语言的字符串。这意味着对每种语言来说他们的值可能不同(或者相同, 由你决定)。这允许你容易的使你的安装程序多语言化为不需要再脚本里使用大量的开关语句。

每一个语言字符串都有一个特定的名字和一个用于安装程序分配给每一种语言的值。 他们可以在脚本里用于任何运行时字符串。使用一个语言字符串你所需要做的就是把 $(LangString_name_here) 插入到你想插入字串的地方。

注意:

使用范例:

 LangString message ${LANG_ENGLISH} "英语信息"
 LangString message ${LANG_SIMPCHINESE} "简体中文信息"
 LangString message ${LANG_TRADCHINESE} "繁体中文信息"

 MessageBox MB_OK "A translated message: $(message)"

4.9.15.3 LicenseLangString

名称 语言ID 许可文件路径

用法和 LangString 一样,但它仅从一个文本、RTF 文件载入字符串并且定义一个特殊且仅能用于 LicenseData 的 LangString 。

LicenseLangString license ${LANG_ENGLISH} license-english.txt
LicenseLangString license ${LANG_FRENCH} license-french.txt
LicenseLangString license ${LANG_GERMAN} license-german.txt
LicenseData $(license)

上一页 | 目录 | 下一页