InstallOptionsEx Readme

Collapse All | Expand All | Inverse All
Introduction

InstallOptionsEx is a NSIS plugin which allows you to create custom pages for NSIS installers, to prompt the user for extra information. This is a expanded version of original InstallOptions, with additional controls, flags and options.

InstallOptionsEx 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 page system which allows you to add custom pages to your installer without messing with Prev/Next functions. With the this 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 version of InstallOptionsEx has been designed for NSIS 2. It supports customized user interfaces and custom font and DPI settings.

This documentation uses the expand/collapse effect, making information to be in levels. Click on one item name which have an icon to see its respective description.

INI File Structure

This is where everything about the INI file reference (on next section) is explained. Changes to the INI file structure since InstallOptions are represented by these colors:

	Old and supported (InstallOptionsEx/InstallOptions)
	New and supported (InstallOptionsEx only)
	Old but not supported (InstallOptions only)

In that documentation section, items are organized as follows:

  Section
  - Value name (Required) (Input/Output)
    - Flag OR Control Type (With Exceptions)
      - Flag ("Control Type Exceptions")

Your INI file should have this structure based on the information above:

  [Section]
  Value name=Value (or Flag(s))

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 -> Animation)
Controls that receive mostly mouse focus. (Link -> UpDown)
Controls that State text can be edited manually. (Text -> IPAddress)
Controls that contain a customizable list of items. (DropList -> TreeView)
Controls that contain a non-customizable list of items. (TrackBar -> MonthCalendar)

INI File Reference Settings

This section configures the page as a whole. The following are the value names supported by this section:

  ListItems=Item1{SubItem1ofItem1|SubItem2ofItem1}Item2|Item3
  State=0|1|3

Item state flags have to be joined with "bitwise OR" before writing to the INI file. Example:

  3 = 0x0B = Checked + Read-Only.

Then put it like this in the State INI value:

  State=0|1|3

After you run the page, you can verify if one of the bits is selected by doing a "bitwise AND". There is no way to detect if the "Unchecked" state flag is used because it's 0. Instead, try to check for the "Checked" state flag.

State of checkboxes:

0 or 0x00 - Checkbox is unchecked.
1 or 0x01 - Checkbox is checked.
2 or 0x02 - Checkbox is read-only.
4 or 0x04 - No checkbox (not totally supported yet).

Default Value: None
Supported by: InstallOptionsEx 2.4.2 beta 3

Changed State and Notify INI value names from Settings INI section:

Fixed: State had the value of 0 and Notify didn't even appear when OPEN_FILEREQUEST, SAVE_FILEREQUEST or DIRREQUEST were used on a Button control.

As the appearance of these INI value names are imminent: If State = 0, the page returned a notification. If Notify = ONNEXT, ONBACK or ONCANCEL, the user clicked on next, back or cancel buttons, respectively.
IOEx DLL version 2.4.1 beta 10

(10/29/2004)

Fixed VSCROLL flag: wasn't supported by ListBox controls.

Changed flag name: HORIZONTAL to HSCROLL.

Mentioned PASSWORD for Text and DROPLIST for ComboBox controls on the documentation.

Added new feature to Password controls: Password mask character (see Text INI value name).

Added new feature to Animation controls: Adjustment of number of loops (see State INI value name).

Added new features to Icon controls:

Supports getting icons from executables, and dlls (see Text and State INI value names).

Supports default Windows icons (see State INI value). Options: APPLICATION, EXCLAMATION, INFORMATION, QUESTION, STOP and WINLOGO.

Added variables $0-$9, $R0-$R9 support before reserving or showing without reserving pages. It is supported on every value of a value name and can be used multiple times on the same value.
IOEx DLL version 2.4.1 beta 9

(8/23/2004)

Fixed DISABLED Label controls: didn't draw shadow.

DISABLED Label and Link are now controls supported by DisTxtColor value name.

Fixed Label and Link controls: didn't draw background color on the entire control.

Shadow Text feature added. Added TxtShwColor, DisTxtShwColor, SelTxtShwColor and DisSelTxtShwColor.
First DLL optimizations: 0.5 kb smaller on uncompressed build (no change for compressed build).

Fixed text positioning of ComboBox, DropList and ListBox controls. They are now closer to the control border.

Fixed focus rectangle not appearing on ComboBox and DropList.

ListBox, ComboBox and DropList controls have automatic word ellipsis.

FontOrientation and FontEscapement removed - because most of the drawing commands do not support this feature.
IOEx DLL version 2.4.1 beta 8

(8/18/2004)

Added ToolTips feature -> Added ToolTipText, ToolTipFlags, ToolTipMaxWidth, ToolTipTxtColor, ToolTipBgColor, ToolTipIcon and ToolTipTitle value names.

Fixed DISABLED ComboBox and DropList controls bug: Didn't redraw right.

Fixed DISABLED ListBox controls bug: User specified colors didn't apply.
IOEx DLL version 2.4.1 beta 7

(8/14/2004)

Added Notify value name for "Settings" and "Field #" sections.

