InstallOptions 2

InstallOptions is an NSIS plugin which allows you to create custom pages for NSIS installers, to prompt the user for extra information.

The dialogs created by InstallOptions are based on INI files which define the controls on the dialog and their properties. These INI files can be modified from the script to adjust the dialogs on runtime.

The format of INI files is described in a Wikipedia article.

The INI file has one required section. This section includes the number of controls to be created as well as general window attributes. The INI file also includes a variable number of Field sections which are used to create the controls to be displayed.

The required section is named "Settings". It can contain the following values:

Each field section has the heading "Field #" where # must be sequential numbers from 1 to NumFields. Each Field section can contain the following values:

The InstallOptions header files provides macros and functions to easily create custom dialogs. You can include it on the top of your script as follows:

!include InstallOptions.nsh

Extracting the INI file

Function .onInit
  !insertmacro INSTALLOPTIONS_EXTRACT "ioFile.ini"
FunctionEnd

Function .onInit
  !insertmacro INSTALLOPTIONS_EXTRACT_AS "..\ioFile.ini" "ioFile.ini"
FunctionEnd

Displaying the dialog

Page custom CustomPageFunction

Function CustomPageFunction ;Function name defined with Page command
  !insertmacro INSTALLOPTIONS_DISPLAY "ioFile.ini"
FunctionEnd

To get the input of the user, read the State value of a Field using the INSTALLOPTIONS_READ macro:

!insertmacro INSTALLOPTIONS_READ $VAR "ioFile.ini" "Field #" "Name"

The INSTALLOPTIONS_WRITE macro allows you to write values to the INI file to change texts or control settings on runtime:

!insertmacro INSTALLOPTIONS_WRITE "ioFile.ini" "Field #" "Name" "Value"

Some InstallOptions values are escaped (in a similar manner to "C" strings) to allow characters to be used that are not normally valid in INI file values. The affected values are:

• The ValidateText field
• The Text value of Label fields
• The State value of Text fields that have the MULTILINE flag

The escape character is the back-slash character ("\") and the available escape sequences are:

The INSTALLOPTIONS_READ_CONVERT and INSTALLOPTIONS_WRITE_CONVERT macros automatically convert these characters in installer code. In uninstaller code, use INSTALLOPTIONS_READ_UNCONVERT and INSTALLOPTIONS_WRITE_UNCONVERT.

To use these macros in your script, the conversion functions need to be included:

;For INSTALLOPTIONS_READ_CONVERT
  !insertmacro INSTALLOPTIONS_FUNCTION_READ_CONVERT
;For INSTALLOPTIONS_WRITE_CONVERT
  !insertmacro INSTALLOPTIONS_FUNCTION_WRITE_CONVERT
;For INSTALLOPTIONS_READ_UNCONVERT
  !insertmacro INSTALLOPTIONS_UNFUNCTION_READ_CONVERT
;For INSTALLOPTIONS_WRITE_UNCONVERT
  !insertmacro INSTALLOPTIONS_UNFUNCTION_WRITE_CONVERT

To validate the user input (for example, to check whether the user has filled in a textbox) use the leave function of the Page command and Abort when the validation has failed:

Function ValidateCustom

  !insertmacro INSTALLOPTIONS_READ $R0 "test.ini" "Field 1" "State"
  StrCmp $R0 "" 0 +3
    MessageBox MB_ICONEXCLAMATION|MB_OK "Please enter your name."
    Abort

FunctionEnd

• success - The user has pressed the Next button
• back - The user has pressed the Back button
• cancel - The user has pressed the Cancel button
• error - An error has occurred, the dialog cannot be displayed.

You only have to check this value if you need something really special, such as doing something when the user pressed the Back button.

If you need the return value, use the INSTALLOPTIONS_DISPLAY_RETURN or INSTALLOPTIONS_SHOW_RETURN macro. The return value will be added to the stack, so you can use the Pop command to get it.

When using solid compression, it's important that files which are being extracted in user interface functions are located before other files in the data block. Otherwise there may be a delay before a page can be displayed.

To ensure that this is the case, add ReserveFile commands for InstallOptions and the INI files before all sections and functions:

ReserveFile "test.ini"
ReserveFile "${NSISDIR}\Plugins\InstallOptions.dll"

To customize fonts or colors on InstallOptions dialogs, the INSTALLOPTIONS_INITDIALOG and INSTALLOPTIONS_SHOW macro can be used.

INSTALLOPTIONS_INITDIALOG creates the dialog in memory, but does not show it. After inserting this macro, you can set the fonts and colors, and then insert INSTALLOPTIONS_SHOW to show the dialog.

The INSTALLOPTIONS_INITDIALOG macro also pushes the HWND of the custom dialog to the stack. Control HWND's are available for each control in the HWND entry of the corresponding field in the INI file.

Example of using a custom font:

Var HWND
Var DLGITEM
Var FONT

Function FunctionName ;FunctionName defined with Page command

  !insertmacro INSTALLOPTIONS_INITDIALOG "ioFile.ini"
  Pop $HWND ;HWND of dialog
    
  !insertmacro INSTALLOPTIONS_READ $DLGITEM "ioFile.ini" "Field 1" "HWND"
    
  ;$DLGITEM contains the HWND of the first field
  CreateFont $FONT "Tahoma" 10 700 
  SendMessage $DLGITEM ${WM_SETFONT} $FONT 0
        
  !insertmacro INSTALLOPTIONS_SHOW

FunctionEnd

Original version by Michael Bishop
DLL version by Nullsoft, Inc.
DLL version 2 by Amir Szekely, ORTIM, Joost Verburg
New documentation by Joost Verburg

Original version Copyright © 2001 Michael Bishop
DLL version 1 Copyright © 2001-2002 Nullsoft, Inc., ORTIM
DLL version 2 Copyright © 2003-2009 Amir Szekely, Joost Verburg, Dave Laundon

This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute
it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented;
   you must not claim that you wrote the original software.
   If you use this software in a product, an acknowledgment in the
   product documentation would be appreciated but is not required.
2. Altered versions must be plainly marked as such,
   and must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any distribution.