// -*- mode:c++ -*-
/*!
  \page component-definition Component Definition
  \brief Documentation on how to create installer components.

  The Installer is based on the idea of having several components, which are either embedded in the
  installer itself or loaded from a remote repository. For both, embedding components into the installer
  and creating an online repository, you need to keep your components in a certain format readable
  by the installer.

  \section directory-structure Directory Structure

  Components are identified by a domain-like identifier. This
  has to be the name of the directory the component data has to be placed in.
  Within this directory, two subdirectories for \ref data "data" and \ref metadata "meta data" have to exist.

  A packages directory can look like this:

  \verbatim
  -packages
   - com.nokia.sdk
     - data
     - meta
   - com.nokia.sdk.qt
     - data
     - meta
   - com.nokia.sdk.qt
     - data
     - meta
  \endverbatim

  \section metadata Contents of the meta data directory

  The meta data directory contains all files which are not to be deployed by the installer but contain
  information about deployment.

  \subsection packagexml package.xml

  The file package.xml is the main source of information about the component. It's in XML and can look like this:

  \verbatim
  <?xml version="1.0"?>
  <Package>
      <DisplayName>QtGui</DisplayName>
      <Description>Qt gui libraries</Description>
      <Version>4.5.1</Version>
      <ReleaseDate>2009-04-23</ReleaseDate>
      <Name>com.nokia.sdk.qt.gui</Name>
      <Dependencies>com.nokia.sdk.qt.core-4.5.1</Dependencies>
      <Virtual>false</Virtual>
      <Script>installscript.qs</Script>
      <UserInterfaces>
          <UserInteface>specialpage.ui</UserInterface>
          <UserInteface>errorpage.ui</UserInterface>
      </UserInterfaces>
      <Translations>
          <Translation>sv_se.qm</Translation>
          <Translation>de_de.qm</Translation>
      </Translations>
  </Package>
  \endverbatim

  In the example above, you see several XML tags which are filled with values. The following tag names - values - are allowed:

  \li \b DisplayName The human readable name of the component - \a required.
  \li \b Description The human readable description of the component - \a required.
  \li \b Version The version number of the component - \a required.
  \li \b ReleaseDate The day this component version was released - \a optional.
  \li \b Name domain-like identification for this component - \a required.
  \li \b Dependencies Comma-separated list of \ref componentdependencies "dependencies" - \a optional.
  \li \b Virtual Set to true if this is a virtual component not showing up in the installer.
  \li \b SortingPriority Priority of this component when visible in the tree. Lowest priority number is on top.
  \li \b Script File name of a \ref componentscripting "script" being loaded - \a optional.
  \li \b UserInterfaces One ore more file names of \ref componentuserinterfaces "user interfaces" being loaded - \a optional.
  \li \b Translations One ore more file names of \ref componenttranslation "translations" being loaded - \a optional.
  \li \b UpdateText A description added to the component description if the component is an update - \a optional.
  \li \b NewComponent If this flag is set the component appears as an update if its not installed - \a optional.
  \li \b Important The package is marked as important. This is relevant for updates found with UpdateAgent.
  \li \b ForcedInstallation This packages must always be installed and can't get unchecked by the user.
  \li \b AutoSelectOn Define boolean expressions with other components names to define when this components gets autoselected.

  \subsection stuff Scripts, User interfaces and translations

  Additonally, all files named in the package.xml - scripts, user interfaces and translations - have to be in the meta data directory.
  In the example above, this should look like that:

  \verbatim
  -packages
   - com.nokia.sdk.qt.gui
     - data
     - meta
       - de_de.qm
       - errorpage.ui
       - installscript.qs
       - package.xml
       - specialpage.ui
       - sv_se.qm
  \endverbatim


  \subsection componentdependencies Component Dependencies

  Each component can have one or more components it depends on. This can be other real or virtual components. Every
  dependency as defined via its identifier and optionally its version. The version, if given, is separated by the identifier
  by a dash ('-') and can be prefixed by a comparision operator like '=', '>', '<', '>=' or '<=', which means that the version
  of the matching package is compared to the required version and has to be \a equal, \a greater, \a less, \a greater \a or \a equal or 
  \a less \a or \a equal as the version number given in the dependency. If no comparision operator is given, it defaults to '='.

  \subsection componenttranslation Component Translation

  As the installer makes use of the Qt Translation system, all user readable output can be translated to other languages. To make this
  work for strings contained in component scripts and user interfaces, components can provide QTranslator files, which get loaded by the 
  installation system when loading the component. The Installer always loads the translation file with a name matching the current system
  locale. For the system locale being German (Germany), this would be de_de.qm.

  Inside of scripts, you have to use the function qsTr() for literal text. Additionally your script can contain a method 
  Component.prototype.retranslateUi which is called whenever the language of the Installer has changed, i.e. after your translation file 
  was 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
  an user interface.

  \subsection componentuserinterfaces Component User Interfaces

  A component can contain one or more user interface files, which are placed into the installer by the script. The installer is automatically
  loading all ui files listed in the package.xml. You can access the loaded widgets by calling QInstaller::Component::userInterface with the class
  name of the widget:

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

  There are two ways of inserting custom user interface widgets into the installer: Inserting them as a single widget or inserting them as their
  own page. 
  
  To insert them as a single widget, use #QInstaller::Installer::addWizardPageItem. From within the script, this is done by:

  \code
  // add the instance of MyWidget to the component selection page
  installer.addWizardPageItem( component, "MyWidget", QInstaller.ComponentSelection ); \endcode

  To add a completely new page into the Installer, you need to specify in front of which page you want to add it.
  Adding the page is done with #QInstaller::Installer::addWizardPage.
  \code
  // add the instance of MyPage in front of the "Ready to Installation" page
  installer.addWizardPage( component, "MyPage", QInstaller.ReadyForInstallation ); \endcode

  \section data Contents of the data directory

  The data section can contain plain files or directories. Directories will be compressed to 7z archives on creation.
  Plain files will be put into the installer as they are.

  \note We recommend you to put 7zip compatible archives into the data directory.









  \page componentscripting Component Scripting
  \brief Documentation about the scripting abilities inside of components.

  Each component can specify one script handled by the Installer. It has to be compatible to QScriptEngine.

  \section constructor Construction

  The script has to provide an object Component, which will be created by the Installer when loading the script.
  Therefore the script must contains at least a function Component(), which can do all the initialization needed,
  like putting user interfaces in place or connecting signals/slots:

  \verbatim
  function Component()
  {
      // let's assume we have a user interface ErrorPage - which should not be complete
      installer.addWizardPage( component, "ErrorPage", QInstaller.ReadyForInstallation );
      component.userInterface( "ErrorPage" ).complete = false;
  }
  \endverbatim

  The example above places the user interface "ErrorPage" (which is the class name of the ui file loaded from errorpage.ui) in
  front of the installer page "Ready for Installation" and sets his completeness to false. See the documentation for 
  \link QInstaller::Installer::addWizardPage addWizardPage \endlink and
  \link QInstaller::Component::userInterface userInterface \endlink for details.

  \section hooks Hooks called by the Installer

  You can add several hook methods into your script:

  \b Component.prototype.retranslateUi is called, whenever the language of the Installer changes.

  \b Component.prototype.createOperations- see \link QInstaller::Component::createOperations \endlink

  \b Component.prototype.createOperationsForArchive - see \link QInstaller::Component::createOperationsForArchive \endlink

  \b Component.prototype.createOperationsForPath - see \link QInstaller::Component::createOperationsForPath \endlink

  \section globalvariables Global variables

  The Installer puts the following symbols into the scripts space:

  \li \b installer A reference to the component's \link QInstaller::Installer Installer \endlink
  \li \b component A reference to the component's \link QInstaller::Component Component \endlink

  All methods marked with Q_INVOKABLE as well as all signals, slots and properties can be used by the script.
 
  \section messageboxes Message boxes

  You can show a QMessageBox from within the script by using:
  \li QMessageBox.critical
  \li QMessageBox.information
  \li QMessageBox.question
  \li QMessageBox.warning

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





  \page installer The Installer
  \brief Documentation about everything with installation.
 
  \section installeroperations Installer Operations

  Update operations can be created and added to the installation from within a script using \link QInstaller::Component::addOperation Component::addOperation. \endlink
  Every operation has an unique key used for identification and up to five parameters. Inside of the parameters, you can use variables as set in 
  \link QInstaller::Installer::setValue Installer::setValue. \endlink See the \link predefinedvariables list of predefined variables. \endlink.
  
  This is a short list of available installer operations and their use.


  \subsection Copy

  \b Syntax: "Copy" \a source \a target

  Copies a file from \a source to \a target.


  \subsection Move

  \b Syntax: "Move" \a source \a target

  Moves a file from \a source to \a target.


  \subsection Delete

  \b Syntax: "Delete" \a filename

  Deletes the file specified by \a filename.

  
  \subsection Mkdir

  \b Syntax: "Mkdir" \a path

  Creates the directory path \a path.

  
  \subsection Rmdir

  \b Syntax: "Rmdir" \a path

  Removes the directory path \a path.

  
  \subsection AppendFile

  \b Syntax: "AppendFile" \a filename \a text

  Appends \a text to the file specified by \a filename. \a is threated as ASCII text.

  
  \subsection PrepenFile

  \b Syntax: "PrependFile" \a filename \a text

  Prepends \a text to the file specified by \a filename. \a is threated as ASCII text.

  
  \subsection Execute

  \b Syntax: "Execute" [{\aexitcodes}] \a command [\a parameter1 [\a parameter2 [\a parameter3 [\a parameter4]]]]

  Executes the command specified by \a command. Up to four parameters can be passed.
    
  Optionally, you can pass a comma separated list of numbers in {} as first argument, which defines the "valid" exit codes
  of the process, i.e. the codes the execution is considered being successful. This defaults to "{0}".
  
  \subsection CreateShortcut

  \b Syntax: "CreateShortcut" \a filename \a linkname [\a arguments]

  Creates a shortcut from the file specified by \a filename to \a linkname.
  On Windows, this will create a .lnk file which can have \a arguments, on Unix this will create a symobic link.

 
  \subsection CreateDesktopEntry

  \b Syntax: "CreateDesktopEntry" \a filename \a "key=value[\nkey2=value2[\nkey3=value3]]]"

  Creates an INI-file like .desktop file as specified by freedesktop.org
  If \a filename is absolute, the desktop entry is stored there. Otherwise it's stored in locations defined in $XDG_DATA_DIRS/applications
  or $XDG_DATA_HOME/applications, including the default pathes for boths, as defined by freedesktop.org.

  The key/value pairs are written in the file.

  The file is set to a encoding of UTF-8.

  \subsection InstallIcons
  
  \b Syntax: "InstallIcons" \a directory

  Installs the contents of \a directory into a location as specified by freedesktop.org, i.e. in any of $XDG_DATA_DIRS/icons or /usr/share/icons 
  or $HOME/.icons. The files are removed from their initial location. Make sure to add this operation after the operation extracting them form the archive.

  \subsection Extract

  \b Syntax: "Extract" \a archive \a targetdirectory

  Extracts \a archive to \a targetdirectory


  \subsection GlobalConfig

  \b Syntax: "GlobalConfig" \a company \a application \a key \a value <br>
  \a or <br>
  \b Syntax: "GlobalConfig" \a filename \a key \a value

  Stores \a value for \a key in a configuration file. The configuration file is either
  specified by \a filename (using QSettings::NativeFormat, which might be the Windows registry)
  or via the \a application and the \a company name.


  \subsection EnvironmentVariable

  \b Syntax: "EnvironmentVariable" \a key \a value [[\a persistent] \a system]

  Sets the envirnoment variable \a key to a \a value. If \a persistent is set to true, the variable
  will be set persistently. This is currently only supported on Windows. If \a system is set to true, the
  persistent variable will be set system wide, not only for the current user.


  \subsection RegisterFileType

  \b Syntax: "RegisterFileType" \a extension \a command [\a description [\a contentType [\a icon]]].

  Registers the file type with \a extension to be opened via \a command. Optionally, you can specify
  a \a description, a \a contentType and an \a icon. This is currently only supported on Windows.


  \section sec_customoperations Custom Operations

  It is possible to register custom installation operations in the Installer. This works by deriving KDUpdater::UpdateOperation.
  See the following code to know which methods must be implemented:

  \code
  #include <KDUpdater/UpdateOperation>

  class CustomOperation : public KDUpdater::UpdateOperation
  {
  public:
    CustomOperation()
    {
        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;
    }
  };
  \endcode

  Finally, you need to register your custom operation class:
  \code
  #include <KDupdater/UpdateOperationFactory>

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

  Now you can use your operation in the installer like every other of the predefined operations.


  \page toolchain Toolchain
  \brief Documentation about the different tools coming with the Installerbuilder

  \section binarycreator Installer Binary Creation

  Installer Binaries are created using binarycreator. This is done by appending information about
  components and even their data, in case of an offline installer, to a basic binary. Read 
  QInstaller::BinaryContent to know how this works. If you only want to use the provided installerbase, you
  don't need to care about this.

  \subsection Usage

  binarycreator expects the following parameters:

  \li <b>-t \a or --template \a file</b> Use \a file as input file <br>
      This is the binary used to append component information. <br>
      On Windows, this defaults to be installerbase.exe in the current working directory.
      On Unix, installerbase is used.

  \li <b>-p \a or --packages \a directory</b> Use \a directory as packaces directory <br>
      Specifies the directory to get package, i.e. component information from. See 
      \link component-definition Component Definition \endlink to find out how this directory need
      to look like. This setting defaults to the current working directory.

  \li <b>-n \a or --nodeps</b> Add only the selected packages to the compile. Don't add their dependencies.

  \li <b>-c \a or --config \a directory</b> Use \a directory as config directory <br>
      Specifies the directory to be used for \link installer-config Installer Configuration. \endlink

  \li <b>-e \a or --exclude \a p1,...,pn</b> Mark a comma separated list of packages to be retrieved 
      from an online repository, i.e. not to be completely included in the installer binary.

  \li <b>-v \a or --verbose</b> Verbose output. Add this if you are into lots of debug output.

  These parameters are followed by the name of the target binary and a list of packages to be
  availabe for installation. Note that not only these packages will be inside of the installer, but
  even all their dependencies and all packages sharing the same prefix, as long as you add the --nodeps flag.

  On Windows, the name of the target binary is automatically extended with .exe, if it wasn't already added by the user.
  On Mac, the target will be created as application bundle with extension .app, which as automatically added, if not supplied. Additionally, the user can use a .dmg extension, which will create a DMG disk image containing an .app bundle.

  \subsubsection Example

  <b>Offline installer</b>

  \verbatim
  binarycreator.exe -c installer-config SDKInstaller.exe com.nokia.sdk\endverbatim

  This commands puts com.nokia.sdk as well as all packages com.nokia.sdk depends on into the installer
  binary SDKInstaller.exe. Additionally, this binary will contain all packages prefixed with
  com.nokia.sdk.*

  <b>Online installer</b>

  \verbatim
  binarycreator.exe -c installer-config -e com.nokia.sdk.qt,com.nokia.qtcreator SDKInstaller.exe com.nokia.sdk\endverbatim

  The same as above, except that the data for com.nokia.sdk.qt and com.nokia.qtcreator will be downloaded
  from a remote repository.

  If your config.xml contains a RSA private key, components and data will be signed with it. On installer
  runtime, this signature will be used to verify the components. Note that the private key is \b not
  embedded in the installer binary. If your private key is protected with a password, you will be asked
  to provide the password.

  \subsection binacycreatorplatformspecific Platform specific notes

  \subsubsection mac Mac OS X

  \li If the target binary is suffixed with .app, a shiny Mac OS X application bundle will be created
  \li The icon set in the config.xml is extended with ".icns" and used as icon for a created bundle

  \subsubsection win Windows

  \li The icon set in the config.xml is extended with ".ico" and used as application icon for the .exe file.

  \subsection lin Linux

  \li The icon set in the config.xml is extended with ".png" and used as window icon.

  \section sec_repogen Online Repository generation

  To generate online repositories, use the tool repogen.

  \subsection Usage

  repogen expects the following parameters in this order:

  \li <b>Packages directory</b> Directory containing the packages. Same as for binarycreator.
  \li <b>Configuration directory</b> Directory containing the installer configuration. Same as for binarycreator.
  \li <b>Repository directory</b> Target directory to generate the repository. Must not yeut exist.
  \li <b>Components</b> List of components to be placed into the repository. Includes dependencies.

  If your config.xml contains a RSA private key, components and data will be signed with it. On installer
  runtime, this signature will be used to verify the components. Note that the private key is \b not
  put into the repository. If your private key is protected with a password, you will be asked
  to provide the password.
 
  When the repository has been created, you can upload it to anywhere. Just put the location into
  the \link installer-config installer configuration\endlink when creating an installer for it.

  \subsection Example

  \verbatim
  repogen.exe packages installer-config repository com.nokia.sdk.qt com.nokia.sdk.qtcreator\endverbatim

  This command creates a repository inside of \a repository containing com.nokia.sdk.qt and 
  com.nokia.sdk.qtcreator, including all dependencies.


  \page installer-config Installer Configuration
  \brief Explanation about how to configure the created installer
  
  For creation of installer binaries and online repositories, you need to provide a config directory.
  This directory needs to contain at least a file named config.xml containing XML information about
  how to build the installer.

  This file can look like this:
  \verbatim
<?xml version="1.0"?>
<Installer>
    <Name>Nokia SDK</Name>
    <Version>1.0.0</Version>
    <Title>Nokia SDK Setup</Title>
    <Publisher>Nokia</Publisher>
    <ProductUrl>http://qt.nokia.com</ProductUrl>
    <Logo>logo.png</Logo>
    <License>license.txt</License>
    <Watermark>watermark.png</Watermark>
    <RunProgram></RunProgram>
    <RunProgramDescription></RunProgramDescription>
    <StartMenuDir>Nokia SDK</StartMenuDir>

    <PublicKey>
        -----BEGIN PUBLIC KEY-----
        MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDzdb8ti9Ss5kmEY5rGf2HFEsj0
        W6dXOXRIO4W3XXr37Rzc8JI4UMZd6lEcxF9mdnoqOOyhHQABI8/CB2t9HTsZPRPC
        TCq43QLMfVMgI6A5Cgetv6osvZFgNG3nFAlRkLHw2gLO/zxoblY0wPq5p4xmYRh4
        f/YjsgYeA2v9V9FBAQIDAQAB
        -----END PUBLIC KEY-----
    </PublicKey>

    <PrivateKey>
        -----BEGIN RSA PRIVATE KEY-----
        Proc-Type: 4,ENCRYPTED
        DEK-Info: DES-EDE3-CBC,C9D3A294C3702C32

        unYGknjGs+FX+E5Bze/Kk2OZAvpJkYKhhJFJkiPekPy6FLPKDZX0oPyvNFjMnNPG
        wXNQe7Yr2WVMlFFmm92yCFXyzIrokr5Q8mUZEb1aJKHPCjTk4gmfOSCnwYrqPcLk
        XdFdr6e+yVsbaJ0zahPFQfaj4fUac9cK/qrMzwn1SxzYgW5+ZNp4KZVhWUkl8SE8
        TiwDMCN3wLNHzrSZr65A6XFKw5euSyCqcaqDH+tvxvmFZjb8QBhFf9APlTAQKcoK
        NrMGaUCOC96WDcKkj2iNLOUrp5vylo0/YDWKQdIsGHWGFV7L+M0aJgobdjKKXBKa
        ywqVhjgMo0e/cS/Ywtfuj9A3K6PnOrizYL+ukTAWfJdxdU8p91BhuoFR4CsYAJAW
        LZl/EfkCfJHOWgauGFkpvvaaIQMifJ6XObMZUVkYEi8e3jHxA653NmQIXRHoGgTW
        pr7T/AvZgTdrY0AuMcFHaWvKYrJD0CNwLtA7I+kcEMMa0c9Q2ryI8/qLYSRMMpDk
        fsUIiciPelpnruKGp8OQsrMPpmbDG2gYDA3y4aL7DDzZc8vx3ElsXcOU+Ri7asKR
        1fRhhK7tFI+IhU6oHPM1QkX+85hZQR6Rr7w1dapBITCxv/uepJQJfEeur/utn1wB
        EvSr8OSLgxFS7Nuc2R4vtHDb09DCSOqj0310GgtvI7NkrJqjx/dOmxjUEw29vRw6
        1iaV7JrEkAlXn0cJRXaZ4ujxoIx2lBKoDDrQ8n1OUMxKDqKF/NWWh6yrCcsuG2kN
        NBZ0kDxCbqe0cyKeCAFjtjUF1TsiAeXXZt+M3s12sKE0B5BXuir74A==
        -----END RSA PRIVATE KEY-----
    </PrivateKey>

    <Icon>qticon</Icon>

    <!-- @homeDir@ and @rootDir@ are some of the supported vars -->
    <TargetDir>@homeDir@/testinstall</TargetDir>
    <RemoteRepositories>
        <Repository>
            <Url>http://qt.nokia.com/packages/</Url>
        </Repository>      
    </RemoteRepositories>
</Installer>  \endverbatim

  \section Settings

  The following settings are contained in this file. All of them are actually optional.

  \li \b Name The name of the product being installed
  \li \b Version The version of the product being installed
  \li \b Title The title text of the generated installer, i.e. its name
  \li \b MaintenanceTitle The title text of the generated maintenance tool, i.e. its name
  \li \b Pushblisher The publisher of the software
  \li \b ProductUrl URL of the product
  \li \b Logo Filename for a logo used as QWizard::LogoPixmap
  \li \b License Filename of the license text to be accepted by the installing user
  \li \b Watermark Filename for a watermark used as QWizard::WatermarkPixmap
  \li \b Background Filename for an image used as QWizard::BackgroundPixmap
  \li \b RunProgram Command executed after the installer is done, if the user accepts it
  \li \b RunProgramDescription Text shown next to the checkbox for running the program. Defaults to "Run <Name>"
  \li \b StartMenuDir Name of the predefined group in the Windows Start Menu
  \li \b Icon Filename of the installer icon. On Windows, .ico is appended, on Mac, .icns is appended and on Linux, .png is appended.
  \li \b PublicKey RSA public key to be used to verify component signatures
  \li \b PrivateKey RSA private key to be used to sign components
  \li \b TargetDir Predefined target directory for installation
  \li \b RemoteRepositories List of \ref sec_repogen "remote repositories"
  \li \b UninstallerName File name of the generated uninstaller. Defaults to "uninstall". The platform specific executable suffixs is appended.

  \section remoterepo Remote Repositories

  The installer configuration file can contain a list of several remote repositories. Each of them has
  two properties. The first one is the repository URL. In the example above, this is "http://qt.nokia.com/packages/"
  The URL needs to contain a file Updates.xml listing the available packages. See \ref sec_repogen
  to read more about online repositories. The second parameter is "Required". If you set this to true,
  the installer won't work if this repository is not available. If you set it to false, it is working, but just without
  the packages from there.


  \page predefinedvariables Predefined variables
  \brief List over the predefined variables inside of the installer and their meaning

  \li ProductName The name of the product to be installed as defined in config.xml
  \li ProductVersion The version of the product to be installed as defined in config.xml
  \li Title The title of the installation program as defined in config.xml
  \li Publisher The publisher of the installation program as defined in config.xml
  \li Url Product URL as defined in config.xml
  \li StartMenuDir Start menu group as defined in config.xml. Applies only to Microsoft Windows
  \li LicenseFile File name of the program license as defined in config.xml
  \li TargetDir Target directory for installation as selected by the user.
  \li DesktopDir Directory containing the user's desktop.
  \li os The current platform, might be "x11", "win" or "mac"

  \note You can use these variables inside of the parameter list for installation operations.
  "{TargetDir}/settings.xml" might be expanded to "C:/Program Files/My Program/settings.xml".

  \page non-interactive-installation
  \brief page and scripted messagebox handling
  
  \section Installer Page Callbacks
  
  \subsection builtinpages Built-in pages
  
  \subsubsection IntroductionPageCallback
  Wizard buttons:
  \li  Next
  \li  Cancel

  \subsubsection LicenseAgreementPageCallback
  Wizard buttons: 
  \li Next
  \li Cancel
  \li Back

  Radio buttons:
  \li acceptLicenseRB (radio button): Accepts the license Agreement (unchecked by default)
  \li rejectLicenseRB (radio button): Rejects the license Agreement (checked by default)

  \subsubsection TargetDirectoryPageCallback

  Wizard buttons: 
  \li Next 
  \li Cancel 
  \li Back

  targetDirectoryLE (line edit): The target directory for installation

  \subsubsection ComponentSelectionPageCallback

  Wizard buttons: 
  \li Next 
  \li Cancel 
  \li Back

  Methods:

  \li selectComponent( id ): selects the component with the ID id (string)
  \li deselectComponent( id ): deselects the component with the ID id (string)

  In uninstallation mode, additional controls are available:

  \li uninstallAllComponentsRB (radio button): Uninstall all components (default)
  \li keepSelectedComponentsRB (radio button): Uninstall only unselected components (deselectComponent/selectComponent to modify them)

  \subsubsection ReadyForInstallationPageCallback

  Wizard buttons: 
  \li Next ("Install") 
  \li Cancel 
  \li Back

  \subsubsection PerformInstallationPage

  details.button (push button): Shows/hides installation details

  Wizard buttons: Cancel

  \subsubsection FinishedPageCallback

  Wizard buttons:
  \li Finish

\subsection Custom Pages

Custom pages are registered as Dynamic${ObjectName}, where ${ObjectName} is the object name set in the UI file.
Thus the callback called is Dynamic${ObjectName}Callback(). Widgets can be addressed using their object names (from the UI file):

var page = pageWidgetByObjectName( "DynamicSomePage" )
page.myButton.click //direct child of the UI file's widgte
page.someFancyWidget.subWidget.setText( "foobar" ) // nested widget
  
  
  \section messageboxes
	<table>
		<tr>
			<th>Identifier</th>
			<th>Possible Answers</th>
			<th>Description</th>
		</tr>
		<tr>
			<td>cancelInstallation</td>
			<td>Yes, No</td>
			<td>Confirmation for canceling the installation (Cancel button in the wizard)</td>
		</tr>
		<tr>
			<td>overwriteTargetDirectory</td>
			<td>Yes, No</td>
			<td>Confirmation to use an already existing directory as target</td>
		</tr>
		<tr>
			<td>installationError</td>
			<td>Ok</td>
			<td>A fatal error occurred while performing the installation</td>
		</tr>
		<tr>
			<td>installationErrorWithRetry</td>
			<td>Retry, Ignore, Cancel</td>
			<td>An error occurred while performing the installation, Retry possible</td>
		</tr>
		<tr>
			<td>metaInfoJobError</td>
			<td>Ok</td>
			<td>Error occurred retrieving meta information (online installer)</td>
		</tr>
	</table> 
  \page testnokia testing of the nokia installer
  \brief List of the pages and their components from the nokia installer
  
  \section customized pages
  
  \subsection TargetDirectoryPage
  The target directory page got a custom UI file called InstallationKindWidget
  that contains two radio buttons.
  Radio buttons:
  
  \li CustomRadioButton (radio button): Shows the ComponentSelectionPage (unchecked by default)
  \li FullRadioButton (radio button): Marks all available packages for installation (checked by default)
  
  Be aware with the version from 2010_04_06_16_39 setting the CustomRadioButton to checked has no
  effect other than marking the button if next ist clicked the full installation is still performed.
  Only a mouseklick changes the installation behavior as the script uses a buttonReleasedSignal to
  change that behavior.
  

*/