Using the new NSIS 2 plugin system, you don't have to worry about extracting and removing -the DLL anymore. You can also use the Plugins directory to store the INI files. The contents -of the directory will be removed when the installer is being closed. - -Example:
- ;Extract INI File to Plugins directory - InitPluginsDir - File /oname=$PLUGINSDIR\test.ini test.ini - - InstallOptions::dialog $PLUGINSDIR\test.ini - Pop $0 - ; ($0 would be "success" "cancel" "back" or some other value on error) - - ReadINIStr $1 $R0 "Field 1" State ; $1 = Field #1's state --It is often very useful to call InstallOptions from a NSIS custom page callback function. -
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 will 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. Recommended value: "Cancel" |
| NextButtonText | -(optional) | -Overrides the text for the next button. If not specified, the next button text will not be changed. Recommended value: "Next >" |
| BackButtonText | -(optional) | -Overrides the text for the back button. If not specified, the back button text will not be changed. Recommended value: "< Back" |
| 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. |
Each field section has the heading "Field #" where # must be sequential -numbers from 1 to NumFields. Each Field section contains the following values: -
| Type | -(required) | -Type of control to be created. Valid
- values are "Label", "Text", "Password",
- "Combobox", "DropList", "Listbox", "CheckBox",
- "RadioButton",
- "FileRequest", or "DirRequest". A - "label" is used to display static text. (i.e. a caption for a - textbox) A "textbox" 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. - "Icon" control displays an icon. Use no Text to use the installer icon. - "Bitmap" control displays a bitmap. | ||||||||||||||||||||
| Text | -(optional) | -Specifies the caption of a label, checkbox, or radio button control. - For icon and bitmaps control this specifies the path to the image. - | ||||||||||||||||||||
| 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). - | ||||||||||||||||||||
| 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 a particular field fails the test for
- "MinLen" or "MaxLen", a messagebox will be displayed with
- this text. NOTE: The only formatting performed on this - text is "\n" will be replaced with a newline in the - messagebox. | ||||||||||||||||||||
| Left Right Top Bottom |
- (required) | -The position on the dialog where this
- control appears. Sorry, no GUI here to help you. NOTE: 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 szed 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. NOTE (2): - FileRequest and DirRequest controls will allocate 20 pixels to the - browse button. Make this control wide enough the contents of the textbox - can be seen. Note that you can specify negative coordinates to specify the - distance from the right or bottom edge. | ||||||||||||||||||||
| Filter | -(optional) | -Specifies the filter to be used in the
- "FileRequest" control. This is constructed by putting pairs of - entries together, each item seperated 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: -
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 seperated by a |
- character, and you should be careful not to put any spaces around the |
- character. -
|
InstallOptions supports the new UI enhancements in the new NSIS 2. To support them,
-InstallOptions now has two new functions, initDialog, and show.
-The first creates the dialog but doesn't show it. It pushes the HWND of the custom dialog to the stack.
-To get the HWND of any of the controls use:
-
GetDlgItem (output var) (hwnd of the custom dialog) (1200 + field number - 1)-To finally show the tweaked dialog use the show function. - -Here is a little example: -
- # we don't want the DLL to unload so it will remember
- # our ini file when we are trying to show it
- InstallOptions::initDialog /NOUNLOAD file.ini
- Pop $0
- IntCmp $0 0 error
- ; $0 is now the IO dialog HWND
- ; use getdlgitem with it and sendmessage
- GetDlgItem $1 $0 1200 ; 1200 + field number - 1
- ; $1 is now the HWND of the first field
- CreateFont $2 "Tahoma" 10 700
- SendMessage $1 ${WM_SETFONT} $2 0
- InstallOptions::show
- Pop $0
- StrCmp $0 "success" done
- StrCmp $0 "back" done
- StrCmp $0 "cancel" done
- error:
- MessageBox MB_OK|MB_ICONSTOP "IO error: $0"
- Quit
- done:
--
Copyright © 2001 Michael Bishop - Portions Copyright © 2001 Nullsoft, Inc. - - 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 source 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 source distribution. -diff --git a/Contrib/InstallOptions/Readme.html b/Contrib/InstallOptions/Readme.html new file mode 100644 index 00000000..2e220278 --- /dev/null +++ b/Contrib/InstallOptions/Readme.html @@ -0,0 +1,523 @@ + + + + +
+
|