Component Scripting

For each component, you can specify one script that prepares the operations to be performed by the installer. The script format has to be compatible with QJSEngine.


The script has to contain a Component object that the installer creates when it loads the script. Therefore, the script must contain at least the Component() function, which performs initialization, such as putting pages in the correct places or connecting signals and slots.

The following code snippet places the ErrorPage (which is the class name of the user interface file loaded from errorpage.ui) in front of the ready for installation page and sets its completeness to false.

function Component()
    // Add a user interface file called ErrorPage, which should not be complete
    installer.addWizardPage( component, "ErrorPage", QInstaller.ReadyForInstallation );
    component.userInterface( "ErrorPage" ).complete = false;

For more information, see the documentation for installer::addWizardPage() and component::userInterface().

Installer Hooks

You can add the following hook methods into your script:

Component.prototype.retranslateUiCalled when the language of the installer changes.
Component.prototype.createOperationsSee component::createOperations().
Component.prototype.createOperationsForArchiveSee component::createOperationsForArchive().
Component.prototype.createOperationsForPathSee component::createOperationsForPath().

Global Variables

The installer puts the following symbols into the script space:

installerReference to the QInstaller of the component
componentReference to the Component of the component

Message Boxes

You can show a QMessageBox from within the script by using the following static members:

For your convenience, the values for QMessageBox::StandardButton are made available by using QMessageBox.Ok, QMessageBox.Open, and so on.

Adding Operations to Components

You might want to add custom operations after extracting the content, when copying files or patching file content, for example. You can create and add update operations to the installation from within a script using component::addOperation(). If you need to run an operation that requires administrative rights, use component::addElevatedOperation() instead.

Operations need to be added before the actual installation step. Override component::createOperations() to register custom operations for a component.

Each operation has a unique key used for identification and can take up to five parameters. In the parameter values, you can use variables as set in installer::setValue(). For more information, see Predefined Variables.

For a summary of all available operations, see Operations.

Registering Custom Operations

You can register custom installation operations in the installer by deriving the KDUpdater::UpdateOperation class. The following code displays the methods that you must implement:

#include <KDUpdater/UpdateOperation>

class CustomOperation : public KDUpdater::UpdateOperation
      setName( "CustomOperation" );

  void backup()
      // do whatever is needed to restore the state in undoOperation()

  bool performOperation()
      const QStringList args = arguments();
      // do whatever is needed to do for the given arguments

      bool success = ...;
      return success;

  void undoOperation()
      // restore the previous state, as saved in backup()

  bool testOperation()
      // currently unused
      return true;

  CustomOperation* clone() const
      return new CustomOperation;

  QDomDocument toXml()
      // automatically adds the operation's arguments and everything set via setValue
      QDomDocument doc = KDUpdater::UpdateOperation::toXml();

      // if you need any information to undo the operation you did,
      // add them to the doc here

      return doc;

  bool fromXml( const QDomDocument& doc )
      // automatically loads the operation's arguments and everything set via setValue
      if( !KDUpdater::UpdateOperation::fromXml( doc ) )
          return false;

      // if you need any information to undo the operation you did,
      // read them from the doc here

      return true;

Finally, you need to register your custom operation class, as follows:

#include <KDupdater/UpdateOperationFactory>

KDUpdater::UpdateOperationFactory::instance().registerUpdateOperation< CustomOperation >( "CustomOperation" );

Now you can use your operation in the installer in the same way as the predefined operations.

Predefined Variables

You can use the following predefined variables in scripts to facilitate directory access:

ProductNameName of the product to be installed, as defined in config.xml.
ProductVersionVersion number of the product to be installed, as defined in config.xml.
TitleTitle of the installation program, as defined in config.xml.
PublisherPublisher of the installation program, as defined in config.xml.
UrlProduct URL, as defined in config.xml.
StartMenuDirStart menu group, as defined in config.xml. Only available on Windows.
TargetDirTarget directory for installation, as selected by the user.
DesktopDirName of the directory that contains the user's desktop.

Only available on Windows.

osCurrent platform: "x11", "win", or "mac".

This variable is deprecated: Use systemInfo instead.

RootDirRoot directory of the filesystem.
HomeDirHome directory of the current user.
ApplicationsDirApplications directory.

For example, C:\Program Files on Windows, /opt on Linux and /Applications on OS X.

InstallerDirPathThe directory that contains the installer application executable.
InstallerFilePathThe file path of the installer application executable.
UserStartMenuProgramsPathThe path to the folder containing the items in the Start menu of the user.

For example, C:\Users\USERNAME\AppData\Roaming\Microsoft\Windows\Start Menu\Programs

Only available on Windows.

AllUsersStartMenuProgramsPathThe path to the folder containing the items in the Start menu for all users.

For example, C:\ProgramData\Microsoft\Windows\Start Menu\Programs

Only available on Windows.

The variables can be resolved by calls to installer::value(). If embedded in '@' they can also be part of strings passed as arguments to installation operations:

if (installer.value("os") === "win") {
    component.addOperation("CreateShortcut", "@TargetDir@/MyApp.exe", "@StartMenuDir@/MyApp.lnk");

© 2017 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.