Adding custom installer pages

Author: Afrow UK (talk, contrib)

Description

One of the more common questions that get asked is how to add custom pages/dialogs to one's installer. You may want to get some user input and take action depending on that input.

InstallOptions was the first way to add custom dialogs, with basic controls support such as text boxes, directory request fields and so on. There is also the InstallOptionsEx plug-in for more advanced dialogs with more controls and events.

There are other plug-ins out there now to display a range of dialogs, such as the nsWeb plug-in, the PassDialog plug-in, the EmbeddedLists plug-in and now the nsDialogs plug-in with NSIS (to serve as a replacement for InstallOptions).

To generate the InstallOptions INI files, see this list of form designers.

InstallOptions Code Snippet #1

This is the least complicated script with no run-time events or dialog manipulation.

!include "MUI.nsh"
 
OutFile "myCustomPage.exe"
 
Page Custom MyCustomPage MyCustomLeave
 
Function MyCustomPage
  # If you need to skip the page depending on a condition, call Abort.
  ReserveFile "InstallOptionsFile.ini"
  !insertmacro MUI_INSTALLOPTIONS_EXTRACT "InstallOptionsFile.ini"
  !insertmacro MUI_INSTALLOPTIONS_DISPLAY "InstallOptionsFile.ini"
FunctionEnd
 
Function MyCustomLeave
  # Form validation here. Call Abort to go back to the page.
  # Use !insertmacro MUI_INSTALLOPTIONS_READ $Var "InstallOptionsFile.ini" ...
  # to get values.
FunctionEnd
 
Section Dummy
SectionEnd

InstallOptions Code Snippet #2

This code demonstrates modifying the dialog at run time to highlight a field that has not been filled in.

!include LogicLib.nsh
...
 
Page Custom MyCustomPage MyCustomLeave
 
Function MyCustomPage
  ReserveFile "InstallOptionsFile.ini"
  !insertmacro MUI_INSTALLOPTIONS_EXTRACT "InstallOptionsFile.ini"
  !insertmacro MUI_INSTALLOPTIONS_DISPLAY "InstallOptionsFile.ini"
FunctionEnd
 
Function MyCustomLeave
  # Get control window handle.
  !insertmacro MUI_INSTALLOPTIONS_READ $R0 "InstallOptionsFile.ini" "Field 1" "HWND"
  # Check if text has been entered in field 1.
  !insertmacro MUI_INSTALLOPTIONS_READ $R1 "InstallOptionsFile.ini" "Field 1" "State"
  # Make field background red!
  ${If} $R1 == ""
    SetCtlColors $R1 0x000000 0xFF0000
    Abort # Go back to page.
  # Reset field colours.
  ${Else}
    SetCtlColors $R1 0x000000 0xFFFFFF
  ${EndIf}
FunctionEnd

InstallOptions Code Snippet #3

This code demonstrates manipulating the dialog at run time before it is displayed. This works a bit like InstallOptions Code Snippet #2.

Page Custom MyCustomPage MyCustomLeave
 
Function MyCustomPage
  ReserveFile "InstallOptionsFile.ini"
  !insertmacro MUI_INSTALLOPTIONS_EXTRACT "InstallOptionsFile.ini"
  !insertmacro MUI_INSTALLOPTIONS_INITDIALOG "InstallOptionsFile.ini"
 
  # Get the control window handle.
  !insertmacro MUI_INSTALLOPTIONS_READ $R0 "InstallOptionsFile.ini" "Field 1" "HWND"
  # Make the field background colour red.
  SetCtlColors $R0 0x000000 0xFF0000
 
  !insertmacro MUI_INSTALLOPTIONS_SHOW
FunctionEnd
 
Function MyCustomLeave
  # Form validation here. Call Abort to go back to the page.
  # Use !insertmacro MUI_INSTALLOPTIONS_READ $Var "InstallOptionsFile.ini" ...
  # to get values.
FunctionEnd

InstallOptions Code Snippet #4

This code shows how to do something when a button is pressed on your custom page. You need Flags=NOTIFY on your button field in the INI file.

!include LogicLib.nsh
...
 
Page Custom MyCustomPage MyCustomLeave
 
Function MyCustomPage
  ReserveFile "InstallOptionsFile.ini"
  !insertmacro MUI_INSTALLOPTIONS_EXTRACT "InstallOptionsFile.ini"
  !insertmacro MUI_INSTALLOPTIONS_DISPLAY "InstallOptionsFile.ini"
FunctionEnd
 
Function MyCustomLeave
  # Find out which field event called us. 0 = Next button called us.
  !insertmacro MUI_INSTALLOPTIONS_READ $R0 "InstallOptionsFile.ini" "Settings" "State"
  ${If} $R0 == 1 # Field 1.
    # Do something useful here and then go back to the page.
    Abort
  ${EndIf}
FunctionEnd