diff options
Diffstat (limited to 'src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc')
| -rw-r--r-- | src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc | 378 |
1 files changed, 378 insertions, 0 deletions
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc new file mode 100644 index 00000000..a85890f5 --- /dev/null +++ b/src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc @@ -0,0 +1,378 @@ +/**************************************************************************** +** +** 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/theme changes + \li Yes \sup 1 + \li Yes \sup 2 + \row + \li Can be used on Desktop + \li Yes + \li Yes \sup 3 + \row + \li Can be used on Mobile + \li Yes \sup 4 + \li Yes + \row + \li Can be used on Embedded + \li Yes \sup 4 + \li Yes + \row + \li Internal event handling + \li QML + \li C++ + \endtable + + \list 1 + \li Not officially supported, but technically possible via private APIs + \li Only themes for specific styles can be changed at runtime, styles are fixed + \li No hover effects + \li Performance may not be optimal + \endlist + + \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 \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] {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 +*/ |