path: root/doc/scripting-api/component.qdoc

/****************************************************************************
**
** Copyright (C) 2016 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 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::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::valueChanged(string key, string value)

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

    \sa setValue
*/

/*!
    \qmlsignal component::virtualStateChanged()

    Emitted when the virtual state of the component changes.
*/

/*!
    \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 the
    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 \c 0 if the widget 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
    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 \a path.
*/

/*!
    \qmlmethod void component::createOperationsForArchive(string archive)

    Creates all operations needed to install this component's \a 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 \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:

    \code
    Component.prototype.createOperations = function()
    {
        // call default implementation
        component.createOperations();
        // ... add custom operations
    }
    \endcode

    The default implementation calls createOperationsForArchive for all archives in this component.

    \sa component::addOperation()
*/

/*!
    \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, or 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)

    A convenience method for adding or removing the request for stopping
    \a process depending on whether \a requested is \c true (add) or \c false
    (remove).
*/

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

    The method is typically called from within \l component::createOperations().
*/

/*!
    \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 whether 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 whether the component is installed.
*/

/*!
    \qmlmethod boolean component::installationRequested()

    Determines whether 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 whether the user wants to install the update for this component.
*/

/*!
    \qmlmethod boolean component::componentChangeRequested()

    Returns \c true if this component will be changed (update, installation, or
    uninstallation).
*/

/*!
    \qmlmethod void component::setUninstalled()

    Sets the component state to uninstalled.
*/

/*!
    \qmlmethod boolean component::isUninstalled()

    Determines whether the component is uninstalled.
*/

/*!
    \qmlmethod boolean component::uninstallationRequested()

    Determines whether 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
*/