Installer - Configuring Applications

Applications are configured on the screens & and actions tab.

The top-level nodes represent the different applications that can be configured for the project. There are 3 types of applications:
- Installer
  The installer is the application that is executed when the media file is invoked by the user, for example, when the user double-clicks on the installer executable in the Windows explorer. The installer cannot be deleted from the tree of installer elements.
- Uninstaller
  
  The uninstaller is a special application for uninstalling an installation. It is used in various contexts:
  - Directly invoked by the user
  - Invoked from the Windows software registry
  - Invoked by the "Uninstall previous installation" action
  The uninstaller cannot be deleted from the tree of installer elements. If you do not wish to generate an uninstaller, you can disable it.
- Custom installer application
  You can add any number of custom installer applications that can be invoked after the installation. install4j comes with several templates for auto-updaters. Custom applications can also be used for writing maintenance applications for your installation.
  You can add new custom installer application by clicking on the [Add] button on the right side of the list and choosing Add Application from the popup. The application templates dialog will be displayed and lets you choose a starting point for your custom installer application. Application templates are entirely made up of existing screens, actions and form components. You can modify the selected application template after adding it.
  
  Unlike the installer and uninstaller above, custom applications are also created for archive media files. Please see the help topic on screens and actions for more information on how to create first-run installers for archives.
  
  Custom installer applications with a non-empty "executable directory" property are automatically added to the "Default file set". Unlike launchers, they cannot be assigned to specific file sets. If your installation components do no include the root of the default file set, you have to select the custom installer applications explicitly in the installation component configuration. If the custom installer application is added to the .install4j directory by leaving the executable directory empty, they will always be included.

Each installer application has a startup sequence of actions. Those actions are executed before the installer application presents a user interface. If any of these actions fails and has a "Quit on failure" failure strategy, the installer application will not be shown.

The configurable properties of the three types of applications are listed below:

Installer

The installer is the sequence of screens and actions that are executed when the user invokes the media file.

Properties:

Executable icon [Executable]
By default, a standard installer icon is used for the executable. To customize the icon, press the customizer button in the configuration pane.
Allow unattended mode [Execution Modes]
If selected, the user can pass -q as an argument to run the installer application without a GUI. No user input is required, the installer applications works with the default values. Please see the corresponding help topic on installer modes for more information. All standard actions and standard screens support unattended installations. If your policy forbids unattended installations or if you include custom code that cannot handle unattended installations, you can disable them by deselecting this property.
Allow console installations [Execution Modes]
If selected, the user can pass -c as an argument to run the installer application on the console. The installer asks for user input on the console in that mode. Please see the corresponding help topic on installer modes for more information. All standard actions and standard screens support console installations, form screens are also fully mapped to console installers. If your policy forbids console installations or if you include custom code that cannot handle console installations, you can disable them by deselecting this property.
Fall back to console mode on Unix
On Unix, users often operate in environments where no X11 server is available and no GUI can be displayed. The installer will fallback to console mode if console mode execution is allowed and this option is selected. Otherwise an error message will be displayed that tells the user how to invoke the installer in console mode.
Note: This property is only visible if "Allow console installations" is selected.
Console screen change handler
By default, a screen in console mode does not show any particular separation. You insert your own custom display with this script. The title parameter gives you access to the title of the screen. In console mode, screens display their subtitle only, so the title string will not be displayed again.
Note: This property is only visible if "Allow console installations" is selected.
Default execution mode [Execution Modes]
The default execution mode for the installer application. By default, a GUI wizard will be shown, but it is also possible to run in console mode or unattended mode by default.
Title for progress dialog
The title for the progress dialog, for example "Updating installation".This title and the unattended mode with a progress window can also be set by passing -splash [title] as an argument from the command line.
Note: This property is only visible if "Default execution mode" is set to "Unattended mode with progress dialog".
Windows console executable [Execution Modes]
If selected, a console executable will be created on Windows. A non-hideable console will be shown when the installer is double-clicked in the explorer. This improves the user experience for a console-only installer (default execution mode set to console) and allows execution through rsh.
VM parameters [Execution Options]
If you need to pass special VM parameters to the installer application, you can enter them here.A common case would be to raise the maximum heap size with a different -Xmx parameter if your installers require a lot of memory.
Arguments [Execution Options]
If you need to pass fixed default arguments to the installer application, you can enter them here. For example, if you want to display a splash screen in unattended mode by default, you can set the arguments to -splash "Installing ...". Please note that command line arguments will be appended to this list, so it is not possible to "override" a fixed argument from the command line.
Suppress initial progress dialog [Execution Options]
If selected, the initial native progress dialog of the installer is not displayed.
Custom image for title bar [GUI Options]
You can optionally choose a different image for the top right corner of the installer wizard. The recommended size for this image is 60 x 60 pixels. Clear to reset to the default image.
Icon can overlap text
If selected, the icon can overlap the title and subtitle text. In this case, the icon should be suitable as a background upon which black text can be read. If not selected, the image will be aligned at the right side of the screen, otherwise the anchor property below will be used.
Icon anchor
The anchor where the icon will be fixed in the title bar area.
Note: This property is only visible if "Icon can overlap text" is selected.
Background color for title bar [GUI Options]
With this property, you can adjust the background color of the title bar, the default value is suitable for the standard icon. Set to "None" in order to reset to the default value.
Foreground color for title bar [GUI Options]
With this property, you can adjust the foreground color of the title bar used for text, the default value is suitable for the standard background color. Set to "None" in order to reset to the default value.
Window width [GUI Options]
The width of the window displayed by the installer application. The default value is 500. If the "Size client area" property is selected, this does not include the size of the window frame border.
Window height [GUI Options]
The height of the window displayed by the installer application. The default value is 390.If the "Size client area" property is selected, this does not include the size of the window frame border.
Size client area [GUI Options]
If selected, the supplied size for the window will not be applied to the outer dimensions of the window, but to the actually usable area inside the window. Unusually large window frame borders can occur due to user settings (accessibility, window themes, etc.) and may interfere with banner images or introduce unwanted scroll bars to form screens.
Resizable [GUI Options]
If selected, the window displayed by the installer application is resizable.
Add install4j watermark to installer screens [GUI Options]
If selected, install4j watermarks will be added to the divider that separates the navigation buttons on every screen of the installer application.
Custom watermark text
By default, the watermark text is "install4j". If you would like to display a different text instead, you can enter it here.
Note: This property is only visible if "Add install4j watermark to installer screens" is selected.
Customize version info [Windows]
If selected, you can customize the fields of the Windows version info in the nested properties. A windows version info is always generated for the executable with default values for product name and file version taken from the general settings.
Product name
The product name field in the version resource. If empty, the full name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.
File version
The file version field in the version resource. If empty, the version from the general settings is used. The file version must consist of 4 numbers separated by spaces, commas or dots.
Note: This property is only visible if "Customize version info" is selected.
Internal name
The internal name field in the version resource. If empty, the short name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.
File description
The file description field in the version resource. If empty, the full name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.
Copyright
The copyright field in the version resource. If empty, the publisher name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.
Create log file for stderr output [Windows]
If selected, and output on stderr is detected, an file named error.log will be created next to the installer and all output to stderr will be redirected to that file.

Uninstaller

The uninstaller removes the installed application. If you do not wish to provide an uninstaller, you can disable it.

Properties:

