12. Installer Customization

Installers created with InstallBuilder can be customized in a variety of ways, including language, size and other aspects which are described in the following sections.

12.1. Languages

InstallBuilder supports installations in multiple languages. The following table lists all of the available languages and their codes:

Supported Languages

code

language name

sq

Albanian

ar

Arabic

es_AR

Argentine Spanish

az

Azerbaijani

eu

Basque

pt_BR

Brazilian Portuguese

bg

Bulgarian

ca

Catalan

hr

Croatian

cs

Czech

da

Danish

nl

Dutch

en

English

et

Estonian

fi

Finnish

fr

French

de

German

el

Greek

he

Hebrew

hu

Hungarian

id

Indonesian

it

Italian

ja

Japanese

kk

Kazakh

ko

Korean

lv

Latvian

lt

Lithuanian

no

Norwegian

fa

Persian

pl

Polish

pt

Portuguese

ro

Romanian

ru

Russian

sr

Serbian

zh_CN

Simplified Chinese

sk

Slovak

sl

Slovenian

es

Spanish

sv

Swedish

th

Thai

zh_TW

Traditional Chinese

tr

Turkish

tk

Turkmen

va

Valencian

vi

Vietnamese

cy

Welsh

[Note]

Right to left languages such as Arabic and Hebrew are currently only supported in InstallBuilder for Qt

By default, the language selection dialog is not displayed but it can be enabled just by modifying the <allowLanguageSelection> tag:

  <project>
     ...
     <allowLanguageSelection>1</allowLanguageSelection>
     ...
  </project>

By default, it will display both the English and the native version of the languages, as displayed in Figure 54. However it can also be configured to show just the English or the native version using the <languageSelectionStyle> project property, which allows: default (for both the English and the native version, Figure 54), onlyNativeNames (for the native representation of the language , Figure 55) and onlyEnglishNames (for just the English name, Figure 56)

  <project>
     ...
     <languageSelectionStyle>default</languageSelectionStyle>
     ...
  </project>

Figure 60. Default Language Selection

Default Language Selection

  <project>
     ...
     <languageSelectionStyle>onlyNativeNames</languageSelectionStyle>
     ...
  </project>

Figure 61. Native Only Language Selection

Native Only Language Selection

  <project>
     ...
     <languageSelectionStyle>onlyEnglishNames</languageSelectionStyle>
     ...
  </project>

Figure 62. English Only Language Selection

English Only Language Selection

Out of all of the languages supported by InstallBuilder, you can configure which of them will be available in your installer using the <allowedLanguages> tag:

  <project>
     ...
     <allowedLanguages>en es ja</allowedLanguages>
     <defaultLanguage>es</defaultLanguage>
     ...
  </project>

The snippet above also uses the <defaultLanguage> tag to specify the default language to use. When enabling the language selection, this will be the selected item in the dialog and when the language selection is disabled, it will be automatically configured as the installation language.

Take into account that the <defaultLanguage> must be one of the allowed languages or it will be ignored, using the first allowed language instead.

You can also use the installer-language command line flag to overwrite the <defaultLanguage> setting. The allowed values will be those configured in <allowedLanguages>:

$> sample-1.0-linux-installer.run --installer-language ja

Autodetecting the System Language

The <defaultLanguage> tag also allows a special code, auto, that will make the installer autodetect the system language and use it as the default language:

  <project>
     ...
     <defaultLanguage>auto</defaultLanguage>
     <allowedLanguages>de en es ja</allowedLanguages>
     ...
  </project>

If the autodetected language does not match any of the allowed languages configured using <allowedLanguages> (in case any was provided), the first language in the list will be used, de in the above example. If the <allowedLanguages> value was not specified or was set to empty, it will be ignored. In the event that the autodetected language is not supported by InstallBuilder, en will be used as the language.

You can also check which language was selected at runtime by accessing the built-in variable ${installation_language_code}.

12.2. Changing Built-in Installer Text Strings

InstallBuilder allows customizing most of its built-in language strings using custom language files. These files are basically plain text files with an INI-style format. The keys are language string identifiers that will be shared among all languages (database.title, database.explanation, database.description). The values contain the corresponding text strings for each language (Database Selection, Default database, Which database?). For example, to modify the Welcome Page, you can create a new language file custom-en.lng with the strings to override the default ones:

