4.7 Functions

Functions are similar to Sections in that they contain zero or more instructions. User functions are not called by the installer directly, instead they are called from Sections using the Call instruction. Callback functions will be called by the installer when a certain event occurs.

函数类似于Sections，它们包含零条或多条指令。用户函数不是由安装程序直接调用的，而是使用Call指令从Sections中调用的。当某个事件发生时，安装程序将调用回调函数。

Functions must be declared outside of Sections or other Functions.

函数必须在section或其他函数之外声明。

4.7.1 Function Commands

4.7.1.1 Function

Function [function_name]

Begins and opens a new function. Function names beginning with "." (e.g. ".Whatever") are generally reserved for callback functions. Function names beginning with "un." are functions that will be generated in the Uninstaller. Hence, normal install Sections and functions cannot call uninstall functions, and the Uninstall Section and uninstall functions cannot call normal functions.

开始并打开一个新函数。以.开头的函数名（如.whatever）通常保留在回调函数中。以un.开头的函数名是将在卸载程序中生成的函数。因此，普通的安装节和函数不能调用卸载函数，卸载节和卸载函数不能调用普通函数。

Function func
  # some commands
FunctionEnd

Section
  Call func
SectionEnd

4.7.1.2 FunctionEnd

This command closes the current open function.

4.7.2 Callback Functions

You can create callback functions (which have special names), that will be called by the installer at certain points in the install. Below is a list of available callbacks:

4.7.2.1 Install Callbacks

4.7.2.1.1 .onGUIInit

This callback will be called just before the first page is loaded and the installer dialog is shown, allowing you to tweak the user interface.

这个回调函数将在第一个页面被加载和安装对话框显示之前被调用，允许你调整用户界面。

Example:

!include "WinMessages.nsh"

Function .onGUIInit
  # 1028 is the id of the branding text control
  GetDlgItem $R0 $HWNDPARENT 1028
  CreateFont $R1 "Tahoma" 10 700
  SendMessage $R0 ${WM_SETFONT} $R1 0
  # set background color to white and text color to red
  SetCtlColors $R0 FFFFFF FF0000
FunctionEnd

4.7.2.1.2 .onInit

This callback will be called when the installer is nearly finished initializing. If the '.onInit' function calls Abort, the installer will quit instantly.

这个回调将在安装程序几乎完成初始化时被调用。如果.onInit的函数调用Abort，安装程序将立即退出。

Here are two examples of how this might be used:

Function .onInit
  MessageBox MB_YESNO "This will install. Continue?" IDYES NoAbort
    Abort ; causes installer to quit.
  NoAbort:
FunctionEnd

or:

Function .onInit
  ReadINIStr $INSTDIR $WINDIR\wincmd.ini Configuration InstallDir
  StrCmp $INSTDIR "" 0 NoAbort
    MessageBox MB_OK "Windows Commander not found. Unable to get install path."
    Abort ; causes installer to quit.
  NoAbort:
FunctionEnd

4.7.2.1.3 .onInstFailed

This callback is called when the user hits the 'cancel' button after the install has failed (if it could not extract a file, or the install script used the Abort command).

当用户在安装失败后点击“cancel”按钮时（如果它不能提取文件，或者安装脚本使用了Abort命令），这个回调函数被调用。

Example:

Function .onInstFailed
  MessageBox MB_OK "Better luck next time."
FunctionEnd

4.7.2.1.4 .onInstSuccess

This callback is called when the install was successful, right before the install window closes (which may be after the user clicks 'Close' if AutoCloseWindow or SetAutoClose is set to false).

这个回调函数在安装成功时调用，正好在安装窗口关闭之前（如果AutoCloseWindow或SetAutoClose设置为false，则可能是在用户单击“Close”之后）。

Example:

Function .onInstSuccess
  MessageBox MB_YESNO "Congrats, it worked. View readme?" IDNO NoReadme
    Exec notepad.exe ; view readme or whatever, if you want.
  NoReadme:
FunctionEnd

4.7.2.1.5 .onGUIEnd

This callback is called right after the installer window closes. Use it to free any user interface related plug-ins if needed.

这个回调函数在安装程序窗口关闭后被调用。如果需要，可以使用它来释放任何与用户界面相关的插件。

4.7.2.1.6 .onMouseOverSection

This callback is called whenever the mouse position over the sections tree has changed. This allows you to set a description for each section for example. The section id on which the mouse is over currently is stored, temporarily, in $0.

每当鼠标在sections树上的位置发生变化时，这个回调函数就会被调用。例如，这允许您为每个部分设置描述。鼠标所在的section id目前暂时存储在$0中。

Example:

Function .onMouseOverSection
  FindWindow $R0 "#32770" "" $HWNDPARENT
  GetDlgItem $R0 $R0 1043 ; description item (must be added to the UI)

  StrCmp $0 0 "" +2
    SendMessage $R0 ${WM_SETTEXT} 0 "STR:first section description"

  StrCmp $0 1 "" +2
    SendMessage $R0 ${WM_SETTEXT} 0 "STR:second section description"
FunctionEnd

4.7.2.1.7 .onRebootFailed

This callback is called if Reboot fails. WriteUninstaller, plug-ins, File and WriteRegBin should not be used in this callback.

如果Reboot失败，这个回调函数被调用。WriteUninstaller，插件，File和WriteRegBin不应该在这个回调中使用。

Example:

Function .onRebootFailed
  MessageBox MB_OK|MB_ICONSTOP "Reboot failed. Please reboot manually." /SD IDOK