Executable icon [Executable]
By default, a standard installer icon is used for the executable. To customize the icon, press the customizer button in the configuration pane.
Executable name [Executable]
The name of the executable for the uninstaller. Please enter a name without any path components and without a file extension.
Executable directory [Executable]
The directory to which the executable of the uninstaller will be written. If empty, it will be placed in the .install4j directory.
Allow unattended mode [Execution Modes]
If selected, the user can pass -q as an argument to run the installer application without a GUI. No user input is required, the installer applications works with the default values. Please see the corresponding help topic on installer modes for more information. All standard actions and standard screens support unattended installations. If your policy forbids unattended installations or if you include custom code that cannot handle unattended installations, you can disable them by deselecting this property.
Allow console installations [Execution Modes]
If selected, the user can pass -c as an argument to run the installer application on the console. The installer asks for user input on the console in that mode. Please see the corresponding help topic on installer modes for more information. All standard actions and standard screens support console installations, form screens are also fully mapped to console installers. If your policy forbids console installations or if you include custom code that cannot handle console installations, you can disable them by deselecting this property.
Fall back to console mode on Unix
On Unix, users often operate in environments where no X11 server is available and no GUI can be displayed. The installer will fallback to console mode if console mode execution is allowed and this option is selected. Otherwise an error message will be displayed that tells the user how to invoke the installer in console mode.
Note: This property is only visible if "Allow console installations" is selected.
Console screen change handler
By default, a screen in console mode does not show any particular separation. You insert your own custom display with this script. The title parameter gives you access to the title of the screen. In console mode, screens display their subtitle only, so the title string will not be displayed again.
Note: This property is only visible if "Allow console installations" is selected.
Default execution mode [Execution Modes]
The default execution mode for the installer application. By default, a GUI wizard will be shown, but it is also possible to run in console mode or unattended mode by default.
Title for progress dialog
The title for the progress dialog, for example "Updating installation".This title and the unattended mode with a progress window can also be set by passing -splash [title] as an argument from the command line.
Note: This property is only visible if "Default execution mode" is set to "Unattended mode with progress dialog".
Windows console executable [Execution Modes]
If selected, a console executable will be created on Windows. A non-hideable console will be shown when the installer is double-clicked in the explorer. This improves the user experience for a console-only installer (default execution mode set to console) and allows execution through rsh.
VM parameters [Execution Options]
If you need to pass special VM parameters to the installer application, you can enter them here.A common case would be to raise the maximum heap size with a different -Xmx parameter if your installers require a lot of memory.
Arguments [Execution Options]
If you need to pass fixed default arguments to the installer application, you can enter them here. For example, if you want to display a splash screen in unattended mode by default, you can set the arguments to -splash "Installing ...". Please note that command line arguments will be appended to this list, so it is not possible to "override" a fixed argument from the command line.
Custom image for title bar [GUI Options]
You can optionally choose a different image for the top right corner of the installer wizard. The recommended size for this image is 60 x 60 pixels. Clear to reset to the default image.
Icon can overlap text
If selected, the icon can overlap the title and subtitle text. In this case, the icon should be suitable as a background upon which black text can be read. If not selected, the image will be aligned at the right side of the screen, otherwise the anchor property below will be used.
Icon anchor
The anchor where the icon will be fixed in the title bar area.
Note: This property is only visible if "Icon can overlap text" is selected.
Background color for title bar [GUI Options]
With this property, you can adjust the background color of the title bar, the default value is suitable for the standard icon. Set to "None" in order to reset to the default value.
Foreground color for title bar [GUI Options]
With this property, you can adjust the foreground color of the title bar used for text, the default value is suitable for the standard background color. Set to "None" in order to reset to the default value.
Window width [GUI Options]
The width of the window displayed by the installer application. The default value is 500. If the "Size client area" property is selected, this does not include the size of the window frame border.
Window height [GUI Options]
The height of the window displayed by the installer application. The default value is 390.If the "Size client area" property is selected, this does not include the size of the window frame border.
Size client area [GUI Options]
If selected, the supplied size for the window will not be applied to the outer dimensions of the window, but to the actually usable area inside the window. Unusually large window frame borders can occur due to user settings (accessibility, window themes, etc.) and may interfere with banner images or introduce unwanted scroll bars to form screens.
Resizable [GUI Options]
If selected, the window displayed by the installer application is resizable.
Add install4j watermark to installer screens [GUI Options]
If selected, install4j watermarks will be added to the divider that separates the navigation buttons on every screen of the installer application.
Custom watermark text
By default, the watermark text is "install4j". If you would like to display a different text instead, you can enter it here.
Note: This property is only visible if "Add install4j watermark to installer screens" is selected.
Unix mode [Unix]
The executable mode for the uninstaller on Unix.
Customize version info [Windows]
If selected, you can customize the fields of the Windows version info in the nested properties. A windows version info is always generated for the executable with default values for product name and file version taken from the general settings.
Product name
The product name field in the version resource. If empty, the full name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.
File version
The file version field in the version resource. If empty, the version from the general settings is used. The file version must consist of 4 numbers separated by spaces, commas or dots.
Note: This property is only visible if "Customize version info" is selected.
Internal name
The internal name field in the version resource. If empty, the short name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.
File description
The file description field in the version resource. If empty, the full name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.
Copyright
The copyright field in the version resource. If empty, the publisher name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.

Custom application

A custom installer application is installed by the installer. Users can start it manually or it can be executed programmatically from your own code via the API.

Properties:

