Component Class | Qt Installer Framework Manual

- Qt Installer Framework Manual
- Component

# Component Class

class QInstaller::Component

The Component class represents the current component. More...

Header: | #include <Component>
Inherits: | QInstaller::ComponentModelHelper and

- List of all members, including inherited members

## Public Types

struct | SortingPriorityGreaterThan
struct | SortingPriorityLessThan
enum | UnstableError { DepencyToUnstable, ShaMismatch, ScriptLoadingFailed, MissingDependency, InvalidTreeName, DescendantOfUnstable }

## Properties

- archives : const QStringList
- autoCreateOperations : bool
- autoDependencies : const QStringList
- default : const bool
- dependencies : const QStringList
- displayName : const QString
- enabled : const bool

- fromOnlineRepository : const bool
- installed : const bool
- name : const QString
- repositoryUrl : const QUrl
- treeName : const QString
- unstable : const bool
- userInterfaces : const QStringList

## Public Functions

| Component(QInstaller::PackageManagerCore *core)
virtual | ~Component()
void | addAutoDependOn(const QString &newDependOn)
void | addDependency(const QString &newDependency)
void | addDownloadableArchive(const QString &path)
void | addElevatedOperation(QInstaller::Operation *operation)
bool | addElevatedOperation(const QString &operation, const QStringList &parameters)
void | addOperation(QInstaller::Operation *operation)
bool | addOperation(const QString &operation, const QStringList &parameters)
void | addStopProcessForUpdateRequest(const QString &process)
void | appendComponent(QInstaller::Component *component)
QStringList | archives() const
bool | autoCreateOperations() const
QStringList | autoDependencies() const
virtual void | beginInstallation()
bool | componentChangeRequested()
virtual void | createOperations()
virtual void | createOperationsForArchive(const QString &archive)
virtual void | createOperationsForPath(const QString &path)
QStringList | currentDependencies() const
QStringList | dependencies() const
QList<QInstaller::Component *> | descendantComponents() const
QString | displayName() const
QStringList | downloadableArchives()
bool | forcedInstallation() const
bool | installationRequested() const
bool | isAutoDependOn(const QSet<QString> &componentsToInstall) const
bool | isDefault() const
bool | isEssential() const
bool | isForcedUpdate()
bool | isFromOnlineRepository() const
bool | isInstalled(const QString &version = QString()) const
bool | isSelected() const
bool | isSelectedForInstallation() const
bool | isUninstalled() const
bool | isUnstable() const
bool | isUpdateAvailable() const
bool | isVirtual() const
QHash<QString, QVariantMap> | licenses() const
void | loadComponentScript(const bool postLoad = false)
void | loadDataFromPackage(const QInstaller::Package &package)
void | loadDataFromPackage(const KDUpdater::LocalPackage &package)
void | loadLicenses(const QString &directory, const QHash<QString, QVariant> &licenseHash)
void | loadTranslations(const QDir &directory, const QStringList &qms)
void | loadUserInterfaces(const QDir &directory, const QStringList &uis)
void | loadXMLExtractOperations()
void | loadXMLOperations()
QStringList | localDependencies() const
QString | localTempPath() const
void | markAsPerformedInstallation()
QString | name() const
QInstaller::OperationList | operations(const Operation::OperationGroups &mask = Operation::All) const
bool | operationsCreatedSuccessfully() const
QInstaller::PackageManagerCore * | packageManagerCore() const
QInstaller::Component * | parentComponent() const
QList<QPair<QString, bool>> | pathsForUninstallation() const
void | registerPathForUninstallation(const QString &path, bool wipe = false)
void | removeComponent(QInstaller::Component *component)
void | removeDownloadableArchive(const QString &path)
void | removeStopProcessForUpdateRequest(const QString &process)
int | removeValue(const QString &key)
QUrl | repositoryUrl() const
void | setInstalled()
void | setRepositoryUrl(const QUrl &url)
void | setStopProcessForUpdateRequest(const QString &process, bool requested)
void | setUninstalled()
void | setUnstable(Component::UnstableError error, const QString &errorMessage = QString())
void | setUpdateAvailable(bool isUpdateAvailable)
void | setValidatorCallbackName(const QString &name)
void | setValue(const QString &key, const QString &value)
QStringList | stopProcessForUpdateRequests() const
QString | treeName() const
bool | treeNameMoveChildren() const
bool | uninstallationRequested() const
bool | updateRequested() const
quint64 | updateUncompressedSize()
QWidget * | userInterface(const QString &name) const
QStringList | userInterfaces() const
bool | validatePage()
QString | value(const QString &key, const QString &defaultValue = QString()) const
QHash<QString, QString> | variables() const