Built-in strings in en.lng

...
Installer.Welcome.Title=Setup - %1$s
Installer.Welcome.Text=Welcome to the %1$s Setup Wizard.
...

New custom-en.lng strings. 

Installer.Welcome.Title=Installation of %1$s
Installer.Welcome.Text=This is the installer of %1$s.

You can then load the new file in your project:

<customLanguageFileList>
   <language>
      <code>en</code>
      <file>path/to/custom-en.lng</file>
   </language>
</customLanguageFileList>

You can download the complete list of tags or request the latest version by writing to us at support@bitrock.com. A copy of the language file is also included in all InstallBuilder installations inside the docs directory:

$> /home/user/installbuilder-17.1.0/docs/userguide/en.lng

Please note that although the original file contains many other strings, you only need to specify those that need to be modified in your language file.

Some of the built-in strings contain special identifiers with names like %1$s. This refers to a value that will be automatically substituted at runtime by the installer (in most cases the full product name). Other common fields inserted in messages are filenames when the string is related to file manipulation actions or error information:

...
Installer.Welcome.Text=This is the installer of %1$s.
...
Installer.Error.Installation.CreatingDirectory=Error creating directory %1$s
...
Installer.Error.PostInstallScript=Error executing post installation script\n%1$s\n\%2$s
...

The internally provided values for the identifiers cannot be modified but if you need to display different settings, you can just use regular InstallBuilder variables. For example, to include the short name and version instead of the full name in the previous string, you could rewrite your translation as:

...
Installer.Welcome.Text=This is the installer of ${project.shortName}-${project.version}.
...

Or mix both:

...
Installer.Welcome.Text=This is the installer of %1$s (${project.shortName}-${project.version}).
...

Where the above string will be resolved as: This is the installer of Sample Installer (sample-1.0).

Adding New Localized Strings

InstallBuilder includes complete language translations for all its built-in messages, but if you customize the installer with new screens or dialogs, you will need to add the strings to your custom language files. You will need to provide a custom language file for each of the languages supported by your installer:

custom-en.lng:

database.title=Database Selection
database.explanation=Default database
database.description=Which database?

custom-es.lng:

database.title=Selección de base de datos
database.explanation=Base de datos por defecto
database.description=Qué base de datos?

Once you have created a language file for each of your supported languages, you will need to load them from your XML project:

  <project>
     ...
     <customLanguageFileList>
       <language>
         <code>en</code>
         <encoding>iso8859-1</encoding>
         <file>path/to/custom-en.lng</file>
       </language>
       <language>
         <code>de</code>
         <encoding>iso8859-1</encoding>
         <file>path/to/custom-de.lng</file>
       </language>
       <language>
         <code>fr</code>
         <encoding>iso8859-1</encoding>
         <file>path/to/custom-fr.lng</file>
       </language>
     </customLanguageFileList>
     ...
  </project>

Please note that the language files are mapped to the desired language using the <code>. It is also very important to configure the <encoding> accordingly to your language files or you could end up with an unreadable translation.

Those language files will then be included in the installer at build time and the translated strings will be available at runtime using the ${msg()} notation. The following example shows how the strings above can be used to localize a choice parameter:

<choiceParameter>
   <ask>1</ask>
   <default>oracle</default>
   <description>${msg(database.description)}</description>
   <explanation>${msg(database.explanation)}</explanation>
   <title>${msg(database.title)}</title>
   <name>database</name>
   <optionList>
     <option>
       <value>oracle</value>
       <text>Oracle</text>
     </option>
     <option>
       <value>mysql</value>
       <text>Mysql</text>
     </option>
   </optionList>
</choiceParameter>

Component-Level Translations

Components can also provide their own <customLanguageFileList>. The component-level language files will be processed after the main one (project level) and the keys there will overwrite the project-level ones. This feature allows you to share translations among multiple projects.