Executable icon [Executable]
By default, a standard installer icon is used for the executable. To customize the icon, press the customizer button in the configuration pane.
File set [Executable]
Choose the file set to which the installer application is added. File sets can be defined on the Files->Define Distribution Tree tab.
Executable name [Executable]
The name of the executable for the custom application. Please enter a name without any path components and without a file extension.
Executable directory [Executable]
The directory to which the executable of the custom application will be written. If empty, it will be placed in the .install4j directory.
Allow unattended mode [Execution Modes]
If selected, the user can pass -q as an argument to run the installer application without a GUI. No user input is required, the installer applications works with the default values. Please see the corresponding help topic on installer modes for more information. All standard actions and standard screens support unattended installations. If your policy forbids unattended installations or if you include custom code that cannot handle unattended installations, you can disable them by deselecting this property.
Allow console installations [Execution Modes]
If selected, the user can pass -c as an argument to run the installer application on the console. The installer asks for user input on the console in that mode. Please see the corresponding help topic on installer modes for more information. All standard actions and standard screens support console installations, form screens are also fully mapped to console installers. If your policy forbids console installations or if you include custom code that cannot handle console installations, you can disable them by deselecting this property.
Fall back to console mode on Unix
On Unix, users often operate in environments where no X11 server is available and no GUI can be displayed. The installer will fallback to console mode if console mode execution is allowed and this option is selected. Otherwise an error message will be displayed that tells the user how to invoke the installer in console mode.
Note: This property is only visible if "Allow console installations" is selected.
Console screen change handler
By default, a screen in console mode does not show any particular separation. You insert your own custom display with this script. The title parameter gives you access to the title of the screen. In console mode, screens display their subtitle only, so the title string will not be displayed again.
Note: This property is only visible if "Allow console installations" is selected.
Default execution mode [Execution Modes]
The default execution mode for the installer application. By default, a GUI wizard will be shown, but it is also possible to run in console mode or unattended mode by default.
Title for progress dialog
The title for the progress dialog, for example "Updating installation".This title and the unattended mode with a progress window can also be set by passing -splash [title] as an argument from the command line.
Note: This property is only visible if "Default execution mode" is set to "Unattended mode with progress dialog".
Windows console executable [Execution Modes]
If selected, a console executable will be created on Windows. A non-hideable console will be shown when the installer is double-clicked in the explorer. This improves the user experience for a console-only installer (default execution mode set to console) and allows execution through rsh.
Change working directory [Execution Options]
If selected the working directory will be changed to the value in 'Working directory' at startup.
Working directory [Execution Options]
The working directory to be used when 'Change working directory' is selected.
VM parameters [Execution Options]
If you need to pass special VM parameters to the installer application, you can enter them here.A common case would be to raise the maximum heap size with a different -Xmx parameter if your installers require a lot of memory.
Arguments [Execution Options]
If you need to pass fixed default arguments to the installer application, you can enter them here. For example, if you want to display a splash screen in unattended mode by default, you can set the arguments to -splash "Installing ...". Please note that command line arguments will be appended to this list, so it is not possible to "override" a fixed argument from the command line.
Window title [GUI Options]
The title of the application window.
Show message when user cancels [GUI Options]
If selected, a message will be shown when the user cancels the installer application by clicking on the "Cancel" button or closing the application frame.
Cancel message
The message that is shown if the user cancels the installer application by clicking on the "Cancel" button or closing the application frame. The options that are presented to the user are "Cancel" or "Continue".
Note: This property is only visible if "Show message when user cancels" is selected.
Custom image for title bar [GUI Options]
You can optionally choose a different image for the top right corner of the installer wizard. The recommended size for this image is 60 x 60 pixels. Clear to reset to the default image.
Icon can overlap text
If selected, the icon can overlap the title and subtitle text. In this case, the icon should be suitable as a background upon which black text can be read. If not selected, the image will be aligned at the right side of the screen, otherwise the anchor property below will be used.
Icon anchor
The anchor where the icon will be fixed in the title bar area.
Note: This property is only visible if "Icon can overlap text" is selected.
Background color for title bar [GUI Options]
With this property, you can adjust the background color of the title bar, the default value is suitable for the standard icon. Set to "None" in order to reset to the default value.
Foreground color for title bar [GUI Options]
With this property, you can adjust the foreground color of the title bar used for text, the default value is suitable for the standard background color. Set to "None" in order to reset to the default value.
Window width [GUI Options]
The width of the window displayed by the installer application. The default value is 500. If the "Size client area" property is selected, this does not include the size of the window frame border.
Window height [GUI Options]
The height of the window displayed by the installer application. The default value is 390.If the "Size client area" property is selected, this does not include the size of the window frame border.
Size client area [GUI Options]
If selected, the supplied size for the window will not be applied to the outer dimensions of the window, but to the actually usable area inside the window. Unusually large window frame borders can occur due to user settings (accessibility, window themes, etc.) and may interfere with banner images or introduce unwanted scroll bars to form screens.
Resizable [GUI Options]
If selected, the window displayed by the installer application is resizable.
Add install4j watermark to installer screens [GUI Options]
If selected, install4j watermarks will be added to the divider that separates the navigation buttons on every screen of the installer application.
Custom watermark text
By default, the watermark text is "install4j". If you would like to display a different text instead, you can enter it here.
Note: This property is only visible if "Add install4j watermark to installer screens" is selected.
Unix mode [Unix]
The executable mode for the custom application on Unix.
Execution level [Windows]
The execution level for this application. If you want to modify files in the installation direction, you most likely need administrator rights. This is only relevant for Windows Vista and higher.
Customize version info [Windows]
If selected, you can customize the fields of the Windows version info in the nested properties. A windows version info is always generated for the executable with default values for product name and file version taken from the general settings.
Product name
The product name field in the version resource. If empty, the full name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.
File version
The file version field in the version resource. If empty, the version from the general settings is used. The file version must consist of 4 numbers separated by spaces, commas or dots.
Note: This property is only visible if "Customize version info" is selected.
Internal name
The internal name field in the version resource. If empty, the short name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.
File description
The file description field in the version resource. If empty, the full name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.
Copyright
The copyright field in the version resource. If empty, the publisher name from the general settings is used.
Note: This property is only visible if "Customize version info" is selected.

