Doc: move component scripting docs to a separate file

Reformat the docs in the C++ file as C++ documentation.
Fix language and style issues.

Change-Id: Ifc2ac0a99700d8b2a2ca6835927cdfb0abd7ed2e
Reviewed-by: Niels Weber <niels.weber@theqtcompany.com>
Reviewed-by: Leena Miettinen <riitta-leena.miettinen@theqtcompany.com>

2 files changed, 426 insertions, 1 deletions

diff --git a/doc/config/ifw.qdocconf b/doc/config/ifw.qdocconf
index 32ace9625..2087c30a6 100644
--- a/doc/config/ifw.qdocconf
+++ b/doc/config/ifw.qdocconf
@@ -62,7 +62,6 @@ navigation.homepage = "Qt Installer Framework Manual"
 
 defines                 += ABSTRACTTASK_H \
                            ADMINAUTHORIZATION_H \
-                           COMPONENT_H \
                            COMPONENT_P_H \
                            COMPONENTCHECKER_H \
                            CONSTANTS_H \
diff --git a/doc/scripting-api/component.qdoc b/doc/scripting-api/component.qdoc
new file mode 100644
index 000000000..d9160aac8
--- /dev/null
+++ b/doc/scripting-api/component.qdoc
@@ -0,0 +1,426 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the Qt Installer Framework.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.  Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: http://www.gnu.org/copyleft/fdl.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \qmltype component
+    \inqmlmodule scripting
+
+    \brief Represents the current component that the Qt Script belongs to.
+
+    A minimal valid script needs to contain a constructor, which can look like this:
+
+    \code
+    function Component()
+    {
+        // Access the global component's name property and log it to the debug console.
+        console.log("component: " + component.displayName);
+    }
+    \endcode
+
+    The \c Component class and the script engine both modify the script before it is evaluated.
+    When the modifications are applied to the above snippet, the script changes to:
+
+    \code
+    (function() { [1]
+        var component = installer.componentByName('Component.Name.This.Script.Belongs.To'); [2]
+        function Component()
+        {
+            // Access the global component's name property and log it to the debug console.
+            console.log("component: " + component.displayName);
+        }
+
+        if (typeof Component != undefined) [1]
+            return new Component; [1]
+        else [1]
+            throw "Missing Component constructor. Please check your script." [1]
+    })();
+
+    [1] Changes done by the script engine.
+    [2] Changes done by the Component class.
+    \endcode
+
+    \note The \e component (in lower case) is the global variable the C++ \c Component class
+    introduced. The \e component variable represents the C++ \c Component object that the script
+    belongs to. The \e Component (in upper case) is a JavaScript object that gets instantiated by
+    the script engine.
+*/
+
+/*!
+    \qmlproperty string component::name
+
+    Returns the name of the component as set in the \c <Name> tag of the package
+    information file.
+*/
+
+/*!
+    \qmlproperty string component::displayName
+
+    Returns the name of the component as shown in the user interface.
+*/
+
+/*!
+    \qmlproperty boolean component::selected
+
+    Indicates whether the component is currently selected.
+*/
+
+/*!
+    \qmlproperty boolean component::autoCreateOperations
+
+    Specifies whether some standard operations for the component should be
+    automatically created when the installation starts. The default is \c true.
+*/
+
+/*!
+    \qmlproperty stringlist component::archives
+
+    Returns the list of archive URL's (prefixed with \c installer://) registered
+    for the component.
+
+    \sa addDownloadableArchive, removeDownloadableArchive
+*/
+
+/*!
+    \qmlproperty stringlist component::dependencies
+
+    This read-only property contains components this component depends on.
+*/
+
+/*!
+    \qmlproperty stringlist component::autoDependencies
+
+    Returns the value of the \c <AutoDependOn> tag in the package information file.
+*/
+
+/*!
+    \qmlproperty boolean component::fromOnlineRepository
+
+    Returns whether this component has been loaded from an online repository.
+
+    \sa isFromOnlineRepository
+*/
+
+/*!
+    \qmlproperty url component::repositoryUrl
+
+    Returns the repository URL the component is downloaded from.
+    When this component is not downloaded from an online repository, returns an empty #QUrl.
+
+*/
+
+/*!
+    \qmlproperty boolean component::default
+
+    This read-only property indicates if the component is a default one.
+
+    \note Always \c false for virtual components.
+
+    \sa isDefault
+*/
+
+/*!
+    \qmlproperty boolean component::installed
+
+    This read-only property returns if the component is installed.
+
+    \sa isInstalled
+*/
+
+/*!
+    \qmlproperty boolean component::enabled
+
+    Indicates whether the component is currently enabled. The property is both readable and writable.
+*/
+
+/*!
+    \qmlsignal component::loaded()
+
+    Emitted when the component has been loaded.
+*/
+
+/*!
+    \qmlsignal component::selectedChanged(boolean isSelected)
+
+    Emitted when the component selection has changed to \a isSelected.
+*/
+
+/*!
+    \qmlsignal component::valueChanged(string key, string value)
+
+    Emitted when the variable with name \a key has changed to \a value.
+
+    \sa setValue
+*/
+
+/*!
+    \qmlmethod string component::value(string key, string value = "")
+
+    Returns the value of variable name \a key. If \a key is not known yet, \a defaultValue is returned.
+    Note: If a component is virtual and you ask for the component value with key "Default", it will always
+    return \c false.
+*/
+
+/*!
+    \qmlmethod void component::setValue(string key, string value)
+
+    Sets the value of the variable with \a key to \a value.
+*/
+
+/*!
+    \qmlproperty stringlist component::userInterfaces
+
+    Returns a list of all user interface class names known to this component.
+*/
+
+/*!
+    \qmlmethod QWidget component::userInterface(string name)
+
+    Returns the QWidget created for \a name or 0 if the widget already has been deleted or cannot be found.
+*/
+
+/*!
+    \qmlmethod void component::createOperationsForPath(string path)
+
+    Creates all operations needed to install this component's \a path. \a path is a full qualified
+    filename including the component's name. This method gets called from
+    component::createOperationsForArchive. You can override it by providing a method with
+    the same name in the component script.
+
+    \note RSA signature files are omitted by this method.
+    \note If you call this method from a script, it won't call the scripts method with the same name.
+
+    The default implementation is recursively creating Copy and Mkdir operations for all files
+    and folders within \a path.
+*/
+
+/*!
+    \qmlmethod void component::createOperationsForArchive(string archive)
+
+    Creates all operations needed to install this component's \a archive. This method gets called
+    from component::createOperations. You can override this method by providing a method with the
+    same name in the component script.
+
+    \note If you call this method from a script, it won't call the scripts method with the same name.
+
+    The default implementation calls createOperationsForPath for everything contained in the archive.
+    If \a archive is a compressed archive known to the installer system, an Extract operation is
+    created, instead.
+*/
+
+/*!
+    \qmlmethod void component::beginInstallation()
+
+    Starts the component installation.
+    You can override this method by providing a method with the same name in the component script.
+
+    \code
+    Component.prototype.beginInstallation = function()
+    {
+        // call default implementation
+        component.beginInstallation();
+        // ...
+    }
+    \endcode
+*/
+
+/*!
+    \qmlmethod void component::createOperations()
+
+    Creates all operations needed to install this component.
+    You can override this method by providing a method with the same name in the component script.
+
+    \note If you call this method from a script, it won't call the scripts method with the same name.
+
+    The default implementation calls createOperationsForArchive for all archives in this component.
+*/
+
+/*!
+    \qmlmethod void component::registerPathForUninstallation(string path, boolean wipe = false)
+
+    Registers the file or directory at \a path for being removed when this component gets uninstalled.
+    In case of a directory, this will be recursive. If \a wipe is set to \c true, the directory will
+    also be deleted if it contains changes done by the user after installation.
+*/
+
+/*!
+    \qmlmethod void component::addDownloadableArchive(string path)
+
+    Adds the archive \a path to this component. This can only be called when this component was
+    downloaded from an online repository. When adding \a path, it will be downloaded from the
+    repository when the installation starts.
+
+    \sa removeDownloadableArchive, fromOnlineRepository, archives
+*/
+
+/*!
+    \qmlmethod void component::removeDownloadableArchive(string path)
+
+    Removes the archive \a path previously added via addDownloadableArchive from this component.
+    This can only be called when this component was downloaded from an online repository.
+
+    \sa addDownloadableArchive, fromOnlineRepository, archives
+*/
+
+/*!
+    \qmlmethod void component::addStopProcessForUpdateRequest(string process)
+
+    Adds a request for quitting the process \a process before installing/updating/uninstalling the
+    component.
+*/
+
+/*!
+    \qmlmethod void component::removeStopProcessForUpdateRequest(string process)
+
+    Removes the request for quitting the process \a process again.
+*/
+
+/*!
+    \qmlmethod void component::setStopProcessForUpdateRequest(string process, boolean requested)
+
+    Convenience: Add/remove request depending on \a requested (add if \c true, remove if \c false).
+*/
+
+/*!
+    \qmlmethod boolean component::addOperation(string operation, string parameter1 = "", string parameter2 = "", ..., string parameter10 = "")
+
+    Convenience method for calling addOperation(string, stringlist) with up to 10 arguments.
+*/
+
+/*!
+    \qmlmethod boolean component::addOperation(string operation, stringlist parameters)
+
+    Creates and adds an installation operation for \a operation. Add any number of parameters.
+    The contents of the parameters get variables like "@TargetDir@" replaced with their values,
+    if contained.
+*/
+
+/*!
+    \qmlmethod boolean component::addElevatedOperation(string operation, string parameter1 = "", string parameter2 = "", ..., string parameter10 = "")
+
+    Convenience method for calling addElevatedOperation(string, stringlist) with up to 10 arguments.
+*/
+
+/*!
+    \qmlmethod boolean component::addElevatedOperation(string operation, stringlist parameters)
+
+    Creates and adds an installation operation for \a operation. Add any number of parameters.
+    The contents of the parameters get variables like "@TargetDir@" replaced with their values,
+    if contained. \a operation is executed with elevated rights.
+*/
+
+/*!
+    \qmlmethod void component::setAutoCreateOperations(boolean autoCreateOperations)
+
+    Setter for the \l autoCreateOperations property.
+*/
+
+/*!
+    \qmlmethod void component::addDependency(string newDependency)
+
+    Adds a new component \a newDependency to the list of dependencies.
+
+    \sa dependencies
+*/
+
+/*!
+    \qmlmethod void component::setInstalled()
+
+    Set's the components state to installed.
+*/
+
+/*!
+    \qmlmethod boolean component::isAutoDependOn(QSet<string> componentsToInstall)
+
+    Determines if the component comes as an auto dependency. Returns \c true if the component needs
+    to be installed.
+*/
+
+/*!
+    \qmlmethod boolean component::isDefault()
+
+    Indicates if the component is a default one.
+
+    \note Always returns \c false for virtual components.
+
+    \sa default
+*/
+
+/*!
+    \qmlmethod boolean component::isInstalled()
+
+    Determines if the component is installed.
+*/
+
+/*!
+    \qmlmethod boolean component::installationRequested()
+
+    Determines if the user wants to install the component
+*/
+
+/*!
+    \qmlmethod void component::setUpdateAvailable(boolean isUpdateAvailable)
+
+    Sets a flag that the core found an update
+*/
+
+/*!
+    \qmlmethod boolean component::updateRequested()
+
+    Determines if the user wants to install the update for this component
+*/
+
+/*!
+    \qmlmethod boolean component::componentChangeRequested()
+
+    Returns \c true if that component will be changed (update/installation/uninstallation).
+*/
+
+/*!
+    \qmlmethod void component::setUninstalled()
+
+    Sets the component state to uninstalled.
+*/
+
+/*!
+    \qmlmethod boolean component::isUninstalled()
+
+    Determines if the component is uninstalled.
+*/
+
+/*!
+    \qmlmethod boolean component::uninstallationRequested()
+
+    Determines if the user wants to uninstall the component.
+*/
+
+/*!
+    \qmlmethod boolean component::isFromOnlineRepository()
+
+    Determines whether this component has been loaded from an online repository.
+
+    \sa addDownloadableArchive, fromOnlineRepository
+*/