## Public Slots

void | setAutoCreateOperations(bool autoCreateOperations)

## Signals

void | loaded()
void | valueChanged(const QString &key, const QString &value)
void | virtualStateChanged()

## Detailed Description

## Member Type Documentation

### enum Component::UnstableError

This enum type holds the component unstable error reason:

Constant | Value | Description
--- | --- | ---
`QInstaller::Component::DepencyToUnstable` | `0` | Component has a dependency to an unstable component.
`QInstaller::Component::ShaMismatch` | `1` | Component has packages with non-matching SHA values.
`QInstaller::Component::ScriptLoadingFailed` | `2` | Component script has errors or loading fails.
`QInstaller::Component::MissingDependency` | `3` | Component has dependencies to missing components.
`QInstaller::Component::InvalidTreeName` | `4` | Component has an invalid tree name.
`QInstaller::Component::DescendantOfUnstable` | `5` | Component is descendant of an unstable component.

## Property Documentation

### `[read-only]` archives : const QStringList

This property holds the list of archive URLs registered for the component.

The URLs are prefixed with `installer://`.

Access functions:

QStringList | archives() const

See also addDownloadableArchive() and removeDownloadableArchive().

### autoCreateOperations : bool

This property holds whether some standard operations for the component should be automatically created when the installation starts.

The default is `true`.

Access functions:

bool | autoCreateOperations() const
void | setAutoCreateOperations(bool autoCreateOperations)

### `[read-only]` autoDependencies : const QStringList

This property holds the value of the `<AutoDependOn>` element in the package information file.

Access functions:

QStringList | autoDependencies() const

### `[read-only]` default : const bool

This property holds whether the component is a default one. This is a read-only property.

Note: Always `false` for virtual components.

Access functions:

bool | isDefault() const | [see note below]

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[read-only]` dependencies : const QStringList

This property holds the components this component depends on. This is a read-only property.

Access functions:

QStringList | dependencies() const

### `[read-only]` displayName : const QString

This property holds the name of the component as shown in the user interface.

Access functions:

QString | displayName() const

### enabled : const bool

This property holds whether the component is currently enabled. The property is both readable and writable.

### `[read-only]` fromOnlineRepository : const bool

This property holds whether this component has been loaded from an online repository.

Access functions:

bool | isFromOnlineRepository() const | [see note below]

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[read-only]` installed : const bool

This property holds whether the component is installed. This is a read-only property.

Access functions:

bool | isInstalled(const QString &version = QString()) const | [see note below]

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[read-only]` name : const QString

This property holds the name of the component as set in the `<Name>` tag of the package information file.

Access functions:

QString | name() const

### `[read-only]` repositoryUrl : const QUrl

This property holds the repository URL the component is downloaded from.

If this component is not downloaded from an online repository, returns an empty QUrl.

Access functions:

QUrl | repositoryUrl() const

### `[read-only]` treeName : const QString

This property holds the tree name of the component. Specifies the location of the component in the install tree view.

Note: If the tree name is not set, the tree view is organized based on the component name.

Note: Must be unique, the tree name must not conflict with other component's names or tree names.

Access functions:

QString | treeName() const

### `[read-only]` unstable : const bool

This property holds whether the component is unstable. This is a read-only property.

Note: Unstable components cannot be selected for installation.

Access functions:

bool | isUnstable() const

### `[read-only]` userInterfaces : const QStringList

This property holds a list of all user interface class names known to this component.

Access functions:

QStringList | userInterfaces() const

## Member Function Documentation

### `[explicit]` Component::Component(QInstaller::PackageManagerCore *core)

Creates a new component in the package manager specified by core.

### `[virtual noexcept]` Component::~Component()

Destroys the component.

### `[invokable]` void Component::addAutoDependOn(const QString &newDependOn)

Adds the component specified by newDependOn to the automatic depend-on list. Alternatively, multiple components can be specified by separating each with a comma.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.addAutoDependOn and autoDependencies.

### `[invokable]` void Component::addDependency(const QString &newDependency)

Adds the component specified by newDependency to the list of dependencies. Alternatively, multiple components can be specified by separating each with a comma.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.addDependency and dependencies.

### `[invokable]` void Component::addDownloadableArchive(const QString &path)

Adds the archive path to this component. This can only be called if this component was downloaded from an online repository. When adding path, it will be downloaded from the repository when the installation starts.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.addDownloadableArchive, removeDownloadableArchive(), fromOnlineRepository, and archives.

### void Component::addElevatedOperation(QInstaller::Operation *operation)

Adds operation to the list of operations needed to install this component. operation is executed with elevated rights.

### bool Component::addElevatedOperation(const QString &operation, const QStringList &parameters)

Creates and adds the installation operation operation. Add any number of parameters. The variables that the parameters contain, such as `@TargetDir@`, are replaced with their values. The operation is executed with elevated rights.

Returns `true` if the operation is created; otherwise returns `false`.

See also component.addElevatedOperation.

### void Component::addOperation(QInstaller::Operation *operation)

Adds operation to the list of operations needed to install this component.

### bool Component::addOperation(const QString &operation, const QStringList &parameters)

Creates and adds an installation operation for operation. Add any number of parameters. The variables that the parameters contain, such as `@TargetDir@`, are replaced with their values.

Returns `true` if the operation is created; otherwise returns `false`.

See also component.addOperation.

### `[invokable]` void Component::addStopProcessForUpdateRequest(const QString &process)

Adds a request for quitting the process process before installing, updating, or uninstalling the component.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.addStopProcessForUpdateRequest.

### void Component::appendComponent(QInstaller::Component *component)

Appends component as a child of this component. If component already has a parent, it is removed from the previous parent. If the component contains several children and has the SortingPriorityGreaterThan() sorting priority set, the child list is sorted so that the child component with the highest priority is placed on top.

### QStringList Component::archives() const

Contains the names of all archives known to this component. Even downloaded archives are mapped to the `installer://` URL through the used QFileEngineHandler during the download process.

Note: Getter function for property archives.

### bool Component::autoCreateOperations() const

Specifies whether operations should be automatically created when the installation starts. This would be done by calling createOperations(). If you set this to `false`, it is completely up to the component's script to create all operations.

Returns `false` when component's script will create all operations; otherwise returns `true`.

Note: Getter function for property autoCreateOperations.

See also setAutoCreateOperations() and component.autoCreateOperations.

### `[virtual invokable]` void Component::beginInstallation()

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.beginInstallation.

### `[invokable]` bool Component::componentChangeRequested()

Returns `true` if that component will be changed (update, installation, or uninstallation).

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.componentChangeRequested.

### `[virtual invokable]` void Component::createOperations()

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.createOperations and createOperationsForArchive().

### `[virtual invokable]` void Component::createOperationsForArchive(const QString &archive)

Creates all operations needed to install this component's archive. This method gets called from 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 will not call the script's method with the same name.

The default implementation calls createOperationsForPath for everything contained in the archive. If archive is a compressed archive known to the installer system, an Extract operation is created, instead.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.createOperationsForArchive.

### `[virtual invokable]` void Component::createOperationsForPath(const QString &path)

Creates all operations needed to install this component's path. path is a fully qualified filename including the component's name. This method gets called from 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 will not call the script's method with the same name.

The default implementation is recursively creating Copy and Mkdir operations for all files and folders within path.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.createOperationsForPath.

### QStringList Component::currentDependencies() const

Returns a list of dependencies that the component currently has. The dependencies can vary when component is already installed with different dependency list than what is introduced in the repository. If component is not installed, or update is requested to an installed component, current dependencies are read from repository so that correct dependencies are calculated for the component when it is installed or updated.

### QStringList Component::dependencies() const

Returns a list of dependencies defined in the the repository or in the package.xml.

Note: Getter function for property dependencies.

### QList<QInstaller::Component *> Component::descendantComponents() const

Returns a list of child components, including all descendants of the component's children.

Note: The returned list does include all children; non-virtual components as well as virtual components.

### QString Component::displayName() const

Contains this component's display name as visible to the user.

Note: Getter function for property displayName.

### QStringList Component::downloadableArchives()

Returns the archives to be downloaded from the online repository before installation. Should be called only once when the installation starts.

### bool Component::forcedInstallation() const

Returns whether this component should always be installed.

### `[invokable]` bool Component::installationRequested() const

Returns whether the user wants to install the component.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.installationRequested.