The second tab in the configuration area for installer applications is the Installer variables tab. Here, you can check the bindings for all detected installer variables and pre-define installer variables. For more information, please see the help topic on variables and the help on the variable selection dialog.
An additional feature with respect to the variable selection dialog is that you can navigate to a binding by selecting an element in the binding tree at the bottom and click on the [Go To Selection] button.

Custom installer applications have a Launcher integrations tab in the configuration area that helps you to start them when launchers are executed.
The first way to start an installer application is programmatically, by using the API contained in [install4j installation directory]/resource/i4jruntime.jar. To get the code snippet for starting the selected installer application, click on the [Start integration wizard] button. The integration wizard will present a number of options that control the condition and possible call backs from the installer application. Note that you do not have to distribute i4jruntime.jar, since it is automatically available for installed applications.

The second way to start an installer application is automatically, by defining a launch schedule and a launch mode. The launch schedule is one of
- Always
  Every time you start the launcher, the installer application will be started as well.
- According to update schedule
  install4j provides a built-in update schedule registry that can be configured by the user on a form screen with an "Update schedule selector" form component. Also, you can programatically modify the update schedule through the class com.install4j.api.update.UpdateScheduleRegistry in the API. The selected installer application will be started only if the update schedule requires an update check.
- First run of any launcher in archive media file
  For archive media files (such as a Windows ZIP file), no installer is available. To execute a sequence of screens and actions when a launcher is started for the first time after the archive has been extracted, use this launch schedule. It may be convenient to link to screen groups in the installer in order to avoid duplicating configuration in your custom installer application.
  In your launcher, you can check for this condition with Boolean.getBoolean("install4j.firstRun") in case you want to perform some actions outside of a custom installer application.
The launch mode is one of
- Blocking at start up
  When the launcher is started, the selected installer application will be started first. When the installer application terminates, the launcher will then start up (unless a "Shut down calling launcher" action has been executed).
- Non-blocking at start up
  When the launcher is started, the selected installer application will be started immediately. The launcher continues to start up in parallel.
- When first window is shown
  The selected installer application will be started when the first window is shown. This works for AWT, Swing and SWT applications. If you have a SWT application, the "Uses SWT" check box in the executable info step of the launcher wizard must be selected.
Just like with the API, the installer application can be started in the launcher process itself or in a new process. By default, the installer application is started in the same process. If the "Blocking at start up" or "Non-blocking at start up" launch modes are selected, the look and feel it set to the system look and feel. For the "When first window is shown" launch mode, the look and feel is not changed, so your own look and feel will be used. When the installer application is executed in the same process, the "Shutdown calling launcher" action has a different effect: The whole process will be terminated when the installer application exits. Furthermore, the "Request privileges" action only works for elevating a helper process, not the main process in this case.

By default, the selected installer application is started for all launchers in your project. If this is not desired, you can restrict the integration to selected launchers. Note that if "All launchers" is selected and the project is merged into another project, the integration will be performed for all launchers in the main project as well.