NSIS/Docs/src/callback.but

\S1{callbacks} 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 currently available callbacks:

\S2{instcallbacks} Install Callbacks

\S3{onguiinit} .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:

\c  !include "${NSISDIR}\Examples\WinMessages.NSH"
\c
\c  Function .onGUIInit
\c    # 1028 is the id of the branding text control
\c    GetDlgItem $R0 $HWNDPARENT 1028
\c    CreateFont $R1 "Tahoma" 10 700
\c    SendMessage $R0 ${WM_SETFONT} $R1 0
\c    SetStaticBkColor $R0 0x00FFFFFF
\c  FunctionEnd

\S3{oninit} .onInit

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

Here are two examples of how this might be used:

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

or:

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

\S3{oninstfailed} .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).

Example:

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

\S3{oninstsuccess} .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 is set to false).

Example:

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

\S3{onmouseoversection} .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.

Example:

\c   Function .onMouseOverSection
\c     FindWindow $R0 "#32770" "" $HWNDPARENT
\c     GetDlgItem $R0 $R0 1043 ; description item
\c
\c     StrCmp $0 0 "" +2
\c       SendMessage $R0 $\{WM_SETTEXT\} 0 "first section description"
\c
\c     StrCmp $0 1 "" +2
\c       SendMessage $R0 $\{WM_SETTEXT\} 0 "second section description"
\c   FunctionEnd

\S3{onselchange} .onSelChange

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

\S3{onuserabort} .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.

Example:

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

\S3{onverifyinstdir} .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 likes. If this function calls Abort, the installation path in $INSTDIR is deemed invalid.

Example:

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

\S2{uninstcallbacks} Uninstall Callbacks

\S3{unonguiinit} 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 (\K{onguiinit}) for an example.

\S3{unonInit} 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.

Here are two examples of how this might be used:

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

or:

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

\S3{unonuninstfailed} 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).

Example:

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

\S3{unonuninstsuccess} 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 AutoCloseWindow is set to false).

Example:

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

\S3{unonuserabort} 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.

Example:

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