When a specific language is needed for a particular installer, you can add a translation component that will take care of redefining some of the language strings:

  <project>
     ...
     <customLanguageFileList>
       <language>
         <code>en</code>
         <encoding>iso8859-1</encoding>
         <file>path/to/custom-en.lng</file>
       </language>
     </customLanguageFileList>
     ...
     <componentList>
       <component>
          <name>translations</name>
          <show>0</show>
          <customLanguageFileList>
            <language>
              <code>en</code>
              <encoding>iso8859-1</encoding>
             <file>path/to/alternative-custom-en.lng</file>
            </language>
          </customLanguageFileList>
       </component>
     </componentList>
     ...
  </project>

Displaying a Localized License and Readme

You can specify multiple localized versions for your <licenseFile> using the <licenseFileList> tag. Take into account that you still need to provide a value for the <licenseFile> tag to make the installer show the license page. This <licenseFile> will be also used as the default license file in case there’s no localized license file for the current language.

Inside this tag, you can add as many <licenseFile> elements as localized licenses you provide. For each <licenseFile> element, you’ll need to provide the license file path, its language identifier and the file encoding.

Here’s an example of how it works:

<licenseFileList>
   <licenseFile>
     <code>en</code>
     <file>/home/user/license-english.txt</file>
     <encoding>iso8859-1</encoding>
   </licenseFile>
   <licenseFile>
     <code>ja</code>
     <file>/home/user/license-japanese.txt</file>
     <encoding>utf-8</encoding>
   </licenseFile>
</licenseFileList>

The installer will pick the right license file depending on the current selected language for the installer.

If you need to display more than one license page, or simply to make them display conditionally, you can use a <licenseParameter>:

<licenseParameter>
    <name>myLicense</name>
    <title>License Agreement</title>
    <description>Please read the following License Agreement. You must accept
    the terms of this agreement before continuing with the installation.</description>
    <explanation></explanation>
    <file>some/default/license.txt</file>
    <htmlFile>some/default/license.html</htmlFile>
    <licenseFileList>
      <licenseFile>
        <code>en</code>
        <file>/home/user/license-english.txt</file>
        <htmlFile>/home/user/license-english.html</htmlFile>
        <encoding>iso8859-1</encoding>
      </licenseFile>
      <licenseFile>
        <code>ja</code>
        <htmlFile>/home/user/license-japanese.html</htmlFile>
        <file>/home/user/license-japanese.txt</file>
        <encoding>utf-8</encoding>
      </licenseFile>
    </licenseFileList>
</licenseParameter>

You can do a similar arrangement with readme files and the <readmeFileList> tag:

<readmeFileList>
  <readmeFile>
    <code>en</code>
    <file>/home/user/readme-english.txt</file>
    <encoding>iso8859-1</encoding>
  </readmeFile>
  <readmeFile>
    <code>ja</code>
    <file>/home/user/readme-japanese.txt</file>
    <encoding>utf-8</encoding>
  </readmeFile>
</readmeFileList>

Providing a main <readmeFile> at the <project> level is required to enable the readme file. This <readmeFile> will be used as the default readme file in case there’s no localized readme file for the current language.

[Note]

Even if the installer provides a project level <licenseFileList>, the license page won’t be displayed if a value is not provided to the <licenseFile>, the default license file will display if the localized license for the current language was not provided.

The <readmeFile> follows the same rule. If a value is not provided for the default readme file, no readme will be displayed, despite of the value of the <readmeFileList>. The <readmeFile> will also be used if a localized readme was not provided for the current language.

[Note]HTML license and readme files in Qt mode

Both the main license file (using the <htmlLicenseFile>) and the <licenseParameter> are capable of displaying html files in qt mode. As they are only allowed in qt mode, you still have to provide a regular <file>:

<project>
   <shortName>sample</shortName>
   <fullName>Sample Project</fullName>
   <version>1.0</version>
   <installerFilename></installerFilename>
   <licenseFile>some/default-license.txt</licenseFile>
   <htmlLicenseFile>some/default-license.html</htmlLicenseFile>
   ...
   <licenseFileList>
      <licenseFile code="de" file="main-license_de.txt" htmlFile="main-license_de.html"/>
      <licenseFile code="en" file="main-license_en.txt" htmlFile="main-license_en.html"/>
      <licenseFile code="es" file="main-license_es.txt" htmlFile="main-license_es.html"/>
   </licenseFileList>
   ...
   <parameterList>
     <licenseParameter>
       <name>otherLicense</name>
       <title>Other License Agreement</title>
       <file>some/default/other-license.txt</file>
       <htmlFile>some/default/other-license.html</htmlFile>
       <licenseFileList>
          <licenseFile code="de" file="other-license_de.txt" htmlFile="other-license_de.html"/>
          <licenseFile code="en" file="other-license_en.txt" htmlFile="other-license_en.html"/>
          <licenseFile code="es" file="other-license_es.txt" htmlFile="other-license_es.html"/>
       </licenseFileList>
     </licenseParameter>
   </parameterList>
   ...
