/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $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 https://www.qt.io/terms-conditions. For further
** information use the contact form at https://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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \page qtquickcontrols-overview.html
    \title Qt Quick Controls Overview
    \brief A set of UI controls to create user interfaces in Qt Quick

    The Qt Quick Controls provide a set of UI controls to create user interfaces
    in Qt Quick.

    \section1 Getting Started

    The QML types can be imported into your application using the following import statement in your \c {.qml} file.

    \code
     import QtQuick.Controls 1.2
    \endcode

    \section1 Creating a basic example

    A basic example of a QML file that makes use of controls is shown here:

    \code
    import QtQuick.Controls 1.2

    ApplicationWindow {
        title: "My Application"
        width: 640
        height: 480
        visible: true

        Button {
            text: "Push Me"
            anchors.centerIn: parent
        }
    }
    \endcode

    For an overview of the controls provided by \l{Qt Quick Controls}, you can look at
    the \l{Qt Quick Controls - Gallery}{Gallery} example.

    \image qtquickcontrols-example-gallery-osx.png

    \section1 Setting Up Controls from C++

    Although we have traditionally used a QQuickView window to display QML files
    in a C++ application, doing this means you can only set window properties from C++.

    With Qt Quick Controls, declare an ApplicationWindow as the root item of your application and launch it by using the
    QQmlApplicationEngine instead. This ensures that you can control top level window properties from QML.

    A basic example of a source file that makes use of controls is shown here:

    \code
    #include <QApplication>
    #include <QQmlApplicationEngine>

    int main(int argc, char *argv[])
    {
        QApplication app(argc, argv);
        QQmlApplicationEngine engine("main.qml");
        return app.exec();
    }
    \endcode

    \note We are using QApplication and not QGuiApplication in this example.
    Though you can use QGuiApplication instead, doing this will eliminate platform-dependent styling.
    This is because it is relying on the widget module to provide the native look and feel.

    \section2 Using C++ Data From QML

    If you need to register a C++ class to use from QML, you can call, for example,
    qmlRegisterType() before declaring your QQmlApplicationEngine. You can find the list
    of all registering functions \l{QQmlEngine}{here}.

    If you need to expose data to QML components, you need to set them
    to the context of the current QML engine. See QQmlContext for more
    information.

    \section2 Deploying Qt Quick Controls

    Since Qt 5.2, the Qt Quick Controls JavaScript and QML files are embedded into the plugin
    using \l{The Qt Resource System}{Qt resources} (.qrc) for the QtQuick.Controls and QtQuick.Controls.Styles imports. It is only
    necessary to deploy the qtquickcontrolsplugin C++ library and its qmldir file found in the plugin directory
    \e{qml/QtQuick/Controls}.

    The .js/.qml files are still placed into the plugin directory though for keeping the development
    tasks convenient, debugging and autocompletion capabilities remain unchanged. For deployment,
    these files can be ignored. In practice, the \e{Styles} and \e{Private} subfolders can be deleted as
    well as all .js and .qml files present under \e{qml/QtQuick/Controls}.

    \note On Windows, the \l{Qt for Windows - Deployment#The Windows Deployment Tool}{Windows Deployment Tool}
    only deploys the Qt Quick Controls plugin and its qmldir file.

    Using resources facilitates the deployment of the Qt Quick Controls though it has limitations
    that still need to be addressed.

    \note On iOS, the qmlimportscanner tool is used to parse the required qml imports so they can
    be deployed accordingly. The files embedded in resources are not scanned by this tool though
    and when linking statically, some required imports used by the Qt Quick Controls can be
    forgotten. This is a known limitation and a workaround is to add potentially missing imports in
    one of the qml files of the application using the controls.

    \section2 Testing Desktop and Mobile behavior of the controls
    You can test how the controls on your application or style will behave on
    a mobile platform by setting the environment variable \e QT_QUICK_CONTROLS_MOBILE, to force a behavior optimized for mobile devices.

    \section1 Related information

     \list
      \li \l{Qt Quick}
      \li \l{Qt Quick Controls}
      \li \l{Qt Quick Controls Examples}
    \endlist
*/