Added: ONSETFOCUS, ONKILLFOCUS, ONLISTOPEN, ONLISTCLOSE, ONSELCHANGE, ONTEXTCHANGE, ONTEXTUPDATE, ONCLICK, ONDBLCLICK, ONTEXTTRUNCATE, ONTEXTVSCROLL, ONSTART and ONSTOP notification flags.

Added BackShow, NextEnabled and NextShow for "Settings" section.

Fixed the control extension beyond the rectangle height and width addition of the last version removed.

Fixed Text controls: "black" color was being set even when you didn't.

Fixed ListBox controls: didn't appear as they were disabled.

Added missing features to the documentation which last version's didn't mention.

Added FontName for Label, Link, ListBox, ComboBox, DropList, Text and Password controls, DisBgColor, DisTxtColor, DisSelBgColor and DisSelTxtColor for ListBox control.

ListItems for Button controls w/ DIRREQUEST flag is the text which appears above the Tree-View control of directories.

Added a new flag to CheckBox controls, the old and famous "3STATE" flag that allows you to set additionally an indetermined (or grayed) state.
IOEx DLL version 2.4.1 beta 6 (7/25/2004)
Added a wide range of commands for setting initial color and font formatting without using NSIS commands.

Fixed the control extention beyond the rectangle height and width. This makes the control to resize itself when necessary.

Added file verification before setting a bitmap or icon to DropList, ComboBox and Button controls.

Added Height and Width value names.

Fixed a stupid bug that made some controls flags to be set when you did not specify them.

Fixed another stupid bug that made ProgresBar controls to do not show their indicator bar correctly.

Added one laking information about the stand alone keys for HotKey controls.

Fixed other minor bugs.

Added ellipsis style for all controls that support ownerdraw style.
IOEx DLL version 2.4.1 beta 5 (6/27/2004)
Added HotKey control.

Added support of NOTIFY flag for MonthCalendar, DateTime, UpDown and HotKey controls.

Added information to controls and options their minimum supportable OS.

C style escape characters restored again.

Fixed problems with new controls about the TabStop not working.
IOEx DLL version 2.4.1 beta 4 (6/11/2004)
Added UpDown control.

Removed FileRequest and DirRequest controls. Use Text and Button controls instead.

Added FILEREQUEST and DIRREQUEST flags for Button controls and LEFT, HORIZONTAL and WRAP flags for UpDown controls.

NSIS $\n, $\r and $\t imported to remove the need for conversions between NSIS characters and plugin's.
IOEx DLL version 2.4.1 beta 3 (6/7/2004)
Added DateTime and MonthCalendar controls.

Added UPDOWN flag for DateTime controls and NOTODAY, NOTODAYCIRCLE and WEEKNUMBERS flags for MonthCalendar controls.
IOEx DLL version 2.4.1 beta 2 (5/31/2004)
Added TrackBar and IPAddress controls.

Added ability of Button controls of supporting an image or icon.

Added BACK_RECT, TOOLTIPS and NO_TICKS flags for TrackBar controls and BITMAP and ICON flags for Button controls.

Added support of NOTIFY flag for IPAddress control.

Removed NOAUTOPLAY flag for Animation control.
IOEx DLL version 2.4.1 beta 1 (5/24/2004)
Removed NumFields from INI File "Settings" section.

Added Animation and ProgressBar controls.

Added ability of ComboBox and DropList controls of supporting images for each item in their list boxes.

Added TRANSPARENT, CENTER and NOAUTOPLAY flags for Animation controls and SMOOTH and VERTICAL flags for ProgressBar controls.

Added support of NOTIFY flag for Text, Password and ComboBox controls.
IO DLL version 2.4.1 (5/8/2004)
Bitmaps are now automatically centered

Fixed a bug which prevented enabling the next button from the leave function of InstallOptions pages

Fixed a rare freeze
IO DLL version 2.4 (1/4/2004)
Initial focus is set in "initDialog" making it possible to override it from NSIS prior to calling "show"

When initial focus is to a Text field InstallOptions now follows standard Windows behaviour by having the text selected

Label and other static fields no longer have State= written to the INI file when leaving the dialog

NOTIFY flag can now be used with Link fields (State should be omitted in this case)

Likewise, State can now be used with Button fields (behaves the same as with Link fields)

NOTIFY flag can also now be used with ListBox and DropList fields to have NSIS notified when the selection changes

Meaning of RIGHT flag is now reversed in right-to-left language mode

HSCROLL and VSCROLL flags are no longer restricted to Text fields

Various Link field fixes
IO DLL version 2.3 (12/4/2003)
Added new control type "Button"

Added new flag "NOTIFY"

Added new flag "NOWORDWRAP" for multi-line text boxes

Reduced size down to 12K

Better RTL support
IO DLL version 2.2 (6/10/2003)
Added New control type LINK

\r\n converts to newline in Multiline edit box

Support for multiline edit box

Better tab order in DirRequest and FileRequest

Added READONLY option to text box

Minor fixes
IO DLL version 2.1 (3/15/2003)
\r\n converts to newline in both label Text and ValidateText

New browse dialog style (modern)