</project>

Although the <readmeFile> cannot display HTML text, you could use an <infoParameter> instead:

<infoParameter>
  <name>readme</name>
  <title>Readme</title>
  <explanation>Readme</explanation>
  <value>${textValue}</value>
  <htmlValue>${htmlValue}</htmlValue>
   <preShowPageActionList>
     <readFile>
        <path>${installdir}/readme.html</path>
        <name>htmlValue</name>
     </readFile>
     <readFile>
        <path>${installdir}/readme.txt</path>
        <name>textValue</name>
     </readFile>
   </preShowPageActionList>
</infoParameter>

12.3. Images

InstallBuilder provide default images for all the generated installers but you can also configure them. All images need to be provided in PNG format except for:

  • Windows installer and uninstaller icons (which must be provided in ICO format)
  • OS X installer and uninstaller icons (which must be provided in ICNS format)

Splash Screen

It is possible to configure the splash screen image and the time while it will be displayed:

<project>
   ...
   <splashImage>path/to/mySplash.png</splashImage>
   <!-- Additional delay in milliseconds -->
   <splashScreenDelay>3000</splashScreenDelay>
   ...
</project>

The splash image will be displayed for an additional 3 seconds (in addition to the built-in delay of 1 second).

The splash screen can be also disabled using the <disableSplashScreen> setting:

<project>
   ...
   <disableSplashScreen>1</disableSplashScreen>
   ...
</project>

Figure 63. Splash Screen

Splash Screen

Left and Top Images

It is possible to configure the images that will appear on the left side and the top right corner of the wizard UI, as shown below:

<project>
   ...
   <style>standard</style>
   <logoImage>path/to/topImage.png</logoImage>
   <leftImage>path/to/leftImage.png</leftImage>
   ...
</project>

The layout of the installer pages and when the left and top images are displayed depends on the <style> configured in the project.

InstallBuilder supports two display styles:

  • Standard Style:

In the standard style, the left image is displayed in the welcome and the final page and the top image is displayed in all the parameter pages and the readytoinstall page. The installation page will also display the top image if no slideshow images were configured or the slideshow if they were.

<project>
   ...
   <style>standard</style>
   ...
</project>
  • Custom Style:

When using the custom style, no top right image is displayed and all of the pages will show the left image. Parameter pages can configure the left image displayed through their <leftImage> property:

<project>
   ...
   <style>custom</style>
   ...
   <parameterList>
      <directoryParameter>
         <name>installdir</name>
         <description>Installer.Parameter.installdir.description</description>
         ...
         <leftImage>path/to/installdir_image.png</leftImage>
         ...
      </directoryParameter>
   </parameterList>
   ...
</project>

Figure 64. Custom Style Welcome

Custom Style Welcome

Figure 65. Custom Style Parameter Page

Custom Style Parameter Page

Figure 66. Custom Style Ready to Install

Custom Style Ready to Install

Figure 67. Custom Style Installation Page

Custom Style Installation Page

Figure 68. Custom Style Installation Finished

Custom Style Installation Finished

The installation page will also display the project level left image if no slideshow images were configured or the slideshow if they were.

<project>
   ...
   <style>custom</style>
   ...
</project>

Windows specific images

Windows Icons

Windows icons are also customizable for both the installer and the uninstaller. InstallBuilder expects an ICO file containing the below images:

  • 64 x 64 pixels, 32bpp (16.7 million Colors)
  • 48 x 48 pixels, 32bpp (16.7 million Colors)
  • 32 x 32 pixels, 32bpp (16.7 million Colors)
  • 24 x 24 pixels, 32bpp (16.7 million Colors)
  • 16 x 16 pixels, 32bpp (16.7 million Colors)
  • 48 x 48 pixels, 8bpp (256 Colors)
  • 32 x 32 pixels, 8bpp (256 Colors)
  • 16 x 16 pixels, 8bpp (256 Colors)

