diff options
Diffstat (limited to 'src/imports/controls/doc/src/qtlabscontrols-index.qdoc')
| -rw-r--r-- | src/imports/controls/doc/src/qtlabscontrols-index.qdoc | 342 |
1 files changed, 342 insertions, 0 deletions
diff --git a/src/imports/controls/doc/src/qtlabscontrols-index.qdoc b/src/imports/controls/doc/src/qtlabscontrols-index.qdoc new file mode 100644 index 00000000..e24b269a --- /dev/null +++ b/src/imports/controls/doc/src/qtlabscontrols-index.qdoc @@ -0,0 +1,342 @@ +/**************************************************************************** +** +** 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-index.html + \title Qt Labs Controls + + \brief Provides a set of UI controls for Qt Quick. + + Qt Labs Controls provides a set of controls that can be used + to build complete interfaces in Qt Quick. + + \section1 QML Types + + \section2 Qt.labs.controls Module + \generatelist {qmltypesbymodule Qt.labs.controls} + + \section2 Qt.labs.calendar Module + \generatelist {qmltypesbymodule Qt.labs.calendar} + + \section1 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 \l {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. + + Control-specific style objects have been replaced by a Theme object that + offers a simple set of themable attributes. Basic color adjustments can be + made by setting a few properties that are automatically inherited by the + hierarchy of children. + + \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 { + label: 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] {CalendarView} instead. + \row + \li \l [QtQuickControls] {CheckBox} + \li \l [QtLabsControls] {CheckBox} + \row + \li \l [QtQuickControls] {ExclusiveGroup} + \li \l [QtLabsControls] {ExclusiveGroup} + \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] {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 No equivalent; see \l [QtLabsControls] {Tumbler} instead. + \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 Getting Started + + A basic example of a QML file that makes use of controls is shown here: + + \snippet basic-example.qml 0 + + \section1 Setting Up Controls from C++ + + Although QQuickView has traditionally been used to display QML files in a + C++ application, doing this means you can only set window properties from + C++. + + With Qt Labs Controls, declare an ApplicationWindow as the root item of + your application and launch it by using 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[]) + { + QGuiApplication app(argc, argv); + QQmlApplicationEngine engine("main.qml"); + return app.exec(); + } + \endcode + + \section2 Using C++ Data From QML + + If you need to register a C++ class to use from QML, you can call + qmlRegisterType() before declaring your QQmlApplicationEngine. + See \l [QtQml] {Defining QML Types from C++} for more information. + + If you need to expose data to QML components, you need to make them + available to the context of the current QML engine. See QQmlContext for + more information. + + \section2 Deploying Qt Labs Controls + + TODO + + \section1 Related Information + + \list + \li \l{Qt Quick} + \li \l{Qt Quick Layouts} + \li \l{Qt Labs Calendar} + \li \l{Qt Labs Controls QML Types}{Qt Labs Controls QML Types} + \endlist +*/ |