Word wrapping for check boxes and radio buttons

No ugly border for edit fields under XP

Scroll bar for list boxes

Works with SetStaticBkColor

DISABLED dir and file request fields now disable the browse button too

No more STATE value for labels

Minor fixes
IO DLL version 2.0 (1/4/2003)
Supports custom font and DPI settings (by Joost Verburg)

INI files should contain dialog units now, no pixels (by Joost Verburg)

RESIZETOFIT flag for Bitmap control (by Amir Szekely)

New documentation (by Joost Verburg)

New GROUP/NOTABSTOP/DISABLED flags

Added Rect INI value name.
IO DLL version 1.7 beta (11/2/2002)
Added initDialog and show DLL functions.

Removed CancelConfirm, CancelConfirmCaption, CancelConfirmFlags INI value names.

Renamed BackDisabled INI value name to BackEnabled. IO DLL version 1.6 beta (9/30/2002)

CancelConfirmIcon becomes CancelConfirmFlags and can now take the other common MessageBox flags

IO DLL version 1.5 beta (9/26/2002)
Made close [x] button behave like Cancel (thanks brainsucker)
IO DLL version 1.4 beta (9/4/2002)
Added Icon and Bitmap controls (by Amir Szekely)
IO DLL version 1.3 beta (8/15/2002)
Added CancelShow (by ORTIM)

Added pixel transformation for widgets (by ORTIM)
IO DLL version 1.2 beta (7/31/2002)
Added CancelEnabled (by ORTIM)

Added CancelConfirmCaption and CancelConfirmIcon (by Amir Szekely)
IO DLL version 1.1 beta (7/22/2002)
Font is now taken from the main NSIS window (by Amir Szekely)
IO DLL version 1.0 beta (12/16/2001)
Moved to DLL, no longer need parentwnd ini writing

Tons of changes - no longer fully compatible (see source for a big list)

removed support for silent installers (it seems the old version would bring up it's own dialog)
IO DLL version 1.4 (11/18/2001)
Added Listbox controls.

Added MULTISELECT flag.

Made the HWND list for the parent window controls dynamically allocated. This prevents a crash if NSIS ever gets more than 150 controls on it's main window.

The TEXT property of DirRequest control can be used to specify an initial directory. The current directory is automatically selected when clicking the browse button of the DirRequest control.

Added ROOT property to DirRequest which can be used to set the root directory (mostly due to felfert)

Edit controls will now auto scroll (thanks felfert)

Fixed a problem where the window wouldn't draw properly on some systems (thanks felfert)
IO DLL version 1.3 (11/03/2001)
Got rid of the call to RedrawWindow() because it's no longer needed with the WS_CLIPCHILDREN flag for NSIS.

Removed a few hardcoded limits of buffer sizes

Added Checkbox and RadioButton controls

Added RIGHT and CHECKED flags
IO DLL version 1.2.2 (10/30/2001)
Additional size reductions. Further reduced the size down to 8k.

The text parameter to a combobox can now be used to specify the initial value

Changed from InvalidateRect() to RedrawWindow() to force a redraw after a browse dialog

On startup, set the flags of the NSIS window to include WS_CLIPCHILDREN. Otherwise, our controls don't get drawn right.
IO DLL version 1.2.1 (10/28/2001)
Bug fix. ControlID for the caption and the OK button were reused by the first two controls. (Thanks Schultz)
IO DLL version 1.2.0.1 (10/28/2001)
8.5kb from 44kb. heh. (by Justin Frankel)
IO DLL version 1.2 (10/28/2001)
Still 44k

Added the "FileRequest" and "DirRequest" control types (thanks Schultz)

Added "MinLen", "MaxLen", and "ValidateText" properties to fields

Added "Flags" as a way to specify additional parameters for controls

Few more changes to the documentation

Cleaned the code in a few places...still trying to make it smaller
IO DLL version 1.1 (10/27/2001)
Added the "Title" option (thanks Alex)

Moved the OK button so it is in the same location as the buttons on the main NSIS window (thanks Alex)

Pressing "ENTER" will now automatically select the OK button (thanks Alex)

Slightly improved the documentation
IO DLL version 1.0.1 (10/25/2001)
Fixed the SetFocus loop so it exits after the first control like it was supposed to

Added the license to the documentation
IO DLL version 1.0 (10/25/2001)
Barely qualifies as a distribution.
Credits
Original IO version by Michael Bishop
IO DLL version by Nullsoft, Inc.
IO DLL version 2 by Amir Szekely, ORTIM, Joost Verburg
IOEx DLL (changed from original IO 2) by Diego Pedroso

Documentation for InstallOptions 2 by Joost Verburg
InstallOptionsEx Documentation (changed from InstallOptions') by Diego Pedroso
License
Original IO version Copyright © 2001 Michael Bishop IO DLL version 1 Copyright © 2001-2002 Nullsoft, Inc., ORTIM IO DLL version 2 Copyright © 2003-2005 Amir Szekely, Joost Verburg, Dave Laundon IOEx DLL (changed from original IO 2) Copyright © 2004-2005 Diego Pedroso 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.