Although some of them can be skipped, you must at least provide the following sizes:

  • 48 x 48 pixels, 32bpp (16.7 million Colors) or 8bpp (256 Colors)
  • 32 x 32 pixels, 32bpp (16.7 million Colors) or 8bpp (256 Colors)
  • 16 x 16 pixels, 32bpp (16.7 million Colors) or 8bpp (256 Colors)

If your icon file contains any additional images (such as a 256x256 image), they will just be ignored.

Those icons must then be configured in your project:

<project>
   ...
   <windowsExecutableIcon>path/to/installer.ico</windowsExecutableIcon>
   <windowsUninstallerExecutableIcon>path/to/uninstaller.ico</windowsUninstallerExecutableIcon>
   ...
</project>

If the uninstaller icon is not configured explicitly, the installer icon will be used instead. Similarly, if no installer icon is specified, the default InstallBuilder icon will be used.

The locations specified in the <windowsExecutableIcon> and <windowsUninstallerExecutableIcon> refer to files in the build machine.

Other Windows images

Apart from the installer and uninstaller icons, you can also provide images for other settings:

  • Add/Remove Programs Menu Icon: This icon is configured through the <productDisplayIcon> tag and will be displayed in the ARP menu in addition to your application details. The icon is configured at runtime so the provided location must point to a file in the target machine, in most of the cases, installed by your application:

<project>
   ...
   <!-- Path in the target machine -->
   <productDisplayIcon>${installdir}/icons/arp.ico</productDisplayIcon>
   ...
   <componentList>
     <component>
        <name>windowsComponent</name>
        <folderList>
          <folder>
            <name>icons</name>
             <destination>${installdir}</destination>
               <distributionFileList>
                  <!-- Directory containing arp.ico icon -->
                  <distributionDirectory origin="/path/to/icons"/>
               </distributionFileList>
          </folder>
        </folderList>
     </component>
   </componentList>
</project>
  • Shortcuts icons: When creating shortcuts to executables on Windows, the icon of the application will be used. If the shortcut points to a different file-type such as a .txt or .bat file, the icon of the associated program will be displayed. Of course, you can also provide your own custom icon:

 <createShortcuts>
    <destination>${windows_folder_startmenu}/${project.fullName}</destination>
    <shortcutList>
      <shortcut>
        <comment>Launches ${project.fullName}</comment>
        <name>Launch ${project.fullName}</name>
        <windowsIcon>${installdir}/icons/custom.ico</windowsIcon>
        <windowsExec>${installdir}/myApp.exe</windowsExec>
      </shortcut>
    </shortcutList>
  </createShortcuts>

The <windowsIcon> tag can also point to an executable. In that case, the icon of the referenced binary will be used. For example, to configure you .bat files to look like a cmd prompt:

 <createShortcuts>
    <destination>${windows_folder_startmenu}/${project.fullName}</destination>
    <shortcutList>
      <shortcut>
        <comment>Launches ${project.fullName}</comment>
        <name>Launch ${project.fullName}</name>
        <windowsIcon>%SystemRoot%\system32\cmd.exe</windowsIcon>
        <windowsExec>${installdir}/script/wrapped-shell.bat</windowsExec>
      </shortcut>
    </shortcutList>
  </createShortcuts>

OS X Icons

Similarly to Windows, OS X installer and uninstaller application bundles can also include custom icons, provided using the <osxApplicationBundleIcon> and <osxUninstallerApplicationBundleIcon> project properties:

<project>
   ...
   <osxApplicationBundleIcon>path/to/Bundle.icns</osxApplicationBundleIcon>
   <osxUninstallerApplicationBundleIcon>path/to/UninstallerBundle.icns</osxUninstallerApplicationBundleIcon>
   ...
</project>

InstallBuilder will check if the provided icons are valid .icns files and will throw an error if the check fails. In addition, you must take into account the required icons in your .icns file as described in the Apple guidelines. At a minimum, the icon bundle must contain the following sizes:

  • 512 x 512 pixels (For finder icons in OS X 10.5 and later)
  • 128 x 128 pixels
  • 32 x 32 pixels
  • 16 x 16 pixels

