path: root/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}.

    Following a list of all available operations, which
    can be added to a installation script.

    \section2 Copy

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

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


  \section2 Move

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

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


  \section2 Delete

  \bold Syntax: "Delete" \a filename

  Deletes the file specified by \a filename.


  \section2 Mkdir

  \bold Syntax: "Mkdir" \a path

  Creates the directory path \a path.


  \section2 Rmdir

  \bold Syntax: "Rmdir" \a path

  Removes the directory path \a path.


  \section2 AppendFile

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

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


  \section2 PrependFile

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

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


  \section2 Execute

  \bold Syntax: "Execute" [{\a exitcodes}] \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}".

  \section2 CreateShortcut

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


  \section2 CreateDesktopEntry

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

  \section2 InstallIcons

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

  \section2 Extract

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

  Extracts \a archive to \a targetdirectory


  \section2 GlobalConfig

  \bold Syntax: "GlobalConfig" \a company \a application \a key \a value <br>
  \a or <br>
  \bold 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.


  \section2 EnvironmentVariable

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


  \section2 RegisterFileType

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


  \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"}.
*/