/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://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 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$
**
****************************************************************************/

/*!
    \page qtquickcontrols2-differences.html
    \title Differences between Qt Quick Controls

    Qt Quick Controls were originally developed to support desktop platforms,
    with mobile and embedded support coming shortly afterwards. They have a
    very broad scope, in that they provide a styling system flexible enough to
    allow the development of applications that have either a platform-dependent
    or platform-independent style.

    On embedded systems, where the hardware has limited resources, this approach
    can be inefficient. Qt Quick Controls 2 were designed to solve this problem,
    using
    \l {https://blog.qt.io/blog/2015/03/31/qt-quick-controls-for-embedded/}{benchmarks}
    to guide the development.

    \section2 C++ and QML

    In many cases, the internal state of a control can be more efficiently
    processed in C++. For example, handling input events in C++ makes a
    difference for controls that would otherwise need to create internal
    MouseAreas and attached Keys objects.

    \section2 Styles

    Not only does handling events and logic in C++ increase performance, but it
    allows the visual QML layer to be a simple, declarative layer on top. This
    is reflected in the structure of the controls project: all visual
    implementations sit in the \e imports folder, so that users who want to
    create their own complete style can copy the folder and start tweaking.
    Read more about implementing a style plugin
    \l {Creating a Custom Style}{here}.

    In Qt Quick Controls 2, styles no longer provide components that are
    dynamically instantiated by controls, but controls themselves consist of
    item delegates that can be replaced. In effect, this means that delegates
    are Qt Quick items that are instantiated on the spot, as properties of the
    control, and are simply parented to the control.

    \section2 Modularity and Simplicity

    When it comes to more complex controls, it is sometimes better to split
    them up into separate building blocks. As an example, the complex
    ScrollView control:

    \qml
    ScrollView {
        horizontalScrollBarPolicy: Qt.ScrollBarAlwaysOff
        Flickable {
            // ...
        }
    }
    \endqml

    Is replaced with simple ScrollBar/ScrollIndicator controls that can be
    attached to any Flickable:

    \qml
    Flickable {
        // ...
        ScrollBar.vertical: ScrollBar { }
    }
    \endqml

    The API of Qt Quick Controls 2 aims to be clean and simple. Common
    operations are easy, and more advanced ones are liberally documented with
    snippets that can be copied into your code.

    \section2 Feature Comparison Table

    \table
    \header
        \li
        \li Qt Quick Controls
        \li Qt Quick Controls 2
    \row
        \li Stylable delegates
        \li Yes
        \li Yes
    \row
        \li Pre-built native styles
        \li Yes
        \li No
    \row
        \li Runtime style changes
        \li Yes
        \li Yes
    \row
        \li Can be used on Desktop
        \li Yes
        \li Yes
    \row
        \li Can be used on Mobile
        \li Yes
        \li Yes
    \row
        \li Can be used on Embedded
        \li Yes
        \li Yes
    \row
        \li Internal event handling
        \li QML
        \li C++
    \endtable

    \section2 Porting Qt Quick Controls Code

    The API of Qt Quick Controls 2 is very similar to Qt Quick Controls, but it
    does come with some changes necessary to facilitate the improvements. The
    majority of changes are to do with styling; all of a control's delegates
    are now accessible in the control itself, instead of in a separate style
    object.

    For example, to style a button in Qt Quick Controls:

    \badcode
    Button {
        style: ButtonStyle {
            label: Label {
                // ...
            }
        }
    }
    \endcode

    To style a button in Qt Quick Controls 2:

    \qml
    Button {
        contentItem: Label {
            // ...
        }
    }
    \endqml

    \section3 Preparing for Migration

    With this in mind, a good way to prepare for a migration to Qt Quick
    Controls 2 is to place each control that you have a custom style for in its
    own QML file. For example, the Qt Quick Controls button above could be
    moved to a file named \c Button.qml in a directory named \c controls, and
    used in the following manner:

    \badcode
    import "controls" as Controls

    Controls.Button {
        ...
    }
    \endcode

    This works with both modules, and will reduce the amount of work needed
    when the migration begins.

    \section3 Type Comparison Table

    \table
    \header
        \li Qt Quick Controls 1, Qt Quick Extras
        \li Qt Quick Controls 2, Qt Labs Calendar
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {AbstractButton}
    \row
        \li \l [QML QtQuickControls] {Action}
        \li \span {} {\mdash \nbsp \sub {(see \l [QML QtQuick] {Shortcut} instead)}}
    \row
        \li \l [QML QtQuickControls] {ApplicationWindow}
        \li \l [QML QtQuickControls2] {ApplicationWindow}
    \row
        \li \l [QML QtQuickControls] {BusyIndicator}
        \li \l [QML QtQuickControls2] {BusyIndicator}
    \row
        \li \l [QML QtQuickControls] {Button}
        \li \l [QML QtQuickControls2] {Button}
    \row
        \li \l [QML QtQuickExtras] {CircularGauge}
        \li \mdash
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {Control}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {Container}
    \row
        \li \l [QML QtQuickControls] {Calendar}
        \li \l [QML QtLabsCalendar] {MonthGrid},
            \l [QML QtLabsCalendar] {DayOfWeekRow},
            \l [QML QtLabsCalendar] {WeekNumberColumn}
    \row
        \li \l [QML QtQuickControls] {CheckBox}
        \li \l [QML QtQuickControls2] {CheckBox}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {CheckDelegate}
    \row
        \li \l [QML QtQuickControls] {ComboBox}
        \li \l [QML QtQuickControls2] {ComboBox}
    \row
        \li \l [QML QtQuickExtras] {DelayButton}
        \li \mdash
    \row
        \li \l [QML QtQuickExtras] {Dial}
        \li \l [QML QtQuickControls2] {Dial}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {Drawer}
    \row
        \li \l [QML QtQuickControls] {ExclusiveGroup}
        \li \l [QML QtQuickControls2] {ButtonGroup}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {Frame}
    \row
        \li \l [QML QtQuickExtras] {Gauge}
        \li \mdash
    \row
        \li \l [QML QtQuickControls] {GroupBox}
        \li \l [QML QtQuickControls2] {GroupBox}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {ItemDelegate}
    \row
        \li \l [QML QtQuickControls] {Label}
        \li \l [QML QtQuickControls2] {Label}
    \row
        \li \l [QML QtQuickControls] {Menu}
        \li \l [QML QtQuickControls2] {Menu}
    \row
        \li \l [QML QtQuickControls] {MenuBar}
        \li \mdash
    \row
        \li \l [QML QtQuickControls] {MenuItem}
        \li \l [QML QtQuickControls2] {MenuItem}
    \row
        \li \l [QML QtQuickControls] {MenuSeparator}
        \li \l [QML QtQuickControls2] {MenuSeparator}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {Page}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {PageIndicator}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {Pane}
    \row
        \li \l [QML QtQuickExtras] {Picture}
        \li \mdash
    \row
        \li \l [QML QtQuickExtras] {PieMenu}
        \li \mdash
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {Popup}
    \row
        \li \l [QML QtQuickControls] {ProgressBar}
        \li \l [QML QtQuickControls2] {ProgressBar}
    \row
        \li \l [QML QtQuickControls] {RadioButton}
        \li \l [QML QtQuickControls2] {RadioButton}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {RadioDelegate}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {RangeSlider}
    \row
        \li \l [QML QtQuickControls] {ScrollView}
        \li \l [QML QtQuickControls2] {ScrollBar},
            \l [QML QtQuickControls2] {ScrollIndicator}
    \row
        \li \l [QML QtQuickControls] {Slider}
        \li \l [QML QtQuickControls2] {Slider}
    \row
        \li \l [QML QtQuickControls] {SplitView}
        \li \mdash
    \row
        \li \l [QML QtQuickControls] {SpinBox}
        \li \l [QML QtQuickControls2] {SpinBox}
    \row
        \li \l [QML QtQuickControls] {StackView},
            \l [QML QtQuickControls] {StackViewDelegate},
            \l [QML QtQuickControls] {Stack}
        \li \l [QML QtQuickControls2] {StackView}
    \row
        \li \l [QML QtQuickControls] {StatusBar}
        \li \mdash
    \row
        \li \l [QML QtQuickExtras] {StatusIndicator}
        \li \mdash
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {SwipeDelegate}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {SwipeView}
    \row
        \li \l [QML QtQuickControls] {Switch}
        \li \l [QML QtQuickControls2] {Switch}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {SwitchDelegate}
    \row
        \li \l [QML QtQuickControls] {TabView},
            \l [QML QtQuickControls] {Tab}
        \li \l [QML QtQuickControls2] {TabBar},
            \l [QML QtQuickControls2] {TabButton}
    \row
        \li \l [QML QtQuickControls] {TableView}
        \li \mdash
    \row
        \li \l [QML QtQuickControls] {TextArea}
        \li \l [QML QtQuickControls2] {TextArea}
    \row
        \li \l [QML QtQuickControls] {TextField}
        \li \l [QML QtQuickControls2] {TextField}
    \row
        \li \l [QML QtQuickExtras] {ToggleButton}
        \li \mdash
    \row
        \li \l [QML QtQuickControls] {ToolBar}
        \li \l [QML QtQuickControls2] {ToolBar}
    \row
        \li \l [QML QtQuickControls] {ToolButton}
        \li \l [QML QtQuickControls2] {ToolButton}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {ToolSeparator}
    \row
        \li \mdash
        \li \l [QML QtQuickControls2] {ToolTip}
    \row
        \li \l [QML QtQuickControls] {TreeView}
        \li \mdash
    \row
        \li \l [QML QtQuickExtras] {Tumbler},
            \l [QML QtQuickExtras] {TumblerColumn}
        \li \l [QML QtQuickControls2] {Tumbler}
    \endtable

    \section1 Related Information

    \list
      \li \l{Qt Quick}
      \li \l{Qt Quick Controls 2 QML Types}
      \li \l{Qt Quick Controls QML Types}
      \li \l{Qt Quick Extras QML Types}
    \endlist
*/