Other images

Window Manager Image

The <wmImage> tag expects a 48x48 GIF or PNG logo image that will be shown in the window manager task bar. On Windows and OS X, when running in Qt mode, it will also be used as the window icon (displayed in the window title bar). On Windows, in modes other than Qt, the window icon will be obtained from the 16pixel image included in the executable.

If a <wmImage> is not provided, a default image is displayed.

  <project>
    ...
    <wmImage>path/in/the/build/machine/logo.png</wmImage>
    ...
  </project>
Slide Show Images

InstallBuilder allows displaying a slide show while the files are being copied. This is really useful to show your application features or promote other products or services from your company. Each slide is represented by a 500x222 GIF or PNG image configured using a <slideShowImage> element:

  <project>
    ...
    <slideShowImageList>
       <slideShowImage>
          <path>path/to/image1.png</path>
       </slideShowImage>
       <slideShowImage>
          <path>path/to/image2.png</path>
       </slideShowImage>
       <slideShowImage>
          <path>path/to/image3.png</path>
       </slideShowImage>
    </slideShowImageList>
    ...
  </project>

Where the paths to the images correspond to where they are located at build time.

The behavior of the slide show can be configured to continuously loop during the installation (through the <slideShowLoop> tag) or not. The number of seconds that each image will be displayed can be also defined (specified in the <slideShowTiming> tag). For example, if you want to display 5 slides without repeating them with 10 seconds for each of them, you can use:

  <project>
    ...
    <slideShowLoop>0</slideShowLoop>
    <slideShowTiming>10</slideShowTiming>
    <slideShowImageList>
       <slideShowImage>
          <path>path/to/feature1.png</path>
       </slideShowImage>
       <slideShowImage>
          <path>path/to/feature2.png</path>
       </slideShowImage>
       <slideShowImage>
          <path>path/to/feature3.png</path>
       </slideShowImage>
       <slideShowImage>
          <path>path/to/feature4.png</path>
       </slideShowImage>
       <slideShowImage>
          <path>path/to/feature5.png</path>
       </slideShowImage>
    </slideShowImageList>
    ...
  </project>
Label Parameter Images

It is also possible to display images in custom parameter pages using a <labelParameter>, which allows providing an image in its <image> tag:

<parameterGroup>
    <name>autoupdate</name>
    <title>AutoUpdate</title>
    <orientation>horizontal</orientation>
    <parameterList>
        <labelParameter>
            <name>autoUpdateImage</name>
            <image>/path/to/autoupdate.png</image>
        </labelParameter>
        <booleanParameter>
            <name>includeAutoUpdate</name>
            <description>Install AutoUpdate</description>
            <default>1</default>
            <displayStyle>radiobuttons</displayStyle>
        </booleanParameter>
    </parameterList>
</parameterGroup>

Figure 69. Image in a Label Parameter

Image in a Label Parameter

Option Images

It is also possible to add images to the <option> elements used in a <choiceParameter>:

<choiceParameter>
   <name>dbmsserver</name>
   <description>DBMS</description>
   <explanation>Database server</explanation>
   <allowEmptyValue>1</allowEmptyValue>
   <displayType>combobox</displayType>
   <optionList>
     <option>
       <description>MySQL server</description>
       <text>MySQL</text>
       <value>mysql</value>
       <image>${build_project_directory}/img/mysql-logo.png</image>
     </option>
     <option>
       <description>PostgreSQL server</description>
       <text>PostgreSQL</text>
       <value>postgres</value>
       <image>${build_project_directory}/img/postgresql-logo.png</image>
     </option>
   </optionList>
</choiceParameter>

Recommended Image Sizes

Although InstallBuilder will try to accommodate the layout of the pages to any image size, there are recommended sizes for some of them. The table below summarizes those sizes:

Table 4. Recommended image sizes

Image Width Height

Left panel image (<leftImage>)

163 pixels

314 pixels

Top right image (<logoImage>)

48 pixels

48 pixels

SlideShow image (<slideShowImage>)

500 pixels

222 pixels

Splash screen (<splashImage>)

300-350 pixels

100-150 pixels