Customizing Installers

You can use scripting to customize installers by:

• Adding Qt Installer Framework operations that are prepared by the scripts and performed by the installer.
• Adding new pages that you specify in the package.xml file and place in the packages directory.
• Modifying existing pages by inserting custom user interface elements into them as single widgets.
• Adding language variants.

You can use both component scripts and a control script to customize installers. A component script is associated with a particular component by specifying it in the Script element of the package.xml file of the component. The script is loaded when the component's metadata is fetched. For more information about component scripts, see Component Scripting.

A control script is associated with the whole installer by specifying it in the ControlScript element of the config.xml file of the installer. Control scripts can be part of the installer resources or be passed on the command line. They can be used to modify the installer pages that are presented to users before components are loaded. Also, you can use them to modify pages in the uninstaller. For more information, see Controller Scripting.

For more information about the global JavaScript objects that can be used in component and control scripts, see Scripting API.

Adding Operations

You can use component scripts to perform Qt Installer Framework operations during the installation process. Typically, operations manipulate files by moving, copying, or patching them. Use the QInstaller::Component::addOperation or QInstaller::Component::addElevatedOperation function to add operations. For more information, see Adding Operations to Components.

In addition, you can implement methods to register custom installation operations in the installer by deriving KDUpdater::UpdateOperation. For more information, see Registering Custom Operations.

For a summary of available operations, see Operations.

Adding Pages

A component can contain one or more user interface files, which are placed into the installer by a component or control script. The installer automatically loads all user interface files listed in the UserInterfaces element of the package.xml file.

Using Component Scripts to Add Pages

To add a new page to the installer, use the installer::addWizardPage() method and specify the location of the new page. For example, the following code adds an instance of MyPage before the ready for installation page:

installer.addWizardPage( component, "MyPage", QInstaller.ReadyForInstallation );

You can use component scripts to access the loaded widgets by calling the component::userInterface() method with the class name of the widget, as illustrated by the following code snippet:

component.userInterface( "MyPage" ).checkbox.checked = true;

You can also have a callback for the page that is added. To access it, use the object name set in the UI file (for example, "MyPage"). Then create the Dynamic${ObjectName}Callback function (for example, DynamicMyPageCallback):

Component.prototype.DynamicMyPageCallback = function()
{
    var page = gui.pageWidgetByObjectName("DynamicMyPage");
    page.myButton.click,
    page.myWidget.subWidget.setText("hello")
}

You can access widgets by using their object names that are set in the UI file. For example, myButton and myWidget are widget object names in the code above.

Adding Widgets

You can use component or control scripts to insert custom user interface elements into the installer as single widgets (such as a check box).

To insert a single widget, use the installer::addWizardPageItem method. For example, the following code snippet adds an instance of MyWidget to the component selection page from within a script:

installer.addWizardPageItem( component, "MyWidget", QInstaller.ComponentSelection );

Interacting with Installer Functionality

You can use control scripts to execute installer functions automatically in tests, for example. The following snippet illustrates how to automatically click the Next button on the target directory selection page:

Controller.prototype.TargetDirectoryPageCallback = function()
{
    gui.clickButton(buttons.NextButton);
}

Translating Pages

The installer uses the Qt Translation system to support the translation of user-readable output to several languages. To provide end users with localized versions of strings contained in the component scripts and user interfaces, create QTranslator files that the installation system loads along with the component. The installer loads the translation file that matches the current system locale. For example, if the system locale is German, the de.qm file is loaded. In addition, a localized license_de.txt is shown instead of the default license.txt if it is found.

Translations need to be added to the package.xml file to be activated for a component:

<Translations>
    <Translation>de.qm</Translation>
</Translations>

Use the qsTranslate() function for literal text within scripts. Additionally, you can add the Component.prototype.retranslateUi method to the script. It is called when the language of the installer changes and the translation file is loaded.

Configuring and Overwriting Default Translations

The installer has been localized into several languages. System language is used to define the loaded language. In case you want to define the used language for your installer, define the languages in config.xml using the <Translations> element. For example, using only German translations:

<Translations>
    <Translation>ifw_de</Translation>
    <Translation>qt_de</Translation>
</Translations>

The default translations can be also overwritten. Write your own translation file and add it to a custom resource called :/translations_new. This custom resource can be added to the installer using binarycreator option -r. For more information, see Summary of binarycreator Parameters.

If the translated language is not already part of the existing translations of Qt Installer Framework, you need to also include the Qt Base translation for that language in the resource file. For this you need to point to the qtbase_*.qm for your language from the location of QT_INSTALL_TRANSLATIONS and alias it in the resource file.

For example, for the Czech translation a custom translations_new.qrc should look like this:

<!DOCTYPE RCC><RCC version="1.0">
<qresource prefix="/translations_new">
    <file>ifw_cs.qm</file>
    <file alias="qt_cs.qm">%QT_INSTALL_TRANSLATIONS%/qtbase_cs.qm</file>
</qresource>
</RCC>

The path for replacing QT_INSTALL_TRANSLATIONS can be retrieved from the output of qmake -query of your Qt installation.