diff options
Diffstat (limited to 'src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc')
| -rw-r--r-- | src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc | 689 |
1 files changed, 0 insertions, 689 deletions
diff --git a/src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc deleted file mode 100644 index 7f8a066d..00000000 --- a/src/imports/controls/doc/src/qtquickcontrols2-differences.qdoc +++ /dev/null @@ -1,689 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2017 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 qtquickcontrols2-differences.html - \title Differences with Qt Quick Controls 1 - - Qt Quick Controls 1 was 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 was 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, 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 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 1 - \li Qt Quick Controls - \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 - \row - \li Can be used on Mobile - \li Yes \sup 3 - \li Yes - \row - \li Can be used on Embedded - \li Yes \sup 3 - \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 Performance may not be optimal - \endlist - - \section2 Porting Qt Quick Controls 1 Code - - The API of Qt Quick Controls is very similar to Qt Quick Controls 1, 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 1: - - \qml - Button { - style: ButtonStyle { - label: Label { - // ... - } - } - } - \endqml - - To style a button in Qt Quick 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 - 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 1 button above could be - moved to a file named \c Button.qml in a directory named \c controls, and - used in the following manner: - - \qml - import "controls" as Controls - - Controls.Button { - // ... - } - \endqml - - This works with both modules, and will reduce the amount of work needed - when the migration begins. - - \section2 Type Comparison Table - - The first column lists all types available in \l {Qt Quick Controls 1}, - \l {Qt Quick Dialogs}, and \l {Qt Quick Extras}. - The second column documents the respective type in Qt Quick Controls. - When a direct alternative is not available, the third column contains - an alternative that provides related functionality. The last column - contains some remarks about the differences between the types in the - different modules. - - \table - \header - \li Qt Quick Controls 1 - \li Qt Quick Controls - \li Alternatives - \li Remarks - \row - \li \l [QML QtQuickControls1] {Action} - \li \l [QML QtQuickControls2] {Action} - \li \l [QML QtQuick] {Shortcut} \br\sup {(Qt Quick)} - \li - \row - \li \l [QML QtQuickControls1] {ApplicationWindow} - \li \l [QML QtQuickControls2] {ApplicationWindow} - \li - \li - \row - \li \l [QML QtQuickControls1] {BusyIndicator} - \li \l [QML QtQuickControls2] {BusyIndicator} - \li - \li - \row - \li \l [QML QtQuickControls1] {Button} - \li \l [QML QtQuickControls2] {Button} - \li - \li - \row - \li \l [QML QtQuickControls1] {Calendar} - \li \mdash - \li \l [QML QtQuickCalendar] {MonthGrid},\br - \l [QML QtQuickCalendar] {DayOfWeekRow},\br - \l [QML QtQuickCalendar] {WeekNumberColumn} \br\sup {(Qt Quick Calendar)} - \li \list - \li \b {Qt Quick Calendar}: \c MonthGrid, \c DayOfWeek, and \c WeekNumberColumn - are \e unstyled building blocks for calendar views. - \endlist - \row - \li \l [QML QtQuickControls1] {CheckBox} - \li \l [QML QtQuickControls2] {CheckBox} - \li - \li - \row - \li \l [QML QtQuickControls1] {ComboBox} - \li \l [QML QtQuickControls2] {ComboBox} - \li - \li - \row - \li \l [QML QtQuickControls1] {ExclusiveGroup} - \li \mdash - \li \l [QML QtQuickControls2] {ActionGroup},\br - \l [QML QtQuickControls2] {ButtonGroup} \br\sup {(Qt Quick Controls)} - \li \list - \li \b {Qt Quick Controls}: \c ActionGroup and \c ButtonGroup offer similar functionality. - \endlist - \row - \li \l [QML QtQuickControls1] {GroupBox} - \li \l [QML QtQuickControls2] {GroupBox} - \li - \li - \row - \li \l [QML QtQuickControls1] {Label} - \li \l [QML QtQuickControls2] {Label} - \li - \li - \row - \li \l [QML QtQuickControls1] {Menu} - \li \l [QML QtQuickControls2] {Menu} - \li \l [QML QtLabsPlatform] {Menu} \br\sup {(Qt Labs Platform)} - \li \list - \li \b {Qt Quick Controls 1}: \c Menu is native on platforms where an - implementation is available in the Qt Platform Abstraction Layer. - Other platforms use a QML-based top-level menu popup window. \c Menu - supports traditional desktop style cascading submenus, but does not - work on Embedded Linux because \l EGLFS does not support multiple - top-level windows. - \li \b {Qt Quick Controls}: \c Menu is a non-native \c Item-based popup - that is stacked above the application content. Due to this, menu popups - are restricted within window boundaries. \c Menu is fully customizable - using QML and Qt Quick, and allows adding any \c Items. Traditional - desktop oriented features, such as cascading submenus and visualizing - keyboard shortcuts are missing. - \li \b {Qt Labs Platform}: \c Menu is an \e experimental native menu that - uses Qt Widgets as a fallback on platforms where a native implementation - is not available in the Qt Platform Abstraction Layer. - \endlist - \row - \li \l [QML QtQuickControls1] {MenuBar} - \li \l [QML QtQuickControls2] {MenuBar} - \li \l [QML QtLabsPlatform] {MenuBar} \br\sup {(Qt Labs Platform)} - \li \list - \li \b {Qt Quick Controls 1}: \c MenuBar is native on platforms where an - implementation is available in the Qt Platform Abstraction Layer. Other - platforms use a QML-based menubar item stacked at the top of the window. - \li \b {Qt Quick Controls}: \c MenuBar is a non-native QML-based menubar - that can be fully customized using QML and Qt Quick. - \li \b {Qt Labs Platform}: \c MenuBar is an \e experimental native menubar. - It is only available on platforms where a native implementation is available - in the Qt Platform Abstraction Layer. - \endlist - \row - \li \l [QML QtQuickControls1] {MenuItem},\br - \l [QML QtQuickControls1] {MenuSeparator} - \li \l [QML QtQuickControls2] {MenuItem},\br - \l [QML QtQuickControls2] {MenuSeparator} - \li \l [QML QtLabsPlatform] {MenuItem},\br - \l [QML QtLabsPlatform] {MenuSeparator} \br\sup {(Qt Labs Platform)} - \li \list - \li \b {Qt Quick Controls 1}: \c MenuItem and \c MenuSeparator are native - on platforms where an implementation is available in the Qt Platform - Abstraction Layer. Other platforms use QML-based menu items and separators. - \li \b {Qt Quick Controls}: \c MenuItem and \c MenuSeparator are a non-native - QML-based menu items and separators that can be fully customized using QML - and Qt Quick. - \li \b {Qt Labs Platform}: \c MenuItem and \c MenuSeparator are \e experimental - native menu items and separators. - \endlist - \row - \li \l [QML QtQuickControls1] {ProgressBar} - \li \l [QML QtQuickControls2] {ProgressBar} - \li - \li - \row - \li \l [QML QtQuickControls1] {RadioButton} - \li \l [QML QtQuickControls2] {RadioButton} - \li - \li - \row - \li \l [QML QtQuickControls1] {ScrollView} - \li \l [QML QtQuickControls2] {ScrollView} - \li - \li - \row - \li \l [QML QtQuickControls1] {Slider} - \li \l [QML QtQuickControls2] {Slider} - \li - \li - \row - \li \l [QML QtQuickControls1] {SpinBox} - \li \l [QML QtQuickControls2] {SpinBox} - \li - \li - \row - \li \l [QML QtQuickControls1] {SplitView} - \li \l [QML QtQuickControls2] {SplitView} - \li - \li \list - \li \b {Qt Quick Controls 1}: Uses \l Layout attached properties - to specify size hints. - \li \b {Qt Quick Controls}: Uses dedicated - \l [QML QtQuickControls2] {SplitView} attached properties - to specify size hints. - Allows \l {SplitView::saveState()}{saving} and - \l {SplitView::restoreState()}{restoring} state. - Separate attached \l SplitHandle API for managing split - handles. - \endlist - \row - \li \l [QML QtQuickControls1] {StackView},\br - \l [QML QtQuickControls1] {StackViewDelegate},\br - \l [QML QtQuickControls1] {Stack} - \li \l [QML QtQuickControls2] {StackView} - \li - \li \list - \li \b {Qt Quick Controls}: \c StackView provides customizable transitions - and attached properties via a single \c StackView type. - \endlist - \row - \li \l [QML QtQuickControls1] {StatusBar} - \li \mdash - \li \l [QML QtQuickControls2] {ToolBar} \br\sup {(Qt Quick Controls)} - \li \list - \li \b {Qt Quick Controls}: \c ApplicationWindow allows assigning any - item or control, such as \c ToolBar, as a header or footer. - \endlist - \row - \li \l [QML QtQuickControls1] {Switch} - \li \l [QML QtQuickControls2] {Switch} - \li - \li - \row - \li \l [QML QtQuickControls1] {TabView},\br - \l [QML QtQuickControls1] {Tab} - \li \mdash - \li \l [QML QtQuickControls2] {TabBar},\br - \l [QML QtQuickControls2] {TabButton} \br\sup {(Qt Quick Controls)} - \li \list - \li \b {Qt Quick Controls}: \c TabBar and \c TabButton offer similar - functionality, and can be used to build tabbed views. - \endlist - \row - \li \l [QML QtQuickControls1] {TableView} - \li \mdash - \li The new \l [QML QtQuick] {TableView} can be found in the Qt Quick - module. - \li - \row - \li \l [QML QtQuickControls1] {TextArea} - \li \l [QML QtQuickControls2] {TextArea} - \li - \li \list - \li \b {Qt Quick Controls 1}: \c TextArea inherits \c ScrollView and is therefore - always a scrollable editor. - \li \b {Qt Quick Controls}: \c TextArea is a simpler multi-line editor that can - be optionally attached to a \c Flickable to provide scrolling functionality. - This allows using \c TextArea in a scrollable page without having two nested - scrollable areas, which can be problematic and cause usability issues. - \endlist - \row - \li \l [QML QtQuickControls1] {TextField} - \li \l [QML QtQuickControls2] {TextField} - \li - \li - \row - \li \l [QML QtQuickControls1] {ToolBar} - \li \l [QML QtQuickControls2] {ToolBar} - \li - \li - \row - \li \l [QML QtQuickControls1] {ToolButton} - \li \l [QML QtQuickControls2] {ToolButton} - \li - \li - \row - \li \l [QML QtQuickControls1] {TreeView} - \li \mdash - \li - \li - - \header - \li Qt Quick Dialogs - \li Qt Quick Controls - \li Alternatives - \li Remarks - \row - \li \l [QML QtQuickDialogs] {Dialog} - \li \mdash - \li \l [QML QtQuickControls2] {Dialog} - \li \list - \li \b {Qt Quick Dialogs}: \c Dialog is either a top-level window or an \c Item-based popup - depending on whether the underlying platform supports multiple top-level windows. - \li \b {Qt Quick Controls}: \c Dialog is not a top-level window, but an \c Item-based - popup that is stacked above the application content. Due to this, dialogs are restricted - within window boundaries. - \endlist - \row - \li \l [QML QtQuickDialogs] {ColorDialog},\br - \l [QML QtQuickDialogs] {FileDialog},\br - \l [QML QtQuickDialogs] {FontDialog},\br - \l [QML QtQuickDialogs] {MessageDialog} - \li \mdash - \li \l [QML QtLabsPlatform] {ColorDialog},\br - \l [QML QtLabsPlatform] {FileDialog},\br - \l [QML QtLabsPlatform] {FolderDialog},\br - \l [QML QtLabsPlatform] {FontDialog},\br - \l [QML QtLabsPlatform] {MessageDialog} \br\sup {(Qt Labs Platform)} - \li \list - \li \b {Qt Quick Dialogs}: Dialogs are native on platforms where an implementation - is available in the Qt Platform Abstraction Layer. Other platforms use either - Qt Widgets or QML-based dialogs depending on whether the underlying platform - supports multiple top-level windows. - \li \b {Qt Labs Platform}: \e Experimental native dialogs that use Qt Widgets as - a fallback on platforms where a native implementation is not available in the - Qt Platform Abstraction Layer. - \endlist - - \header - \li Qt Quick Extras - \li Qt Quick Controls - \li Alternatives - \li Remarks - \row - \li \l [QML QtQuickExtras] {CircularGauge} - \li \mdash - \li - \li - \row - \li \l [QML QtQuickExtras] {DelayButton} - \li \l [QML QtQuickControls2] {DelayButton} - \li - \li - \row - \li \l [QML QtQuickExtras] {Dial} - \li \l [QML QtQuickControls2] {Dial} - \li - \li - \row - \li \l [QML QtQuickExtras] {Gauge} - \li \mdash - \li - \li - \row - \li \l [QML QtQuickExtras] {Picture} - \li \mdash - \li - \li - \row - \li \l [QML QtQuickExtras] {PieMenu} - \li \mdash - \li - \li - \row - \li \l [QML QtQuickExtras] {StatusIndicator} - \li \mdash - \li - \li - \row - \li \l [QML QtQuickExtras] {ToggleButton} - \li \mdash - \li - \li - \row - \li \l [QML QtQuickExtras] {Tumbler},\br - \l [QML QtQuickExtras] {TumblerColumn} - \li \l [QML QtQuickControls2] {Tumbler} - \li - \li \list - \li \b {Qt Quick Extras}: \c Tumbler can consist of multiple columns. - \li \b {Qt Quick Controls}: \c Tumbler presents a single spinnable wheel. - Multiple columns can be created by placing multiple \c Tumblers next - to each other. - \endlist - - \header - \li No Predecessor - \li Qt Quick Controls - \li Alternatives - \li Remarks - \row - \li \mdash - \li \l [QML QtQuickControls2] {AbstractButton} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {ActionGroup} - \li \l [QML QtQuickControls1] {ExclusiveGroup} \br\sup {(Qt Quick Controls 1)} - \li \list - \li \b {Qt Quick Controls 1}: \c ExclusiveGroup offers similar functionality. - \endlist - \row - \li \mdash - \li \l [QML QtQuickControls2] {ButtonGroup} - \li \l [QML QtQuickControls1] {ExclusiveGroup} \br\sup {(Qt Quick Controls 1)} - \li \list - \li \b {Qt Quick Controls 1}: \c ExclusiveGroup offers similar functionality. - \endlist - \row - \li \mdash - \li \l [QML QtQuickControls2] {CheckDelegate} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {Container} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {Control} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {Drawer} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {Frame} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {ItemDelegate} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {Page} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {PageIndicator} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {Pane} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {Popup} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {RadioDelegate} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {RangeSlider} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {RoundButton} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {ScrollBar},\br - \l [QML QtQuickControls2] {ScrollIndicator} - \li \l [QML QtQuickControls1] {ScrollView} \br\sup {(Qt Quick Controls 1)} - \li \list - \li \b {Qt Quick Controls 1}: \c ScrollView offers similar functionality. - It combines horizontal and vertical scrollbars, and the background and - frame around the scrollable view. - \endlist - \row - \li \mdash - \li \mdash - \li \l [QML QtLabsPlatform] {StandardPaths} \br\sup {(Qt Labs Platform)} - \li \list - \li \b {Qt Quick Dialogs}: \c FileDialog offers a shortcut property that can be used - to access the most common standard paths. - \li \b {Qt Labs Platform}: \c StandardPaths offers a separate type to give full access - to the standard paths. - \endlist - \row - \li \mdash - \li \l [QML QtQuickControls2] {SwipeDelegate} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {SwipeView} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {SwitchDelegate} - \li - \li - \row - \li \mdash - \li \mdash - \li \l [QML QtLabsPlatform] {SystemTrayIcon} \br\sup {(Qt Labs Platform)} - \li \list - \li \b {Qt Labs Platform}: \c SystemTrayIcon is an \e experimental native - system tray icon that uses Qt Widgets as a fallback on platforms where - a native implementation is not available in the Qt Platform Abstraction - Layer. - \endlist - \row - \li \mdash - \li \l [QML QtQuickControls2] {TabBar},\br - \l [QML QtQuickControls2] {TabButton} - \li \l [QML QtQuickControls1] {TabView} \br\sup {(Qt Quick Controls 1)} - \li \list - \li \b {Qt Quick Controls 1}: \c TabView offers similar functionality. - It combines the tab bar, background and frame around the tabs. - \endlist - \row - \li \mdash - \li \l [QML QtQuickControls2] {ToolSeparator} - \li - \li - \row - \li \mdash - \li \l [QML QtQuickControls2] {ToolTip} - \li - \li \list - \li \b {Qt Quick Controls 1}: \c Button and \c Action have built-in - Qt Widgets-based tooltips. - \li \b {Qt Quick Controls}: \c ToolTip can be attached to any \c Item. - \endlist - \endtable - - \section1 Related Information - - \list - \li \l{Qt Quick} - \li \l{Qt Quick Controls QML Types} - \li \l{Qt Quick Controls 1 QML Types} - \li \l{Qt Quick Extras QML Types} - \li \l{Qt Labs Calendar QML Types} - \li \l{Qt Labs Platform QML Types} - \endlist -*/ |