// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \qmlmodule QtQuick.Controls
    \keyword Qt Quick Controls QML Types
    \title Qt Quick Controls QML Types
    \keyword Qt Quick Controls 2 QML Types
    \ingroup qmlmodules
    \brief Provides QML types for user interfaces (Qt Quick Controls).

    \l{Qt Quick Controls} provides QML types for creating user interfaces.
    These QML types work in conjunction with \l{Qt Quick} and
    \l{Qt Quick Layouts}.

    Qt Quick Controls QML types can be imported into your application
    using the following import statement in your .qml file:

    \qml
    import QtQuick.Controls
    \endqml

    \section1 QML Types
    \generatelist {qmltypesbymodule QtQuick.Controls}
    \noautolist

    \section1 Using Qt Quick Controls types in property declarations

    As mentioned in \l {Qt Quick Templates 2 QML Types}, each type in Qt Quick
    Controls is backed by a C++ "template" type. These types are \l {Qt Quick
    Templates 2}{non-visual implementations of controls' logic and behavior}.

    For example, the \l Menu type's API and behavior is defined by the C++
    type in Qt Quick Templates. Each \l {Definition of a Style}{style} that
    wants to provide a Menu must have a Menu.qml available, and the root
    item in that file must be the Menu from Qt Quick Templates. When you
    import QtQuick.Controls and create a Menu in QML, the type you get is
    actually the QML Menu defined by the style's Menu.qml.

    In order to use a control as the type in a property declaration, you should
    use the corresponding type from Qt Quick Templates. For example, suppose
    you had a \c PopupOpener component, which was a Button that opened a
    Popup:

    \qml
    // PopupButton.qml
    import QtQuick.Controls

    Button {
        required property Popup popup

        onClicked: popup.open()
    }

    // main.qml
    PopupButton {
        popup: saveChangesDialog
    }

    Dialog {
        id: saveChangesDialog

        // ...
    }
    \endqml

    Running this code will result in an error:

    \badcode
    Unable to assign Dialog_QMLTYPE to Popup_QMLTYPE
    \endcode

    This is because of the inheritance hierarchy:

    \badcode
    Popup (C++ type in QtQuick.Templates)
    │   └── Popup (QML type in QtQuick.Controls)
    └── Dialog (C++ type in QtQuick.Templates)
        └── Dialog (QML type in QtQuick.Controls)
    \endcode

    Dialog from \c QtQuick.Controls does not derive from the Popup from
    \c QtQuick.Controls, but from \c QtQuick.Templates.

    Instead, use the Popup from Qt Quick Templates as the property type:

    \qml
    // PopupButton.qml
    import QtQuick.Controls
    import QtQuick.Templates as T

    Button {
        required property T.Popup popup

        onClicked: popup.open()
    }
    \endqml

    For more information on the Qt Quick Controls module, see the
    \l {Qt Quick Controls} module documentation.

    \section1 Related Information
    \list
    \li \l {Qt Quick Controls Guidelines}
    \endlist
*/