dfd8dc1227
git-svn-id: https://svn.code.sf.net/p/nsis/code/NSIS/trunk@3831 212acab6-be3b-0410-9dea-997c60f758d6
879 lines
29 KiB
HTML
879 lines
29 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>InstallOptions 2</title>
|
|
<meta http-equiv="Content-Type" content=
|
|
"text/html; charset=us-ascii" />
|
|
<style type="text/css">
|
|
/*<![CDATA[*/
|
|
|
|
body
|
|
{
|
|
padding: 10px;
|
|
background-color: #F0F0F0;
|
|
font-family: Verdana, Arial, Helvetica, sans-serif;
|
|
font-size: 13px;
|
|
font-weight: normal;
|
|
text-align: left;
|
|
}
|
|
|
|
p, li
|
|
{
|
|
font-size: 13px;
|
|
}
|
|
|
|
.center
|
|
{
|
|
text-align: center;
|
|
}
|
|
|
|
table
|
|
{
|
|
margin: auto;
|
|
font-size: 13px;
|
|
background-color: #FFFFFF;
|
|
}
|
|
|
|
.maintable
|
|
{
|
|
border: 2px solid #376EAB;
|
|
}
|
|
|
|
.parameter
|
|
{
|
|
font-weight: bold;
|
|
color: #6586AC;
|
|
}
|
|
|
|
|
|
h1
|
|
{
|
|
font-size: 30px;
|
|
color: #333333;
|
|
font-weight: normal;
|
|
text-align: center;
|
|
margin-top: 20px;
|
|
}
|
|
|
|
h2
|
|
{
|
|
font-size: 20px;
|
|
color: #7A7272;
|
|
font-weight: normal;
|
|
}
|
|
|
|
h3
|
|
{
|
|
font-size: 17px;
|
|
font-weight: bold;
|
|
color: #303030;
|
|
}
|
|
|
|
pre {
|
|
font-size: 13px;
|
|
}
|
|
|
|
div
|
|
{
|
|
margin: 20px;
|
|
}
|
|
|
|
a:link, a:visited, a:active
|
|
{
|
|
color: #294F75;
|
|
text-decoration: none;
|
|
}
|
|
|
|
a:hover
|
|
{
|
|
color: #182634;
|
|
text-decoration: underline;
|
|
}
|
|
|
|
.subtable
|
|
{
|
|
border: 0px;
|
|
margin-left: 20px;
|
|
margin-right: 20px;
|
|
}
|
|
|
|
.lefttable
|
|
{
|
|
background-color: #CCCCCC;
|
|
vertical-align: top;
|
|
}
|
|
|
|
.righttable
|
|
{
|
|
background-color: #EEEEEE;
|
|
vertical-align: top;
|
|
}
|
|
|
|
/*]]>*/
|
|
</style>
|
|
</head>
|
|
<body>
|
|
<table width="750" class="maintable" cellspacing="0" cellpadding=
|
|
"0" align="center">
|
|
<tr>
|
|
<td>
|
|
<h1>InstallOptions 2</h1>
|
|
<div>
|
|
<h2>Introduction</h2>
|
|
<div>
|
|
<p>InstallOptions is a NSIS plugin which allows you to create
|
|
custom pages for NSIS installers, to prompt the user for extra
|
|
information.</p>
|
|
<p>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.</p>
|
|
<p>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.</p>
|
|
<p>This new version of InstallOptions has been designed for NSIS 2.
|
|
It supports customized user interfaces and custom font and DPI
|
|
settings.</p>
|
|
</div>
|
|
<h2>INI File</h2>
|
|
<div>
|
|
<p>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.</p>
|
|
<p>The required section is named "<em>Settings</em>". It can
|
|
contain the following values:</p>
|
|
<table class="subtable">
|
|
<tr>
|
|
<td class="lefttable"><strong>NumFields</strong></td>
|
|
<td class="lefttable"><em>(required)</em></td>
|
|
<td class="righttable">The number of control elements to be
|
|
displayed on the dialog window.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>Title</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">If specified, gives the text to set the
|
|
titlebar to. Otherwise, the titlebar text is not changed.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>CancelEnabled</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>CancelShow</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>BackEnabled</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>CancelButtonText</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">Overrides the text for the cancel button. If
|
|
not specified, the cancel button text will not be changed.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>NextButtonText</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">Overrides the text for the next button. If
|
|
not specified, the next button text will not be changed.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>BackButtonText</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">Overrides the text for the back button. If
|
|
not specified, the back button text will not be changed.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>Rect</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">Overrides the default rect ID to run over.
|
|
This will make IO resize itself according to a different rect than
|
|
NSIS's dialogs rect.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>RTL</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>State</strong></td>
|
|
<td class="lefttable"><em>(output)</em></td>
|
|
<td class="righttable">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.</td>
|
|
</tr>
|
|
</table>
|
|
<p>Each field section has the heading "Field #" where # must be
|
|
sequential numbers from 1 to NumFields. Each Field section can
|
|
contain the following values:</p>
|
|
<table class="subtable">
|
|
<tr>
|
|
<td class="lefttable"><strong>Type</strong></td>
|
|
<td class="lefttable"><em>(required)</em></td>
|
|
<td class="righttable">Type of control to be created. Valid values
|
|
are "<em>Label</em>", "<em>Text</em>", "<em>Password</em>",
|
|
"<em>Combobox</em>", "<em>DropList</em>", "<em>Listbox</em>",
|
|
"<em>CheckBox</em>", "<em>RadioButton</em>",
|
|
"<em>FileRequest</em>", "<em>DirRequest</em>" "<em>Icon</em>",
|
|
"<em>Bitmap</em>", "<em>GroupBox</em>", "<em>Link</em>" or
|
|
"<em>Button</em>".<br />
|
|
<br />
|
|
A "<em>Label</em>" is used to display static text. (i.e. a caption
|
|
for a textbox)<br />
|
|
A "<em>Text</em>" and "<em>Password</em>" accept text input from
|
|
the user. "<em>Password</em>" masks the input with *
|
|
characters.<br />
|
|
A "<em>Combobox</em>" allows the user to type text not in the popup
|
|
list, a "<em>Droplist</em>" only allows selection of items in the
|
|
list.<br />
|
|
A "<em>Listbox</em>" shows multiple items and can optionally allow
|
|
the user to select more than one item.<br />
|
|
A "<em>CheckBox</em>" control displays a check box with
|
|
label.<br />
|
|
A "<em>RadioButton</em>" control displays a radio button with
|
|
label.<br />
|
|
A "<em>FileRequest</em>" 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.<br />
|
|
A "<em>DirRequest</em>" 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.<br />
|
|
An "<em>Icon</em>" control displays an icon. Use no Text to use the
|
|
installer icon.<br />
|
|
A "<em>Bitmap</em>" control displays a bitmap.<br />
|
|
A "<em>GroupBox</em>" control displays a frame to group
|
|
controls.<br />
|
|
A "<em>Link</em>" control displays a static hot text. When the user
|
|
clicks the control the contents of <strong>State</strong> (e.g.
|
|
http://...) will be executed using ShellExecute. Alternatively
|
|
<strong>State</strong> can be omitted and the <em>NOTIFY</em> flag
|
|
used to have your NSIS script called. See the "<em>NOTIFY</em>"
|
|
flag below for more information.<br />
|
|
A "<em>Button</em>" control displays a push button that can be used
|
|
in the same way as the "<em>Link</em>" control above.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>Text</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">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.<br />
|
|
<br />
|
|
<strong>Note:</strong> 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 <a href=
|
|
"#escaping">below</a> are NSIS functions for converting text
|
|
to/from this format.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>State</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">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).<br />
|
|
<br />
|
|
<strong>Note:</strong> 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
|
|
<a href="#escaping">below</a> are NSIS functions for converting
|
|
text to/from this format.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>ListItems</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">A list of items to display in a combobox,
|
|
droplist, or listbox.<br />
|
|
This is a single line of text with each item separated by a pipe
|
|
character '|'</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>MaxLen</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">Causes validation on the selected control to
|
|
limit the maximum length of text.<br />
|
|
If the user specifies more text than this, a message box will
|
|
appear when they click "OK" and the dialog will not be
|
|
dismissed.<br />
|
|
You should not use this on a "<em>combobox</em>" since the user can
|
|
not control what is selected.<br />
|
|
This should be set to a maximum of 260 for "<em>FileRequest</em>"
|
|
and "<em>DirRequest</em>" controls.<br />
|
|
Ignored on "<em>Label</em>" controls.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>MinLen</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">Causes validation on the selected control to
|
|
force the user to enter a minimum amount of text.<br />
|
|
If the user specifies less text than this, a message box will
|
|
appear when they click "OK" and the dialog will not be
|
|
dismissed.<br />
|
|
Unlike MaxLen, this is useful for "<em>Combobox</em>" controls. By
|
|
setting this to a value of "1" the program will force the user to
|
|
select an item.<br />
|
|
Ignored on "<em>Label</em>" controls.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>ValidateText</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">If the field fails the test for
|
|
"<em>MinLen</em>" or "<em>MaxLen</em>", a messagebox will be
|
|
displayed with this text.<br />
|
|
<br />
|
|
<strong>Note:</strong> \r\n will be converted to a newline, two
|
|
back-slashes will be converted to one - \\. Described <a href=
|
|
"#escaping">below</a> are NSIS functions for converting text
|
|
to/from this format.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>Left<br />
|
|
Right<br />
|
|
Top<br />
|
|
Bottom</strong></td>
|
|
<td class="lefttable"><em>(required)</em></td>
|
|
<td class="righttable">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.<br />
|
|
<br />
|
|
<strong>Note:</strong> You can specify negative coordinates to
|
|
specify the distance from the right or bottom edge.<br />
|
|
<br />
|
|
<strong>Note (2):</strong> For combobox or droplist, the
|
|
"<em>bottom</em>" value is not used in the same way.<br />
|
|
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.<br />
|
|
<br />
|
|
<strong>Note (3):</strong> 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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>Filter</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">Specifies the filter to be used in the
|
|
"<em>FileRequest</em>" control.<br />
|
|
This is constructed by putting pairs of entries together, each item
|
|
separated by a | character.<br />
|
|
The first value in each pair is the text to display for the
|
|
filter.<br />
|
|
The second value is the pattern to use to match files.<br />
|
|
For example, you might specify:<br />
|
|
Filter=Text Files|*.txt|Programs|*.exe;*.com|All Files|*.*<br />
|
|
If not specified, then the filter defaults to All Files|*.*<br />
|
|
<br />
|
|
<strong>Note:</strong> you should not put any extra spaces around
|
|
the | characters.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>Root</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">Used by <strong>DirRequest</strong> 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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>Flags</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">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.<br />
|
|
<table class="righttable">
|
|
<tr>
|
|
<td class="righttable"><strong>Value</strong></td>
|
|
<td class="righttable"><strong>Meaning</strong></td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">REQ_SAVE</td>
|
|
<td class="righttable">This causes "<em>FileRequest</em>" controls
|
|
to display a Save As dialog. If not specified, an Open dialog is
|
|
used.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">FILE_MUST_EXIST</td>
|
|
<td class="righttable">Used by "<em>FileRequest</em>" to determine
|
|
if the selected file must exist.<br />
|
|
This only applies if an "Open" dialog is being displayed.<br />
|
|
This currently does not force the file to exist other than through
|
|
the browse button.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">FILE_EXPLORER</td>
|
|
<td class="righttable">Used by "<em>FileRequest</em>", enables new
|
|
file request look (recommended)</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">FILE_HIDEREADONLY</td>
|
|
<td class="righttable">Used by "<em>FileRequest</em>", hides "open
|
|
read only" checkbox in open dialog.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">WARN_IF_EXIST</td>
|
|
<td class="righttable">Used by "<em>FileRequest</em>" to display a
|
|
warning message if the selected file already exists.<br />
|
|
The warning message is only displayed for files selected with the
|
|
browse button.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">PATH_MUST_EXIST</td>
|
|
<td class="righttable">Used by "<em>FileRequest</em>" to force the
|
|
path to exist. Prevents the user from typing a non-existent path
|
|
into the browse dialog window.<br />
|
|
This only validates path's selected with the browse button.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">PROMPT_CREATE</td>
|
|
<td class="righttable">Used by "<em>FileRequest</em>" to display a
|
|
warning if the selected file does not exist. However, it still
|
|
allows the user to select the file.<br />
|
|
This only displays the warning for files selected with the browse
|
|
button.<br />
|
|
Doesn't work along with REQ_SAVE.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">RIGHT</td>
|
|
<td class="righttable">Used by "<em>Checkbox</em>" and
|
|
"<em>Radiobutton</em>" controls to specify you want the checkbox to
|
|
the right of the text instead of the left as is the default.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">MULTISELECT</td>
|
|
<td class="righttable">Used by "<em>Listbox</em>" 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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">EXTENDEDSELCT</td>
|
|
<td class="righttable">Used by "<em>Listbox</em>" 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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">RESIZETOFIT</td>
|
|
<td class="righttable">This causes "<em>Bitmap</em>" 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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">GROUP</td>
|
|
<td class="righttable">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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">NOTABSTOP</td>
|
|
<td class="righttable">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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">DISABLED</td>
|
|
<td class="righttable">Causes a control to be disabled.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">ONLY_NUMBERS</td>
|
|
<td class="righttable">Used by "<em>Text</em>" controls. Forces the
|
|
user to enter only numbers into the edit box.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">MULTILINE</td>
|
|
<td class="righttable">Used by "<em>Text</em>" controls. Causes the
|
|
control to accept multiple-lines.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">WANTRETURN</td>
|
|
<td class="righttable">Used by "<em>Text</em>" 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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">NOWORDWRAP</td>
|
|
<td class="righttable">Used by "<em>Text</em>" 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.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">HSCROLL</td>
|
|
<td class="righttable">Show a horizontal scrollbar. When used by
|
|
"<em>Text</em>" controls with multiple-lines this also disables
|
|
word-wrap.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">VSCROLL</td>
|
|
<td class="righttable">Show a vertical scrollbar.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">READONLY</td>
|
|
<td class="righttable">Used by "<em>Text</em>" controls. Prevents
|
|
the user from entering or editing text in the edit control, but
|
|
allow the user to select and copy the text.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="righttable">NOTIFY</td>
|
|
<td class="righttable">Used by "<em>Button</em>", "<em>Link</em>",
|
|
"<em>CheckBox</em>", "<em>RadioButton</em>", "<em>ListBox</em>" and
|
|
"<em>DropList</em>" 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
|
|
"<em>State</em>" value from the "<em>Settings</em>" 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 Contrib\InstallOptions
|
|
folder contains an example script showing how this might be
|
|
used.</td>
|
|
</tr>
|
|
</table>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable"><strong>TxtColor</strong></td>
|
|
<td class="lefttable"><em>(optional)</em></td>
|
|
<td class="righttable">Used by <strong>Link</strong> controls to
|
|
specify the foreground color of the text. Format: 0xBBRRGG
|
|
(hexadecimal).</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
<h2>How to use</h2>
|
|
<div>
|
|
<h3>Modern UI</h3>
|
|
<div>
|
|
<p>For information about using InstallOptions with the Modern UI,
|
|
have a look at the <a href=
|
|
"../Modern%20UI/Readme.html#customPages">Modern UI
|
|
documentation</a>.</p>
|
|
</div>
|
|
<h3>Extract the INI File</h3>
|
|
<div>
|
|
<p>First, you have to extract the INI files for the dialogs in the
|
|
.onInit function:</p>
|
|
<pre>
|
|
Function .onInit
|
|
|
|
InitPluginsDir
|
|
File /oname=$PLUGINSDIR\test.ini test.ini
|
|
|
|
FunctionEnd
|
|
</pre></div>
|
|
<h3>Call the DLL</h3>
|
|
<div>
|
|
<p>You can call InstallOptions in a page function, check the
|
|
<a href="../../Docs/Chapter4.html#4.5">NSIS documentation</a> for
|
|
information about the page system. Example:</p>
|
|
<pre>
|
|
Page custom SetCustom ValidateCustom
|
|
</pre>
|
|
<p>The InstallOptions DLL has three functions:</p>
|
|
<ul>
|
|
<li>dialog - Creates the dialog immediately</li>
|
|
<li>initDialog - Creates the dialog in memory, does not show
|
|
it</li>
|
|
<li>show - Shows a dialog created in memory</li>
|
|
</ul>
|
|
<p>Usually, you only need to use the dialog function:</p>
|
|
<pre>
|
|
Function SetCustom ;FunctionName defined with Page command
|
|
|
|
;Display the Install Options dialog
|
|
|
|
Push $R0
|
|
|
|
InstallOptions::dialog $PLUGINSDIR\test.ini
|
|
Pop $R0
|
|
|
|
FunctionEnd
|
|
</pre></div>
|
|
<h3>Get the input</h3>
|
|
<div>
|
|
<p>To get the input of the user, read the State value of a Field
|
|
using ReadINIStr:</p>
|
|
<pre>
|
|
ReadINIStr $R0 "$PLUGINSDIR\test.ini" "Field 1" "State"
|
|
</pre>
|
|
<p><a name="escaping" id="escaping"></a><strong>Note:</strong></p>
|
|
<p>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:</p>
|
|
<ul>
|
|
<li>The ValidateText field</li>
|
|
<li>The Text value of Label fields</li>
|
|
<li>The State value of Text fields that have the MULTILINE
|
|
flag</li>
|
|
</ul>
|
|
<p>The escape character is the back-slash character ("\") and the
|
|
available escape sequences are:</p>
|
|
<table class="subtable">
|
|
<tr>
|
|
<td class="lefttable">"\\"</td>
|
|
<td class="righttable">Back-slash</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable">"\r"</td>
|
|
<td class="righttable">Carriage return (ASCII 13)</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable">"\n"</td>
|
|
<td class="righttable">Line feed (ASCII 10)</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="lefttable">"\t"</td>
|
|
<td class="righttable">Tab (ASCII 9)</td>
|
|
</tr>
|
|
</table>
|
|
<p>The following functions can be used to convert a string to and
|
|
from this format:</p>
|
|
<pre>
|
|
; 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
|
|
|
|
; 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
|
|
</pre></div>
|
|
<h3>Validate the input</h3>
|
|
<div>
|
|
<p>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:</p>
|
|
<pre>
|
|
Function ValidateCustom
|
|
|
|
ReadINIStr $R0 "$PLUGINSDIR\test.ini" "Field 1" "State"
|
|
StrCmp $R0 "" 0 +3
|
|
MessageBox MB_ICONEXCLAMATION|MB_OK "Please enter your name."
|
|
Abort
|
|
|
|
FunctionEnd
|
|
</pre></div>
|
|
<h3>Return value</h3>
|
|
<div>
|
|
<p>After you have called the DLL, InstallOptions adds one string to
|
|
the stack, with one of the following values:</p>
|
|
<ul>
|
|
<li>success - The user has pressed the Next button</li>
|
|
<li>back - The user has pressed the Back button</li>
|
|
<li>cancel - The user has pressed the Cancel button</li>
|
|
<li>error - An error has occurred, the dialog cannot be
|
|
displayed.</li>
|
|
</ul>
|
|
<p>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).</p>
|
|
<p>You only have to check this value if you need something really
|
|
special, such as doing something when the user pressed the Back
|
|
button.</p>
|
|
</div>
|
|
</div>
|
|
<h2>Reserve files</h2>
|
|
<div>
|
|
<p>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.</p>
|
|
<p>If there are File commands in your sections or functions above
|
|
the init- or page functions, add ReserveFile commands above your
|
|
sections and functions:</p>
|
|
<pre>
|
|
ReserveFile "test.ini"
|
|
ReserveFile "${NSISDIR}\Plugins\InstallOptions.dll"
|
|
</pre></div>
|
|
<h2>Fonts and colors</h2>
|
|
<div>
|
|
<p>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. To get the HWND of the controls
|
|
use:</p>
|
|
<pre>
|
|
GetDlgItem (output var) (hwnd of the custom dialog) (1200 + Field number - 1)
|
|
</pre>
|
|
<p>Example of using a custom font:</p>
|
|
<pre>
|
|
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
|
|
|
|
GetDlgItem $R1 $R0 1200 ;1200 + Field number - 1
|
|
|
|
;$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
|
|
|
|
FunctionEnd
|
|
</pre></div>
|
|
<h2>Version history</h2>
|
|
<div>
|
|
<ul>
|
|
<li>DLL version 2.41 (5/8/2004)
|
|
<ul>
|
|
<li>Bitmaps are now automatically centered</li>
|
|
<li>Fixed a bug which prevented enabling the next button from</li>
|
|
the leave function of InstallOptions pages
|
|
<li>Fixed a rare freeze</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p><a href="Changelog.txt">Complete version history</a></p>
|
|
</div>
|
|
<h2>Credits</h2>
|
|
<div>
|
|
<p>Original version by Michael Bishop<br />
|
|
DLL version by Nullsoft, Inc.<br />
|
|
DLL version 2 by Amir Szekely, ORTIM, Joost Verburg<br />
|
|
New documentation by Joost Verburg</p>
|
|
</div>
|
|
<h2>License</h2>
|
|
<div>
|
|
<pre>
|
|
Original version Copyright © 2001 Michael Bishop
|
|
DLL version 1 Copyright © 2001-2002 Nullsoft, Inc., ORTIM
|
|
DLL version 2 Copyright © 2003-2005 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.
|
|
</pre></div>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|