InstallOptions and InstallOptionsEx are NSIS plugins which allow you to create custom pages for
NSIS installers, to prompt the user for extra information. InstallOptionsEx is an expanded version of
InstallOptions containing many new features, with size drawback. As it is not in the main distribution,
InstallOptionsEx aims for experiments towards new GUI features in order to achieve long term goals that
InstallOptions couldn't achive.
InstallOptionsEx creates dialogs that can be displayed inside the NSIS
window. The controls inside the dialog are translated from a resource file - a file with .ini
extention with contents conforming standards from this documentation.
NSIS 2 has a new standard page system which allows the plugin to add custom pages to your installer
without being bothered by complex "next" and "previous" page functions from the previous NSIS version.
It has also a newer and improved plugin system allowing automatic extraction and plugin deletion
when a plugin is used. The temporary plugins folder, used by default by this plugin, is deleted automatically -
resource files can be stored there for automatic deletion as you wish.
This version of InstallOptionsEx has been designed for NSIS 2, thus supporting
customized user interfaces and custom font and DPI settings.
This documentation uses the "expand and collapse" effect. This makes information to be easily
organized and accessed by only showing revelant items in a category. Clicking in a category name will open
up or close down greater details towards the category. It is also possible to click on "Collapse All", "Expand All" and
"Invert All" links located in the top of this document to open or close categories.
Page INI File Reference
This category contains the complete resource file reference. For greater readibility for those
who used InstallOptions priorily, the reference uses colors representing the changes between InstallOptionsEx
and InstallOptions, as stated below:
The resource file structure needs to conform with the basic Windows Registry
file format for the proper translation, as shown below:
This section configures both the dialog and the window as a whole. The following are
the keys supported by this section:
NumFields
Specifies the control type. One of the following can be used to determine
a control type:
Controls in that section are organized as follows, from the simplest
control to the most complex:
- Controls that don't receive any focus at all. (Label -> VLine)
- Controls that receive mostly mouse focus. (Link -> UpDown)
- Controls that State text can be edited manually. (Text -> RichText)
- Controls that contain a customizable list of items. (DropList -> TreeView)
- Controls that contain a non-customizable list of items. (TrackBar -> MonthCalendar)
Label
Used to display static text.
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
GroupBox
Displays a frame to group controls.
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
Image
Can display the following:
an icon file (.ico);
a cursor file (.cur);
an animated cursor file (.ani);
an icon from an executable file (.exe);
an icon from a dll file (.dll);
a bitmap file (.bmp);
an Audio Video Interleave file without sound with no or with run-length of 8 bits (BI_RLE8) encoding compression (.avi).
a Graphics Interchange Format file (uses OLE) (.gif);
a Joint Photographic Experts Group file (uses OLE) (.jpg, .jpeg);
The plugin will always try to use the best image appearance for the user's display.
Supported by: InstallOptionsEx 2.4.2 beta 5
Icon
Integrated with Image controls but still supported for compatibility.
Supported by: InstallOptions 1.4 beta, InstallOptionsEx 2.4.1 beta 1 - 2.4.2 beta 4
Bitmap
Integrated with Image controls but still supported for compatibility.
Supported by: InstallOptions 1.4 beta, InstallOptionsEx 2.4.1 beta 1 - 2.4.2 beta 4
Animation
Integrated with Image controls but still supported for compatibility.
Supported by: InstallOptionsEx 2.4.1 beta 1 - 2.4.2 beta 4
ProgressBar
Displays a bar that shows progress. To make use of the ability to show progress, use
the TimeOut INI key for Settings INI section.
Supported by: InstallOptionsEx 2.4.1 beta 1
HLine
Displays a horizontal line to separate controls.
Supported by: InstallOptions 2.47, InstallOptionsEx 2.4.5 beta 2
VLine
Displays a vertical line to separate controls.
Supported by: InstallOptions 2.47, InstallOptionsEx 2.4.5 beta 2
Link
Displays a static hot text that, when the mouse is passed over its area,
the mouse cursor turns into a hand.
Supported by: InstallOptions 2.2, InstallOptionsEx 2.4.1 beta 1
CheckBox
Displays a check box with label.
Supported by: InstallOptions 1.3, InstallOptionsEx 2.4.1 beta 1
RadioButton
Displays a radio button with label.
Supported by: InstallOptions 1.3, InstallOptionsEx 2.4.1 beta 1
Button
Displays a push button that can be used in the same way as the "Link" control above.
Supported by: InstallOptions 2.3, InstallOptionsEx 2.4.1 beta 1
UpDown
Displays a pair of arrow buttons used to increment or decrement a number
in a Text, Password, RichText or ComboBox buddy controls,
to change the selection upwards or downwards of a ListBox control,
or to be used alone (without the user knowing what number the user selected).
Supported by: InstallOptionsEx 2.4.1 beta 4
Text
Accepts text input from the user.
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
Password
Accepts password input from the user. The input is masked with asterisk "*" characters by default.
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
IPAddress
Displays an edit box used specially for IP address input.
Supported by: InstallOptionsEx 2.4.1 beta 2
FileRequest
Use Text and Button controls instead.
Supported by: InstallOptions 1.2, InstallOptionsEx 2.4.1 beta 1-4 only
DirRequest
Use Text and Button controls instead.
Supported by: InstallOptions 1.2, InstallOptionsEx 2.4.1 beta 1-4 only
RichText
Displays an edit box with the contents of a file specified and with advanced editor options.
This control supports the following types of files:
a text file (.txt);
a rich text file (.rtf).
The following versions of this control are used by this plug-in:
2.0 - (Recommended) Included in all Windows versions except Windows 95. Compatible in all versions of Windows.
1.0 - Included in all Windows versions except Windows 2000, and XP.
Notes:
Supported by: InstallOptionsEx 2.4.2 beta 5
DropList
Only allows selection of items in the list.
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
ComboBox
Allows the user to select a item in the pop up list and to type text not in there.
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
DateTime
Displays a combobox where the user can pick or select a date or time
he/she wants.
Supported by: InstallOptionsEx 2.4.1 beta 3
ListBox
Shows multiple items and can optionally allow the user to select more than one item.
Supported by: InstallOptions 1.4, InstallOptionsEx 2.4.1 beta 1
ListView
Shows a linear list of items. Each item consists of a
label, optional 16x16px and 32x32px images. Images are respectively from
SmallImageList and LargeImageList keys.
Supported by: InstallOptionsEx 2.4.2 beta 3
TreeView
Shows a hierarchical list of items. Each item consists of a
label, and each item can have a list of subitems associated with it. By
clicking an item, the user can expand or collapse the associated list of
subitems.
Supported by: InstallOptionsEx 2.4.2 beta 1
TrackBar
Displays a bar where the user can select with the slider one of the
options indicated by ticks. It doesn't include labels.
Supported by: InstallOptionsEx 2.4.1 beta 2
MonthCalendar
Displays a month calendar where the user can select a date he/she wants.
Supported by: InstallOptionsEx 2.4.1 beta 3
Default Value: None
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
Text
Generally specifies control caption, but this can depend on the control type:
Label
Specifies the control caption.
Default Value: None
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
Image
Specifies the path to the image. The type of image will be determined by its
file extension, as described in Type key for Field # section.
Default Value: None
Supported by: InstallOptionsEx 2.4.2 beta 5
CheckBox/RadioButton
Specifies the control caption.
Default Value: None
Supported by: InstallOptions 1.3, InstallOptionsEx 2.4.1 beta 1
Button
Specifies control's text. If ICON or BITMAP flags are
associated with a button control, this specifies the path where the icon or
bitmap is.
For InstallOptions and InstallOptionsEx 2.4.1 beta 1 only:
This only specifies control's text.
Default Value: None
Supported by: InstallOptions 2.3, InstallOptionsEx 2.4.1 beta 1
Text/Password/RichText
When the PASSWORD flag is specified, except for Password controls, this
specifies the password mask character. The displayed control characters are immediately
hidden by the character specified.
Default Value: *
Supported by: InstallOptionsEx 2.4.1 beta 10
DateTime
Specifies the format to show the State value. The format basic explanation
can be found on the Regional and Language Options on
Control Panel.
Default Value: Date format
specified by the user in the Regional and Language Options from
Control Panel. Example: dd/MM/yyyy.
Supported by: InstallOptionsEx 2.4.1 beta 3
ListBox
Specifies the width of the vertical columns inside the control in
pixels. Specifying 0 makes the control to have only one column occupying
the entire control.
Default Value: 0 (1 column occupying entire control).
Supported by: InstallOptionsEx 2.4.1 beta 13
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
State
If the image is an icon from an executable or dll file, this specifies the
icon index number of the desired icon inside the executable or dll file. 0 or an empty
value means that the first icon inside the file will be used.
If the image is an animation, this specifies the number of times the animation
is repeated from the MinLen to the MaxLen value point.
If more than 0, the animation will repeat that number of times. If 0, the
animation doesn't get played when the dialog is shown. If -1, the number of
loops is unlimited.
If the file indicated by Text's value doesn't exist, this specifies a flag
which determines a default icon, cursor or bitmap from the operationing system. This
can be one of the following:
Icons (32x32 pixels resources):
APPLICATION
Shows the default application icon for programs.
EXCLAMATION
Shows an icon with an exclamation mark inside a yellow triangle.
INFORMATION
Shows an icon with an exclamation mark inside a white balloon.
QUESTION
Shows an icon with a question mark inside a white balloon.
STOP
Shows an icon with the letter "X" inside a red circle.
WINLOGO
Shows a Windows icon.
For Windows XP:
Same as APPLICATION.
Cursors (32x32 pixels resources):
APPSTARTING
Shows the default cursor generally shaped like an small arrow pointing between north/north-west
with an hourglass that appears when an application in the background is occupied.
ARROW
Shows the default cursor generally shaped like an arrow pointing between north/north-west
for usual use.
CROSS
Shows the default cursor generally shaped like a cross and used by some graphic programs
to select a group of pixels more accuratelly than using the default cursor.
HAND
Shows the default cursor generally shaped like a hand with a finger pointing to north
and used by some applications to give more attention to the location pointed. The
plug-in always shows this cursor when the cursor is over a Link control.
HELP
Shows the default cursor generally shaped like an small arrow pointing between north/north-west
with a question mark used by some applications for giving more information about an item.
IBEAM
Shows the default cursor generally shaped like a roman numeral "I" used by
text supporting applications to distinguish the position of the cursor between 2
letters, so their selection can be easier.
NO
Shows the default cursor generally shaped like a circle with a north-west to
south-east diagonal line used by some applications to inform the user that the
cursor current position is not allowed for a determined mouse operation.
SIZEALL
Shows the default cursor generally shaped like a cross with arrow heads on all the line ends
used for moving objects from one place to another.
SIZENESW
Shows the default cursor generally shaped like a north-east to south-west diagonal line
with arrow heads on the line ends for resizing objects.
SIZENS
Shows the default cursor generally shaped like a north to south vertical line
with arrow heads on the line ends for resizing objects.
SIZENWSE
Shows the default cursor generally shaped like a north-west to south-east diagonal line
with arrow heads on the line ends for resizing objects.
SIZEWE
Shows the default cursor generally shaped like a west to east horizontal line
with arrow heads on the line ends for resizing objects.
UPARROW
Shows the default cursor generally shaped like a vertical line
with an arrow head on the top for selecting columns of stacked objects.
WAIT
Shows the default cursor generally shaped like a hourglass that appears when the
program on the foreground is occupied.
Bitmaps (resources with varied sizes):
BTNCORNERS
Shows the default bitmap that shows the corners of a button (?).
SIZE
Shows the default bitmap generally shaped like 3 south-west to north-east diagonal
lines, usually accompanied by the SIZENWSE cursor that shows that you can resize a button.
CHECK
Shows the default bitmap generally shaped like a check mark that shows that
an option is enabled or a process has been completed.
CHECKBOXES
Shows the default bitmap for the checkboxes and radiobuttons for all controls.
CLOSE
Shows the default bitmap for the default application icons in 16x16 each (?).
COMBO
Shows the default bitmap generally shaped like an arrow without its tail pointing south
that shows that an option has sub-options or a process has sub-processes.
DNARROW
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing south that is used by scroll bars or for the future ScrollBar control.
DNARROW
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing south that is used by scroll bars to allow the user to scroll down a
window or control.
DNARROWD
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing south that is used by scroll bars to allow the user to scroll down a
window or control. This shows DNARROW's pressed state.
DNARROWI
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing south that is used by scroll bars to allow the user to scroll down a
window or control. This shows DNARROW's disabled state.
LFARROW
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing left that is used by scroll bars to allow the user to scroll left a
window or control.
LFARROWD
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing left that is used by scroll bars to allow the user to scroll left a
window or control. This shows LFARROW's pressed state.
LFARROWI
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing left that is used by scroll bars to allow the user to scroll left a
window or control. This shows LFARROW's disabled state.
MNARROW
Shows the default bitmap generally shaped like an arrow without
its tail pointing right that is used to show that options or processes are going
to be completed or that show that there are sub-options or sub-processes that
are not being shown.
REDUCE
Shows the default bitmap generally shaped like a button with a small horizontal
line that is used to show the window can be minimized to the taskbar.
REDUCED
Shows the default bitmap generally shaped like a button with a small horizontal
line that is used to show the window can be minimized to the taskbar.
This shows REDUCE's pressed state.
REDUCED
Shows the default bitmap generally shaped like a button with a small horizontal
line that is used to show the window can be minimized to the taskbar.
This shows REDUCE's pressed state.
RESTORE
Shows the default bitmap generally shaped like a button with the drawing of two small
windows that is used to show the window can be restored to its original size.
RESTORED
Shows the default bitmap generally shaped like a button with the drawing of two small
windows that is used to show the window can be restored to its original size.
This shows RESTORE's pressed state.
RGARROW
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing right that is used by scroll bars to allow the user to scroll right a
window or control.
RGARROWD
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing right that is used by scroll bars to allow the user to scroll right a
window or control. This shows LFARROW's pressed state.
RGARROWI
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing right that is used by scroll bars to allow the user to scroll right a
window or control. This shows LFARROW's disabled state.
SIZE
Shows the default bitmap generally shaped like 3 south-west to north-east diagonal
lines, usually accompanied by the SIZENWSE cursor that shows that you can resize a window.
UPARROW
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing up that is used by scroll bars to allow the user to scroll up a
window or control.
UPARROWD
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing up that is used by scroll bars to allow the user to scroll up a
window or control. This shows UPARROW's pressed state.
UPARROWI
Shows the default bitmap generally shaped like a button with an arrow without
its tail pointing up that is used by scroll bars to allow the user to scroll up a
window or control. This shows UPARROW's disabled state.
ZOOM
Shows the default bitmap generally shaped like a button with the drawing of a small
window that is used to show the window can be maximized to its maximum size.
ZOOMD
Shows the default bitmap generally shaped like a button with the drawing of a small
window that is used to show the window can be maximized to its maximum size.
This shows ZOOM's pressed state.
Default Values:
If the image is of type icon from an executable or dll file: 0 (the first icon).
If the image is of type animation: -1 (unlimited animation loops).
If the file indicated by Text's value doesn't exist: Program default icon.
Supported by: InstallOptionsEx 2.4.2 beta 5
ProgressBar
Specifies something to be executed or opened. Doesn't support parameters.
If one of the flags names ended in "REQUEST" is specified, this specifies the return value for the
operation done in the dialog. This can change, depending on which "REQUEST" flag is
chosen on Flags key:
OPEN_FILEREQUEST
Specifies a file to be selected in the "Open" dialog by default. If MULTISELECT
flag is specified, files are enclosed inside double quotes (") and separated by a space
character ( ). If the dialog is canceled, the default value is the previous specified file as state.
Default Value: No file is selected, but the folder location depends on OS version.
Supported by: InstallOptionsEx 2.4.2 beta 3
SAVE_FILEREQUEST
Specifies a file to be selected in the "Save" dialog by default. If the dialog is canceled,
the default value is the previous specified file as state.
Default Value: No file is selected, but the folder location depends on OS version.
Supported by: InstallOptionsEx 2.4.2 beta 3
DIRREQUEST
Specifies the folder to select in the "Browse" dialog. If the dialog is canceled,
the default value is the previous folder specified as state.
Default Value: Desktop (same as $DESKTOP variable on NSIS).
Supported by: InstallOptionsEx 2.4.2 beta 3
COLORREQUEST
Specifies the color to appear or selected in "Color" dialog by default. Format:
0xBBRRGG (hexadecimal). If the dialog is canceled, the default value is the previous string specified as state.
Default Value: None, string is treated as black (0x000000).
Supported by: InstallOptionsEx 2.4.2 beta 3
FONTREQUEST
Specifies the font to appear or selected in "Font" dialog by default. The format
bases on the actual values of font keys and a color key, separated by
"|" characters in this order:
"FontName|FontHeight|FontBold|FontItalic|FontUnderline|FontStrikeOut|TxtColor".
If the dialog is canceled, the default value is the previous string specified as state.
Default Value: Default font (only if nothing is specified).
Supported by: InstallOptionsEx 2.4.2 beta 3
Default Value: None
Supported by: InstallOptions 2.2 (for Link), InstallOptions 2.3 (for button), InstallOptionsEx 2.4.1 beta 1
UpDown
Causes validation on the selected control to limit the maximum length of
text or options. If the user specifies more text or options than this, a
message box may appear and the dialog will not be dismissed. This specification can change
depending on control type:
Image
If the image is of type animation, this specifies the ending frame. If 0,
it is the first frame of the animation and makes it not to be played. If -1, it is the last
frame of the animation. If this is the same as specified on MinLen
INI key, it will only show that frame without playing the animation.
Default Value: -1 (Last frame of the animation).
Supported by: InstallOptionsEx 2.4.1 beta 5
ProgressBar
Specifies the maximum progress limit. Maximum is 65535.
Default Value: 100.
Supported by: InstallOptionsEx 2.4.1 beta 1
UpDown
Specifies the maximum item number. The default and real maximum values are 2147483646. The minimum value is -2147483646.
Default Value: 2147483646 (maximum value).
Supported by: InstallOptionsEx 2.4.1 beta 1
Text/Password/RichText/ComboBox
Specifies the maximum length of text. There are specific limits for different control types:
- For Text and Password controls without MULTILINE flag and ComboBox controls: 32KB of characters.
- For Text and Password controls with MULTILINE flag: 64KB of characters.
- For RichText controls: 4GB of characters.
BufferSize INI value for Settings INI section only truncates
characters when input or output operations are completed.
If the value is 0, then no text will be allowed in the control.
Default Value: Buffer size or the text limit, whichever is smaller.
Supported by: InstallOptions 1.2, InstallOptionsEx 2.4.1 beta 1
TrackBar
Specifies the maximum number of items.
Default Value: 100.
Supported by: InstallOptionsEx 2.4.1 beta 2
Default Value: None
Supported by: InstallOptions 1.2, InstallOptionsEx 2.4.1 beta 1
MinLen
Removed due to the new notification system.
For InstallOptionsEx 2.4.1 beta 5:
Causes InstallOptionsEx 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 back to the page).
For InstallOptionsEx 2.4.1 beta 4:
Supported by all controls except Label, Bitmap, Icon, GroupBox, MonthCalendar, DateTime, HotKey and UpDown controls.
For InstallOptionsEx 2.4.1 beta 3 and below:
Supported by Text, Password, IPAddress, ComboBox, DropList, ListBox, CheckBox, RadioButton, Link and Button controls.
For InstallOptionsEx 2.4.1 beta 1:
Supported by Text, Password, ComboBox, DropList, ListBox, CheckBox, RadioButton, Link and Button controls.
For InstallOptions:
Supported by DropList, ListBox, CheckBox, RadioButton, Link and Button controls.
For InstallOptions 2.3:
Supported by CheckBox, RadioButton, Button controls.
Supported by: InstallOptions 2.3, InstallOptionsEx 2.4.1 beta 1
DISABLED
Renamed to SAVE_FILEREQUEST.
Supported by: InstallOptions 1.2, InstallOptionsEx 2.4.1 beta 4
DIRREQUEST
Makes the control to display a common dialog requiring a directory for input.
Required: A Notify key flag.
Supported by: InstallOptionsEx 2.4.1 beta 4
FILE_MUST_EXIST
Determines if the selected file must exist. It only affects the
OPEN_FILEREQUEST dialog.
Required flags: OPEN_FILEREQUEST.
Supported by: InstallOptionsEx 2.4.1 beta 4
FILE_EXPLORER
Enables new file request look (recommended).
Required flags: OPEN_FILEREQUEST or SAVE_FILEREQUEST.
Supported by: InstallOptionsEx 2.4.1 beta 4
FILE_HIDEREADONLY
Hides the "open read only" check box.
Required flags: OPEN_FILEREQUEST.
Supported by: InstallOptionsEx 2.4.1 beta 4
WARN_IF_EXIST
Displays a warning message if the selected file already exists. It
only affects OPEN_FILEREQUEST or SAVE_FILEREQUEST dialogs.
Required flags: OPEN_FILEREQUEST or SAVE_FILEREQUEST.
Supported by: InstallOptionsEx 2.4.1 beta 4
PATH_MUST_EXIST
Prevents the user from typing a non-existent path. It only affects
OPEN_FILEREQUEST or SAVE_FILEREQUEST dialogs.
Required flags: OPEN_FILEREQUEST or SAVE_FILEREQUEST.
Supported by: InstallOptionsEx 2.4.1 beta 4
PROMPT_CREATE
Displays a warning if the selected file does not exist. However, it
still allows the user to select the file. It only affects
OPEN_FILEREQUEST dialogs.
Required flags: OPEN_FILEREQUEST.
Supported by: InstallOptionsEx 2.4.1 beta 4
BITMAP
ONLY_NUMBERS
Forces the user to enter only numbers into the edit box. Doesn't allow
negative numbers to be entered. Text can still be pasted normally.
Supported by: InstallOptions 1.2, InstallOptionsEx 2.4.1 beta 1
MULTILINE
Causes the control to accept multiple-lines.
Supported by: InstallOptions 2.2, InstallOptionsEx 2.4.1 beta 1
WANTRETURN
Specifies that a carriage return be inserted when the user presses the
ENTER key while entering text into the text box.
Required flags: MULTILINE.
Supported by: InstallOptions 2.2, InstallOptionsEx 2.4.1 beta 1
NOWORDWRAP
Disables the word-wrap that occurs when long lines are entered. Long
lines instead scroll off to the side.
Required flags: MULTILINE.
Disabled by flags: HSCROLL.
Supported by: InstallOptions 2.2, InstallOptionsEx 2.4.1 beta 1
HSCROLL
Shows a horizontal scroll bar.
Supported by: InstallOptions 1.2, InstallOptionsEx 2.4.1 beta 1
READONLY
Prevents the user from entering or editing text in the edit control,
but allow the user to select and copy the text.
Supported by: InstallOptions 2.2, InstallOptionsEx 2.4.1 beta 1
VSCROLL
Shows a vertical scroll bar.
Supported by: InstallOptions 1.2, InstallOptionsEx 2.4.1 beta 1
PASSWORD
Same as using the control DropList.
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
DateTime
UPDOWN
Makes the control to be like an UpDown control with a Text control, but
using date and time.
Supported by: InstallOptionsEx 2.4.1 beta 3
ListBox
MULTISELECT
Turns string selection on or off each time the user clicks or double-clicks
a string in the control. The user can select any number of strings.
Supported by: InstallOptions 1.4, InstallOptionsEx 2.4.1 beta 1
EXTENDEDSELECT
Allows multiple items to be selected by using the SHIFT key and the
mouse or special key combinations.
Disabled by flags: MULTISELECT.
Supported by: InstallOptionsEx 2.4.1 beta 11
EXTENDEDSELCT
Renamed to EXTENDEDSELECT, but kept for compatibility purposes.
Disabled by flags: MULTISELECT.
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
VSCROLL
Shows a disabled vertical scroll bar when there is no need for one.
Disabled by flags: MULTISELECT.
Supported by: InstallOptions 2.4, InstallOptionsEx 2.4.1 beta 1
ListView/TreeView
CHECKBOXES
Enables check boxes for items in TreeView and
ListView controls and the use of the space character to switch
among states. A check box is displayed only if an image is associated
with the item by using StateImageList INI key. See
State INI key for more information regarding the selection
of items.
Internet Explorer 3.0 or above required.
Supported by: InstallOptionsEx 2.4.2 beta 1
EDITLABELS
Enables the edition of ListItems items in the control
by selecting the item first and then clicking over the label. It's doesn't
yet return values
Supported by: InstallOptionsEx 2.4.2 beta 3
MULTISELECT
This specifies flags for the horizontal alignment of controls. Only
one of the flags below can be used:
LEFT
Self-explanatory.
Supported by: InstallOptionsEx 2.4.2 beta 1
CENTER
Self-explanatory.
Supported by: InstallOptionsEx 2.4.2 beta 1
RIGHT
Self-explanatory.
Supported by: InstallOptionsEx 2.4.2 beta 1
These below are controls that support some or all of the flags above. Flags
can be utilized differently from control to control:
CheckBox/RadioButton
Positions the button to the custom aligment; left or right
of the text. RTL INI key from "Settings" INI section inverts
this value.
Supports: LEFT, RIGHT flags.
Default Value: LEFT.
Supported by: InstallOptionsEx 2.4.2 beta 1
UpDown
Positions the control to the custom aligment; left or right
of a buddy control. This has no effect if Text INI key is not
used. RTL INI key from "Settings" INI section inverts this
value.
Supports: LEFT, RIGHT flags.
Default Value: RIGHT.
Supported by: InstallOptionsEx 2.4.2 beta 1
DateTime
Positions the month calendar to the custom alignment; to the
left or right margin of the control. This has no effect if UPDOWN flag
from Flags INI key is specified. RTL INI key
from "Settings" INI section inverts this value.
Supports: LEFT, RIGHT flags.
Default Value: LEFT.
Supported by: InstallOptionsEx 2.4.2 beta 1
TrackBar
Positions the ticks to the custom alignment; to the left, both
ends (CENTER), or right margin of the control. This has no effect if
VSCROLL flag from Flags INI key is not specified.
Supports: LEFT, CENTER, RIGHT flags.
Required flag: VSCROLL from Flags INI key.
Default Value: RIGHT.
Supported by: InstallOptionsEx 2.4.2 beta 1
Supported by: InstallOptionsEx 2.4.2 beta 1
VAlign
This specifies flags for the horizontal alignment of text on
controls. Only one of the flags below can be used:
LEFT
Self-explanatory.
Supported by: InstallOptionsEx 2.4.2 beta 1
CENTER
Self-explanatory.
Supported by: InstallOptionsEx 2.4.2 beta 1
RIGHT
Self-explanatory.
Supported by: InstallOptionsEx 2.4.2 beta 1
JUSTIFY
Self-explanatory. Reserved for future use.
Supported by: InstallOptionsEx 2.4.2 beta 1
These below are controls that support some or all of the flags above. Flags
can be utilized differently from control to control:
Label/GroupBox/Link
Positions the text to the custom aligment; to the left, center,
or right margin of the control. RTL INI key from "Settings"
INI section inverts this value.
Supports: LEFT, CENTER, RIGHT flags.
Default Value: LEFT.
Supported by: InstallOptionsEx 2.4.2 beta 1
CheckBox/RadioButton
Positions the text to the custom aligment; left or right
of the button. RTL INI key from "Settings" INI section inverts
this value.
Supports: LEFT, RIGHT flags.
Default Value: LEFT.
Supported by: InstallOptionsEx 2.4.2 beta 1
Button
Positions the text to the custom aligment; to the left, center,
or right margin of the control. RTL INI key from "Settings"
INI section inverts this value.
Supports: LEFT, CENTER, RIGHT flags.
Default Value: CENTER.
Supported by: InstallOptionsEx 2.4.2 beta 1
Text/Password
Positions the text to the custom aligment; to the left, center,
or right margin of the control. RTL INI key from "Settings"
INI section inverts this value.
Windows 95, Windows NT 4.0 and earlier require: MULTILINE
flag from Flags INI key.
Supports: LEFT, CENTER, RIGHT flags.
Default Value: LEFT.
Supported by: InstallOptionsEx 2.4.2 beta 1
DropList/ComboBox/ListBox
Positions the text of items and text box to the custom aligment;
to the left, center, or right margin of items and control. RTL INI
key from "Settings" INI section inverts this value.
Supports: LEFT, CENTER, RIGHT flags.
Default Value: CENTER.
Supported by: InstallOptionsEx 2.4.2 beta 1
Supported by: InstallOptionsEx 2.4.2 beta 1
TxtVAlign
After initDialog returns, this will contain the HWND of the control created by this field. It can be used instead of FindWindow and GetDlgItem.
Supported by: InstallOptions 2.4.4, InstallOptionsEx 2.4.5 beta 1
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
How to Use
Step 1: Using With Modern UI
As this is a different module than the original InstallOptions, none of
the commands provided by Modern UI supports InstallOptionsEx.dll, but you can
make a "trick" by renaming this dll to InstallOptions.dll. But remember, if you
use mixed Modern UI with these commands below, you'll have to call like you would
for the normal InstallOptions.dll. Both dlls calling are similar. If you do this
above, you can see instructions from
Modern UI documentation. However, I don't garantee that Modern UI will work
correctly with this plugin.
Step 2: Extract the INI File
First, you have to extract the INI files for the dialogs in the
.onInit function:
Function .onInit
InitPluginsDir
File /oname=$PLUGINSDIR\test.ini test.ini
FunctionEnd
Step 3: Call the DLL
You can call InstallOptionsEx in a page function, check the
NSIS documentation for
information about the page system. Example:
Page custom SetCustom ValidateCustom
The InstallOptionsEx DLL has three functions:
dialog "ini_file"
Creates the dialog immediately. Parameters:
"ini_file"
Specifies the location where the INI file that will be used by
the plugin to create the dialog is. This can be:
Relative path from the current plugin location. The path has to be without "." or "..". (i.e. "test.ini" = "$PLUGINSDIR\test.ini")
Relative path from the current installer location. The path has to be with "." or "..". (i.e. ".\test.ini" = "$EXEDIR\test.ini")
Absolute path. (i.e. "C:\test.ini")
Default Value: No default value.
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
initDialog "ini_file"
Creates the dialog in memory and doesn't show it. Parameters:
"ini_file"
Specifies the location where the INI file that will be used by
the plugin to create the dialog is. This can be:
Relative path from the current plugin location. The path has to be without "." or "..". (i.e. "test.ini" = "$PLUGINSDIR\test.ini")
Relative path from the current installer location. The path has to be with "." or "..". (i.e. ".\test.ini" = "$EXEDIR\test.ini")
Absolute path. (i.e. "C:\test.ini")
Default Value: No default value.
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
show
Shows a previously dialog created in memory by the DLL function "initDialog".
Supported by: InstallOptions 1.0, InstallOptionsEx 2.4.1 beta 1
setFocus "HWND"
Set the focus on the specified control in parameter but prefer to use the FOCUS flag if you can.
This function was designed to be employed in your leave script functions (when the control is already shown).
Supported by: InstallOptionsEx 2.4.5 beta 2
Usually, you only need to use the dialog function:
Function SetCustom ;FunctionName defined with Page command
;Display the InstallOptionsEx dialog
Push $R0
InstallOptionsEx::dialog $PLUGINSDIR\test.ini
Pop $R0
FunctionEnd
Note that the page can be updated by changing anything on the INI file.
That means, you should secure it in difficult places so that no one can
change it when you're not expecting it. But this will probably change in future
versions.
Step 4: Get the Output
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 InstallOptionsEx values are escaped to allow characters to
be used that are not normally valid in INI file values. For new lines,
carriage return, line feed and back-slash, the affected values are:
- The ValidateText field.
- The Text value of Label, Link, DropList, ComboBox
DropList and ListView (except Tab character) fields.
- The State value of Text fields that have the MULTILINE flag.
- The ListItems value of Button fields that have the DIRREQUEST flag.
For "\|", the affected values are:
- All list based values that don't use numbers alone of ListBox, DropList,
ComboBox, ListView and TreeView controls.
For "\{" and "\}", the affected values are:
- All list based values that don't use numbers alone of ListView and TreeView controls.
Every value of a key is affected by variables
which are updated to the time the page was reserved or showed
without reserving.
Escape characters and variables:
- $0-$9, $R0-$R9 - Variables
- \r - Carriage return (ASCII 13)
- \n - Line feed (ASCII 10)
- \t - Tab (ASCII 9)
- \\ - Back-slash
- \| - Pipe
- \{ - Start curly bracket
- \} - End curly bracket
Step 5: Validate the Output
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:
Function ValidateCustom
ReadINIStr $R0 "$PLUGINSDIR\test.ini" "Field 1" "State"
StrCmp $0 "" 0 +3
MessageBox MB_ICONEXCLAMATION|MB_OK "Please enter your name."
Abort
FunctionEnd
Step 6: Return Value
After you have called the DLL, InstallOptionsEx 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 on initialization or page functions
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\InstallOptionsEx.dll"
Versions History
IOEx DLL version 2.4.5 beta 2