From 6cbe1e880db97b2121b0aca26aed4872f59591d9 Mon Sep 17 00:00:00 2001 From: Leena Miettinen Date: Fri, 8 May 2015 15:33:47 +0200 Subject: 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 Reviewed-by: Karsten Heimrich --- doc/scripting-api/packagemanagercore.qdoc | 733 ++++++++++++++++++++++++++++++ 1 file changed, 733 insertions(+) create mode 100644 doc/scripting-api/packagemanagercore.qdoc (limited to 'doc/scripting-api') 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 components) + + Emitted when a new list of root components is added. + + \sa componentAdded, updaterComponentsAdded +*/ + +/*! + \qmlsignal installer::updaterComponentsAdded(list 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 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 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. +*/ -- cgit v1.2.3