Introduction
InstallOptions is a NSIS plugin which allows you to create custom pages for NSIS installers, to prompt the user for extra information.
-InstallerOptions will create a dialog which will be displayed inside +
InstallOptions will create a dialog which will be displayed inside the NSIS window. The controls on the dialog can be defined in an INI file.
NSIS 2 has a new page system, which allows you to add custom pages to your installer without messing with Prev/Next functions. With the new plugin @@ -203,7 +203,7 @@ It can contain the following values:
Each field section has the heading "Field #" where # must be sequential @@ -248,8 +248,10 @@ numbers from 1 to NumFields. Each Field section can contain the following values
| PATH_MUST_EXIST | Used by "FileRequest"
to force the path to
- exist. Prevents the user from typing a non-existant path into the
+ exist. Prevents the user from typing a non-existent path into the
browse dialog window. This only validates path's selected with the browse button. |
|
| MULTISELECT | Used by "Listbox" - controls. Turns string selection on or off each time the user clicks or double-clicks a string in the list box. The user can select any number of strings. If this flag and EXTENDEDSELCT are not specified, only one item can be selected from the the list. | |
| EXTENDEDSELCT | Used by "Listbox" - controls. Allows multiple items to be selected by using the SHIFT key and the mouse or special key combinations. If this flag and MULTISELECT are not specified, only one item can be selected from the the list. | |
| RESIZETOFIT | This causes "Bitmap" @@ -421,20 +429,20 @@ numbers from 1 to NumFields. Each Field section can contain the following values | Used by "Text" controls. Forces the user to enter only numbers into the edit box. |
| MULTILINE | -Used by "Text" controls. Causes the control to accept multiple-lines. | Used by "Text" controls. Causes the control to accept multiple-lines. |
| WANTRETURN | -Used by "Text" controls with multiple-line. Specifies that a carriage return be inserted when the user presses the ENTER key - while entering text into the text box. | Used by "Text" controls with multiple-line. Specifies that a carriage return be inserted when the user presses the ENTER key + while entering text into the text box. |
| HSCROLL | -Used by "Text" controls with multiple-line. Show a horizontal scrollbar. | Used by "Text" controls with multiple-line. Show a horizontal scrollbar. |
| VSCROLL | -Used by "Text" controls with multiple-line. Show a vertical scrollbar. | Used by "Text" controls with multiple-line. Show a vertical scrollbar. |
| READONLY | -Used by "Text" controls. Prevents the user from entering or editing text in the edit control, but allow the user to select and copy the text. | Used by "Text" controls. Prevents the user from entering or editing text in the edit control, but allow the user to select and copy the text. |
Call the DLL
@@ -467,7 +475,7 @@ Page custom SetCustom ValidateCustomThe InstallOptions DLL has three functions:
ReadINIStr $R0 "$PLUGINSDIR\test.ini" "Field 1" "State"-
Note:
-For Multiline edit boxes the output "State" comes with "\r\n" -if the text contains more than one line. You have to convert it to "$\r$\n" if needed, -using this macro:
-!macro NORMALIZE_CRCF 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 escape character is the back-slash character ("\") + and the available escape sequences are:
+| "\\" | +Back-slash | +
| "\r" | +Carriage return (ASCII 13) | +
| "\n" | +Line feed (ASCII 10) | +
| "\t" | +Tab (ASCII 9) | +
The following functions can be used to convert a string to and from + this format:
+; Convert an NSIS string to a form suitable for use by InstallOptions
+; Usage:
+; Push <NSIS-string>
+; Call Nsis2Io
+; Pop <IO-string>
+Function Nsis2Io
+ Exch $0 ; The source
+ Push $1 ; The output
+ Push $2 ; Temporary char
+ StrCpy $1 "" ; Initialise the output
+loop:
+ StrCpy $2 $0 1 ; Get the next source char
+ StrCmp $2 "" done ; Abort when none left
+ StrCpy $0 $0 "" 1 ; Remove it from the source
+ StrCmp $2 "\" "" +3 ; Back-slash?
+ StrCpy $1 "$1\\"
+ Goto loop
+ StrCmp $2 "$\r" "" +3 ; Carriage return?
+ StrCpy $1 "$1\r"
+ Goto loop
+ StrCmp $2 "$\n" "" +3 ; Line feed?
+ StrCpy $1 "$1\n"
+ Goto loop
+ StrCmp $2 "$\t" "" +3 ; Tab?
+ StrCpy $1 "$1\t"
+ Goto loop
+ StrCpy $1 "$1$2" ; Anything else
+ Goto loop
+done:
+ StrCpy $0 $1
+ Pop $2
+ Pop $1
+ Exch $0
+FunctionEnd
- ;Note: Do not use $R1-$R4 as value
-
- Push $R1 ; Index
- Push $R2 ; Output char by char
- Push $R3 ; Output char by char next
- Push $R4 ; Text Accumulator
-
- StrCpy $R1 "0"
-
- DONEXT:
- StrCpy $R2 ${VALUE} 1 $R1
- IntOp $R1 $R1 + 1
- StrCpy $R3 ${VALUE} 1 $R1
- StrCmp $R3 "" EOT
- StrCmp $R2 "\" 0 NORMAL_CHAR
- StrCmp $R3 "r" FOUND_CR
- StrCmp $R3 "n" 0 NORMAL_CHAR
-
- StrCpy $R4 "$R4$\r"
- IntOp $R1 $R1 + 1
- Goto DONEXT
-
- FOUND_CR:
- StrCpy $R4 "$R4$\n"
- IntOp $R1 $R1 + 1
- Goto DONEXT
-
- NORMAL_CHAR:
- StrCpy $R4 "$R4$R2"
- Goto DONEXT
-
- EOT:
- StrCpy ${VALUE} $R4
-
- Pop $R4
- Pop $R3
- Pop $R2
- Pop $R1
-
-!macroend
+; Convert an InstallOptions string to a form suitable for use by NSIS
+; Usage:
+; Push <IO-string>
+; Call Io2Nsis
+; Pop <NSIS-string>
+Function Io2Nsis
+ Exch $0 ; The source
+ Push $1 ; The output
+ Push $2 ; Temporary char
+ StrCpy $1 "" ; Initialise the output
+loop:
+ StrCpy $2 $0 1 ; Get the next source char
+ StrCmp $2 "" done ; Abort when none left
+ StrCpy $0 $0 "" 1 ; Remove it from the source
+ StrCmp $2 "\" +3 ; Escape character?
+ StrCpy $1 "$1$2" ; If not just output
+ Goto loop
+ StrCpy $2 $0 1 ; Get the next source char
+ StrCpy $0 $0 "" 1 ; Remove it from the source
+ StrCmp $2 "\" "" +3 ; Back-slash?
+ StrCpy $1 "$1\"
+ Goto loop
+ StrCmp $2 "r" "" +3 ; Carriage return?
+ StrCpy $1 "$1$\r"
+ Goto loop
+ StrCmp $2 "n" "" +3 ; Line feed?
+ StrCpy $1 "$1$\n"
+ Goto loop
+ StrCmp $2 "t" "" +3 ; Tab?
+ StrCpy $1 "$1$\t"
+ Goto loop
+ StrCpy $1 "$1$2" ; Anything else (should never get here)
+ Goto loop
+done:
+ StrCpy $0 $1
+ Pop $2
+ Pop $1
+ Exch $0
+FunctionEnd
Validate the input
If you want to validate the input on the page, @@ -549,7 +616,7 @@ Function ValidateCustom StrCmp $0 "" 0 +3 MessageBox MB_ICONEXCLAMATION|MB_OK "Please enter your name." Abort - + FunctionEnd
Return value
@@ -559,12 +626,12 @@ adds one value to the stack, with one of the following values:Usually, you don't need to check this value, but you still have to remove it from the stack (have a look at the example above).
-If you want to check the user input immidiately, +
If you want to check the user input immediately, for example, to display a warning when the input is invalid, you should check whether the user has pressed the Back or Next button.
ReserveFile
@@ -599,17 +666,17 @@ Function FunctionName ;FunctionName defined with Page command InstallOptions::initDialog /NOUNLOAD $PLUGINSDIR\test.ini Pop $R0 - + GetDlgItem $R1 $R0 1200 ;1200 + Field number - 1 - + ;$R1 contains the HWND of the first field - CreateFont $R2 "Tahoma" 10 700 + CreateFont $R2 "Tahoma" 10 700 SendMessage $R1 ${WM_SETFONT} $R2 0 - + InstallOptions::show Pop $R0 - - Pop $R2 + + Pop $R2 Pop $R1 Pop $R0 @@ -676,7 +743,7 @@ 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; +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.