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 control.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;

Using Control Scripts to Add Pages

To register a custom page, use the installer::addWizardPage() method and the object name set in the UI file (for example, "MyPage"). Then call the Dynamic${ObjectName}Callback() function (for example, DynamicMyPageCallback()):

function Controller()
{
    installer.addWizardPage(component, "MyPage", QInstaller.TargetDirectory)
}

Controller.prototype.DynamicMyPageCallback()
{
    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 qsTr() 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.

The context being used for translation is the basename of the script file when using qsTr or the class name of the UI file when translating a user interface. For example, if the script file is called installscript.qs, the context will be installscript.

Note: The translation system can also be used to customize the UI. Use e.g. an en.ts file to replace any text in the installer with a custom English version.

© 2016 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. The Qt Company, Qt and their respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.