### `[invokable]` bool Component::isAutoDependOn(const QSet<QString> &componentsToInstall) const

Determines whether the component comes as an auto dependency. Returns `true` if all components in componentsToInstall are already installed or selected for installation and this component thus needs to be installed as well.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.isAutoDependOn.

### bool Component::isEssential() const

Returns whether this component is essential. Essential components are always installed, and updated before other components.

### `[invokable]` bool Component::isForcedUpdate()

Returns `true` if the component is installed and has a `ForcedUpdate` flag set. ForcedUpdate components will be updated together with essential components before any other component can be updated or installed.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.isForcedUpdate.

### `[invokable]` bool Component::isFromOnlineRepository() const

Returns whether this component has been loaded from an online repository.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

Note: Getter function for property fromOnlineRepository.

See also component.isFromOnlineRepository, addDownloadableArchive(), and fromOnlineRepository.

### bool Component::isSelected() const

Returns whether the component is selected.

### bool Component::isSelectedForInstallation() const

Returns whether the component is selected for installation.

### `[invokable]` bool Component::isUninstalled() const

Returns whether the component is uninstalled.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.isUninstalled.

### bool Component::isUnstable() const

Returns `true` if this component is unstable.

Note: Getter function for property unstable.

### `[invokable]` bool Component::isUpdateAvailable() const

Returns whether update is available for this component.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.isUpdateAvailable.

### bool Component::isVirtual() const

Returns whether this component is virtual.

### QHash<QString, QVariantMap> Component::licenses() const

Returns a hash that contains the file names, text and priorities of license files for the component.

### void Component::loadComponentScript(const bool postLoad = false)

Loads the component script into the script engine. Call this method with postLoad `true` to a list of components that are updated or installed to improve performance if the amount of components is huge and there are no script functions that need to be called before the installation starts.

### void Component::loadDataFromPackage(const QInstaller::Package &package)

Sets variables according to the values set in the package.xml file of package. Also loads UI files, licenses and translations if they are referenced in the package.xml. If the `PackageManagerCore` object of this component is run as package viewer, then only sets the variables without loading referenced files.

### void Component::loadDataFromPackage(const KDUpdater::LocalPackage &package)

Sets variables according to the values set in the package.xml file of a local package.

### void Component::loadLicenses(const QString &directory, const QHash<QString, QVariant> &licenseHash)

Loads the text of the licenses contained in licenseHash from directory. This is saved into a new hash containing the filename, the text and the priority of that file.

### void Component::loadTranslations(const QDir &directory, const QStringList &qms)

Loads the translations matching the name filters qms inside directory. Only translations with a base name matching the current locale's name are loaded. For more information, see Translating Pages.

### void Component::loadUserInterfaces(const QDir &directory, const QStringList &uis)

Loads the user interface files matching the name filters uis inside directory. The loaded interface can be accessed via userInterfaces() by using the class name set in the UI file.

### void Component::loadXMLExtractOperations()

Loads all Extract operations defined in the component.xml. Operations are overwriting the default implementation of Extract operation.

### void Component::loadXMLOperations()

Loads all operations defined in the component.xml except Extract operation. Operations are added to the list of operations needed to install this component.

### `[signal]` void Component::loaded()

See also component.loaded.

### QStringList Component::localDependencies() const

Returns a list of installed components dependencies defined in the components.xml.

### QString Component::localTempPath() const

Returns the path to the local directory where the component is temporarily stored.

### void Component::markAsPerformedInstallation()

Marks the component as installed.

### QString Component::name() const

Contains the unique identifier of this component.

Note: Getter function for property name.

### QInstaller::OperationList Component::operations(const Operation::OperationGroups &mask = Operation::All) const

Returns the operations needed to install this component. If autoCreateOperations() is `true`, createOperations() is called if no operations have been automatically created yet.

The mask parameter filters the returned operations by their group.

### bool Component::operationsCreatedSuccessfully() const

Returns whether the operations needed to install this component were created successfully.

### QInstaller::PackageManagerCore *Component::packageManagerCore() const

Returns the installer this component belongs to.

### QInstaller::Component *Component::parentComponent() const

Returns the parent of this component. For example, the parent of a component called `org.qt-project.sdk.qt` is `org.qt-project.sdk` if it exists.

### QList<QPair<QString, bool>> Component::pathsForUninstallation() const