FunctionEnd

4.7.2.1.8 .onSelChange

Called when the selection changes on the component page. Useful for using with SectionSetFlags and SectionGetFlags.

当组件页上的选择更改时调用。与SectionSetFlags和SectionGetFlags一起使用很有用。

Selection changes include both section selection and installation type changes. The section id of the changed section is stored in $0. $0 is -1 if the installation type changed. You only get notifications for changes initiated by the user and only one notification per action even if the action also affected child sections and/or parent groups.

4.7.2.1.9 .onUserAbort

This callback is called when the user hits the 'cancel' button, and the install hasn't already failed. If this function calls Abort, the install will not be aborted.

这个回调函数在用户点击“取消”按钮时被调用，而安装还没有失败。如果这个函数调用Abort，安装将不会被中止。

Example:

Function .onUserAbort
  MessageBox MB_YESNO "Abort install?" IDYES NoCancelAbort
    Abort ; causes installer to not quit.
  NoCancelAbort:
FunctionEnd

4.7.2.1.10 .onVerifyInstDir

This callback enables control over whether or not an installation path is valid for your installer. This code will be called every time the user changes the install directory, so it shouldn't do anything crazy with MessageBox or the like. If this function calls Abort, the installation path in $INSTDIR is deemed invalid.

此回调允许控制安装路径对安装程序是否有效。这段代码将在每次用户更改安装目录时被调用，所以它不应该做任何疯狂的MessageBox或类似的事情。如果这个函数调用Abort，$INSTDIR中的安装路径将被认为无效。

Example:

Function .onVerifyInstDir
  IfFileExists $INSTDIR\Winamp.exe PathGood
    Abort ; if $INSTDIR is not a winamp directory, don't let us install there
  PathGood:
FunctionEnd

4.7.2.2 Uninstall Callbacks

4.7.2.2.1 un.onGUIInit

This callback will be called just before the first page is loaded and the installer dialog is shown, allowing you to tweak the user interface.

这个回调函数将在第一个页面被加载和安装对话框显示之前被调用，允许你调整用户界面。

Have a look at .onGUIInit for an example.

4.7.2.2.2 un.onInit

This callback will be called when the uninstaller is nearly finished initializing. If the 'un.onInit' function calls Abort, the uninstaller will quit instantly. Note that this function can verify and/or modify $INSTDIR if necessary.

这个回调函数将在卸载程序初始化接近完成时被调用。如果un.onInit函数调用Abort，卸载程序将立即退出。注意，这个函数可以在必要时验证和/或修改$INSTDIR。

Here are two examples of how this might be used:

Function un.onInit
  MessageBox MB_YESNO "This will uninstall. Continue?" IDYES NoAbort
    Abort ; causes uninstaller to quit.
  NoAbort:
FunctionEnd

or:

Function un.onInit
  IfFileExists $INSTDIR\myfile.exe found
    Messagebox MB_OK "Uninstall path incorrect"
    Abort
  found:
FunctionEnd

4.7.2.2.3 un.onUninstFailed

This callback is called when the user hits the 'cancel' button after the uninstall has failed (if it used the Abort command or otherwise failed).

当用户在卸载失败后点击“取消”按钮（如果它使用了Abort命令或其他失败），这个回调被调用。

Example:

Function un.onUninstFailed
  MessageBox MB_OK "Better luck next time."
FunctionEnd

4.7.2.2.4 un.onUninstSuccess

This callback is called when the uninstall was successful, right before the install window closes (which may be after the user clicks 'Close' if SetAutoClose is set to false).

当卸载成功时调用这个回调，正好在安装窗口关闭之前（如果SetAutoClose设置为false，可能是在用户单击“Close”之后）。

Example:

Function un.onUninstSuccess
  MessageBox MB_OK "Congrats, it's gone."
FunctionEnd

4.7.2.2.5 un.onGUIEnd

This callback is called right after the uninstaller window closes. Use it to free any user interface related plug-ins if needed.

这个回调函数在卸载窗口关闭后被调用。如果需要，可以使用它来释放任何与用户界面相关的插件。

4.7.2.2.6 un.onRebootFailed

This callback is called if Reboot fails. WriteUninstaller, plug-ins, File and WriteRegBin should not be used in this callback.

如果Reboot失败，这个回调函数被调用。WriteUninstaller，插件，File和WriteRegBin不应该在这个回调中使用。

Example:

Function un.onRebootFailed
  MessageBox MB_OK|MB_ICONSTOP "Reboot failed. Please reboot manually." /SD IDOK
FunctionEnd

4.7.2.2.7 un.onSelChange

Called when the selection changes on the component page. Useful for using with SectionSetFlags and SectionGetFlags.

当组件页上的选择更改时调用。与SectionSetFlags和SectionGetFlags一起使用很有用。

Selection changes include both section selection and installation type changes. The section id of the changed section is stored in $0. $0 is -1 if the installation type changed. You only get notifications for changes initiated by the user and only one notification per action even if the action also affected child sections and/or parent groups.

4.7.2.2.8 un.onUserAbort

This callback is called when the user hits the 'cancel' button and the uninstall hasn't already failed. If this function calls Abort, the install will not be aborted.

当用户点击“取消”按钮并且卸载还没有失败时，调用这个回调。如果这个函数调用Abort，安装将不会被中止。

Example:

Function un.onUserAbort
  MessageBox MB_YESNO "Abort uninstall?" IDYES NoCancelAbort
    Abort ; causes uninstaller to not quit.
  NoCancelAbort:
FunctionEnd