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

/*!
    \example componenterror
    \ingroup qtifwexamples
    \title Component Error Example

    \brief Using a component script to stop the installation if the components
    cannot be installed.

    \image qtifw-examples-componenterror.png

    \e{Component Error} demonstrates how to stop the installation and display
    error messages if one or several components cannot be installed.

    \include installerfw-examples-configuring.qdocinc

    \quotefile componenterror/config/config.xml

    \include installerfw-examples-packaging.qdocinc

    \list
        \li The \c <Script> element specifies the file name of the JavaScript
            file that is loaded to perform operations.
    \endlist

    \quotefile componenterror/packages/root/meta/package.xml

    This example attempts to install three components, so we create a
    package.xml file in each component directory: \c root, \c root.component1,
    and \c root.component2 and specify the component name and description in
    each of them.

    \section1 Stopping the Installation on Errors

    In installscript.js in the \c root directory, we call the
    \c abortInstaller() function to hide all the default installer pages and to
    display an error message if the components contain errors:

    \quotefromfile componenterror/packages/root/meta/installscript.js
    \skipto abortInstaller()
    \printuntil FinishedText
    \printuntil }

    We use the \c reactOnAbortInstallerChange() signal to stop the installation
    if \c ComponentError is \c true:

    \printuntil }

    We use the \c Component() function to connect to the
    \c reactOnAbortInstallerChange() signal when the list of new root
    components has been updated:

    \printuntil }

    To open the page that displays the error message, we create fake errors by
    setting \c ComponentError to \c true in installscript.js in the
    \c root.component1 and \c root.component2 directories:

    \quotefromfile componenterror/packages/root.component1/meta/installscript.js
    \skipto Component()
    \printuntil /^\}/

    Each component adds a message to the \c component_errors variable. In your
    app, the \c error variable should return the results of a real check for an
    existing file or system feature.

    \include installerfw-examples-generating.qdocinc
*/