Returns the list of paths previously registered for uninstallation with registerPathForUninstallation().

### `[invokable]` void Component::registerPathForUninstallation(const QString &path, bool wipe = false)

Registers the file or directory at path for being removed when this component gets uninstalled. In case of a directory, this will be recursive. If wipe is set to `true`, the directory will also be deleted if it contains changes made by the user after installation.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.registerPathForUninstallation.

### void Component::removeComponent(QInstaller::Component *component)

Removes component if it is a child of this component. The component object still exists after the function returns. It is up to the caller to delete the passed component.

### `[invokable]` void Component::removeDownloadableArchive(const QString &path)

Removes the archive path previously added via addDownloadableArchive() from this component. This can only be called if this component was downloaded from an online repository.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.removeDownloadableArchive, addDownloadableArchive(), fromOnlineRepository, and archives.

### `[invokable]` void Component::removeStopProcessForUpdateRequest(const QString &process)

Removes the request for quitting the process process again.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.removeStopProcessForUpdateRequest.

### int Component::removeValue(const QString &key)

Removes all the values that have the key from the variables set for this component. Returns the number of values removed which is 1 if the key exists in the variables, and 0 otherwise.

### QUrl Component::repositoryUrl() const

Contains the repository URL this component is downloaded from. If this component is not downloaded from an online repository, returns an empty QUrl.

Note: Getter function for property repositoryUrl.

See also setRepositoryUrl().

### `[invokable]` void Component::setInstalled()

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also isInstalled() and component.setInstalled.

### void Component::setRepositoryUrl(const QUrl &url)

Sets this component's repository URL as url.

See also repositoryUrl().

### `[invokable]` void Component::setStopProcessForUpdateRequest(const QString &process, bool requested)

A convenience function for adding or removing the request for stopping process depending on whether requested is `true` (add) or `false` (remove).

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.addStopProcessForUpdateReques.

### `[invokable]` void Component::setUninstalled()

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also isUninstalled() and component.setUninstalled.

### void Component::setUnstable(Component::UnstableError error, const QString &errorMessage = QString())

Sets this component, all its child components and all the components depending on this component unstable with the error code error and message errorMessage.

See also isUnstable().

### `[invokable]` void Component::setUpdateAvailable(bool isUpdateAvailable)

Sets the isUpdateAvailable flag to `true` to indicate that the core found an update.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also isUpdateAvailable() and component.setUpdateAvailable.

### void Component::setValidatorCallbackName(const QString &name)

Sets the validator callback name to name.

### `[invokable]` void Component::setValue(const QString &key, const QString &value)

Sets the value of the variable with key to value.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also value() and component.setValue.

### QStringList Component::stopProcessForUpdateRequests() const

The list of processes that need to be closed before installing, updating, or uninstalling this component.

### QString Component::treeName() const

Returns this component's location in the tree view. If the tree name is not set, returns the component name. The tree name must be unique, it must not conflict with other tree names or component names.

Note: Getter function for property treeName.

### bool Component::treeNameMoveChildren() const

Returns `true` if descendants of this component should have automatically created tree names in relation to the parent component's modified location, `false` otherwise.

### `[invokable]` bool Component::uninstallationRequested() const

Returns whether the user wants to uninstall the component.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.uninstallationRequested.

### `[invokable]` bool Component::updateRequested() const

Returns whether the user wants to install the update for this component.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.updateRequested.

### quint64 Component::updateUncompressedSize()

Returns the size of a compressed archive.

### `[invokable]` QWidget *Component::userInterface(const QString &name) const

Returns the QWidget created for name or `0` if the widget has been deleted or cannot be found.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also component.userInterface.

### bool Component::validatePage()

Calls the script method with the validator callback name. Returns `true` if the method returns `true`. Always returns `true` if the validator callback name is empty.

### `[invokable]` QString Component::value(const QString &key, const QString &defaultValue = QString()) const

Returns the value of variable name key. If key is not known yet, defaultValue is returned.

Note: If a component is virtual and you ask for the component value with the key `Default`, it will always return `false`.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

See also setValue().

### `[signal]` void Component::valueChanged(const QString &key, const QString &value)

Emitted when the value of the variable with the name key changes to value.

See also component.valueChanged and setValue().

### QHash<QString, QString> Component::variables() const

Returns a key and value based hash of all variables set for this component.

### `[signal]` void Component::virtualStateChanged()

See also component.virtualStateChanged.