From 13425ee143c18f04349ecc210e9788317ca2ee55 Mon Sep 17 00:00:00 2001 From: joostverburg Date: Thu, 9 Aug 2007 00:53:45 +0000 Subject: [PATCH] * New header file with macros and conversion functions for use with InstallOptions * Updated InstallOptions documentation git-svn-id: https://svn.code.sf.net/p/nsis/code/NSIS/trunk@5226 212acab6-be3b-0410-9dea-997c60f758d6 --- Contrib/InstallOptions/InstallOptions.nsh | 232 +++ Contrib/InstallOptions/Readme.html | 1660 +++++++++++---------- Contrib/InstallOptions/SConscript | 7 +- 3 files changed, 1071 insertions(+), 828 deletions(-) create mode 100644 Contrib/InstallOptions/InstallOptions.nsh diff --git a/Contrib/InstallOptions/InstallOptions.nsh b/Contrib/InstallOptions/InstallOptions.nsh new file mode 100644 index 00000000..24cb2f38 --- /dev/null +++ b/Contrib/InstallOptions/InstallOptions.nsh @@ -0,0 +1,232 @@ +/* + +InstallOptions.nsh +Macros and conversion functions for InstallOptions + +*/ + +!macro INSTALLOPTIONS_FUNCTION_READ_CONVERT + !insertmacro INSTALLOPTIONS_FUNCTION_IO2NSIS "" +!macroend + +!macro INSTALLOPTIONS_UNFUNCTION_READ_CONVERT + !insertmacro INSTALLOPTIONS_FUNCTION_IO2NSIS un. +!macroend + +!macro INSTALLOPTIONS_FUNCTION_WRITE_CONVERT + !insertmacro INSTALLOPTIONS_FUNCTION_NSIS2IO "" +!macroend + +!macro INSTALLOPTIONS_UNFUNCTION_WRITE_CONVERT + !insertmacro INSTALLOPTIONS_FUNCTION_NSIS2IO un. +!macroend + +!macro INSTALLOPTIONS_FUNCTION_NSIS2IO UNINSTALLER_FUNCPREFIX + + ; Convert an NSIS string to a form suitable for use by InstallOptions + ; Usage: + ; Push + ; Call Nsis2Io + ; Pop + + Function ${UNINSTALLER_FUNCPREFIX}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 + +!macroend + +!macro INSTALLOPTIONS_FUNCTION_IO2NSIS UNINSTALLER_FUNCPREFIX + + ; Convert an InstallOptions string to a form suitable for use by NSIS + ; Usage: + ; Push + ; Call Io2Nsis + ; Pop + + Function ${UNINSTALLER_FUNCPREFIX}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 + +!macroend + +!macro INSTALLOPTIONS_EXTRACT FILE + + InitPluginsDir + File "/oname=$PLUGINSDIR\${FILE}" "${FILE}" + !insertmacro INSTALLOPTIONS_WRITE "${FILE}" "Settings" "RTL" "$(^RTL)" + + !verbose pop + +!macroend + +!macro INSTALLOPTIONS_EXTRACT_AS FILE FILENAME + + InitPluginsDir + File "/oname=$PLUGINSDIR\${FILENAME}" "${FILE}" + !insertmacro INSTALLOPTIONS_WRITE "${FILENAME}" "Settings" "RTL" "$(^RTL)" + +!macroend + +!macro INSTALLOPTIONS_DISPLAY FILE + + Push $0 + + InstallOptions::dialog "$PLUGINSDIR\${FILE}" + Pop $0 + + Pop $0 + +!macroend + +!macro INSTALLOPTIONS_DISPLAY_RETURN FILE + + InstallOptions::dialog "$PLUGINSDIR\${FILE}" + +!macroend + +!macro INSTALLOPTIONS_INITDIALOG FILE + + InstallOptions::initDialog /NOUNLOAD "$PLUGINSDIR\${FILE}" + +!macroend + +!macro INSTALLOPTIONS_SHOW + + Push $0 + + InstallOptions::show + Pop $0 + + Pop $0 + +!macroend + +!macro INSTALLOPTIONS_SHOW_RETURN + + InstallOptions::show + +!macroend + +!macro INSTALLOPTIONS_READ VAR FILE SECTION KEY + + ReadIniStr ${VAR} "$PLUGINSDIR\${FILE}" "${SECTION}" "${KEY}" + +!macroend + +!macro INSTALLOPTIONS_WRITE FILE SECTION KEY VALUE + + WriteIniStr "$PLUGINSDIR\${FILE}" "${SECTION}" "${KEY}" "${VALUE}" + +!macroend + +!macro INSTALLOPTIONS_READ_CONVERT VAR FILE SECTION KEY + + ReadIniStr ${VAR} "$PLUGINSDIR\${FILE}" "${SECTION}" "${KEY}" + Push ${VAR} + Call Io2Nsis + Pop ${VAR} + +!macroend + +!macro INSTALLOPTIONS_READ_UNCONVERT VAR FILE SECTION KEY + + ReadIniStr ${VAR} "$PLUGINSDIR\${FILE}" "${SECTION}" "${KEY}" + Push ${VAR} + Call un.Io2Nsis + Pop ${VAR} + +!macroend + +!macro INSTALLOPTIONS_WRITE_CONVERT FILE SECTION KEY VALUE + + Push $0 + StrCpy $0 "${VALUE}" + Push $0 + Call Nsis2Io + Pop $0 + + WriteIniStr "$PLUGINSDIR\${FILE}" "${SECTION}" "${KEY}" $0 + + Pop $0 + +!macroend + +!macro INSTALLOPTIONS_WRITE_UNCONVERT FILE SECTION KEY VALUE + + Push $0 + StrCpy $0 "${VALUE}" + Push $0 + Call un.Nsis2Io + Pop $0 + + WriteIniStr "$PLUGINSDIR\${FILE}" "${SECTION}" "${KEY}" $0 + + Pop $0 + +!macroend + \ No newline at end of file diff --git a/Contrib/InstallOptions/Readme.html b/Contrib/InstallOptions/Readme.html index 8ba38b00..d4ef80b4 100644 --- a/Contrib/InstallOptions/Readme.html +++ b/Contrib/InstallOptions/Readme.html @@ -2,877 +2,885 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -InstallOptions 2 - - + .righttable + { + background-color: #EEEEEE; + vertical-align: top; + } + /*]]>*/ - - -
-

