From dc5b4044fddfa31509610b22f9527435cd1c580c Mon Sep 17 00:00:00 2001 From: Venugopal Shivashankar Date: Tue, 22 Mar 2016 14:40:51 +0100 Subject: Rename Qt Labs Controls to Qt Quick Controls 2 - doc filenames Except the .qdocconf all .qdoc files are renamed to use "qtquickcontrols2" instead of "qtlabscontrols". Change-Id: I317a4e81ea4e78b63a0d4d849d7352f496824cb3 Reviewed-by: J-P Nurmi --- .../doc/src/qtquickcontrols2-differences.qdoc | 283 +++++++++++++++++++++ 1 file changed, 283 insertions(+) create mode 100644 src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc (limited to 'src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc') 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..ccdab0ef --- /dev/null +++ b/src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc @@ -0,0 +1,283 @@ +/**************************************************************************** +** +** 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 qtlabscontrols-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 Labs Controls 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 {TODO}{here}. + + In Qt Labs Controls, 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 Labs Controls 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 Labs Controls + \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 \b * + \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 + + \b {* No hover support} + + \section2 Porting Qt Quick Controls Code + + The API of Qt Labs Controls 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 Labs Controls: + + \qml + Button { + contentItem: Label { + // ... + } + } + \endqml + + \section3 Preparing for Migration + + With this in mind, a good way to prepare for a migration to Qt Quick + Labs 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 Button.qml, 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 Changes + + \table + \header + \li Qt Quick Controls + \li Qt Labs Controls + \row + \li \l [QtQuickControls] {Action} + \li No equivalent; see \l [QtQuick] {Shortcut} instead. + \row + \li \l [QtQuickControls] {ApplicationWindow} + \li \l [QtLabsControls] {ApplicationWindow} + \row + \li \l [QtQuickControls] {BusyIndicator} + \li \l [QtLabsControls] {BusyIndicator} + \row + \li \l [QtQuickControls] {Button} + \li \l [QtLabsControls] {Button} + \row + \li \l [QtQuickControls] {Calendar} + \li No equivalent; see \l [QML] {MonthGrid}, \l [QML] {DayOfWeekRow} and \l [QML] {WeekNumberColumn} instead. + \row + \li \l [QtQuickControls] {CheckBox} + \li \l [QtLabsControls] {CheckBox} + \row + \li \l [QtQuickControls] {ComboBox} + \li \l [QtLabsControls] {ComboBox} + \row + \li \l [QtQuickControls] {ExclusiveGroup} + \li \l [QtLabsControls] {ButtonGroup} + \row + \li \l [QtQuickControls] {GroupBox} + + \li \l [QtLabsControls] {GroupBox}, or \l [QtLabsControls] {Frame} + if a title is not required. + + \row + \li \l [QtQuickControls] {Label} + \li \l [QtLabsControls] {Label} + \row + \li \l [QtQuickControls] {Menu} + \li \l [QtLabsControls] {Menu} + \row + \li \l [QtQuickControls] {ProgressBar} + \li \l [QtLabsControls] {ProgressBar} + \row + \li \l [QtQuickControls] {RadioButton} + \li \l [QtLabsControls] {RadioButton} + \row + \li \l [QtQuickControls] {ScrollView} + \li \l [QtLabsControls] {ScrollBar}, + \l [QtLabsControls] {ScrollIndicator} + \row + \li \l [QtQuickControls] {Slider} + \li \l [QtLabsControls] {Slider} + \row + \li \l [QtQuickControls] {SpinBox} + \li \l [QtLabsControls] {SpinBox} + \row + \li \l [QtQuickControls] {Stack}, + \l [QtQuickControls] {StackView}, + \l [QtQuickControls] {StackViewDelegate} + \li \l [QtLabsControls] {StackView} + \row + \li \l [QtQuickControls] {StatusBar} + \li No equivalent + \row + \li \l [QtQuickControls] {Switch} + \li \l [QtLabsControls] {Switch} + \row + \li \l [QtQuickControls] {Tab}, + \l [QtQuickControls] {TabView} + \li \l [QtLabsControls] {TabBar} in combination with, for example, + \l [QtLabsControls] {SwipeView}. + \row + \li \l [QtQuickControls] {TableView} + \li No equivalent + \row + \li \l [QtQuickControls] {TextArea} + \li \l [QtLabsControls] {TextArea} + \row + \li \l [QtQuickControls] {TextField} + \li \l [QtLabsControls] {TextField} + \row + \li \l [QtQuickControls] {ToolBar} + \li \l [QtLabsControls] {ToolBar} + \row + \li \l [QtQuickControls] {ToolButton} + \li \l [QtLabsControls] {ToolButton} + \row + \li \l [QtQuickControls] {TreeView} + \li No equivalent + \endtable + + \section1 Related Information + + \list + \li \l{Qt Quick} + \li \l{Qt Quick Controls} + \li \l{Qt Labs Controls QML Types}{Qt Labs Controls QML Types} + \endlist +*/ -- cgit v1.2.3