installer-framework/doc/scripting-api/packagemanagercore.qdoc

/****************************************************************************
**
** Copyright (C) 2017 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://www.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.
*/

/*!
    \qmlmethod array installer::components()

    Returns an array of all components currently available.
    If the repository metadata have not been fetched yet,
    the array will be empty.

    \sa component, installer::finishAllComponentsReset(), installer::finishUpdaterComponentsReset()
*/

/*!
    \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 string installer::readFile(string filePath, string codecName)

    Returns the contents of the file \a filePath using the encoding specified
    by \a codecName. The file is read in the text mode, that is, end-of-line
    terminators are translated to the local encoding.

    \note If the file does not exist or an error occurs while reading the file, an
     empty string is returned.
*/

/*!
    \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 = "", string stdinCodec = "latin1",
                                        string stdoutCodec = "latin1")

    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.

    \a stdInCodec is the name of the codec to use for converting the input string
    into bytes to write to the standard input of the application.

    \a stdOutCodec is the name of the codec to use for converting data written by the
    application to standard output into a string.

    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.
*/