InstallOptions 2

-
-

Introduction

-
-

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

-

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 system, you also don't have to worry anymore -about extracting and deleting the DLL file. When you store the INI -files in the plugins directory, NSIS will also delete them -automatically.

-

This new version of InstallOptions has been designed for NSIS 2. -It supports customized user interfaces and custom font and DPI -settings.

-
-

INI File

-
-

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:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NumFields(required)The number of control elements to be -displayed on the dialog window.
Title(optional)If specified, gives the text to set the -titlebar to. Otherwise, the titlebar text is not changed.
CancelEnabled(optional)If specified, overrides NSIS settings and -enables or disables the cancel button. If set to 1, the cancel -button will be enabled. If set to 0, the cancel button will be -disabled.
CancelShow(optional)If specified, overrides NSIS settings and -shows or hides the cancel button If set to 1, the cancel button -will be shown. If set to 0, the cancel button will be hidden.
BackEnabled(optional)If specified, overrides NSIS settings and -enables or disables the back button. If set to 1, the back button -will be enabled. If set to 0, the back button will be -disabled.
CancelButtonText(optional)Overrides the text for the cancel button. If -not specified, the cancel button text will not be changed.
NextButtonText(optional)Overrides the text for the next button. If -not specified, the next button text will not be changed.
BackButtonText(optional)Overrides the text for the back button. If -not specified, the back button text will not be changed.
Rect(optional)Overrides the default rect ID to run over. -This will make IO resize itself according to a different rect than -NSIS's dialogs rect.
RTL(optional)If 1 is specified the dialog will be -mirrored and all texts will be aligned to the right. Use NSIS's -$(^RTL) to fill this field, it's the easiest way.
State(output)This is not something you have to supply -yourself but is set by InstallOptions, before calling your custom -page validation function, to the field number of the custom Button -control (or other control having the Notify flag) the user pressed, -if any.
-

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

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Type(required)Type of control to be created. Valid values -are "Label", "Text", "Password", -"Combobox", "DropList", "Listbox", -"CheckBox", "RadioButton", -"FileRequest", "DirRequest" "Icon", -"Bitmap", "GroupBox", "HLine", -"VLine", "Link" or "Button".
-
-A "Label" is used to display static text. (i.e. a caption -for a textbox)
-A "Text" and "Password" accept text input from -the user. "Password" masks the input with * -characters.
-A "Combobox" allows the user to type text not in the popup -list, a "Droplist" only allows selection of items in the -list.
-A "Listbox" shows multiple items and can optionally allow -the user to select more than one item.
-A "CheckBox" control displays a check box with -label.
-A "RadioButton" control displays a radio button with -label.
-A "FileRequest" control displays a textbox and a browse -button. Clicking the browse button will display a file requester -where the user can browse for a file.
-A "DirRequest" control displays a textbox and a browse -button. Clicking the browse button will display a directory -requester where the user can browse for a directory.
-An "Icon" control displays an icon. Use no Text to use the -installer icon.
-A "Bitmap" control displays a bitmap.
-A "GroupBox" control displays a frame to group -controls.
-A "HLine" control displays a horizontal line to separate -controls.
-A "VLine" control displays a vertical line to separate -controls.
-A "Link" control displays a static hot text. When the user -clicks the control the contents of State (e.g. -http://...) will be executed using ShellExecute. Alternatively -State can be omitted and the NOTIFY flag -used to have your NSIS script called. See the "NOTIFY" -flag below for more information.
-A "Button" control displays a push button that can be used -in the same way as the "Link" control above.
Text(optional)Specifies the caption of a label, checkbox, -or radio button control. For DirRequest control this specifies the -title of the browse dialog. For icon and bitmaps control this -specifies the path to the image.
-
-Note: For labels, \r\n will be converted to a -newline. To use a back-slash in your text you have to escape it -using another back-slash - \\. Described below are NSIS functions for converting text -to/from this format.
State(optional)Specifies the state of the control. This is -updated when the user closes the window, so you can read from it -from NSIS. For edit texts and dir and file request boxes, this is -the string that is specified. For radio button and check boxes, -this can be '0' or '1' (for unchecked or checked). For list boxes, -combo boxes and drop lists this is the selected items separated by -pipes ('|'). For Links and Buttons this can specify something to be -executed or opened (using ShellExecute).
-
-Note: For Text fields with the MULTILINE flag, -\r\n will be converted to a newline. To use a back-slash in your -text you have to escape it using another back-slash - \\. Described -below are NSIS functions for converting -text to/from this format.
ListItems(optional)A list of items to display in a combobox, -droplist, or listbox.
-This is a single line of text with each item separated by a pipe -character '|'
MaxLen(optional)Causes validation on the selected control to -limit the maximum length of text.
-If the user specifies more text than this, a message box will -appear when they click "OK" and the dialog will not be -dismissed.
-You should not use this on a "combobox" since the user can -not control what is selected.
-This should be set to a maximum of 260 for "FileRequest" -and "DirRequest" controls.
-Ignored on "Label" controls.
MinLen(optional)Causes validation on the selected control to -force the user to enter a minimum amount of text.
-If the user specifies less text than this, a message box will -appear when they click "OK" and the dialog will not be -dismissed.
-Unlike MaxLen, this is useful for "Combobox" controls. By -setting this to a value of "1" the program will force the user to -select an item.
-Ignored on "Label" controls.
ValidateText(optional)If the field fails the test for -"MinLen" or "MaxLen", a messagebox will be -displayed with this text.
-
-Note: \r\n will be converted to a newline, two -back-slashes will be converted to one - \\. Described below are NSIS functions for converting text -to/from this format.
Left
-Right
-Top
-Bottom		(required)The position on the dialog where this -control appears. All sizes should be set in dialog units. To get -the right dimensions for your controls, design your dialog using a -resource editor and copy the dimensions to the INI file.
-
-Note: You can specify negative coordinates to -specify the distance from the right or bottom edge.
-
-Note (2): For combobox or droplist, the -"bottom" value is not used in the same way.
-In this case, the bottom value is the maximum size of the window -when the pop-up list is being displayed. All other times, the -combobox is automatically sized to be one element tall. If you have -trouble where you can not see the combobox drop-down, then check -the bottom value and ensure it is large enough. A rough guide for -the height required is the number of items in the list multiplied -by 8, plus 20.
-
-Note (3): FileRequest and DirRequest controls will -allocate 15 dialog units to the browse button. Make this control -wide enough the contents of the textbox can be seen.
Filter(optional)Specifies the filter to be used in the -"FileRequest" control.
-This is constructed by putting pairs of entries together, each item -separated by a | character.
-The first value in each pair is the text to display for the -filter.
-The second value is the pattern to use to match files.
-For example, you might specify:
-Filter=Text Files|*.txt|Programs|*.exe;*.com|All Files|*.*
-If not specified, then the filter defaults to All Files|*.*
-
-Note: you should not put any extra spaces around -the | characters.
Root(optional)Used by DirRequest controls -to specify the root directory of the search. By default, this -allows the user to browse any directory on the computer. This will -limit the search to a particular directory on the system.
Flags(optional)This specifies additional flags for the -display of different controls. Each value should be separated by a -| character, and you should be careful not to put any spaces around -the | character.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ValueMeaning
REQ_SAVEThis causes "FileRequest" controls -to display a Save As dialog. If not specified, an Open dialog is -used.
FILE_MUST_EXISTUsed by "FileRequest" to determine -if the selected file must exist.
-This only applies if an "Open" dialog is being displayed.
-This currently does not force the file to exist other than through -the browse button.
FILE_EXPLORERUsed by "FileRequest", enables new -file request look (recommended)
FILE_HIDEREADONLYUsed by "FileRequest", hides "open -read only" checkbox in open dialog.
WARN_IF_EXISTUsed by "FileRequest" to display a -warning message if the selected file already exists.
-The warning message is only displayed for files selected with the -browse button.
PATH_MUST_EXISTUsed by "FileRequest" to force the -path to 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.
PROMPT_CREATEUsed by "FileRequest" to display a -warning if the selected file does not exist. However, it still -allows the user to select the file.
-This only displays the warning for files selected with the browse -button.
-Doesn't work along with REQ_SAVE.
RIGHTUsed by "Checkbox" and -"Radiobutton" controls to specify you want the checkbox to -the right of the text instead of the left as is the default.
MULTISELECTUsed 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 list.
EXTENDEDSELCTUsed 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 list.
RESIZETOFITThis causes "Bitmap" controls to -resize the image to the size of the control. Also useful to support -custom DPI settings. Without this, the image will be centered -within the specified area.
TRANSPARENTUsed by "Bitmap" controls. Hides -every pixel with the same color as of the top left pixel. This -allows to see-through to controls behind it. This flag doesn't -work well with a combination of the RESIZETOFIT flag and bitmaps -with more than 256 colors.
GROUPAdd this flag to the first control of a -group of controls to group them. Grouping controls allows you to -create multiple groups of radio button and makes keyboard -navigation using arrow keys easier.
FOCUSSets focus on the specified control, -instead of the first focusable control. If more than one field -is specified with this flag, only the first one will receive -focus.
NOTABSTOPDo not stop on the control when the user -pressed the Tab key. Add NOTABSTOP to all controls of a group -except the first one to allow navigation between groups with the -Tab key.
DISABLEDCauses a control to be disabled.
ONLY_NUMBERSUsed by "Text" controls. Forces the -user to enter only numbers into the edit box.
MULTILINEUsed by "Text" controls. Causes the -control to accept multiple-lines.
WANTRETURNUsed 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.
NOWORDWRAPUsed by "Text" controls with -multiple-line. Disables the word-wrap that occurs when long lines -are entered. Long lines instead scroll off to the side. Specifying -the HSCROLL flag also has this effect.
HSCROLLShow a horizontal scrollbar. When used by -"Text" controls with multiple-lines this also disables -word-wrap.
VSCROLLShow a vertical scrollbar.
READONLYUsed 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.
NOTIFYUsed by "Button", "Link", -"CheckBox", "RadioButton", "ListBox" and -"DropList" controls. Causes InstallOptions to call your -NSIS custom page validation/leave function whenever the control's -selection changes. Your validation/leave function can read the -"State" value from the "Settings" section to -determine which control caused the notification, if any, and -perform some appropriate action followed by an Abort instruction -(to tell NSIS to return to the page). The Examples\InstallOptions -folder contains an example script showing how this might be -used.
-
TxtColor(optional)Used by Link controls to -specify the foreground color of the text. Format: 0xBBGGRR -(hexadecimal).
HWND
HWND2		(output)After initDialog returns, this will contain -the HWND of the control created by this field. It can be used -instead of FindWindow and GetDlgItem. HWND2 contains the HWND of -an additional control, such as the browse button.
-
-

How to use

-
-

Modern UI

-
-

For information about using InstallOptions with the Modern UI, -have a look at the Modern UI -documentation.

-
-

Extract the INI File

-
-

First, you have to extract the INI files for the dialogs in the -.onInit function:

-
+    
+        
+            
-
-

+                

+                    InstallOptions 2

+                

+                    

+                        The InstallOptions plug-in is deprecated. For new scripts, it is recommended to
+                        use the new nsDialogs plug-in instead.

+                

+                

+                    

+                        Introduction

+                    

+                        

+                            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.

+                    

+                    

+                        INI file structure

+                    

+                        

+                            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:

+                        
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                        

+                                    NumFields
+                                    (required)
+                                    The number of control elements to be displayed on the dialog window.

+                                    Title
+                                    (optional)
+                                    If specified, gives the text to set the titlebar to. Otherwise, the titlebar text
+                                    is not changed.

+                                    CancelEnabled
+                                    (optional)
+                                    If specified, overrides NSIS settings and enables or disables the cancel button.
+                                    If set to 1, the cancel button will be enabled. If set to 0, the cancel button will
+                                    be disabled.

+                                    CancelShow
+                                    (optional)
+                                    If specified, overrides NSIS settings and shows or hides the cancel button If set
+                                    to 1, the cancel button will be shown. If set to 0, the cancel button will be hidden.

+                                    BackEnabled
+                                    (optional)
+                                    If specified, overrides NSIS settings and enables or disables the back button. If
+                                    set to 1, the back button will be enabled. If set to 0, the back button will be
+                                    disabled.

+                                    CancelButtonText
+                                    (optional)
+                                    Overrides the text for the cancel button. If not specified, the cancel button text
+                                    will not be changed.

+                                    NextButtonText
+                                    (optional)
+                                    Overrides the text for the next button. If not specified, the next button text will
+                                    not be changed.

+                                    BackButtonText
+                                    (optional)
+                                    Overrides the text for the back button. If not specified, the back button text will
+                                    not be changed.

+                                    Rect
+                                    (optional)
+                                    Overrides the default rect ID to run over. This will make IO resize itself according
+                                    to a different rect than NSIS's dialogs rect.

+                                    RTL
+                                    (optional)
+                                    If 1 is specified the dialog will be mirrored and all texts will be aligned to the
+                                    right. The INSTALLOPTIONS_EXTRACT macros automatically set this field to the right
+                                    value for the current installer language as given by the NSIS string $(^RTL).

+                                    State
+                                    (output)
+                                    This is not something you have to supply yourself but is set by InstallOptions,
+                                    before calling your custom page validation function, to the field number of the
+                                    custom Button control (or other control having the Notify flag) the user pressed,
+                                    if any.

+                        

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

+                        
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+                            
+                            
+                                
+                                
+                                
+        
+        
+            
+            
+            
+        
+        
+            
+            
+            
+        
+    

+                                    Type
+                                    (required)
+                                    Type of control to be created. Valid values are "Label", "Text",
+                                    "Password", "Combobox", "DropList",
+                                    "Listbox", "CheckBox", "RadioButton",
+                                    "FileRequest", "DirRequest" "Icon",
+                                    "Bitmap", "GroupBox", "HLine",
+                                    "VLine", "Link" or "Button".

+                                    

+                                    A "Label" is used to display static text. (i.e. a caption for
+                                    a textbox)

+                                    A "Text" and "Password" accept text input
+                                    from the user. "Password" masks the input with * characters.

+                                    A "Combobox" allows the user to type text not in the popup list,
+                                    a "Droplist" only allows selection of items in the list.

+                                    A "Listbox" shows multiple items and can optionally allow the
+                                    user to select more than one item.

+                                    A "CheckBox" control displays a check box with label.

+                                    A "RadioButton" control displays a radio button with label.

+                                    A "FileRequest" control displays a textbox and a browse button.
+                                    Clicking the browse button will display a file requester where the user can browse
+                                    for a file.

+                                    A "DirRequest" control displays a textbox and a browse button.
+                                    Clicking the browse button will display a directory requester where the user can
+                                    browse for a directory.

+                                    An "Icon" control displays an icon. Use no Text to use the installer
+                                    icon.

+                                    A "Bitmap" control displays a bitmap.

+                                    A "GroupBox" control displays a frame to group controls.

+                                    A "HLine" control displays a horizontal line to separate controls.

+                                    A "VLine" control displays a vertical line to separate controls.

+                                    A "Link" control displays a static hot text. When the user clicks
+                                    the control the contents of State (e.g. http://...) will be executed
+                                    using ShellExecute. Alternatively State can be omitted and the
+                                    NOTIFY flag used to have your NSIS script called. See the "NOTIFY"
+                                    flag below for more information.

+                                    A "Button" control displays a push button that can be used in
+                                    the same way as the "Link" control above.

+                                    Text
+                                    (optional)
+                                    Specifies the caption of a label, checkbox, or radio button control. For DirRequest
+                                    control this specifies the title of the browse dialog. For icon and bitmaps control
+                                    this specifies the path to the image.

+                                    

+                                    Note: For labels, \r\n will be converted to a newline. To use a
+                                    back-slash in your text you have to escape it using another back-slash - \\. Described
+                                    below are NSIS functions for converting text to/from this
+                                    format.

+                                    State
+                                    (optional)
+                                    Specifies the state of the control. This is updated when the user closes the window,
+                                    so you can read from it from NSIS. For edit texts and dir and file request boxes,
+                                    this is the string that is specified. For radio button and check boxes, this can
+                                    be '0' or '1' (for unchecked or checked). For list boxes, combo boxes and drop lists
+                                    this is the selected items separated by pipes ('|'). For Links and Buttons this
+                                    can specify something to be executed or opened (using ShellExecute).

+                                    

+                                    Note: For Text fields with the MULTILINE flag, \r\n will be converted
+                                    to a newline. To use a back-slash in your text you have to escape it using another
+                                    back-slash - \\. Described below are NSIS functions for
+                                    converting text to/from this format.

+                                    ListItems
+                                    (optional)
+                                    A list of items to display in a combobox, droplist, or listbox.

+                                    This is a single line of text with each item separated by a pipe character '|'

+                                    MaxLen
+                                    (optional)
+                                    Causes validation on the selected control to limit the maximum length of text.

+                                    If the user specifies more text than this, a message box will appear when they click
+                                    "OK" and the dialog will not be dismissed.

+                                    You should not use this on a "combobox" since the user can not
+                                    control what is selected.

+                                    This should be set to a maximum of 260 for "FileRequest" and
+                                    "DirRequest" controls.

+                                    Ignored on "Label" controls.

+                                    MinLen
+                                    (optional)
+                                    Causes validation on the selected control to force the user to enter a minimum amount
+                                    of text.

+                                    If the user specifies less text than this, a message box will appear when they click
+                                    "OK" and the dialog will not be dismissed.

+                                    Unlike MaxLen, this is useful for "Combobox" controls. By setting
+                                    this to a value of "1" the program will force the user to select an item.

+                                    Ignored on "Label" controls.

+                                    ValidateText
+                                    (optional)
+                                    If the field fails the test for "MinLen" or "MaxLen",
+                                    a messagebox will be displayed with this text.

+                                    

+                                    Note: \r\n will be converted to a newline, two back-slashes will
+                                    be converted to one - \\. Described below are NSIS functions
+                                    for converting text to/from this format.

+                                    Left

+                                        Right

+                                        Top

+                                        Bottom		
+                                    (required)
+                                    The position on the dialog where this control appears. All sizes should be set in
+                                    dialog units. To get the right dimensions for your controls, design your dialog
+                                    using a resource editor and copy the dimensions to the INI file.

+                                    

+                                    Note: You can specify negative coordinates to specify the distance
+                                    from the right or bottom edge.

+                                    

+                                    Note (2): For combobox or droplist, the "bottom"
+                                    value is not used in the same way.

+                                    In this case, the bottom value is the maximum size of the window when the pop-up
+                                    list is being displayed. All other times, the combobox is automatically sized to
+                                    be one element tall. If you have trouble where you can not see the combobox drop-down,
+                                    then check the bottom value and ensure it is large enough. A rough guide for the
+                                    height required is the number of items in the list multiplied by 8, plus 20.

+                                    

+                                    Note (3): FileRequest and DirRequest controls will allocate 15
+                                    dialog units to the browse button. Make this control wide enough the contents of
+                                    the textbox can be seen.

+                                    Filter
+                                    (optional)
+                                    Specifies the filter to be used in the "FileRequest" control.

+                                    This is constructed by putting pairs of entries together, each item separated by
+                                    a | character.

+                                    The first value in each pair is the text to display for the filter.

+                                    The second value is the pattern to use to match files.

+                                    For example, you might specify:

+                                    Filter=Text Files|*.txt|Programs|*.exe;*.com|All Files|*.*

+                                    If not specified, then the filter defaults to All Files|*.*

+                                    

+                                    Note: you should not put any extra spaces around the | characters.

+                                    Root
+                                    (optional)
+                                    Used by DirRequest controls to specify the root directory of the
+                                    search. By default, this allows the user to browse any directory on the computer.
+                                    This will limit the search to a particular directory on the system.

+                                    Flags
+                                    (optional)
+                                    This specifies additional flags for the display of different controls. Each value
+                                    should be separated by a | character, and you should be careful not to put any spaces
+                                    around the | character.

+                                    
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                            
+                                            
+                                        
+                                        
+                                        
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                            
+                                
+                                
+                            
+                        

+                                                Value
+                                                Meaning

+                                                REQ_SAVE
+                                                This causes "FileRequest" controls to display a Save As dialog.
+                                                If not specified, an Open dialog is used.

+                                                FILE_MUST_EXIST
+                                                Used by "FileRequest" to determine if the selected file must
+                                                exist.

+                                                This only applies if an "Open" dialog is being displayed.

+                                                This currently does not force the file to exist other than through the browse button.

+                                                FILE_EXPLORER
+                                                Used by "FileRequest", enables new file request look (recommended)

+                                                FILE_HIDEREADONLY
+                                                Used by "FileRequest", hides "open read only" checkbox
+                                                in open dialog.

+                                                WARN_IF_EXIST
+                                                Used by "FileRequest" to display a warning message if the selected
+                                                file already exists.

+                                                The warning message is only displayed for files selected with the browse button.

+                                                PATH_MUST_EXIST
+                                                Used by "FileRequest" to force the path to 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.

+                                                PROMPT_CREATE
+                                                Used by "FileRequest" to display a warning if the selected file
+                                                does not exist. However, it still allows the user to select the file.

+                                                This only displays the warning for files selected with the browse button.

+                                                Doesn't work along with REQ_SAVE.

+                                                RIGHT
+                                                Used by "Checkbox" and "Radiobutton" controls
+                                                to specify you want the checkbox to the right of the text instead of the left as
+                                                is the default.

+                                                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 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 list.

+                                                RESIZETOFIT
+                                                This causes "Bitmap" controls to resize the image to the size
+                                                of the control. Also useful to support custom DPI settings. Without this, the image
+                                                will be centered within the specified area.

+                                            TRANSPARENT
+                                            Used by "Bitmap" controls. Hides every pixel with the same color
+                                            as of the top left pixel. This allows to see-through to controls behind it. This
+                                            flag doesn't work well with a combination of the RESIZETOFIT flag and bitmaps with
+                                            more than 256 colors.

+                                    GROUP
+                                    Add this flag to the first control of a group of controls to group them. Grouping
+                                    controls allows you to create multiple groups of radio button and makes keyboard
+                                    navigation using arrow keys easier.

+                                    FOCUS
+                                    Sets focus on the specified control, instead of the first focusable control. If
+                                    more than one field is specified with this flag, only the first one will receive
+                                    focus.

+                                    NOTABSTOP
+                                    Do not stop on the control when the user pressed the Tab key. Add NOTABSTOP to all
+                                    controls of a group except the first one to allow navigation between groups with
+                                    the Tab key.

+                                    DISABLED
+                                    Causes a control to be disabled.

+                                    ONLY_NUMBERS
+                                    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.

+                                    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.

+                                    NOWORDWRAP
+                                    Used by "Text" controls with multiple-line. Disables the word-wrap
+                                    that occurs when long lines are entered. Long lines instead scroll off to the side.
+                                    Specifying the HSCROLL flag also has this effect.

+                                    HSCROLL
+                                    Show a horizontal scrollbar. When used by "Text" controls with
+                                    multiple-lines this also disables word-wrap.

+                                    VSCROLL
+                                    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.

+                                    NOTIFY
+                                    Used by "Button", "Link", "CheckBox",
+                                    "RadioButton", "ListBox" and "DropList"
+                                    controls. Causes InstallOptions to call your NSIS custom page validation/leave function
+                                    whenever the control's selection changes. Your validation/leave function can read
+                                    the "State" value from the "Settings" section
+                                    to determine which control caused the notification, if any, and perform some appropriate
+                                    action followed by an Abort instruction (to tell NSIS to return to the page). The
+                                    Examples\InstallOptions folder contains an example script showing how this might
+                                    be used.

+            

+                TxtColor
+                (optional)
+                Used by Link controls to specify the foreground color of the text.
+                Format: 0xBBGGRR (hexadecimal).

+                HWND

+                    HWND2		
+                (output)
+                After initDialog returns, this will contain the HWND of the control created by this
+                field. It can be used instead of FindWindow and GetDlgItem. HWND2 contains the HWND
+                of an additional control, such as the browse button.

+    

+    

+        Header file

+    

+        

+            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
+

+    

+    

+        Creating dialogs

+    

+        

+            Extracting the INI file

+        

+            

+                First, you have to extract your InstallOptions INI files in the .onInit function
+                (or un.onInit for the uninstaller) using the INSTALLOPTIONS_EXTRACT macro. The files
+                will be extracted to a temporary folder (the NSIS plug-ins folder) that is automatically
+                created.

+            
 Function .onInit
-
-  InitPluginsDir
-  File /oname=$PLUGINSDIR\test.ini test.ini
-
+  !insertmacro INSTALLOPTIONS_EXTRACT "ioFile.ini"
 FunctionEnd
-

-
Call the DLL

-

-
You can call InstallOptions in a page function, check the
-NSIS documentation (Scripting Reference -> Pages) for
-information about the page system. Example:

-
-Page custom SetCustom ValidateCustom
 

-
The InstallOptions DLL has three functions:

-
    
-
  • dialog - Creates the dialog immediately
    • 
-
  • initDialog - Creates the dialog in memory, does not show
-it
    • 
-
  • show - Shows a dialog created in memory
    • 
-

-
Usually, you only need to use the dialog function:

-
-Function SetCustom ;FunctionName defined with Page command
-
-  ;Display the Install Options dialog
-
-  Push $R0
-
-  InstallOptions::dialog $PLUGINSDIR\test.ini
-  Pop $R0
-
+            

+                If the INI file is located in another directory, use INSTALLOPTIONS_EXTRACT_AS.
+                The second parameter is the filename in the temporary folder, which is the filename
+                that should be used as input for the other macros.

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

-
Get the input

-

-
To get the input of the user, read the State value of a Field
-using ReadINIStr:

-
-ReadINIStr $R0 "$PLUGINSDIR\test.ini" "Field 1" "State"
 

-
Note:

-
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:

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
"\\"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
+        

+        

+            Displaying the dialog

+        

+            

+                You can call InstallOptions in a page function defined with the Page or UninstPage
+                command. Check the NSIS documentation (Scripting Reference -> Pages) for information
+                about the page system.

+            
+Page custom CustomPageFunction

+            

+                To display the dialog, use the INSTALLOPTIONS_DISPLAY macro:
+Function CustomPageFunction ;Function name defined with Page command
+  !insertmacro INSTALLOPTIONS_DISPLAY "ioFile.ini"
 FunctionEnd
-
-; 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, for example, you
-want 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:

-
+

+        

+    

+    

+        User input

+    

+        

+            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"
+

+    

+    

+        Writing to INI files

+    

+        

+            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"
+

+    

+    

+        Escaped values

+    

+        

+            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:

+        
+            
+                
+                
+            
+            
+                
+                
+            
+            
+                
+                
+            
+            
+                
+                
+            
+        

+                    "\\"
+                    Back-slash

+                    "\r"
+                    Carriage return (ASCII 13)

+                    "\n"
+                    Line feed (ASCII 10)

+                    "\t"
+                    Tab (ASCII 9)

+        

+            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
+

+    

+    

+        Input validation

+    

+        

+            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
 
-  ReadINIStr $R0 "$PLUGINSDIR\test.ini" "Field 1" "State"
+  !insertmacro INSTALLOPTIONS_READ $R0 "test.ini" "Field 1" "State"
   StrCmp $R0 "" 0 +3
     MessageBox MB_ICONEXCLAMATION|MB_OK "Please enter your name."
     Abort
 
 FunctionEnd
-

-
Return value

-

-
After you have called the DLL, InstallOptions adds one string to
-the stack, with one of the following values:

-
    
-
  • 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.
    • 
-

-
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).

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

-

-

-
Reserve files

-

-
If you are using BZIP2 (solid) compression, it's important that
-files which are being extracted in init- or page functions function
-are located before other files in the data block, because this will
-make your installer faster.

-
If there are File commands in your sections or functions above
-the init- or page functions, add ReserveFile commands above your
-sections and functions:

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

-
Fonts and colors

-

-
If you want to use custom fonts or colors on your InstallOptions
-dialogs, you should use the initDialog and show functions.
-initDialog creates the dialog in memory, but does not show it.
-After calling initDialog, you can set the fonts and colors, and
-call show to show the dialog. initDialog 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:

-
+

+    

+    

+        Return value

+    

+        After a dialog is created (using display or show), a return value is available:

+        
    
+            
  • 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.

+    

+    

+        Reserve files

+    

+        

+            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"
+

+    

+    

+        Fonts and colors

+    

+        

+            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
 
-  ;Display the Install Options dialog
-
-  Push $R0
-  Push $R1
-  Push $R2
-
-    InstallOptions::initDialog /NOUNLOAD $PLUGINSDIR\test.ini
-    Pop $R0
-
-    ReadINIStr $R1 $PLUGINSDIR\test.ini "Field 1" "HWND"
-
-    ;$R1 contains the HWND of the first field
-    CreateFont $R2 "Tahoma" 10 700
-    SendMessage $R1 ${WM_SETFONT} $R2 0
-
-    InstallOptions::show
-    Pop $R0
-
-  Pop $R2
-  Pop $R1
-  Pop $R0
+  !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
-

-
Version history

-

-
    
-
  • DLL version 2.47 (April 27th, 2007)
-
      
-
    • Line breaks support in Link control
      • 
-
    • Added HLine and VLine controls
      • 
-
    
-
    • 
-

-
Complete version history

-

-
Credits

-

-
Original version by Michael Bishop

-DLL version by Nullsoft, Inc.

-DLL version 2 by Amir Szekely, ORTIM, Joost Verburg

-New documentation by Joost Verburg

-

-
License

-

-
+

+    

+    

+        Credits

+    

+        

+            Original version by Michael Bishop

+            DLL version by Nullsoft, Inc.

+            DLL version 2 by Amir Szekely, ORTIM, Joost Verburg

+            New documentation by Joost Verburg

+    

+    

+        License

+    

+        
 Original version Copyright © 2001 Michael Bishop
 DLL version 1 Copyright © 2001-2002 Nullsoft, Inc., ORTIM
 DLL version 2 Copyright © 2003-2007 Amir Szekely, Joost Verburg, Dave Laundon
@@ -892,10 +900,8 @@ it freely, subject to the following restrictions:
 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.
-

-
-

+
+
+
diff --git a/Contrib/InstallOptions/SConscript b/Contrib/InstallOptions/SConscript index b0626120..7923d511 100644 --- a/Contrib/InstallOptions/SConscript +++ b/Contrib/InstallOptions/SConscript @@ -33,6 +33,11 @@ docs = Split(""" Readme.html """) -Import('BuildPlugin') +includes = Split(""" + InstallOptions.nsh +""") + +Import('BuildPlugin env') BuildPlugin(target, files, libs, examples, docs, res = resources) +env.DistributeInclude(includes)