函數

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 "${NSISDIR}\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 $WINDIR\wincmd.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, plug-ins, 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 $INSTDIR\Winamp.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 $INSTDIR\myfile.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 , plug-ins , File 和 WriteRegBin 不能用於該回調函數。

例子 :

 Function un.onRebootFailed
   MessageBox MB_OK|MB_ICONSTOP "重啟失敗，請手動重啟。" /SD IDOK
 FunctionEnd

4.7.2.2.7 un.onUserAbort

該回調當用戶按這裡「取消」按鈕且卸載尚未失敗時被調用。如果該函數調用 Abort ，則卸載程式將不登出。

例子:

  Function un.onUserAbort
    MessageBox MB_YESNO "登出卸載？" IDYES NoCancelAbort
      Abort ; 使得卸載程式不能登出。
    NoCancelAbort:
  FunctionEnd