diff options
author | Leena Miettinen <riitta-leena.miettinen@theqtcompany.com> | 2015-03-09 11:51:58 +0100 |
---|---|---|
committer | Leena Miettinen <riitta-leena.miettinen@theqtcompany.com> | 2015-03-09 12:31:43 +0000 |
commit | b6f30576809d16871601cb39a02b72b77386ed12 (patch) | |
tree | 8b2b4a621ed092f347368b849678ac58eb85544a /doc/scripting-api | |
parent | b13d307acd17e73bd299e7505c4bde9557a9d922 (diff) |
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>
Diffstat (limited to 'doc/scripting-api')
-rw-r--r-- | doc/scripting-api/component.qdoc | 426 |
1 files changed, 426 insertions, 0 deletions
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 +*/ |