Doc: add docs for PackageManagerCore

Move the scripting API documentation to a separate
qdoc file. Where possible (no QDoc errors are generated),
only link from the C++ API documentation to the scripting
API documentation.

Change-Id: I969e9afc5cd45c495e6c517b825abb9a9aabdd82
Reviewed-by: Kai Koehne <kai.koehne@theqtcompany.com>
Reviewed-by: Karsten Heimrich <karsten.heimrich@theqtcompany.com>

1 files changed, 733 insertions, 0 deletions

diff --git a/doc/scripting-api/packagemanagercore.qdoc b/doc/scripting-api/packagemanagercore.qdoc
new file mode 100644
index 000000000..817f43b8a
--- /dev/null
+++ b/doc/scripting-api/packagemanagercore.qdoc
@@ -0,0 +1,733 @@
+/****************************************************************************
+**
+** 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 installer
+    \inqmlmodule scripting
+
+    \brief Provides access to core functionality of the Qt Installer Framework.
+*/
+
+/*!
+    \qmlproperty array installer::components
+*/
+
+/*!
+    \qmlsignal installer::aboutCalculateComponentsToInstall()
+
+    Emitted before the ordered list of components to install is calculated.
+*/
+
+/*!
+    \qmlsignal installer::finishedCalculateComponentsToInstall()
+
+    Emitted after the ordered list of components to install was calculated.
+*/
+
+/*!
+    \qmlsignal installer::aboutCalculateComponentsToUninstall()
+
+    Emitted before the ordered list of components to uninstall is calculated.
+*/
+
+/*!
+    \qmlsignal installer::finishedCalculateComponentsToUninstall()
+
+    Emitted after the ordered list of components to uninstall was calculated.
+*/
+
+/*!
+    \qmlsignal installer::componentAdded(Component component)
+
+    Emitted when a new root component is added.
+
+    \sa rootComponentsAdded, updaterComponentsAdded
+*/
+
+/*!
+    \qmlsignal installer::rootComponentsAdded(list<Component> components)
+
+    Emitted when a new list of root components is added.
+
+    \sa componentAdded, updaterComponentsAdded
+*/
+
+/*!
+    \qmlsignal installer::updaterComponentsAdded(list<Component> components)
+
+    Emitted when a new list of updater components is added.
+
+    \sa componentAdded, rootComponentsAdded
+*/
+
+/*!
+    \qmlsignal installer::valueChanged(string key, string value)
+
+    Emitted when a value changes.
+
+    \sa setValue
+*/
+
+/*!
+    \qmlsignal installer::statusChanged(Status status)
+
+    Emitted when the installer status changes.
+*/
+
+/*!
+    \qmlsignal installer::currentPageChanged(int page)
+
+    Emitted when the current page changes.
+*/
+
+/*!
+    \qmlsignal installer::finishButtonClicked()
+
+    Emitted when the user clicks the \uicontrol Finish button of the installer.
+*/
+
+/*!
+    \qmlsignal installer::metaJobProgress(int progress)
+
+    Triggered with progress updates of the communication with a remote
+    repository. Progress ranges from 0 to 100.
+*/
+
+/*!
+    \qmlsignal installer::metaJobInfoMessage(string message)
+
+    Triggered with informative updates of the communication with a remote repository.
+*/
+
+/*!
+    \qmlsignal installer::startAllComponentsReset()
+
+    Triggered when the list of components starts to get updated.
+
+    \sa finishAllComponentsReset
+*/
+
+/*!
+    \qmlsignal installer::finishAllComponentsReset(list<Component> rootComponents)
+
+    Triggered when the list of new root components has been updated.
+
+    \sa startAllComponentsReset
+*/
+
+/*!
+    \qmlsignal installer::startUpdaterComponentsReset()
+
+    Triggered when components start to get updated during a remote update.
+*/
+
+/*!
+    \qmlsignal installer::finishUpdaterComponentsReset(list<Component> componentsWithUpdates)
+
+    Triggered when the list of available remote updates has been updated.
+*/
+
+/*!
+    \qmlsignal installer::installationStarted()
+
+    Triggered when installation has started.
+
+    \sa installationFinished installationInterrupted
+*/
+
+/*!
+    \qmlsignal installer::installationInterrupted()
+
+    Triggered when installation has been interrupted (cancelled).
+
+    \sa interrupt installationStarted installationFinished
+*/
+
+/*!
+    \qmlsignal installer::installationFinished()
+
+    Triggered when installation has finished.
+
+    \sa installationStarted installationInterrupted
+*/
+
+/*!
+    \qmlsignal installer::updateFinished()
+
+    Triggered when an update has finished.
+*/
+
+/*!
+    \qmlsignal installer::uninstallationStarted()
+
+    Triggered when uninstallation has started.
+
+    \sa uninstallationFinished
+*/
+
+/*!
+    \qmlsignal installer::uninstallationFinished()
+
+    Triggered when uninstallation has finished.
+
+    \sa uninstallationStarted
+*/
+
+/*!
+    \qmlsignal installer::titleMessageChanged(string title)
+
+    Emitted when the text of the installer status (on the PerformInstallation page) changes to
+    \a title.
+*/
+
+/*!
+    \qmlsignal installer::wizardPageInsertionRequested(Widget widget, WizardPage page)
+
+    Emitted when a custom \a widget is about to be inserted into \a page by addWizardPage.
+*/
+
+/*!
+    \qmlsignal installer::wizardPageRemovalRequested(Widget widget)
+
+    Emitted when a \a widget is removed by removeWizardPage.
+*/
+
+/*!
+    \qmlsignal installer::wizardWidgetInsertionRequested(Widget widget, WizardPage page)
+
+    Emitted when a \a widget is inserted into \a page by addWizardPageItem.
+*/
+
+/*!
+    \qmlsignal installer::wizardWidgetRemovalRequested(Widget widget)
+
+    Emitted when a \a widget is removed by removeWizardPageItem.
+*/
+
+/*!
+    \qmlsignal installer::wizardPageVisibilityChangeRequested(bool visible, int page)
+
+    Emitted when the visibility of the page with id \a page changes to \a visible.
+
+    \sa setDefaultPageVisible
+*/
+
+/*!
+    \qmlsignal installer::setValidatorForCustomPageRequested(Component component, string name,
+                                        string callbackName)
+
+    Triggered when setValidatorForCustomPage is called.
+*/
+
+/*!
+    \qmlsignal installer::setAutomatedPageSwitchEnabled(bool request)
+
+    Triggered when the automatic switching from PerformInstallation to InstallationFinished page
+    is enabled (\a request = \c true) or disabled (\a request = \c false).
+
+    The automatic switching is disabled automatically when for example the user expands or unexpands
+    the \gui Details section of the PerformInstallation page.
+*/
+
+/*!
+    \qmlsignal installer::coreNetworkSettingsChanged()
+
+    Emitted when the network settings are changed.
+*/
+
+/*!
+    \qmlmethod void installer::setCompleteUninstallation(bool complete)
+
+    Sets the uninstallation to be \a complete. If \a complete is false, only components deselected
+    by the user will be uninstalled. This option applies only on uninstallation.
+*/
+
+/*!
+    \qmlmethod void installer::cancelMetaInfoJob()
+
+    Cancels the retrieval of meta information from a remote repository.
+*/
+
+/*!
+    \qmlmethod void installer::componentsToInstallNeedsRecalculation()
+
+    Ensures that component dependencies are re-calculated.
+*/
+
+/*!
+   \qmlmethod void installer::autoAcceptMessageBoxes()
+
+   Automatically accept all user message boxes.
+
+   \sa autoRejectMessageBoxes, setMessageBoxAutomaticAnswer
+*/
+
+/*!
+   \qmlmethod void installer::autoRejectMessageBoxes()
+
+   Automatically reject all user message boxes.
+
+   \sa autoAcceptMessageBoxes, setMessageBoxAutomaticAnswer
+*/
+
+/*!
+   \qmlmethod void installer::setMessageBoxAutomaticAnswer(string identifier, int button)
+
+   Automatically close the message box with ID \a identifier as if the user had pressed \a button.
+
+   This can be used for unattended (automatic) installations.
+
+   \sa QMessageBox, autoAcceptMessageBoxes, autoRejectMessageBoxes
+*/
+
+/*!
+   \qmlmethod float installer::requiredDiskSpace()
+
+   Returns the additional estimated amount of disk space in bytes required after installation.
+
+   \sa requiredTemporaryDiskSpace
+*/
+
+/*!
+   \qmlmethod float installer::requiredTemporaryDiskSpace()
+
+   Returns the estimated required disk space during installation in bytes.
+
+   \sa requiredDiskSpace
+*/
+
+/*!
+    \qmlmethod boolean installer::isFileExtensionRegistered(string extension)
+
+    Returns whether a file extension is already registered in the Windows registry. Returns \c false
+    on all other platforms.
+*/
+
+/*!
+    \qmlmethod boolean installer::fileExists(string filePath)
+
+    Returns \c true if the \a filePath exists; otherwise returns \c false.
+
+    \note If the file is a symlink that points to a non existing
+     file, \c false is returned.
+*/
+
+/*!
+    \qmlmethod boolean installer::addWizardPage(Component component, string name, int page)
+
+    Adds the widget with objectName() \a name registered by \a component as a new page
+    into the installer's GUI wizard. The widget is added before \a page.
+
+    See \l{Controller Scripting} for the possible values of \a page.
+
+    Returns \c true if the operation succeeded.
+
+    \sa removeWizardPage, setDefaultPageVisible
+*/
+
+/*!
+    \qmlmethod boolean installer::removeWizardPage(Component component, string name)
+
+    Removes the widget with objectName() \a name previously added to the installer's wizard
+    by \a component.
+
+    Returns \c true if the operation succeeded.
+
+    \sa addWizardPage, setDefaultPageVisible, wizardPageRemovalRequested
+*/
+
+/*!
+    \qmlmethod boolean installer::setDefaultPageVisible(int page, boolean visible)
+
+    Sets the visibility of the default page with the ID \a page to \a visible. That is,
+    removes it from or adds it to the wizard. This works only for pages that were
+    in the installer when it was started.
+
+    Returns \c true.
+
+    \sa addWizardPage, removeWizardPage
+*/
+
+/*!
+    \qmlmethod void installer::setValidatorForCustomPage(Component component, string name,
+                                                         string callbackName)
+
+    \sa setValidatorForCustomPageRequested
+*/
+
+/*!
+    \qmlmethod boolean installer::addWizardPageItem(Component component, string name, int page)
+
+    Adds the widget with objectName() \a name registered by \a component as a GUI element
+    into the installer's GUI wizard. The widget is added on \a page.
+
+    See \l{Controller Scripting} for the possible values of \a page.
+
+    \sa removeWizardPageItem, wizardWidgetInsertionRequested
+*/
+
+/*!
+    \qmlmethod boolean installer::removeWizardPageItem(Component component, string name)
+
+    Removes the widget with objectName() \a name previously added to the installer's wizard
+    by \a component.
+
+    \sa addWizardPageItem
+*/
+
+/*!
+    \qmlmethod void installer::addUserRepositories(stringlist repositories)
+
+    Registers additional \a repositories.
+
+    \sa setTemporaryRepositories
+*/
+
+/*!
+    \qmlmethod void installer::setTemporaryRepositories(stringlist repositories, boolean replace)
+
+    Sets additional \a repositories for this instance of the installer or updater.
+    Will be removed after invoking it again.
+
+    \sa addUserRepositories
+*/
+
+/*!
+    \qmlmethod boolean installer::calculateComponentsToInstall()
+
+    Calculates an ordered list of components to install based on the current run mode. Also auto
+    installed dependencies are resolved. The aboutCalculateComponentsToInstall() signal is emitted
+    before the calculation starts, the finishedCalculateComponentsToInstall() signal once all
+    calculations are done.
+*/
+
+/*!
+    \qmlmethod boolean installer::calculateComponentsToUninstall()
+
+    Calculates a list of components to uninstall based on the current run mode. Auto installed
+    dependencies are not yet resolved.  The aboutCalculateComponentsToUninstall() signal is emitted
+    before the calculation starts, the finishedCalculateComponentsToUninstall() signal once all
+    calculations are done. Always returns \c true.
+*/
+
+/*!
+    \qmlmethod boolean installer::gainAdminRights()
+
+    Tries to gain admin rights. On success, it returns \c true.
+
+    \sa dropAdminRights
+*/
+
+/*!
+    \qmlmethod void installer::dropAdminRights()
+
+    Drops admin rights gained by gainAdminRights.
+
+    \sa gainAdminRights
+*/
+
+/*!
+    \qmlmethod boolean installer::isProcessRunning(string name)
+
+    Returns \c true if a process with \a name is running. On Windows, the comparison
+    is case-insensitive.
+*/
+
+/*!
+    \qmlmethod boolean installer::killProcess(string absoluteFilePath)
+
+    Returns \c true if a process with \a absoluteFilePath could be killed or is
+    not running.
+
+    \note This is implemented in a semi blocking way (to keep the main thread to paint the UI).
+*/
+
+/*!
+    \qmlmethod void installer::setDependsOnLocalInstallerBinary()
+
+    Makes sure the installer runs from a local drive. Otherwise the user will get an
+    appropriate error message.
+
+    \note This only works on Windows.
+
+    \sa localInstallerBinaryUsed
+*/
+
+/*!
+    \qmlmethod boolean installer::localInstallerBinaryUsed()
+
+    Returns \c false if the installer is run on Windows, and the installer has been started from
+    a remote file system drive. Otherwise returns \c true.
+
+    \sa setDependsOnLocalInstallerBinary
+*/
+
+/*!
+    \qmlmethod array installer::execute(string program, stringlist arguments = undefined,
+                                        string stdin = "")
+
+    Starts the program \a program with the arguments \a arguments in a
+    new process and waits for it to finish.
+
+    \a stdin is sent as standard input to the application.
+
+    Returns an empty array if the program could not be executed, otherwise
+    the output of command as the first item, and the return code as the second.
+
+    \note On Unix, the output is just the output to stdout, not to stderr.
+
+    \sa executeDetached
+*/
+
+/*!
+    \qmlmethod boolean installer::executeDetached(string program, stringlist arguments = undefined,
+                                                  string workingDirectory = "")
+
+    Starts the program \a program with the arguments \a arguments in a
+    new process, and detaches from it. Returns \c true on success;
+    otherwise returns \c false. If the installer exits, the
+    detached process will continue to live.
+
+    \note Arguments that contain spaces are not passed to the
+    process as separate arguments.
+
+    \b{Unix:} The started process will run in its own session and act
+    like a daemon.
+
+    \b{Windows:} Arguments that contain spaces are wrapped in quotes.
+    The started process will run as a regular standalone process.
+
+    The process will be started in the directory \a workingDirectory.
+*/
+
+/*!
+    \qmlmethod string installer::environmentVariable(string name)
+
+    Returns the content of the environment variable \a name. An empty string is returned if the
+    environment variable is not set.
+*/
+
+/*!
+    \qmlmethod boolean installer::performOperation(string name, stringlist arguments)
+
+    Instantly performs the operation \a name with \a arguments.
+*/
+
+/*!
+    \qmlmethod boolean installer::versionMatches(string version, string requirement)
+
+    Returns \c true when \a version matches the \a requirement.
+    \a requirement can be a fixed version number or it can be prefixed by the comparators '>', '>=',
+    '<', '<=' and '='.
+*/
+
+/*!
+    \qmlmethod string installer::findLibrary(string name, stringlist paths = [])
+
+    Finds a library named \a name in \a paths.
+    If \a paths is empty, it gets filled with platform dependent default paths.
+    The resulting path is returned.
+
+    This method can be used by scripts to check external dependencies.
+
+    \sa findPath
+*/
+
+/*!
+    \qmlmethod string installer::findPath(string name, stringlist paths = [])
+
+    Tries to find a file name \a name in one of \a paths.
+    The resulting path is returned.
+
+    This method can be used by scripts to check external dependencies.
+
+    \sa findLibrary
+*/
+
+/*!
+    \qmlmethod void installer::setInstallerBaseBinary(string path)
+
+    Sets the \c installerbase binary to use when writing the maintenance tool.
+    Set the path if an update to the binary is available.
+
+    If not set, the executable segment of the running installer or uninstaller
+    will be used.
+*/
+
+/*!
+    \qmlmethod string installer::value(string key, string defaultValue = "")
+
+    Returns the installer value for \a key. If \a key is not known to the system, \a defaultValue is
+    returned. Additionally, on Windows, \a key can be a registry key.
+
+    \sa setValue, containsValue, valueChanged
+*/
+
+/*!
+    \qmlmethod stringlist installer::values(string key, stringlist defaultValue = [])
+
+    Returns the installer value for \a key. If \a key is not known to the system, \a defaultValue is
+    returned. Additionally, on Windows, \a key can be a registry key.
+
+    \sa value
+*/
+
+/*!
+    \qmlmethod void installer::setValue(string key, string value)
+
+    Sets the installer value for \a key to \a value.
+
+    \sa value, containsValue, valueChanged
+*/
+
+/*!
+    \qmlmethod boolean installer::containsValue(string key)
+
+    Returns \c true if the installer contains a value for \a key.
+
+    \sa value, setValue, valueChanged
+*/
+
+/*!
+    \qmlmethod void installer::setSharedFlag(string key, boolean value)
+
+    Sets a shared flag with name \a key to \a value. This is one option
+    to share information between scripts.
+
+    Deprecated since 2.0.0. Use setValue instead.
+*/
+
+/*!
+    \qmlmethod boolean installer::sharedFlag(string key)
+
+    Returns shared flag with name \a key. This is one option
+    to share information between scripts.
+
+    Deprecated since 2.0.0. Use \l value or \l values instead.
+*/
+
+/*!
+    \qmlmethod void installer::interrupt()
+
+    Cancels an ongoing installation.
+
+    \sa installationInterrupted
+*/
+
+/*!
+    \qmlmethod void installer::setCanceled()
+
+    Cancels the installation.
+*/
+
+/*!
+    \qmlmethod boolean installer::isInstaller()
+
+    Returns \c true if the application, binary, or executable is executed in
+    installer mode.
+
+    \sa isUninstaller, isUpdater, isPackageManager
+*/
+
+/*!
+    \qmlmethod boolean installer::isOfflineOnly()
+
+    Returns \c true if this is an offline-only installer.
+*/
+
+/*!
+    \qmlmethod void installer::setUninstaller()
+
+    Forces an uninstaller context.
+
+    \sa isUninstaller, setUpdater, setPackageManager
+*/
+
+/*!
+    \qmlmethod boolean installer::isUninstaller()
+
+    Returns \c true if the the application, binary, or executable is executed in
+    uninstaller mode.
+
+    \sa setUninstaller, isInstaller, isUpdater, isPackageManager
+*/
+
+/*!
+    \qmlmethod void installer::setUpdater()
+
+    Forces an updater context.
+
+    \sa isUpdater, setUninstaller, setPackageManager
+*/
+
+/*!
+    \qmlmethod boolean installer::isUpdater()
+
+    Returns \c true if the the application, binary, or executable is executed in
+    updater mode.
+
+    \sa setUpdater, isInstaller, isUninstaller, isPackageManager
+*/
+
+/*!
+    \qmlmethod void installer::setPackageManager()
+
+    Forces a package manager context.
+*/
+
+/*!
+    \qmlmethod boolean installer::isPackageManager()
+
+    Returns \c true if the the application, binary, or executable is executed in
+    package manager mode.
+
+    \sa setPackageManager, isInstaller, isUninstaller, isUpdater
+*/
+
+/*!
+    \qmlmethod boolean installer::runInstaller()
+
+    Runs the installer. Returns \c true on success, \c false otherwise.
+*/
+
+/*!
+    \qmlmethod boolean installer::runUninstaller()
+
+    Runs the uninstaller. Returns \c true on success, \c false otherwise.
+*/
+
+/*!
+    \qmlmethod boolean installer::runPackageUpdater()
+
+    Runs the package updater. Returns \c true on success, \c false otherwise.
+*/
+
+/*!
+    \qmlmethod void installer::languageChanged()
+
+    Calls languangeChanged on all components.
+*/