installer-framework/doc/scripting.qdoc

/*!
    \contentspage{index.html}{InstallerFramework}
    \page scripting.html

    \title Component Scripting

    \section1 Scripting abilities inside of components

    Each component can specify one script, which is loaded and run by the
    installer. The format has to be compatible to QScriptEngine.

    \section1 Contruction

    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:

    \code
    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;
    }
    \endcode

    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 addWizardPage and userInterface for details.

    \section1 Installer Hooks

    You can add several hook methods into your script:

    \list
    \o \bold{Component.prototype.retranslateUi} is called, whenever the language of the Installer changes.
    \o \bold{Component.prototype.createOperations} - see QInstaller::Component::createOperations
    \o \bold{Component.prototype.createOperationsForArchive} - see QInstaller::Component::createOperationsForArchive
    \o \bold{Component.prototype.createOperationsForPath} - see QInstaller::Component::createOperationsForPath
    \endlist

    \section1 Global variables

    The Installer puts the following symbols into the scripts space:

    \list
    \o \bold{installer} A reference to the component's Installer
    \o \bold{component} A reference to the component's Component
    \endlist

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

    \section1 Message boxes

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

    \code
    QMessageBox.critical
    QMessageBox.information
    QMessageBox.question
    QMessageBox.warning
    \endcode

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

    \section1 Adding operations to the component

    In certain situations if it very useful to add custom operations after
    extracting the content. Those include copying files as well as patching
    content of files, etc.
    Update operations can be created and added to the installation from within
    a script using QInstaller::Component::addOperation.
    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
    QInstaller::Installer::setValue. See the list of
    \l{Predefined variables}{predefined variables}.

    A list of all available operations can be found \l{Operations}{here}

  \section1 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.

  \section1 Predefined variables

  Inside scripts you can use predefined variables to ease directory access. Those variables are

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

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