diff options
Diffstat (limited to 'src/quickcontrols2/doc/src')
46 files changed, 7644 insertions, 0 deletions
diff --git a/src/quickcontrols2/doc/src/external-pages.qdoc b/src/quickcontrols2/doc/src/external-pages.qdoc new file mode 100644 index 00000000..05005798 --- /dev/null +++ b/src/quickcontrols2/doc/src/external-pages.qdoc @@ -0,0 +1,36 @@ +/**************************************************************************** +** +** Copyright (C) 2020 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$ +** +****************************************************************************/ + +/*! + \externalpage https://doc.qt.io/qt-5/qtquickcontrols2-differences.html + \title Qt 5.15: Qt Quick Controls vs Qt Quick Controls 1 +*/ + +/*! + \externalpage https://doc.qt.io/qtcreator/creator-project-creating.html#selecting-project-type + \title Qt Creator: Project Types +*/ diff --git a/src/quickcontrols2/doc/src/includes/customize-button-background.qdocinc b/src/quickcontrols2/doc/src/includes/customize-button-background.qdocinc new file mode 100644 index 00000000..0acad02d --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/customize-button-background.qdocinc @@ -0,0 +1,25 @@ +//! [file] +\qml +import QtQuick +import QtQuick.Controls + +ApplicationWindow { + width: 400 + height: 400 + visible: true + + Button { + id: button + text: "A Special Button" + background: Rectangle { + implicitWidth: 100 + implicitHeight: 40 + color: button.down ? "#d6d6d6" : "#f6f6f6" + border.color: "#26282a" + border.width: 1 + radius: 4 + } + } +} +\endqml +//! [file] diff --git a/src/quickcontrols2/doc/src/includes/inputmethodhints.qdocinc b/src/quickcontrols2/doc/src/includes/inputmethodhints.qdocinc new file mode 100644 index 00000000..73710e1e --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/inputmethodhints.qdocinc @@ -0,0 +1,38 @@ +//! [flags] +The value is a bit-wise combination of flags or \c Qt.ImhNone if no hints are set. + +Flags that alter behavior are: + +\list +\li Qt.ImhHiddenText - Characters should be hidden, as is typically used when entering passwords. +\li Qt.ImhSensitiveData - Typed text should not be stored by the active input method + in any persistent storage like predictive user dictionary. +\li Qt.ImhNoAutoUppercase - The input method should not try to automatically switch to upper case + when a sentence ends. +\li Qt.ImhPreferNumbers - Numbers are preferred (but not required). +\li Qt.ImhPreferUppercase - Upper case letters are preferred (but not required). +\li Qt.ImhPreferLowercase - Lower case letters are preferred (but not required). +\li Qt.ImhNoPredictiveText - Do not use predictive text (i.e. dictionary lookup) while typing. + +\li Qt.ImhDate - The text editor functions as a date field. +\li Qt.ImhTime - The text editor functions as a time field. +\endlist + +Flags that restrict input (exclusive flags) are: + +\list +\li Qt.ImhDigitsOnly - Only digits are allowed. +\li Qt.ImhFormattedNumbersOnly - Only number input is allowed. This includes decimal point and minus sign. +\li Qt.ImhUppercaseOnly - Only upper case letter input is allowed. +\li Qt.ImhLowercaseOnly - Only lower case letter input is allowed. +\li Qt.ImhDialableCharactersOnly - Only characters suitable for phone dialing are allowed. +\li Qt.ImhEmailCharactersOnly - Only characters suitable for email addresses are allowed. +\li Qt.ImhUrlCharactersOnly - Only characters suitable for URLs are allowed. +\endlist + +Masks: + +\list +\li Qt.ImhExclusiveInputMask - This mask yields nonzero if any of the exclusive flags are used. +\endlist +//! [flags] diff --git a/src/quickcontrols2/doc/src/includes/qquickcontrol-background.qdocinc b/src/quickcontrols2/doc/src/includes/qquickcontrol-background.qdocinc new file mode 100644 index 00000000..02d92de0 --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickcontrol-background.qdocinc @@ -0,0 +1,13 @@ +//! [notes] + +\note If the background item has no explicit size specified, it automatically + follows the control's size. In most cases, there is no need to specify + width or height for a background item. + +\note Most controls use the implicit size of the background item to calculate +the implicit size of the control itself. If you replace the background item +with a custom one, you should also consider providing a sensible implicit +size for it (unless it is an item like \l Image which has its own implicit +size). + +//! [notes] diff --git a/src/quickcontrols2/doc/src/includes/qquickcontrol-focusreason.qdocinc b/src/quickcontrols2/doc/src/includes/qquickcontrol-focusreason.qdocinc new file mode 100644 index 00000000..b69e9e60 --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickcontrol-focusreason.qdocinc @@ -0,0 +1,15 @@ +This property holds the reason of the last focus change. + +\note This property does not indicate whether the control has \l {Item::activeFocus} + {active focus}, but the reason why the control either gained or lost focus. + +\value Qt.MouseFocusReason A mouse action occurred. +\value Qt.TabFocusReason The Tab key was pressed. +\value Qt.BacktabFocusReason A Backtab occurred. The input for this may include the Shift or Control keys; e.g. Shift+Tab. +\value Qt.ActiveWindowFocusReason The window system made this window either active or inactive. +\value Qt.PopupFocusReason The application opened/closed a pop-up that grabbed/released the keyboard focus. +\value Qt.ShortcutFocusReason The user typed a label's buddy shortcut +\value Qt.MenuBarFocusReason The menu bar took focus. +\value Qt.OtherFocusReason Another reason, usually application-specific. + +\sa Item::activeFocus diff --git a/src/quickcontrols2/doc/src/includes/qquickdial.qdocinc b/src/quickcontrols2/doc/src/includes/qquickdial.qdocinc new file mode 100644 index 00000000..3370b3d8 --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickdial.qdocinc @@ -0,0 +1,13 @@ +//! [inputMode] +Dial supports three \l {inputMode}{input modes}: \c Dial.Circular, +\c Dial.Horizontal and \c Dial.Vertical. The circular input mode operates on an +absolute input system, where the position of the cursor within the dial +directly reflects its value. The horizontal and vertical input modes use a +relative input system, where changes in the cursor's position are "added" to +the value of the dial. + +The following image illustrates the directions in which the various input modes +track movement: + +\image qtquickcontrols2-dial-inputmode.png +//! [inputMode] diff --git a/src/quickcontrols2/doc/src/includes/qquickicon.qdocinc b/src/quickcontrols2/doc/src/includes/qquickicon.qdocinc new file mode 100644 index 00000000..beef5624 --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickicon.qdocinc @@ -0,0 +1,50 @@ +//! [grouped-properties] +\table +\header + \li Name + \li Description +\row + \li name + \li This property holds the name of the icon to use. + + The icon will be loaded from the platform theme. If the icon is found + in the theme, it will always be used; even if \l icon.source is also set. + If the icon is not found, \l icon.source will be used instead. + + For more information on theme icons, see \l {QIcon::fromTheme()}. +\row + \li source + \li This property holds the name of the icon to use. + + The icon will be loaded as a regular image. + + If \l icon.name is set and refers to a valid theme icon, it will always + be used instead of this property. +\row + \li width + \li This property holds the width of the icon. + + The icon's width will never exceed this value, though it will + shrink when necessary. +\row + \li height + \li This property holds the height of the icon. + + The icon's height will never exceed this value, though it will + shrink when necessary. +\row + \li color + \li This property holds the color of the icon. + + The icon is tinted with the specified color, unless the color is + set to \c "transparent". + +\row + \li cache + \li This property specifies whether the icon should be cached. + + The default value is true. + + This property was introduced in QtQuick.Controls 2.13. +\endtable +//! [grouped-properties] diff --git a/src/quickcontrols2/doc/src/includes/qquickimaginestyle.qdocinc b/src/quickcontrols2/doc/src/includes/qquickimaginestyle.qdocinc new file mode 100644 index 00000000..f6fe5a97 --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickimaginestyle.qdocinc @@ -0,0 +1,57 @@ +//! [conf] +\table + \header + \li Variable + \li Description + \row + \li \c Path + \li Specifies the \l {imagine-path-attached-prop}{path} to the directory that contains + the Imagine style assets. If not specified, the built-in assets are used. + + For example, to specify a path to a directory stored in the + \l {The Qt Resource System}{resource system}: + + \badcode + [Imagine] + Path=:/imagine-assets + \endcode + + To specify a relative path to a local directory: + + \badcode + [Imagine] + Path=imagine-assets + \endcode + + \note Due to a technical limitation, the path should not be named + \e "imagine" if it is relative to the \c qtquickcontrols2.conf file. +\endtable +//! [conf] + +//! [env] +\table + \header + \li Variable + \li Description + \row + \li \c QT_QUICK_CONTROLS_IMAGINE_PATH + \li Specifies the path to the directory that contains the Imagine style assets. + If not specified, the built-in assets are used. + + For example, to specify a path to a directory stored in the + \l {The Qt Resource System}{resource system}: + + \badcode + QT_QUICK_CONTROLS_IMAGINE_PATH=:/imagine-assets + \endcode + + To specify a relative path to a local directory: + + \badcode + QT_QUICK_CONTROLS_IMAGINE_PATH=imagine-assets + \endcode + + \note Due to a technical limitation, the path should not be named + \e "imagine" if it is relative to the \c qtquickcontrols2.conf file. +\endtable +//! [env] diff --git a/src/quickcontrols2/doc/src/includes/qquickmaterialstyle.qdocinc b/src/quickcontrols2/doc/src/includes/qquickmaterialstyle.qdocinc new file mode 100644 index 00000000..72c97bb6 --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickmaterialstyle.qdocinc @@ -0,0 +1,79 @@ +//! [conf] +\table + \header + \li Variable + \li Description + \row + \li \c Theme + \li Specifies the default \l {material-theme-attached-prop}{Material theme}. + The value can be one of the available themes, for example \c "Dark". + \row + \li \c Variant + \li Specifies the Material variant. The Material Design has two + variants: a normal variant designed for touch devices, and a dense + variant for desktop. The dense variant uses smaller sizes for + controls and their fonts. + + The value can be \c "Normal" or \c "Dense". + \row + \li \c Accent + \li Specifies the default \l {material-accent-attached-prop}{Material accent color}. + The value can be any \l {colorbasictypedocs}{color}, but it is recommended to use + one of the \l {pre-defined Material colors}, for example \c "Teal". + \row + \li \c Primary + \li Specifies the default \l {material-primary-attached-prop}{Material primary color}. + The value can be any \l {colorbasictypedocs}{color}, but it is recommended to use + one of the \l {pre-defined Material colors}, for example \c "BlueGrey". + \row + \li \c Foreground + \li Specifies the default \l {material-foreground-attached-prop}{Material foreground color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Material colors}, + for example \c "Brown". + \row + \li \c Background + \li Specifies the default \l {material-background-attached-prop}{Material background color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Material colors}, + for example \c "Grey". +\endtable +//! [conf] + +//! [env] +\table + \header + \li Variable + \li Description + \row + \li \c QT_QUICK_CONTROLS_MATERIAL_THEME + \li Specifies the default \l {material-theme-attached-prop}{Material theme}. + The value can be one of the available themes, for example \c "Dark". + \row + \li \c QT_QUICK_CONTROLS_MATERIAL_VARIANT + \li Specifies the Material variant. The Material Design has two + variants: a normal variant designed for touch devices, and a dense + variant for desktop. The dense variant uses smaller sizes for + controls and their fonts. + + The value can be \c "Normal" or \c "Dense". + \row + \li \c QT_QUICK_CONTROLS_MATERIAL_ACCENT + \li Specifies the default \l {material-accent-attached-prop}{Material accent color}. + The value can be any \l {colorbasictypedocs}{color}, but it is recommended to use + one of the \l {pre-defined Material colors}, for example \c "Teal". + \row + \li \c QT_QUICK_CONTROLS_MATERIAL_PRIMARY + \li Specifies the default \l {material-primary-attached-prop}{Material primary color}. + The value can be any \l {colorbasictypedocs}{color}, but it is recommended to use + one of the \l {pre-defined Material colors}, for example \c "BlueGrey". + \row + \li \c QT_QUICK_CONTROLS_MATERIAL_FOREGROUND + \li Specifies the default \l {material-foreground-attached-prop}{Material foreground color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Material colors}, + for example \c "Brown". + \row + \li \c QT_QUICK_CONTROLS_MATERIAL_BACKGROUND + \li Specifies the default \l {material-background-attached-prop}{Material background color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Material colors}, + for example \c "Grey". +\endtable +//! [env] diff --git a/src/quickcontrols2/doc/src/includes/qquickoverlay-popup-parent.qdocinc b/src/quickcontrols2/doc/src/includes/qquickoverlay-popup-parent.qdocinc new file mode 100644 index 00000000..5562f6a0 --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickoverlay-popup-parent.qdocinc @@ -0,0 +1,20 @@ +The following example uses the attached \l {Overlay::overlay}{Overlay.overlay} +property to position a popup in the center of the window, despite the position +of the button that opens the popup: + +\code +Button { + onClicked: popup.open() + + Popup { + id: popup + + parent: Overlay.overlay + + x: Math.round((parent.width - width) / 2) + y: Math.round((parent.height - height) / 2) + width: 100 + height: 100 + } +} +\endcode diff --git a/src/quickcontrols2/doc/src/includes/qquickpopup-padding.qdocinc b/src/quickcontrols2/doc/src/includes/qquickpopup-padding.qdocinc new file mode 100644 index 00000000..31f5d2db --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickpopup-padding.qdocinc @@ -0,0 +1,10 @@ +//! [padding] + +The padding properties are used to control the geometry of the +\l {contentItem}{content item}. + +Popup uses the same approach to padding as \l {Control::padding}{Control}. +For a visual explanation of the padding system, see the \l {Control Layout} +section of the documentation. + +//! [padding] diff --git a/src/quickcontrols2/doc/src/includes/qquickstackview.qdocinc b/src/quickcontrols2/doc/src/includes/qquickstackview.qdocinc new file mode 100644 index 00000000..20c9bdc3 --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickstackview.qdocinc @@ -0,0 +1,5 @@ +//! [pop-ownership] +Only items that StackView created itself (from a \l Component or \l [QML] +url) will be destroyed when popped. See \l {Item Ownership} for more +information. +//! [pop-ownership] diff --git a/src/quickcontrols2/doc/src/includes/qquickswipedelegate-interaction.qdocinc b/src/quickcontrols2/doc/src/includes/qquickswipedelegate-interaction.qdocinc new file mode 100644 index 00000000..05aeadb6 --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickswipedelegate-interaction.qdocinc @@ -0,0 +1,5 @@ +Both interactive and non-interactive items can be used here. Normal +event handling rules apply; if an interactive control like \l Button +is used, interaction signals of SwipeDelegate such as +\l {AbstractButton::}{clicked()} will not get emitted if the button +is clicked. diff --git a/src/quickcontrols2/doc/src/includes/qquickswitch.qdocinc b/src/quickcontrols2/doc/src/includes/qquickswitch.qdocinc new file mode 100644 index 00000000..985f85d9 --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickswitch.qdocinc @@ -0,0 +1,28 @@ +//! [position] + +This property holds the logical position of the thumb indicator. + +The position is expressed as a fraction of the indicator's size, in the range +\c 0.0 - \c 1.0. The position can be used for example to determine whether +the thumb has been dragged past the halfway point. For visualizing a thumb +indicator, the right-to-left aware \l visualPosition should be used instead. + +\sa visualPosition + +//! [position] + + +//! [visualPosition] + +This property holds the visual position of the thumb indicator. + +The position is expressed as a fraction of the indicator's size, in the range +\c 0.0 - \c 1.0. When the control is \l {Control::mirrored}{mirrored}, the +value is equal to \c {1.0 - position}. This makes the value suitable for +visualizing the thumb indicator taking right-to-left support into account. +In order to for example determine whether the thumb has been dragged past +the halfway point, the logical \l position should be used instead. + +\sa position + +//! [visualPosition] diff --git a/src/quickcontrols2/doc/src/includes/qquickuniversalstyle.qdocinc b/src/quickcontrols2/doc/src/includes/qquickuniversalstyle.qdocinc new file mode 100644 index 00000000..a7ecbaef --- /dev/null +++ b/src/quickcontrols2/doc/src/includes/qquickuniversalstyle.qdocinc @@ -0,0 +1,53 @@ +//! [conf] +\table + \header + \li Variable + \li Description + \row + \li \c Theme + \li Specifies the default \l {universal-theme-attached-prop}{Universal theme}. + The value can be one of the available themes, for example \c "Dark". + \row + \li \c Accent + \li Specifies the default \l {universal-accent-attached-prop}{Universal accent color}. + The value can be any \l {colorbasictypedocs}{color}, but it is recommended to use + one of the \l {pre-defined Universal colors}, for example \c "Violet". + \row + \li \c Foreground + \li Specifies the default \l {universal-foreground-attached-prop}{Universal foreground color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Universal colors}, + for example \c "Brown". + \row + \li \c Background + \li Specifies the default \l {universal-background-attached-prop}{Universal background color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Universal colors}, + for example \c "Steel". +\endtable +//! [conf] + +//! [env] +\table + \header + \li Variable + \li Description + \row + \li \c QT_QUICK_CONTROLS_UNIVERSAL_THEME + \li Specifies the default \l {universal-theme-attached-prop}{Universal theme}. + The value can be one of the available themes, for example \c "Dark". + \row + \li \c QT_QUICK_CONTROLS_UNIVERSAL_ACCENT + \li Specifies the default \l {universal-accent-attached-prop}{Universal accent color}. + The value can be any \l {colorbasictypedocs}{color}, but it is recommended to use + one of the \l {pre-defined Universal colors}, for example \c "Violet". + \row + \li \c QT_QUICK_CONTROLS_UNIVERSAL_FOREGROUND + \li Specifies the default \l {universal-foreground-attached-prop}{Universal foreground color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Universal colors}, + for example \c "Brown". + \row + \li \c QT_QUICK_CONTROLS_UNIVERSAL_BACKGROUND + \li Specifies the default \l {universal-background-attached-prop}{Universal background color}. + The value can be any \l {colorbasictypedocs}{color}, or one of the \l {pre-defined Universal colors}, + for example \c "Steel". +\endtable +//! [env] diff --git a/src/quickcontrols2/doc/src/qt6-changes.qdoc b/src/quickcontrols2/doc/src/qt6-changes.qdoc new file mode 100644 index 00000000..efc1b84b --- /dev/null +++ b/src/quickcontrols2/doc/src/qt6-changes.qdoc @@ -0,0 +1,305 @@ +/**************************************************************************** +** +** Copyright (C) 2020 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 qtquickcontrols-changes-qt6.html + \title Changes to Qt Quick Controls + \ingroup changes-qt-5-to-6 + \brief Migrate Qt Quick Controls to Qt 6. + + Qt 6 is a result of the conscious effort to make the framework more + efficient and easy to use. + + We try to maintain compatibility for all the public APIs in each release. + Some changes were inevitable in an effort to make Qt a better framework. + + In this topic we summarize those changes in Qt Quick Controls, and provide + guidance to handle them. + + \section1 Migrating from Qt Quick Controls 1 + + Qt Quick Controls 1 was deprecated in Qt 5.11 and is removed from + Qt 6.0. Use Qt Quick Controls (previously known as Qt Quick Controls 2) + instead. For more information, refer to the + \l{Qt 5.15: Qt Quick Controls vs Qt Quick Controls 1} topic in the Qt 5 + documentation. + + \section1 Type registration changes + + Qt Quick Controls has undergone some large, mostly internal changes in Qt + 6. By making use of the improved type registration introduced in Qt 5.15, + we pave the way for compilation of the module's QML files to C++ and enable + tooling to become more effective. In particular, Qt Creator's QML code + model should have a more complete picture of types, making its completion + and error checking of Qt Quick Controls code more reliable. Static analysis + tools like qmllint and qmlformat also benefit by becoming aware of the + types that are now declared at compile time in C++. + + As a result of these changes, some things are done a little differently. + + \section2 Custom styles are now proper QML modules + + To enable compile time type registration, each Qt Quick Controls style is + now a proper QML module. Previously, a single \c Button.qml was sufficient + to create your own style. While convenient, this required some non-standard + API, which in turn required adaptation in tooling like Qt Designer. + + Now, all QML types that a style implements must be declared in that style's + qmldir file: + + \code + module MyStyle + Button 1.0 Button.qml + \endcode + + \omit + TODO: Once we have documentation for the CMake function qt6_add_qml_module, + this would be a good place to link to it, stating that you don't have to + manually write the qmldir files. + \endomit + + By unifying this with the rest of the QML world, styles become more + familiar to developers and hopefully easier to understand for beginners. As + a consequence, the following API had to be removed: + + \list + \li QQuickStyle::addStylePath() + \li QQuickStyle::availableStyles() + \li QQuickStyle::path() + \li QQuickStyle::stylePathList() + \li QT_QUICK_CONTROLS_STYLE_PATH + \endlist + + Now that the styles are required to be found in the QML engine's import + path like any other QML module, it is no longer necessary or possible to + support this API. + + \section3 Style names + + In addition, there is now only one valid, case-sensitive form for style + names: "Material", "MyStyle", and so on. That is: the style name must + exactly match the name of the QML module. This also applies to file + selectors, where previously, all style names were lower case. For example, + where the following was a valid structure for a Qt 5 project: + + \badcode + MyProject + ├── main.qml + ├── HomePage.qml + └── +material + └───HomePage.qml + \endcode + + In Qt 6, \c +material becomes \c +Material: + + \badcode + MyProject + ├── main.qml + ├── HomePage.qml + └── +Material + └───HomePage.qml + \endcode + + All of the existing ways to \l {Using Styles in Qt Quick Controls}{run an + application with a specific style} are still supported. + + \section2 Runtime and compile time style selection + + Importing a style now has extra meaning due to the way that imports work + internally. Previously, importing \c QtQuick.Controls would register the + control types from the current style with the QML engine: + + \qml + import QtQuick.Controls + \endqml + + We refer to this as runtime style selection, as the style is selected at + runtime. + + Explicitly importing \c QtQuick.Controls.Material would then simply expose + any extra API provided by that style (for example, the attached Material + type): + + \qml + import QtQuick.Controls.Material + \endqml + + Now, explicitly importing a style does both. + + This effectively means that the control types (like Button) from the last + imported style will be used. We refer to this as compile time style + selection. + + This has implications for existing code. Namely, if your application + supports more than one style, move these imports into their own QML files + that are file-selected. + + For example, if you have the following \c main.qml: + + \qml + import QtQuick.Controls + import QtQuick.Controls.Material + import QtQuick.Controls.Universal + + ApplicationWindow { + width: 600 + height: 400 + visible: true + + Material.theme: darkMode ? Material.Dark : Material.Light + Universal.theme: darkMode ? Universal.Dark : Universal.Light + + // Child items, etc. + } + \endqml + + You can move the common code into a "base" component: + + \qml + // MainWindow.qml + + import QtQuick.Controls + + ApplicationWindow {} + \endqml + + Then, add a \c +Material subdirectory, and in it, add the Material-specific code into \c MainWindow.qml: + + \qml + // +Material/MainWindow.qml + + import QtQuick.Controls.Material + + ApplicationWindow { + Material.theme: darkMode ? Material.Dark : Material.Light + } + \endqml + + Do the same for Universal: + + \qml + // +Universal/MainWindow.qml + + import QtQuick.Controls.Universal + + ApplicationWindow { + Universal.theme: darkMode ? Universal.Dark : Universal.Light + } + \endqml + + Then, in \c main.qml: + + \qml + import QtQuick.Controls + + MainWindow { + width: 600 + height: 400 + visible: true + + // Child items, etc. + } + \endqml + + See also: \l {Using File Selectors with Qt Quick Controls}. + + \section1 Default Style + + The Default style was renamed to "Basic", as it is no longer the default + style. Instead, the default style is now chosen based on the platform + that Qt was built for: + + \list + \li Android: \l {Material Style} + \li Linux: \l {Fusion Style} + \li macOS: \macos Style + \li Windows: Windows Style + \li All other platforms: \l {Basic Style} + \endlist + + Therefore, applications that didn't specify a style in Qt 5 and have customized + controls should \l {Using Styles in Qt Quick Controls}{explicitly specify} + the Basic style in Qt 6 to ensure that those controls look and behave as + they did with Qt 5. + + \section1 Palette + + The palette API was moved to QQuickItem. The various APIs that use palettes + in Qt Quick Controls are unchanged. + + \section1 Controls + + \section2 ApplicationWindow + + The deprecated overlay properties and attached API were removed. Use the + \l Overlay attached type instead. + + \section2 ComboBox + + The \l {ComboBox::}{pressed} property is now read-only. To modify the + visual pressed state of a ComboBox, use the \l {ComboBox::}{down} property + instead. + + \section2 Container + + The deprecated \c removeItem(var) function was removed. + \l {Container::}{removeItem(Item)} or \l {Container::}{takeItem(int)} can + be used instead. + + \section2 Dialog + + \l {Dialog}'s \l {Dialog::}{accepted()} and \l {Dialog::}{rejected()} + signals are now emitted before \l {Popup::}{closed()} when calling + \l {Dialog::}{done()}, \l {Dialog::}{accept()} and \l {Dialog::}{reject()}. + + \section2 Menu + + The deprecated \c removeItem(var) function was removed. + \l {Menu::}{removeItem(Item)} or \l {Menu::}{takeItem(int)} can be used + instead. + + \section2 ToolTip + + \l {ToolTip}'s timeout now begins only after \l {Popup::}{opened()} has + been emitted. This results in tooltips with enter transitions being visible + for the entire duration of the timeout property. This means that they are + visible slightly longer than they were before, so it may be worthwhile to + visually check tooltips in your application and adjust timeouts if + necessary. + + \section2 StackView + + The StackView.Transition enum value was deprecated. The operation argument + can be omitted in order to use the default transition for any given + operation. + + \section2 Tumbler + + \l {Item::}{implicitWidth} and \l {Item::}{implicitHeight} must now be + provided for \l {Tumbler}'s \l {Control::}{contentItem}, making it + consistent with all other controls. +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-basic.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-basic.qdoc new file mode 100644 index 00000000..ee8d3ce4 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-basic.qdoc @@ -0,0 +1,55 @@ +/**************************************************************************** +** +** 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-basic.html + \title Basic Style + + The Basic style is a basic all-round style. + + The Basic style is a simple and light-weight style that offers the maximum + performance for Qt Quick Controls. It is built with a minimal amount of Qt + Quick primitives, and keeps animations and transitions to the minimum. + + \image qtquickcontrols2-basic.png + + The style is selected by default when running Qt Quick Controls applications. + It is built into the module's resources, so by default it is shipped with + any application that depends on the Qt Quick Controls module + + \note The Basic style is used as a fallback for other styles. If a style + does not implement a certain control, the Basic style implementation of + that control is selected. + + \b {See also} \l {Material Style}, \l {Universal Style} + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-buttons.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-buttons.qdoc new file mode 100644 index 00000000..6a4c5926 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-buttons.qdoc @@ -0,0 +1,191 @@ +/**************************************************************************** +** +** 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-buttons.html + \title Button Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for button controls + + Qt Quick Controls offers a selection of button-like controls. + + \annotatedlist qtquickcontrols2-buttons + + Each type of button has its own specific use case. The following + sections offer guidelines for choosing the appropriate type of button, + depending on the use case. + + \section1 Button Control + + \l Button is a clickable control that starts an action, or opens or + closes a popup. A button usually has a text label but it can also + contain an icon. + + Button is a very suitable control when a popup or dialog needs + to perform an action. The most common examples are Apply, Cancel, + Save, Close and Help. + + \image qtquickcontrols2-button.gif + + Recommendations: + + \list + \li The button's text should be a verb describing the action, or a noun matching + the title of the popup that will be opened. + \li Don't use a button to set state. \l Switch is more suitable for that. + \li Use the default font unless you have UI guidelines specifying otherwise. + \li If the text is localized, consider the influence of a longer text on the layout. + \endlist + + \b {See also} \l Button and \l AbstractButton + + \section1 CheckBox Control + + \image qtquickcontrols2-checkbox.gif + + \l CheckBox is used to build multi-selection option lists. Any number of + options can be selected, including none, but the options should + not be mutually exclusive. + + Use a single CheckBox for a yes/no choice, such as when you have + to accept the terms of service agreement in a form. + + For a single yes/no choice, it is also possible to use a switch. If the choice + concerns an option, it is best to use a CheckBox. If it concerns action to + be taken, a switch is recommended. + + When options can be grouped, you can use a partially checked CheckBox to + represent the whole group. Use the checkbox's + \l {CheckBox::checkState}{partially checked state} when a user selects + some, but not all, sub-items in the group. + + The three availables check states are: checked, partially checked and + unchecked. + + The checkable options are often listed vertically. + + Recommendations: + \list + \li The checkbox label should be a statement that the check mark makes true, + and that the absence of a check mark makes false. + \li The checkbox label should not contain a negative statement. + \li Use the default font, unless you have UI guidelines specifying otherwise. + \li If the text is localized, consider the influence of a longer text on the layout. + \endlist + + \b {See also} \l CheckBox + + \section1 DelayButton Control + + \l DelayButton is a button that incorporates a delay before triggering an action. + This delay prevents accidental presses. + + \image qtquickcontrols2-delaybutton.gif + + Recommendations: + \list + \li Use in touch user interfaces. + \li Use for actions that must be triggered with care. + \endlist + + \b {See also} \l Button and \l AbstractButton + + \section1 RadioButton Control + + \image qtquickcontrols2-radiobutton.gif + + \l RadioButton is used to select only one option from a set of options. + Selecting one option automatically deselects the one selected before. + + If there are only two mutually exclusive options, combine them into a + single checkbox or a switch. + + Recommendations: + + \list + \li Limit the label text to one line. + \li Ensure that a sensible default option is checked. + \li List RadioButton options vertically. + \li If the text is localized, consider the influence of a longer text on the layout. + \li Use the default font, unless you have UI guidelines that specify otherwise. + \li Just like with CheckBox, do not make the list too large. + \li In order to avoid confusion, do not put two groups of radio buttons next to each + other. + \endlist + + \b {See also} \l RadioButton + + \section1 RoundButton Control + + \l RoundButton is a clickable control that starts an action, or opens or + closes a popup. A round button with a square image icon or one-letter font + icon is circular. A circular RoundButton takes less space than a normal + \l Button, and can also be used as a floating action button. + + \image qtquickcontrols2-roundbutton.png + + Recommendations: + + \list + \li Keep labels short and concise. + \li If the text is localized, consider the influence of a longer text on the layout. + \endlist + + \b {See also} \l RoundButton + + \section1 Switch Control + + \image qtquickcontrols2-switch.png + + \l Switch represents a physical switch that allows users to choose between an "on" + or "off" state. + Use a switch for binary operations that take effect immediately after it has been + switched on. For example, a switch to turn WIFI on or off. + + Recommendations: + + \list + \li Keep labels short and concise. + \li If the text is localized, consider the influence of a longer text on the layout. + \endlist + + \b {See also} \l Switch + + \section1 ToolButton Control + + \image qtquickcontrols2-toolbutton.png + + \l ToolButton is nearly identical to \l Button, but it has a graphical + appearance that makes it more suitable for insertion into a \l ToolBar. + + \b {See also} \l ToolButton + + \section1 Related Information + \list + \li \l {Qt Quick Controls Guidelines} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-configuration.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-configuration.qdoc new file mode 100644 index 00000000..8ac2b275 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-configuration.qdoc @@ -0,0 +1,204 @@ +/**************************************************************************** +** +** 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-configuration.html + \keyword Qt Quick Controls Configuration File + \title Qt Quick Controls Configuration File + \keyword Qt Quick Controls 2 Configuration File + + Qt Quick Controls support a special configuration file, \c qtquickcontrols2.conf, + which is built into an application's resources. + + The configuration file can specify the preferred style and certain style-specific + attributes. The following example specifies that the preferred style is the \l {Material style}. + Furthermore, when the application is run with the Material style, its theme is light and the + accent and primary colors are teal and blue grey, respectively. However, if the application + is run with the \l {Universal style} instead, the accent color is red and the appropriate theme + is chosen based on the system theme colors. + + \code + [Controls] + Style=Material + + [Universal] + Theme=System + Accent=Red + + [Material] + Theme=Light + Accent=Teal + Primary=BlueGrey + \endcode + + It is possible to specify a custom location for the configuration file with + the \l {Supported Environment Variables in Qt Quick Controls} + {QT_QUICK_CONTROLS_CONF} environment variable. + + \section1 Controls Section + + The following values can be specified in a \c Controls section of the + configuration file: + + \table + \header + \li Variable + \li Description + \row + \li \c Style + \li Specifies the style to run the application with. + The value can be the name of one of the \l {Available Styles}{built-in styles} + or a \l {Creating a Custom Style}{custom style}. + \row + \li \c FallbackStyle + \li Specifies the style to use for controls that are not implemented. + The style must be one of the \l {Available Styles}{built-in styles}. + By default, the \l {Basic Style}{Basic} style is used. + \endtable + + \section1 Imagine Section + + The following table lists values that can be used to configure the + \l {Imagine style} in an \c Imagine section of the configuration file: + + \include qquickimaginestyle.qdocinc conf + + \section1 Material Section + + The following table lists values that can be used to configure the + \l {Material style} in a \c Material section of the configuration file: + + \include qquickmaterialstyle.qdocinc conf + + \section1 Universal Section + + The following table lists values that can be used to configure the + \l {Universal style} in a \c Universal section of the configuration file: + + \include qquickuniversalstyle.qdocinc conf + + \section1 Font Configuration + + The default \l {Control::font}{font} can be specified in a \c Font sub-group + in each style's section in the configuration file. The \c Font sub-group can + be defined in two alternative ways: + + \code + [Basic] + Font\Family=Open Sans + Font\PixelSize=20 + + [Material\Font] + Family=Open Sans + PixelSize=20 + \endcode + + Supported font attributes: + \table + \header + \li Variable + \li Description + \row + \li \c Family + \li The \l {QFont::family}{font family}. + \row + \li \c PointSize + \li The \l {QFont::pointSizeF}{point size}. + \row + \li \c PixelSize + \li The \l {QFont::pixelSize}{pixel size}. + \row + \li \c StyleHint + \li The \l {QFont::styleHint}{style hint}. + Available values: \c SansSerif, \c Helvetica, \c Serif, \c Times, \c TypeWriter, \c Courier, + \c OldEnglish, \c Decorative, \c Monospace, \c Fantasy, \c Cursive. + \row + \li \c Weight + \li The \l {QFont::}{weight}. Qt uses a weighting scale from \c 1 to \c 1000 compatible with OpenType. A weight of \c 1 will be thin, + whilst \c 1000 will be extremely black. + Available pre-defined weights: \c Thin (100), \c ExtraLight (200), \c Light (300), \c Normal (400), + \c Medium (500), \c DemiBold (600), \c Bold (700), \c ExtraBold (800), + \c Black (900). + \row + \li \c Style + \li The \l {QFont::}{style}. + Available values: \c StyleNormal, \c StyleItalic, \c StyleOblique. + \endtable + + \section1 Palette Configuration + + The default \c palette can be configured for each style using the + \c Palette sub-group in the configuration file. The \c Palette sub-group can be + defined in two alternative ways: + + \code + [Fusion] + Palette\Window=#dedede + Palette\WindowText=#212121 + \endcode + + or: + \code + [Fusion\Palette] + Window=#dedede + WindowText=#212121 + \endcode + + See \l [QtQuick]{Palette} QML type for more information. + + \section1 Using the Configuration File in a Project + + In order to make it possible for Qt Quick Controls to find the configuration file, + it must be built into application's resources using the \l {The Qt Resource System}. + Here's an example \c .qrc file: + + \code + <!DOCTYPE RCC><RCC version="1.0"> + <qresource prefix="/"> + <file>qtquickcontrols2.conf</file> + </qresource> + </RCC> + \endcode + + \note Qt Quick Controls uses a file selector to load the configuration file. It + is possible to provide a different configuration file for different platforms and + locales. See \l QFileSelector documentation for more details. + + Finally, the \c .qrc file must be listed in the application's \c .pro file so that + the build system knows about it. For example: + + \code + RESOURCES = application.qrc + \endcode + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls} + \li \l{Supported Environment Variables in Qt Quick Controls} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-containers.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-containers.qdoc new file mode 100644 index 00000000..81e24c26 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-containers.qdoc @@ -0,0 +1,113 @@ +/**************************************************************************** +** +** 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-containers.html + \title Container Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for container controls + + Qt Quick Controls offers a selection of container-like controls. + + \annotatedlist qtquickcontrols2-containers + + Each type of container can be used to group a set of controls together. + The following sections offer guidelines for choosing the appropriate type + of container, depending on the use case. + + \section1 ApplicationWindow Control + + \image qtquickcontrols2-applicationwindow-wireframe.png + + \l ApplicationWindow creates the root window of an application, and makes + it easy to add an optional header and footer to that window. + + \section1 Frame Control + + \image qtquickcontrols2-frame.png + + \l Frame is used to layout a logical group of controls together, within + a visual frame. + + \section1 GroupBox Control + + \image qtquickcontrols2-groupbox.png + + \l GroupBox is used to layout a logical group of controls together, + within a titled visual frame. + + \section1 Page Control + + \image qtquickcontrols2-page-wireframe.png + + \l Page provides page-specific header and footer items. + It is perfectly possible to use ApplicationWindow for setting the header + and the footer, but if you have a header and footer which varies per + screen, then it is better to use \l Page. + + \section1 Pane Control + + \image qtquickcontrols2-pane.png + + \l Pane provides a background color that matches with the application + style and theme. Pane does not provide a layout of its own, but requires + you to position its contents, for instance by using a \l RowLayout or + a \l ColumnLayout. + + \section1 ScrollView Control + + \image qtquickcontrols2-scrollview-wireframe.png + + \l ScrollView provides scrolling for user-defined content. + + \section1 StackView Control + + \image qtquickcontrols2-stackview-wireframe.png + + \l StackView organizes content pages into a stack using a last-in-first-out + principle: the last item to be "pushed" onto the stack is the first one to + be removed, and the top-most item is always the one that is visible. + + \section1 SwipeView Control + + \image qtquickcontrols2-swipeview-wireframe.png + + \l SwipeView organizes content pages into a swipable strip. + + \section1 TabBar Control + + \image qtquickcontrols2-tabbar-wireframe.png + + \l TabBar organizes content pages into tabs. + + \section1 ToolBar Control + + \image qtquickcontrols2-toolbar.png + + \l ToolBar is a container of application-wide and context-sensitive + actions and controls. +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-cppclasses.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-cppclasses.qdoc new file mode 100644 index 00000000..293ac6de --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-cppclasses.qdoc @@ -0,0 +1,58 @@ +/**************************************************************************** +** +** Copyright (C) 2020 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$ +** +****************************************************************************/ + +/*! + \module QtQuickControls2 + \keyword Qt Quick Controls C++ Classes + \title Qt Quick Controls C++ Classes + \keyword Qt Quick Controls 2 C++ Classes + \ingroup modules + \qtcmakepackage QuickControls2 + \qtvariable quickcontrols2 + + \brief Provides classes for setting up the controls from C++. + + The C++ types can be included into your application using the following + include statement: + + \code + #include <QtQuickControls2> + \endcode + + \note If you are using a few classes from this module, we recommend including + those specific classes only instead of the module. + + To link against the corresponding C++ libraries, add the following to your + qmake project file: + + \code + QT += quickcontrols2 + \endcode + + The \l{Qt Quick Controls} page contains information about how to use the + module. +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-customize.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-customize.qdoc new file mode 100644 index 00000000..ba62425f --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-customize.qdoc @@ -0,0 +1,986 @@ +/**************************************************************************** +** +** 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-customize.html + \keyword Customizing Qt Quick Controls 2 + \title Customizing Qt Quick Controls + \brief A set of UI controls to create user interfaces in Qt Quick + + Qt Quick Controls consist of a hierarchy (tree) of items. In order to + provide a custom look and feel, the default QML implementation of each + item can be replaced with a custom one. + + \section1 Customizing a Control + + Sometimes you'll want to create a "one-off" look for a specific part of + your UI, and use a complete style everywhere else. Perhaps you're happy + with the style you're using, but there's a certain button that has some + special significance. + + The first way to create this button is to simply define it in-place, + wherever it is needed. For example, perhaps you're not satisfied with the + Basic style's Button having square corners. To make them rounded, you + can override the \l {Control::}{background} item and set the radius + property of Rectangle: + + \include customize-button-background.qdocinc file + + The second way to create the button is good if you plan to use your rounded + button in several places. It involves moving the code into its own QML file + within your project. + + For this approach, we'll copy the background code from the Basic style's + \c Button.qml. This file can be found in the following path in your Qt + installation: + + \c {$QTDIR/qml/QtQuick/Controls/Basic/Button.qml} + + After doing that, we'll simply add the following line: + + \code + radius: 4 + \endcode + + To avoid confusion with the controls in the + module itself, we'll call the file \c MyButton.qml. To use the control in + your application, refer to it by its filename: + + \qml + import QtQuick.Controls + + ApplicationWindow { + MyButton { + text: qsTr("A Special Button") + } + } + \endqml + + The third way to create the button is a bit more structured, both in terms + of where the file sits in the file system and how it is used in QML. First, + copy an existing file as you did above, but this time, put it into a + subfolder in your project named (for example) \c controls. To use the + control, first import the folder into a namespace: + + \qml + import QtQuick.Controls + import "controls" as MyControls + + ApplicationWindow { + MyControls.Button { + text: qsTr("A Special Button") + } + } + \endqml + + As you now have the \c MyControls namespace, you can name the controls after + their actual counterparts in the Qt Quick Controls module. You can repeat + this process for any control that you wish to add. + + An added benefit of these three methods is that it's not necessary to + implement the template from scratch. + + \section1 Creating a Custom Style + + There are several ways to go about creating your own styles. Below, we'll + explain the various approaches. + + \section2 Definition of a Style + + In Qt Quick Controls, a style is essentially a set of QML files within a + single directory. There are four requirements for a style to be + \l {Using Styles in Qt Quick Controls}{usable}: + + \list + \li At least one QML file whose name matches a control (for example, + \c Button.qml) must exist. + \li Each QML file must contain the relevant type from the \l {Qt Quick Templates 2} + {QtQuick.Templates} import as the root item. For example, + Button.qml must contain a Button template as its root item. + + If we instead used the corresponding type from the \l {Qt Quick Controls} + {QtQuick.Controls} import as we did in the previous section, it would not work: + the control we were defining would try to derive from itself. + \li A \l {Module Definition qmldir Files}{qmldir} file must exist alongside + the QML file(s). Below is an example of a simple \c qmldir file for a style that + provides a button: + + \badcode + module MyStyle + Button 2.15 Button.qml + \endcode + + If you're using \l {Compile-Time Style Selection}{compile-time style + selection}, the qmldir should also import the fallback style: + + \badcode + # ... + import QtQuick.Controls.Basic auto + \endcode + + This can also be done for \l {Run-Time Style Selection}{run-time style selection} + instead of using, for example, \l QQuickStyle::setFallbackStyle(). + + The directory structure for such a style looks like this: + + \badcode + MyStyle + ├─── Button.qml + └─── qmldir + \endcode + \li The files must be in a directory that is findable via the \l {QML Import Path}. + + For example, if the path to \e MyStyle directory mentioned above was + \c /home/user/MyApp/MyStyle, then \c /home/user/MyApp must be added to + the QML import path. + + To \l {Using Styles in Qt Quick Controls}{use} \e MyStyle in \e MyApp, + refer to it by name: + + \list + \li \c {./MyApp -style MyStyle} + \endlist + + The style name must match the casing of the style directory; passing + \e mystyle or \e MYSTYLE is not supported. + \endlist + + By default, the styling system uses the Basic style as a fallback for + controls that aren't implemented. To customize or extend any other built-in + style, it is possible to specify a different fallback style using + \l[QtQuickControls2]{QQuickStyle}. + + What this means is that you can implement as many controls as you like for + your custom style, and place them almost anywhere. It also allows users to + create their own styles for your application. + + \section3 Previewing Custom Styles in Qt Quick Designer + + Using the approach above, it is possible to preview a custom style + in Qt Quick Designer. In order to do so, + ensure that the project has a + \l {Qt Quick Controls Configuration File}{qtquickcontrols2.conf} file, + and that the following entry exists: + + \badcode + [Controls] + Style=MyStyle + \endcode + + For more information, take a look at the + \l {Qt Quick Controls - Flat Style}{Flat Style example}. + + \section2 Style-specific C++ Extensions + + Sometimes you may need to use C++ to extend your custom style. There are two + ways to expose such types to QML: + + \list + \li If the style that uses the type is the only style used by an application, + it's enough to register it with the QML engine via qmlRegisterType(): + + \code + qmlRegisterType<ACoolCppItem>("MyApp", 1, 0, "ACoolItem"); + \endcode + + See \l {Using C++ Data From QML} for more information about this. + \li If the style that uses the type is one of many styles used by an + application, it may be better to only register it when necessary. This + is the point at which it would make sense to implement your own + \l {Creating C++ Plugins for QML}{QML plugin}. + + Using a plugin as part of your style is not that much different from + using a set of QML files. The only difference is that the plugin and + its \c qmldir file must be present in the same directory as the QML + files. + \endlist + + \section3 Considerations for custom styles + + When implementing your own style and customizing controls, there are some + points to keep in mind to ensure that your application is as performant as + possible. + + \section4 Avoid assigning an id to styles' implementations of item delegates + + As explained in \l {Definition of a Style}, when you implement your + own style for a control, you start off with the relevant template for + that control. For example, a style's \c Button.qml will be structured + similarly to this: + + \qml + T.Button { + // ... + + background: Rectangle { + // ... + } + + contentItem: Text { + // ... + } + + // ... + } + \endqml + + When you use a Button in your application, the \c background and + \c contentItem items will be created and parented to the root \c Button + item: + + \qml + // Creates the Button root item, the Rectangle background, + // and the Text contentItem. + Button { + text: qsTr("Confirm") + } + \endqml + + Suppose you then needed to do a one-off customization of the Button (as + explained in \l {Customizing a Control}): + + \include customize-button-background.qdocinc file + + In QML, this would normally result in both the default \c background + implementation and the one-off, custom \c background items being created. + Qt Quick Controls uses a technique that avoids creating both items, and + instead only creates the custom \c background, greatly improving the + creation performance of controls. + + This technique relies on the absence of an \l {The id Attribute}{id} in the + style's implementation of that item. If an id is assigned, the technique + cannot work, and both items will be created. For example, it can be + tempting to assign an id to the \c background or \c contentItem so that + other objects within the file can refer to those items: + + \qml + T.Button { + // ... + + background: Rectangle { + id: backgroundRect + // ... + } + + contentItem: Text { + // Use backgroundRect in some way... + } + + // ... + } + \endqml + + With this code, every time a Button instance with a customized background + is created, both backgrounds will be created, resulting in sub-optimal + creation performance. + + Prior to Qt 5.15, the old, unused background would be deleted to release + the resources associated with it. However, as the control does not own the + items, it should not delete them. As of Qt 5.15, old items are no longer + deleted, and so the \c backgroundRect item will live longer than it needs + to—typically until the application exits. Although the old item will be + hidden, visually unparented from the control, and removed from the + accessibility tree, it is important to keep the creation time and memory + usage of these unused items in mind when assigning an id in this context. + + \section4 Avoid imperative assignments of custom items + + The technique mentioned in the section above only works when an item is + \l {Prefer Declarative Bindings Over Imperative Assignments}{declaratively} + assigned for the first time, and so imperative assignments will result in + orphaned items. Always use declarative bindings to assign custom items + when possible. + + \section3 Attached properties + + It is common for a style to have certain properties or attributes that + apply to all controls. \l {Attached Properties and Attached Signal + Handlers}{Attached properties} are a great way of extending an item in QML + without having to modify any existing C++ belonging to that item. For + example, both the \l {Material Style}{Material} and \l {Universal + Style}{Universal} styles have an attached theme property that controls + whether an item and its children will be rendered in a light or dark theme. + + As an example, let's add an attached property that controls elevation. Our + style will illustrate the elevation with a drop shadow; the higher the + elevation, the larger the shadow. + + The first step is to \l {Qt Creator: Project Types}{create a new Qt Quick + Controls application} in Qt Creator. After that, we + \l {Qt Creator: Creating C++ Classes}{add a C++ type} that stores the elevation. Since + the type will be used for every control supported by our style, and because + we may wish to add other attached properties later on, we'll call it + MyStyle. Here is \c MyStyle.h: + + \code + #ifndef MYSTYLE_H + #define MYSTYLE_H + + #include <QObject> + #include <QtQml> + + class MyStyle : public QObject + { + Q_OBJECT + Q_PROPERTY(int elevation READ elevation WRITE setElevation NOTIFY elevationChanged) + + public: + explicit MyStyle(QObject *parent = nullptr); + + static MyStyle *qmlAttachedProperties(QObject *object); + + int elevation() const; + void setElevation(int elevation); + + signals: + void elevationChanged(); + + private: + int m_elevation; + }; + + QML_DECLARE_TYPEINFO(MyStyle, QML_HAS_ATTACHED_PROPERTIES) + + #endif // MYSTYLE_H + \endcode + + \c MyStyle.cpp: + + \code + #include "mystyle.h" + + MyStyle::MyStyle(QObject *parent) : + QObject(parent), + m_elevation(0) + { + } + + MyStyle *MyStyle::qmlAttachedProperties(QObject *object) + { + return new MyStyle(object); + } + + int MyStyle::elevation() const + { + return m_elevation; + } + + void MyStyle::setElevation(int elevation) + { + if (elevation == m_elevation) + return; + + m_elevation = elevation; + emit elevationChanged(); + } + \endcode + + The \c MyStyle type is special in the sense that it shouldn't be + instantiated, but rather used for its attached properties. For that reason, + we register it in the following manner in \c main.cpp: + + \code + #include <QGuiApplication> + #include <QQmlApplicationEngine> + + #include "mystyle.h" + + int main(int argc, char *argv[]) + { + QGuiApplication app(argc, argv); + + qmlRegisterUncreatableType<MyStyle>("MyStyle", 1, 0, "MyStyle", "MyStyle is an attached property"); + + QQmlApplicationEngine engine; + // Make the directory containing our style known to the QML engine. + engine.addImportPath(":/"); + engine.load(QUrl(QLatin1String("qrc:/main.qml"))); + + return app.exec(); + } + \endcode + + We then copy \c Button.qml from the Basic style in + \c {$QTDIR/qml/QtQuick/Controls/Basic/} into a new \c myproject folder in our + project directory. Add the newly copied \c Button.qml to \c qml.qrc, which is + the resource file that contains our QML files. + + Next, we add a drop shadow to the \l {Control::}{background} delegate of + the Button: + + \code + // ... + import QtGraphicalEffects + import MyStyle + // ... + + background: Rectangle { + // ... + + layer.enabled: control.enabled && control.MyStyle.elevation > 0 + layer.effect: DropShadow { + verticalOffset: 1 + color: control.visualFocus ? "#330066ff" : "#aaaaaa" + samples: control.MyStyle.elevation + spread: 0.5 + } + } + \endcode + + Note that we: + + \list + \li Don't bother using the drop shadow when the elevation is \c 0 + \li Change the shadow's color depending on whether or not the button has + focus + \li Make the size of the shadow depend on the elevation + \endlist + + To try out the attached property, we create a \l Row with two Buttons in + \c main.qml: + + \qml + import QtQuick + import QtQuick.Controls + + import MyStyle 1.0 + + ApplicationWindow { + id: window + width: 400 + height: 400 + visible: true + + Row { + spacing: 20 + anchors.centerIn: parent + + Button { + text: "Button 1" + } + Button { + text: "Button 2" + MyStyle.elevation: 10 + } + } + } + \endqml + + One button has no elevation, and the other has an elevation of \c 10. + + With that in place, we can run our example. To tell the application to + use our new style, we pass \c {-style MyStyle} as an application + argument, but there are \l {Using Styles in Qt Quick Controls}{many + ways} to specify the style to use. + + The end result: + + \image qtquickcontrols2-customize-buttons.png + + Note that the \c {import MyStyle 1.0} statement is only necessary + because we are using the attached property belonging to \c MyStyle. + Both buttons will use our custom style, even if we were to remove the + import. + + \section1 Customization Reference + + The following snippets present examples where the Basic style's controls + have been customized using the same approach as the + \l {Customizing a Control} section. The code can be used as a starting + point to implement a custom look and feel. + + \section2 Customizing ApplicationWindow + + ApplicationWindow consists of one visual item: + \l {ApplicationWindow::background}{background}. + + \code + import + import QtQuick.Controls + + ApplicationWindow { + visible: true + + background: Rectangle { + gradient: Gradient { + GradientStop { position: 0; color: "#ffffff" } + GradientStop { position: 1; color: "#c1bbf9" } + } + } + } + \endcode + + + \section2 Customizing BusyIndicator + + BusyIndicator consists of two visual items: \l {Control::background}{background} + and \l {Control::contentItem}{contentItem}. + + \image qtquickcontrols2-busyindicator-custom.png + + \snippet qtquickcontrols2-busyindicator-custom.qml file + + + \section2 Customizing Button + + Button consists of two visual items: \l {Control::background}{background} + and \l {Control::contentItem}{content item}. + + \image qtquickcontrols2-button-custom.png + + \snippet qtquickcontrols2-button-custom.qml file + + + \section2 Customizing CheckBox + + CheckBox consists of three visual items: \l {Control::background}{background}, + \l {Control::contentItem}{contentItem} and \l {AbstractButton::indicator}{indicator}. + + \image qtquickcontrols2-checkbox-custom.png + + \snippet qtquickcontrols2-checkbox-custom.qml file + + \section2 Customizing CheckDelegate + + CheckDelegate consists of three visual items: \l {Control::background}{background}, + \l {Control::contentItem}{contentItem} and \l {AbstractButton::indicator}{indicator}. + + \image qtquickcontrols2-checkdelegate-custom.png + + \snippet qtquickcontrols2-checkdelegate-custom.qml file + + + \section2 Customizing ComboBox + + ComboBox consists of \l {Control::background}{background}, + \l {Control::contentItem}{content item}, \l {ComboBox::popup}{popup}, + \l {ComboBox::indicator}{indicator}, and \l {ComboBox::delegate}{delegate}. + + \image qtquickcontrols2-combobox-custom.png + + \snippet qtquickcontrols2-combobox-custom.qml file + + + \section2 Customizing DelayButton + + DelayButton consists of two visual items: \l {Control::background}{background} + and \l {Control::contentItem}{content item}. + + \image qtquickcontrols2-delaybutton-custom.png + + \snippet qtquickcontrols2-delaybutton-custom.qml file + + + \section2 Customizing Dial + + Dial consists of two visual items: \l {Control::background}{background} + and \l {Dial::handle}{handle}. + + \image qtquickcontrols2-dial-custom.png + + \snippet qtquickcontrols2-dial-custom.qml file + + + \section2 Customizing Drawer + + Drawer can have a visual \l {Control::background}{background} + item. + + \code + background: Rectangle { + Rectangle { + x: parent.width - 1 + width: 1 + height: parent.height + color: "#21be2b" + } + } + \endcode + + + \section2 Customizing Frame + + Frame consists of one visual item: \l {Control::background}{background}. + + \image qtquickcontrols2-frame-custom.png + + \snippet qtquickcontrols2-frame-custom.qml file + + + \section2 Customizing GroupBox + + GroupBox consists of two visual items: \l {Control::background}{background} + and \l {GroupBox::label}{label}. + + \image qtquickcontrols2-groupbox-custom.png + + \snippet qtquickcontrols2-groupbox-custom.qml file + + + \section2 Customizing ItemDelegate + + ItemDelegate consists of two visual items: \l {Control::background}{background} + and \l {Control::contentItem}{content item}. + + \image qtquickcontrols2-itemdelegate-custom.png + + \snippet qtquickcontrols2-itemdelegate-custom.qml file + + + \section2 Customizing Label + + Label can have a visual \l {Label::background}{background} item. + + \image qtquickcontrols2-label-custom.png + + \snippet qtquickcontrols2-label-custom.qml file + + + \section2 Customizing Menu + + \list + \li \l Menu consists of a visual \l {Popup::background}{background} item. + \li \l MenuItem consists of four visual items: \l {Control::background}{background}, + \l {Control::contentItem}{content item}, \l {AbstractButton::}{indicator}, and + \l {MenuItem::}{arrow}. + \li \l MenuSeparator consists of a visual \l {Control::background}{background} and + \l {Control::contentItem}{content item}. + \endlist + + \image qtquickcontrols2-menu-custom.png + + \quotefromfile qtquickcontrols2-menu-custom.qml + \skipto import QtQuick + \printuntil import QtQuick.Controls + \skipto Menu + \printto eof + + + \section2 Customizing MenuBar + + MenuBar can have a visual \l {Control::background}{background} item, + and MenuBarItem consists of two visual items: \l {Control::background} + {background} and \l {Control::contentItem}{content item}. + + \image qtquickcontrols2-menubar-custom.png + + \quotefromfile qtquickcontrols2-menubar-custom.qml + \skipto import QtQuick + \printuntil import QtQuick.Controls + \skipto MenuBar + \printto eof + + + \section2 Customizing PageIndicator + + PageIndicator consists of a \l {Control::background}{background}, \l {Control::contentItem}{content item}, and \l {PageIndicator::delegate}{delegate}. + + \image qtquickcontrols2-pageindicator-custom.png + + \snippet qtquickcontrols2-pageindicator-custom.qml file + + + \section2 Customizing Pane + + Pane consists of a \l {Control::background}{background}. + + \image qtquickcontrols2-pane-custom.png + + \snippet qtquickcontrols2-pane-custom.qml file + + + \section2 Customizing Popup + + Popup consists of a \l {Popup::background}{background} and + \l {Popup::contentItem}{content item}. + + \image qtquickcontrols2-popup-custom.png + + \quotefromfile qtquickcontrols2-popup-custom.qml + \skipto import QtQuick + \printuntil import QtQuick.Controls + \codeline + \skipto Popup + \printuntil { + \printuntil } + \printuntil } + \printuntil } + + + \section2 Customizing ProgressBar + + ProgressBar consists of two visual items: \l {Control::background}{background} + and \l {Control::contentItem}{content item}. + + \image qtquickcontrols2-progressbar-custom.png + + \snippet qtquickcontrols2-progressbar-custom.qml file + + + \section2 Customizing RadioButton + + RadioButton consists of three visual items: \l {Control::background}{background}, + \l {Control::contentItem}{content item} and \l {AbstractButton::indicator}{indicator}. + + \image qtquickcontrols2-radiobutton-custom.png + + \snippet qtquickcontrols2-radiobutton-custom.qml file + + + \section2 Customizing RadioDelegate + + RadioDelegate consists of three visual items: \l {Control::background}{background}, + \l {Control::contentItem}{contentItem} and \l {AbstractButton::indicator}{indicator}. + + \image qtquickcontrols2-radiodelegate-custom.png + + \snippet qtquickcontrols2-radiodelegate-custom.qml file + + + \section2 Customizing RangeSlider + + RangeSlider consists of three visual items: + \l {Control::background}{background}, + \l {RangeSlider::first}{first.handle} and + \l {RangeSlider::second.handle}{second.handle}. + + \image qtquickcontrols2-rangeslider-custom.png + + \snippet qtquickcontrols2-rangeslider-custom.qml file + + + \section2 Customizing RoundButton + + RoundButton can be customized in the same manner as + \l {Customizing Button}{Button}. + + + \section2 Customizing ScrollBar + + ScrollBar consists of two visual items: \l {Control::background}{background} + and \l {Control::contentItem}{content item}. + + \image qtquickcontrols2-scrollbar-custom.png + + \snippet qtquickcontrols2-scrollbar-custom.qml file + + + \section2 Customizing ScrollIndicator + + ScrollIndicator consists of two visual items: \l {Control::background}{background} + and \l {Control::contentItem}{content item}. + + \image qtquickcontrols2-scrollindicator-custom.png + + \snippet qtquickcontrols2-scrollindicator-custom.qml file + + + \section2 Customizing ScrollView + + ScrollView consists of a \l {Control::background}{background} item, + and horizontal and vertical scroll bars. + + \image qtquickcontrols2-scrollview-custom.png + + \snippet qtquickcontrols2-scrollview-custom.qml file + + + \section2 Customizing Slider + + Slider consists of two visual items: \l {Control::background}{background}, + and \l {Slider::handle}{handle}. + + \image qtquickcontrols2-slider-custom.png + + \snippet qtquickcontrols2-slider-custom.qml file + + + \section2 Customizing SpinBox + + SpinBox consists of four visual items: \l {Control::background}{background}, + \l {Control::contentItem}{contentItem}, \l {SpinBox::up.indicator}{up indicator}, + and \l {SpinBox::down.indicator}{down indicator}. + + \image qtquickcontrols2-spinbox-custom.png + + \snippet qtquickcontrols2-spinbox-custom.qml file + + + \section2 Customizing SplitView + + SplitView consists of a visual \l {SplitView::handle}{handle} delegate. + + \image qtquickcontrols2-splitview-custom.png + + \snippet qtquickcontrols2-splitview-custom.qml 1 + + + \section2 Customizing StackView + + StackView can have a visual \l {Control::background}{background} + item, and it allows customizing the transitions that are used for + push, pop, and replace operations. + + \snippet qtquickcontrols2-stackview-custom.qml file + + + \section2 Customizing SwipeDelegate + + SwipeDelegate consists of six visual items: \l {Control::background}{background}, + \l {Control::contentItem}{content item}, \l {AbstractButton::indicator}{indicator}, + \c swipe.left, \c swipe.right, and \c swipe.behind. + + \image qtquickcontrols2-swipedelegate-custom.png + + \snippet qtquickcontrols2-swipedelegate-custom.qml file + + + \section2 Customizing SwipeView + + SwipeView can have a visual \l {Control::background}{background} + item. The navigation is implemented by the \l {Control::contentItem} + {content item}. + + \snippet qtquickcontrols2-swipeview-custom.qml file + + + \section2 Customizing Switch + + Switch consists of three visual items: \l {Control::background}{background}, + \l {Control::contentItem}{content item} and \l {AbstractButton::indicator}{indicator}. + + \image qtquickcontrols2-switch-custom.png + + \snippet qtquickcontrols2-switch-custom.qml file + + \section2 Customizing SwitchDelegate + + SwitchDelegate consists of three visual items: \l {Control::background}{background}, + \l {Control::contentItem}{contentItem} and \l {AbstractButton::indicator}{indicator}. + + \image qtquickcontrols2-switchdelegate-custom.png + + \snippet qtquickcontrols2-switchdelegate-custom.qml file + + + \section2 Customizing TabBar + + TabBar consists of two visual items: \l {Control::background}{background}, + and \l {Control::contentItem}{contentItem}. + + \image qtquickcontrols2-tabbar-custom.png + + \snippet qtquickcontrols2-tabbar-custom.qml file + + + \section2 Customizing TabButton + + TabButton can be customized in the same manner as + \l {Customizing Button}{Button}. + + + \section2 Customizing TextArea + + TextArea consists of a \l {TextArea::background}{background} item. + + \image qtquickcontrols2-textarea-custom.png + + \snippet qtquickcontrols2-textarea-custom.qml file + + + \section2 Customizing TextField + + TextField consists of a \l {TextField::background}{background} item. + + \image qtquickcontrols2-textfield-custom.png + + \snippet qtquickcontrols2-textfield-custom.qml file + + + \section2 Customizing ToolBar + + ToolBar consists of one visual item: \l {Control::background}{background}. + + \image qtquickcontrols2-toolbar-custom.png + + \snippet qtquickcontrols2-toolbar-custom.qml file + + + \section2 Customizing ToolButton + + ToolButton consists of two visual items: \l {Control::background}{background} + and \l {Control::contentItem}{content item}. + + \image qtquickcontrols2-toolbutton-custom.png + + \snippet qtquickcontrols2-toolbutton-custom.qml file + + + \section2 Customizing ToolSeparator + + ToolSeparator consists of two visual items: \l {Control::background}{background} + and \l {Control::contentItem}{content item}. + + \image qtquickcontrols2-toolseparator-custom.png + + \snippet qtquickcontrols2-toolseparator-custom.qml file + + + \section2 Customizing ToolTip + + ToolTip consists of two visual items: \l {Popup::background}{background} + and \l {Popup::contentItem}{content item}. + + \quotefromfile qtquickcontrols2-tooltip-custom.qml + \skipto import QtQuick + \printuntil import QtQuick.Controls + \skipto ToolTip + \printuntil } + \printuntil } + \printuntil } + + + \section2 Customizing Tumbler + + Tumbler consists of three visual items: + \l {Control::background}{background}, + \l {Control::contentItem}{contentItem}, and + \l {Tumbler::delegate}{delegate}. + + \image qtquickcontrols2-tumbler-custom.png + + \snippet qtquickcontrols2-tumbler-custom.qml file + + If you want to define your own contentItem, use either a \l ListView or + \l PathView as the root item. For a wrapping Tumbler, use PathView: + + \snippet qtquickcontrols2-tumbler-pathView.qml contentItem + + For a non-wrapping Tumbler, use ListView: + + \snippet qtquickcontrols2-tumbler-listView.qml contentItem +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-delegates.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-delegates.qdoc new file mode 100644 index 00000000..bea87abf --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-delegates.qdoc @@ -0,0 +1,79 @@ +/**************************************************************************** +** +** 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-delegates.html + \title Delegate Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for delegate controls + + Qt Quick Controls offers a selection of controls that are used as + delegates in views. + + \annotatedlist qtquickcontrols2-delegates + + Each type of delegate has its own specific target use case. The following + sections offer guidelines for choosing the appropriate type of delegate, + depending on the use case. + + \section1 ItemDelegate Control + + \image qtquickcontrols2-itemdelegate.gif + + \l ItemDelegate presents a checkable control that can be pressed and + clicked by the user. + + \section1 RadioDelegate Control + + \image qtquickcontrols2-radiodelegate.gif + + \l RadioDelegate presents a checkable control that can be toggled on + (checked) or off (unchecked). Radio delegates are typically used to select + one option from a set of options. + + \b {See also} \l {RadioButton Control}. + + \section1 SwipeDelegate Control + + \image qtquickcontrols2-swipedelegate.gif + + \l SwipeDelegate presents a view item that can be swiped left or right to + expose more options or information. + + \section1 SwitchDelegate Control + + \image qtquickcontrols2-switchdelegate.gif + + \l SwitchDelegate presents a switchable delegate that can be toggled on or off. + + \b {See also} \l {Switch Control}. + + \section1 Related Information + \list + \li \l {Qt Quick Controls Guidelines} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-deployment.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-deployment.qdoc new file mode 100644 index 00000000..a84d0d87 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-deployment.qdoc @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** 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-deployment.html + \title Deploying Qt Quick Controls Applications + + Deployment of Qt Quick Controls applications is very similar to + deployment of other types of Qt applications. However, there are a few + factors to consider. + + \section1 Deploying an Application with Several Styles + + Suppose you have an application that will be deployed to both Android and + Windows devices. To ensure that only the minimum set of files that are + necessary for the application to run are deployed to each device, you can + use file selectors. For example, your directory structure could look like + this: + + \code + resources.qrc + main.qml + +windows/MyPage.qml + +windows/qtquickcontrols2.conf + +android/MyPage.qml + +android/qtquickcontrols2.conf + \endcode + + In the project above, \c main.qml would import \c QtQuick.Controls, for + example, but shouldn't import, say, \c QtQuick.Controls.Material. Any code + that is style-specific is moved out into separate files; just as we've done + for \c MyPage.qml. + + The \c +windows/qtquickcontrols2.conf file would contain configuration + options specific to the Universal style: + + \code + [Controls] + Style=Universal + + [Universal] + Theme=Dark + Accent=Red + \endcode + + The \c +android/qtquickcontrols2.conf file would contain configuration + options specific to the Material style: + + \code + [Controls] + Style=Material + + [Material] + Theme=Light + Accent=Brown + \endcode + + \section1 Static Builds + + For dynamically built applications, it is not necessary to import a + specific style that should be usable by that application. For statically + built applications, Qt's build system must be involved to ensure that + QML plugins function as expected. Specifically, \c qmake uses + \c qmlimportscanner to scan the QML files in your application for import + statements. For this reason, any styles that should be usable by a + statically built application must explicitly import that style. Where the + import occurs is up to the developer, but it is recommended to follow the + approach mentioned in the \l {Deploying an Application with Several Styles} + section, so that only the minimum set of files that are necessary for a + particular device are deployed. + + \sa {Deploying Qt Applications}, {Using Styles in Qt Quick Controls} +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-environment.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-environment.qdoc new file mode 100644 index 00000000..4484acf3 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-environment.qdoc @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** 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-environment.html + \title Supported Environment Variables in Qt Quick Controls + + This page contains a list of all environment variables that Qt Quick Controls + supports. The environment variables are primarily meant for testing purposes, but + they can also be used to set system-wide defaults. + + \table + \header + \li Variable + \li Description + \row + \li \c QT_QUICK_CONTROLS_STYLE + \li Specifies the default \l {Styling Qt Quick Controls}{Qt Quick Controls style}. + The value can be either one of the built-in styles, for example \c "Material", + or a custom style such as \c "MyStyle". + \row + \li \c QT_QUICK_CONTROLS_FALLBACK_STYLE + \li Specifies a fallback style for \l {Creating a Custom Style}{custom styles}. + The value can be one of the built-in styles, for example \c "Material", + \row + \li \c QT_QUICK_CONTROLS_CONF + \li Specifies the location of the \l {Qt Quick Controls configuration file}. + By default, the configuration file is loaded from the application's + resources in \c ":/qtquickcontrols2.conf". + \row + \li \c QT_QUICK_CONTROLS_HOVER_ENABLED + \li Specifies whether Qt Quick Controls use \l {Control::hoverEnabled}{hover effects}. + The value can be set to \c 0 or \c 1 to disable or enable hover effects, respectively. + \endtable + + \l {Imagine style} specific environment variables: + + \include qquickimaginestyle.qdocinc env + + \l {Material style} specific environment variables: + + \include qquickmaterialstyle.qdocinc env + + \l {Universal style} specific environment variables: + + \include qquickuniversalstyle.qdocinc env + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls} + \li \l{Qt Quick Controls Configuration File} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-examples.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-examples.qdoc new file mode 100644 index 00000000..2924114f --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-examples.qdoc @@ -0,0 +1,37 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \group qtquickcontrols2-examples + \ingroup all-examples + \keyword Qt Quick Controls Examples + \title Qt Quick Controls Examples + \keyword Qt Quick Controls 2 Examples + \brief A collection of examples for \l {Qt Quick Controls} + + These examples demonstrate creating user interfaces using \l {Qt Quick Controls}. +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-fileselectors.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-fileselectors.qdoc new file mode 100644 index 00000000..4c782de1 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-fileselectors.qdoc @@ -0,0 +1,140 @@ +/**************************************************************************** +** +** 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-fileselectors.html + \title Using File Selectors with Qt Quick Controls + + \l {QFileSelector}{File selectors} provide a convenient way of selecting + file variants. Qt offers the platform name and the locale as built-in + selectors. Qt Quick Controls extends the built-in selectors with the name + (lowercase) of the style that an application is running with. + + By using file selectors, style-specific tweaks can be applied without + creating a hard dependency to a style. From the available file variants, + only the selected QML file is loaded by the QML engine. Each file variant + can assume the context, that is, a specific style. This typically leads + to some code duplication, but on the other hand, cuts the aforementioned + hard dependency to the style, and leads to simpler and more efficient + QML code. + + The following example demonstrates a custom rounded button that has a + styled drop shadow in the \l {Material Style}{Material style}, and looks + flat in other styles. The files are organized so that the Material version + of \c CustomButton.qml is placed into a \c +Material sub-directory. + + \code + :/main.qml + :/CustomButton.qml + :/+Material/CustomButton.qml + \endcode + + By default, \c main.qml will use \c CustomButton.qml for the \c CustomButton + type. However, when the application is run with the Material style, the + \c Material selector will be present and the \c +Material/CustomButton.qml + version will be used instead. + + \code + // main.qml + import QtQuick + import QtQuick.Controls + + ApplicationWindow { + id: window + visible: true + + CustomButton { + text: "Button" + anchors.centerIn: parent + } + } + \endcode + + The base implementation of the custom button is a simple rounded + flat button. + + \code + // CustomButton.qml + import QtQuick + import QtQuick.Controls + + Button { + id: control + + background: Rectangle { + radius: width / 2 + implicitWidth: 36 + implicitHeight: 36 + color: control.pressed ? "#ccc" : "#eee" + } + } + \endcode + + The Material style's implementation of the custom button imports the + Material style, requests a dark theme to get light text, and creates + a drop shadow for the background. + + \code + // +Material/CustomButton.qml + import QtQuick + import QtGraphicalEffects + import QtQuick.Controls + import QtQuick.Controls.Material + + Button { + id: control + + Material.theme: Material.Dark + + background: Rectangle { + implicitWidth: 48 + implicitHeight: 48 + color: Material.accentColor + radius: width / 2 + + layer.enabled: control.enabled + layer.effect: DropShadow { + verticalOffset: 1 + color: Material.dropShadowColor + samples: control.pressed ? 20 : 10 + spread: 0.5 + } + } + } + \endcode + + \note It is recommended to use \l QQmlApplicationEngine, which internally + creates a \l QQmlFileSelector instance. This is all that is needed to take + QML file selectors into use. + + \section1 Related Information + \list + \li \l {QFileSelector} + \li \l {QQmlFileSelector} + \li \l {Styling Qt Quick Controls} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-focus.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-focus.qdoc new file mode 100644 index 00000000..77bc9883 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-focus.qdoc @@ -0,0 +1,48 @@ +/**************************************************************************** +** +** Copyright (C) 2018 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-focus.html + \keyword Focus Management in Qt Quick Controls 2 + \title Focus Management in Qt Quick Controls + \brief Overview of focus handling with Qt Quick Controls + + Qt Quick Controls follows the standard + \l {Keyboard Focus in Qt Quick}{Qt Quick focus system}, while also + providing some added convenience. For example, the + \l {Control::}{focusPolicy} property can be used to control the ways in + which a control receives focus. + + \section1 Focus Scope Controls + + Qt Quick Controls offers a selection of controls that act as + \l {Acquiring Focus and Focus Scopes}{focus scopes}: + + \annotatedlist qtquickcontrols2-focusscopes + + \sa {Keyboard Focus in Qt Quick} +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-fusion.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-fusion.qdoc new file mode 100644 index 00000000..ca67985f --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-fusion.qdoc @@ -0,0 +1,93 @@ +/**************************************************************************** +** +** 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-fusion.html + \title Fusion Style + + The Fusion style is a desktop-oriented style. + + The Fusion style is a platform-agnostic style that offers a desktop-oriented + look and feel. It implements the same design language as the + \l {Qt Widget Gallery}{Fusion style for Qt Widgets}. + + \image qtquickcontrols2-fusion.png + + To run an application with the Fusion style, see + \l {Using Styles in Qt Quick Controls}. + + \note The Fusion style is not a native desktop style. The style runs on any + platform, and looks similar everywhere. Minor differences may occur due to + differences in the standard system palettes, available fonts, and font + rendering engines. + + \section2 Customization + + The Fusion style uses the standard system \l[QtQuick]{Palette} + to provide colors that match the desktop environment. + + \image qtquickcontrols2-fusion-palettes.png + + Custom palettes can be specified for any control, + \l{Popup::palette}{popup}, or \l{Window::palette}{application window}. + Explicit palette attributes are automatically propagated from parent to children, + overriding any system defaults for that attribute. In the following example, + the window and all three switches appear with a violet highlight color: + + \table + \row + \li + \qml + import QtQuick 2.12 + import QtQuick.Controls 2.12 + + ApplicationWindow { + visible: true + + palette.highlight: "violet" + + Column { + anchors.centerIn: parent + + Switch { text: qsTr("First"); checked: true } + Switch { text: qsTr("Second"); checked: true } + Switch { text: qsTr("Third") } + } + } + \endqml + \li + \image qtquickcontrols2-fusion-violet.png + \endtable + + \b {See also} \l {Basic Style}, \l {Material Style}, \l {Universal Style} + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-gettingstarted.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-gettingstarted.qdoc new file mode 100644 index 00000000..09209d21 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-gettingstarted.qdoc @@ -0,0 +1,86 @@ +/**************************************************************************** +** +** 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-gettingstarted.html + \keyword Getting Started with Qt Quick Controls 2 + \title Getting Started with Qt Quick Controls + + A basic example of a QML file that makes use of controls is shown here: + + \qml + import QtQuick + import QtQuick.Controls + + ApplicationWindow { + title: "My Application" + width: 640 + height: 480 + visible: true + + Button { + text: "Push Me" + anchors.centerIn: parent + } + } + \endqml + + \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 Quick 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 <QGuiApplication> + #include <QQmlApplicationEngine> + + int main(int argc, char *argv[]) + { + QGuiApplication app(argc, argv); + QQmlApplicationEngine engine; + engine.load(QUrl(QStringLiteral("qrc:/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. +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-guidelines.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-guidelines.qdoc new file mode 100644 index 00000000..83d6db93 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-guidelines.qdoc @@ -0,0 +1,46 @@ +/**************************************************************************** +** +** 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-guidelines.html + \keyword Qt Quick Controls Guidelines + \title Qt Quick Controls Guidelines + \keyword Qt Quick Controls 2 Guidelines + + Qt Quick Controls offers a selection of controls that can be used to + build complete interfaces in Qt Quick. + + Below you will find practical guidelines on how and when to use + the controls. + + \annotatedlist qtquickcontrols2-guidelines + + \section1 Related Information + \list + \li \l{Qt Quick Controls QML Types}{All Qt Quick Controls QML Types} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-icons.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-icons.qdoc new file mode 100644 index 00000000..ea8579dc --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-icons.qdoc @@ -0,0 +1,166 @@ +/**************************************************************************** +** +** 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-icons.html + \keyword Icons in Qt Quick Controls 2 + \title Icons in Qt Quick Controls + + Qt Quick Controls comes with support for icons since Qt 5.10. This means, + Buttons, item delegates, and menu items are now capable of presenting an + icon in addition to a text label. + + \section1 Using Icons + + \l {AbstractButton::icon}{AbstractButton} and \l {Action::icon}{Action} provide + the following properties through which icons can be set: + \list + \li \c icon.name + \li \c icon.source + \li \c icon.width + \li \c icon.height + \li \c icon.color + \li \c icon.cache + \endlist + + Theme icons are referenced by a name, and regular icons by a source URL. Both + \c icon.name and \c icon.source can be set to ensure that an icon will always + be found. If the icon is found in the theme, it will always be used; even if + \c icon.source is also set. If the icon is not found in the theme, \c icon.source + will be used instead. + + \code + Button { + icon.name: "edit-cut" + icon.source: "images/cut.png" + } + \endcode + + Each \l {Styling Qt Quick Controls}{Qt Quick Controls 2 style} requests a + default icon size and color according to their guidelines, but it is possible + to override these by setting the \c icon.width, \c icon.height, and \c icon.color + properties. + + The image that is loaded by an icon whose \c width and \c height are not set + depends on the type of icon in use. For theme icons, the closest available size + will be chosen. For regular icons, the behavior is the same as the \l {Image::} + {sourceSize} property of \l Image. + + The icon color is specified by default so that it matches the text color in + different states. In order to use an icon with the original colors, set the + color to \c "transparent". + + \code + Button { + icon.color: "transparent" + icon.source: "images/logo.png" + } + \endcode + + For buttons, the \l {AbstractButton::}{display} property can be used to control + how the icon and text are displayed within the button. + + \section1 Icon Themes + + Compliant icon themes must follow the freedesktop icon theme specification, + which can be obtained here: \l {http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html}. + + Traditionally, only Linux and UNIX support icon themes on the platform level, + but it is possible to bundle a compliant icon theme in an application to use + themed icons on any platform. + + The default \l {QIcon::themeSearchPaths()}{icon theme search paths} depend on + the platform. On Linux and UNIX, the search path will use the \c XDG_DATA_DIRS + environment variable if available. All platforms have the resource directory + \c :/icons as a fallback. Custom icon theme search paths can be set with + \l QIcon::setThemeSearchPaths(). + + The following example bundles an icon theme called \e mytheme into the application's + resources using \l {The Qt Resource System}{Qt's resource system}. + + \badcode + <RCC> + <qresource prefix="/"> + <file>icons/mytheme/index.theme</file> + <file>icons/mytheme/32x32/myicon.png</file> + <file>icons/mytheme/32x32@2/myicon.png</file> + </qresource> + </RCC> + \endcode + + The \c index.theme file describes the general attributes of the icon theme, and + lists the available theme icon directories: + + \badcode + [Icon Theme] + Name=mytheme + Comment=My Icon Theme + + Directories=32x32,32x32@2 + + [32x32] + Size=32 + Type=Fixed + + [32x32@2] + Size=32 + Scale=2 + Type=Fixed + \endcode + + In order to use the bundled icon theme, an application should call \l QIcon::setThemeName() + before loading the main QML file: + + \code + #include <QGuiApplication> + #include <QQmlApplicationEngine> + #include <QIcon> + + int main(int argc, char *argv[]) + { + QGuiApplication app(argc, argv); + + QIcon::setThemeName("mytheme"); // <-- + + QQmlApplicationEngine engine; + engine.load(QUrl(QStringLiteral("qrc:/main.qml"))); + return app.exec(); + } + \endcode + + Now it is possible to use named icons from the bundled icon theme without having + to specify any fallback source: + + \code + Button { + icon.name: "myicon" + } + \endcode + + The \l {Qt Quick Controls - Gallery}{Gallery example} and \l {Qt Quick Controls 2 - Wearable Demo} + {Wearable Demo} provide complete runnable applications with a bundled icon theme. +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-imagine.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-imagine.qdoc new file mode 100644 index 00000000..aed0f894 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-imagine.qdoc @@ -0,0 +1,2524 @@ +/**************************************************************************** +** +** 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-imagine.html + \title Imagine Style + + The Imagine Style is based on configurable image assets. \l{detailed-desc-imagine}{More...} + + \styleimport {QtQuick.Controls.Imagine 2.12} {Qt 5.10} + + \section1 Attached Properties + + \list + \li \l {imagine-path-attached-prop}{\b path} : string + \endlist + + \section1 Detailed Description + \target detailed-desc-imagine + + The Imagine style is based on image assets. The style comes with a default + set of images, but the images can be easily changed by providing a directory + with images using a predefined naming convention. + + \image qtquickcontrols2-imagine.png + \caption The Imagine style with the default images + + To run an application with the Imagine style, see + \l {Using Styles in Qt Quick Controls}. + + \section2 File Names + + The image files are named using the following convention: + + \c <control>-<element>-<states> + + The \c <control> and \c <element> sections are mandatory, but the + \c <states> section is optional. For example, if a single file named + \c "button-background.9.png" is provided for \l {Button}, it will be used + for every state that \c Button supports. It is up to the developer to + decide the set of states that they will provide images for. However, it + is recommended to provide images for the most common control states where + possible, such as \c disabled, \c pressed, etc. This will ensure that + interactive controls visually behave as the end user would expect them to. + + \section2 Element Reference + + The following table lists which elements are supported for each control, + along with the possible states for that element, and the file extension + that it expects. An element is an image that represents a certain visual + part of the control. For example, \c {Button}'s \c "background" element + represents its \l {Control::}{background}. + + \table + \header + \li Control + \li Element + \li States + \li Extension + \row + \li \l ApplicationWindow + \li background + \li active + \li .9.png (or .png) + \row + \li \l BusyIndicator + \li animation + \li disabled, running, mirrored, hovered + \li .webp + \row + \li + \li background + \li same as above + \li .webp + \row + \li \l Button + \li background + \li disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered + \li .9.png + \row + \li \l CheckBox + \li background + \li disabled, pressed, checked, partially-checked, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li indicator + \li same as above + \li .png + \row + \li \l CheckDelegate + \li background + \li disabled, pressed, checked, partially-checked, focused, highlighted, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li indicator + \li same as above + \li .png + \row + \li \l ComboBox + \li background + \li disabled, pressed, editable, open, focused, mirrored, hovered, flat + \li .9.png (or .png) + \row + \li + \li indicator + \li same as above + \li .png + \row + \li + \li popup + \li same as above + \li .9.png (or .png) + \row + \li \l DelayButton + \li background + \li disabled, pressed, checked, checkable, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li progress + \li same as above + \li .9.png (or .png) + \row + \li + \li mask + \li same as above + \li .9.png (or .png) + \row + \li \l Dial + \li background + \li disabled, pressed, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li handle + \li same as above + \li .9.png (or .png) + \row + \li \l Dialog + \li background + \li modal, dim + \li .9.png (or .png) + \row + \li + \li title + \li same as above + \li .9.png (or .png) + \row + \li + \li overlay + \li modal + \li .9.png (or .png) + \row + \li \l DialogButtonBox + \li background + \li disabled, mirrored + \li .9.png (or .png) + \row + \li \l Drawer + \li background + \li modal, dim, top, left, right, bottom + \li .9.png (or .png) + \row + \li + \li overlay + \li modal + \li .9.png (or .png) + \row + \li \l Frame + \li background + \li disabled, mirrored + \li .9.png (or .png) + \row + \li \l GroupBox + \li background + \li disabled, mirrored + \li .9.png (or .png) + \row + \li + \li title + \li same as above + \li .9.png (or .png) + \row + \li \l ItemDelegate + \li background + \li disabled, pressed, focused, highlighted, mirrored, hovered + \li .9.png (or .png) + \row + \li \l Label + \li background + \li disabled, mirrored, hovered + \li .9.png (or .png) + \row + \li \l Menu + \li background + \li modal, dim + \li .9.png (or .png) + \row + \li + \li overlay + \li modal + \li .9.png (or .png) + \row + \li \l MenuItem + \li arrow + \li disabled, pressed, checked, focused, highlighted, mirrored, hovered + \li .png + \row + \li + \li background + \li same as above + \li .9.png (or .png) + \row + \li + \li indicator + \li same as above + \li .png + \row + \li \l MenuSeparator + \li background + \li disabled, mirrored + \li .9.png (or .png) + \row + \li + \li separator + \li same as above + \li .9.png (or .png) + \row + \li \l Page + \li background + \li disabled, mirrored + \li .9.png (or .png) + \row + \li \l PageIndicator + \li background + \li disabled, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li delegate + \li disabled, pressed, current, mirrored, hovered + \li .png + \row + \li \l Pane + \li background + \li disabled, mirrored + \li .9.png (or .png) + \row + \li \l Popup + \li background + \li modal, dim + \li .9.png (or .png) + \row + \li + \li overlay + \li modal + \li .9.png (or .png) + \row + \li \l ProgressBar + \li animation + \li disabled, mirrored, hovered + \li .png + \row + \li + \li background + \li disabled, indeterminate, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li mask + \li same as above + \li .9.png (or .png) + \row + \li + \li progress + \li same as above + \li .9.png (or .png) + \row + \li \l RadioButton + \li background + \li disabled, pressed, checked, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li indicator + \li same as above + \li .png + \row + \li \l RadioDelegate + \li background + \li disabled, pressed, checked, focused, highlighted, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li indicator + \li same as above + \li .png + \row + \li \l RangeSlider + \li background + \li vertical, horizontal, disabled, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li \l RangeSlider + \li progress + \li same as above + \li .9.png (or .png) + \row + \li + \li handle + \li first, second, vertical, horizontal, disabled, pressed, focused, mirrored, hovered + \li .png + \row + \li \l RoundButton + \li background + \li disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered + \li .9.png (or .png) + \row + \li \l ScrollBar + \li background + \li vertical, horizontal, disabled, interactive, pressed, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li handle + \li same as above + \li .9.png (or .png) + \row + \li \l ScrollIndicator + \li background + \li vertical, horizontal, disabled, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li handle + \li same as above + \li .9.png (or .png) + \row + \li \l ScrollView + \li background + \li disabled, mirrored + \li .9.png (or .png) + \row + \li \l Slider + \li background + \li vertical, horizontal, disabled, pressed, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li handle + \li same as above + \li .9.png (or .png) + \row + \li + \li progress + \li same as above + \li .9.png (or .png) + \row + \li \l SpinBox + \li background + \li disabled, editable, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li editor + \li disabled, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li indicator + \li up, down, disabled, editable, pressed, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li \l StackView + \li background + \li disabled, mirrored + \li .9.png (or .png) + \row + \li \l SwipeDelegate + \li background + \li disabled, pressed, focused, highlighted, mirrored, hovered + \li .9.png (or .png) + \row + \li \l SwipeView + \li background + \li vertical, horizontal, disabled, interactive, focused, mirrored + \li .9.png (or .png) + \row + \li \l Switch + \li background + \li disabled, pressed, checked, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li handle + \li same as above + \li .9.png (or .png) + \row + \li + \li indicator + \li same as above + \li .9.png (or .png) + \row + \li \l SwitchDelegate + \li background + \li disabled, pressed, checked, focused, highlighted, mirrored, hovered + \li .9.png (or .png) + \row + \li + \li handle + \li same as above + \li .9.png (or .png) + \row + \li + \li indicator + \li same as above + \li .9.png (or .png) + \row + \li \l TabBar + \li background + \li disabled, header, footer, mirrored + \li .9.png (or .png) + \row + \li \l TabButton + \li background + \li disabled, pressed, checked, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li \l TextArea + \li background + \li disabled, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li \l TextField + \li background + \li disabled, focused, mirrored, hovered + \li .9.png (or .png) + \row + \li \l ToolBar + \li background + \li disabled, header, footer, mirrored + \li .9.png (or .png) + \row + \li \l ToolButton + \li background + \li disabled, pressed, checked, checkable, focused, highlighted, flat, mirrored, hovered + \li .9.png (or .png) + \row + \li \l ToolSeparator + \li background + \li vertical, horizontal, disabled, mirrored + \li .9.png (or .png) + \row + \li + \li separator + \li same as above + \li .9.png (or .png) + \row + \li \l ToolTip + \li background + \li + \li .9.png (or .png) + \row + \li \l Tumbler + \li background + \li disabled, focused, mirrored, hovered + \li .9.png (or .png) + \endtable + + \section2 Asset Examples + + The following table lists examples of assets (taken from the default + Imagine style assets) for all controls. The list is not exhaustive, + as not all elements need assets, but it can be used as a guide + when creating your own assets. + + \table + \header + \li Control + \li Element + \li States + \li Asset + \li Notes + \row + \li \l ApplicationWindow + \li background + \li + \li \image imagine/images/applicationwindow-background.png + \li \l {sup1}{See footnote} \sup 1 + \row + \li + \li overlay + \li + \li \image imagine/images/applicationwindow-overlay.png + \li \l {sup1}{See footnote} \sup 1 + \row + \li + \li overlay + \li modal + \li \image imagine/images/applicationwindow-overlay-modal.png + \li \l {sup1}{See footnote} \sup 1 + \row + \li \l Button + \li background + \li + \li \image imagine/images/button-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/button-background-disabled.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/button-background-focused.9.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/button-background-pressed.9.png + \li + \row + \li + \li background + \li checked + \li \image imagine/images/button-background-checked.9.png + \li + \row + \li + \li background + \li checked, disabled + \li \image imagine/images/button-background-checked-disabled.9.png + \li + \row + \li + \li background + \li checked, focused + \li \image imagine/images/button-background-checked-focused.9.png + \li + \row + \li + \li background + \li checked, hovered + \li \image imagine/images/button-background-checked-hovered.9.png + \li + \row + \li + \li background + \li highlighted + \li \image imagine/images/button-background-highlighted.9.png + \li + \row + \li + \li background + \li highlighted, disabled + \li \image imagine/images/button-background-highlighted-disabled.9.png + \li + \row + \li + \li background + \li highlighted, focused + \li \image imagine/images/button-background-highlighted-focused.9.png + \li + \row + \li + \li background + \li highlighted, hovered + \li \image imagine/images/button-background-highlighted-hovered.9.png + \li + \row + \li + \li background + \li highlighted, pressed + \li \image imagine/images/button-background-highlighted-pressed.9.png + \li + \row + \li + \li background + \li highlighted, checked + \li \image imagine/images/button-background-highlighted-checked.9.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/button-background-hovered.9.png + \li + \row + \li + \li background + \li flat + \li \image imagine/images/button-background-flat.9.png + \li + \row + \li + \li background + \li flat, disabled + \li \image imagine/images/button-background-flat-disabled.9.png + \li + \row + \li + \li background + \li flat, hovered + \li \image imagine/images/button-background-flat-hovered.9.png + \li + \row + \li + \li background + \li flat, pressed + \li \image imagine/images/button-background-flat-pressed.9.png + \li + \row + \li + \li background + \li flat, checked + \li \image imagine/images/button-background-flat-checked.9.png + \li + \row + \li \l CheckBox + \li indicator + \li + \li \image imagine/images/checkbox-indicator.png + \li + \row + \li + \li indicator + \li disabled + \li \image imagine/images/checkbox-indicator-disabled.png + \li + \row + \li + \li indicator + \li pressed + \li \image imagine/images/checkbox-indicator-pressed.png + \li + \row + \li + \li indicator + \li checked + \li \image imagine/images/checkbox-indicator-checked.png + \li + \row + \li + \li indicator + \li checked, pressed + \li \image imagine/images/checkbox-indicator-checked-pressed.png + \li + \row + \li + \li indicator + \li checked, hovered + \li \image imagine/images/checkbox-indicator-checked-hovered.png + \li + \row + \li + \li indicator + \li checked, focused + \li \image imagine/images/checkbox-indicator-checked-focused.png + \li + \row + \li + \li indicator + \li partially, checked + \li \image imagine/images/checkbox-indicator-partially-checked.png + \li + \row + \li + \li indicator + \li partially, checked, pressed + \li \image imagine/images/checkbox-indicator-partially-checked-pressed.png + \li + \row + \li + \li indicator + \li partially, checked, focused + \li \image imagine/images/checkbox-indicator-partially-checked-focused.png + \li + \row + \li + \li indicator + \li partially, checked, hovered + \li \image imagine/images/checkbox-indicator-partially-checked-hovered.png + \li + \row + \li + \li indicator + \li focused + \li \image imagine/images/checkbox-indicator-focused.png + \li + \row + \li + \li indicator + \li hovered + \li \image imagine/images/checkbox-indicator-hovered.png + \li + \row + \li \l CheckDelegate + \li background + \li + \li \image imagine/images/checkdelegate-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/checkdelegate-background-disabled.9.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/checkdelegate-background-pressed.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/checkdelegate-background-focused.9.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/checkdelegate-background-hovered.9.png + \li + \row + \li + \li indicator + \li + \li \image imagine/images/checkdelegate-indicator.png + \li + \row + \li + \li indicator + \li disabled + \li \image imagine/images/checkdelegate-indicator-disabled.png + \li + \row + \li + \li indicator + \li pressed + \li \image imagine/images/checkdelegate-indicator-pressed.png + \li + \row + \li + \li indicator + \li checked + \li \image imagine/images/checkdelegate-indicator-checked.png + \li + \row + \li + \li indicator + \li checked, pressed + \li \image imagine/images/checkdelegate-indicator-checked-pressed.png + \li + \row + \li + \li indicator + \li checked, focused + \li \image imagine/images/checkdelegate-indicator-checked-focused.png + \li + \row + \li + \li indicator + \li checked, hovered + \li \image imagine/images/checkdelegate-indicator-checked-hovered.png + \li + \row + \li + \li indicator + \li focused + \li \image imagine/images/checkdelegate-indicator-focused.png + \li + \row + \li + \li indicator + \li hovered + \li \image imagine/images/checkdelegate-indicator-hovered.png + \li + \row + \li + \li indicator + \li partially, checked + \li \image imagine/images/checkdelegate-indicator-partially-checked.png + \li + \row + \li + \li indicator + \li partially, checked, pressed + \li \image imagine/images/checkdelegate-indicator-partially-checked-pressed.png + \li + \row + \li + \li indicator + \li partially, checked, focused + \li \image imagine/images/checkdelegate-indicator-partially-checked-focused.png + \li + \row + \li + \li indicator + \li partially, checked, hovered + \li \image imagine/images/checkdelegate-indicator-partially-checked-hovered.png + \li + \row + \li + \li indicator + \li hovered + \li \image imagine/images/checkdelegate-indicator-hovered.png + \li + \row + \li \l ComboBox + \li background + \li + \li \image imagine/images/combobox-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/combobox-background-disabled.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/combobox-background-focused.9.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/combobox-background-hovered.9.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/combobox-background-pressed.9.png + \li + \row + \li + \li background + \li open + \li \image imagine/images/combobox-background-open.9.png + \li + \row + \li + \li background + \li editable + \li \image imagine/images/combobox-background-editable.9.png + \li + \row + \li + \li background + \li editable, focused + \li \image imagine/images/combobox-background-editable-focused.9.png + \li + \row + \li + \li background + \li editable, disabled + \li \image imagine/images/combobox-background-editable-disabled.9.png + \li + \row + \li + \li indicator + \li + \li \image imagine/images/combobox-indicator.png + \li + \row + \li + \li indicator + \li disabled + \li \image imagine/images/combobox-indicator-disabled.png + \li + \row + \li + \li indicator + \li editable + \li \image imagine/images/combobox-indicator-editable.png + \li + \row + \li + \li indicator + \li editable, disabled + \li \image imagine/images/combobox-indicator-editable-disabled.png + \li + \row + \li + \li indicator + \li editable, mirrored + \li \image imagine/images/combobox-indicator-editable-mirrored.png + \li + \row + \li + \li indicator + \li editable, mirrored, disabled + \li \image imagine/images/combobox-indicator-editable-mirrored-disabled.png + \li + \row + \li + \li popup + \li + \li \image imagine/images/combobox-popup.9.png + \li + \row + \li \l DelayButton + \li background + \li + \li \image imagine/images/delaybutton-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/delaybutton-background-disabled.9.png + \li + \row + \li + \li background + \li disabled, checked + \li \image imagine/images/delaybutton-background-disabled-checked.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/delaybutton-background-focused.9.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/delaybutton-background-pressed.9.png + \li + \row + \li + \li background + \li checked + \li \image imagine/images/delaybutton-background-checked.9.png + \li + \row + \li + \li background + \li checked, focused + \li \image imagine/images/delaybutton-background-checked-focused.9.png + \li + \row + \li + \li background + \li checked, hovered + \li \image imagine/images/delaybutton-background-checked-hovered.9.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/delaybutton-background-hovered.9.png + \li + \row + \li + \li progress + \li + \li \image imagine/images/delaybutton-progress.9.png + \li + \row + \li + \li progress + \li disabled + \li \image imagine/images/delaybutton-progress-disabled.9.png + \li + \row + \li + \li mask + \li + \li \image imagine/images/delaybutton-mask.9.png + \li + \row + \li \l Dial + \li background + \li + \li \image imagine/images/dial-background.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/dial-background-disabled.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/dial-background-focused.png + \li + \row + \li + \li handle + \li + \li \image imagine/images/dial-handle.png + \li + \row + \li + \li handle + \li disabled + \li \image imagine/images/dial-handle-disabled.png + \li + \row + \li + \li handle + \li focused + \li \image imagine/images/dial-handle-focused.png + \li + \row + \li + \li handle + \li focused, pressed + \li \image imagine/images/dial-handle-focused-pressed.png + \li + \row + \li + \li handle + \li focused, hovered + \li \image imagine/images/dial-handle-focused-hovered.png + \li + \row + \li + \li handle + \li pressed + \li \image imagine/images/dial-handle-pressed.png + \li + \row + \li + \li handle + \li hovered + \li \image imagine/images/dial-handle-hovered.png + \li + \row + \li \l Dialog + \li background + \li + \li \image imagine/images/dialog-background.9.png + \li + \row + \li + \li overlay + \li + \li \image imagine/images/dialog-overlay.png + \li \l {sup1}{See footnote} \sup 1 + \row + \li + \li overlay + \li modal + \li \image imagine/images/dialog-overlay-modal.png + \li \l {sup1}{See footnote} \sup 1 + \row + \li \l DialogButtonBox + \li background + \li + \li \image imagine/images/dialogbuttonbox-background.9.png + \li + \row + \li \l Drawer + \li background + \li left + \li \image imagine/images/drawer-background-left.9.png + \li + \row + \li + \li background + \li right + \li \image imagine/images/drawer-background-right.9.png + \li + \row + \li + \li background + \li top + \li \image imagine/images/drawer-background-top.9.png + \li + \row + \li + \li background + \li bottom + \li \image imagine/images/drawer-background-bottom.9.png + \li + \row + \li + \li overlay + \li + \li \image imagine/images/drawer-overlay.png + \li \l {sup1}{See footnote} \sup 1 + \row + \li + \li overlay + \li modal + \li \image imagine/images/drawer-overlay-modal.png + \li \l {sup1}{See footnote} \sup 1 + \row + \li \l Frame + \li background + \li + \li \image imagine/images/frame-background.9.png + \li + \row + \li \l GroupBox + \li background + \li + \li \image imagine/images/groupbox-background.9.png + \li + \row + \li + \li title + \li + \li \image imagine/images/groupbox-title.9.png + \li + \row + \li \l ItemDelegate + \li background + \li + \li \image imagine/images/itemdelegate-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/itemdelegate-background-disabled.9.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/itemdelegate-background-pressed.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/itemdelegate-background-focused.9.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/itemdelegate-background-hovered.9.png + \li + \row + \li + \li background + \li highlighted + \li \image imagine/images/itemdelegate-background-highlighted.9.png + \li + \row + \li \l Menu + \li background + \li + \li \image imagine/images/menu-background.9.png + \li + \row + \li \l MenuItem + \li background + \li + \li \image imagine/images/menuitem-background.9.png + \li + \row + \li + \li background + \li highlighted + \li \image imagine/images/menuitem-background-highlighted.9.png + \li + \row + \li + \li arrow + \li + \li \image imagine/images/menuitem-arrow.png + \li + \row + \li + \li arrow + \li mirrored + \li \image imagine/images/menuitem-arrow-mirrored.png + \li + \row + \li + \li arrow + \li disabled + \li \image imagine/images/menuitem-arrow-disabled.png + \li + \row + \li + \li arrow + \li mirrored, disabled + \li \image imagine/images/menuitem-arrow-mirrored-disabled.png + \li + \row + \li + \li indicator + \li + \li \image imagine/images/menuitem-indicator.png + \li + \row + \li + \li indicator + \li disabled + \li \image imagine/images/menuitem-indicator-disabled.png + \li + \row + \li + \li indicator + \li pressed + \li \image imagine/images/menuitem-indicator-pressed.png + \li + \row + \li + \li indicator + \li checked + \li \image imagine/images/menuitem-indicator-checked.png + \li + \row + \li + \li indicator + \li checked, pressed + \li \image imagine/images/menuitem-indicator-checked-pressed.png + \li + \row + \li + \li indicator + \li checked, focused + \li \image imagine/images/menuitem-indicator-checked-focused.png + \li + \row + \li + \li indicator + \li checked, hovered + \li \image imagine/images/menuitem-indicator-checked-hovered.png + \li + \row + \li + \li indicator + \li focused + \li \image imagine/images/menuitem-indicator-focused.png + \li + \row + \li + \li indicator + \li hovered + \li \image imagine/images/menuitem-indicator-hovered.png + \li + \row + \li \l MenuSeparator + \li separator + \li + \li \image imagine/images/menuseparator-separator.9.png + \li + \row + \li \l Page + \li background + \li + \li \image imagine/images/page-background.png + \li \l {sup1}{See footnote} \sup 1 + \row + \li \l PageIndicator + \li delegate + \li + \li \image imagine/images/pageindicator-delegate.png + \li + \row + \li + \li delegate + \li disabled + \li \image imagine/images/pageindicator-delegate-disabled.png + \li + \row + \li + \li delegate + \li disabled, current + \li \image imagine/images/pageindicator-delegate-disabled-current.png + \li + \row + \li + \li delegate + \li pressed + \li \image imagine/images/pageindicator-delegate-pressed.png + \li + \row + \li + \li delegate + \li current + \li \image imagine/images/pageindicator-delegate-current.png + \li + \row + \li \l Pane + \li background + \li + \li \image imagine/images/pane-background.9.png + \li + \row + \li \l Popup + \li background + \li + \li \image imagine/images/popup-background.9.png + \li \l {sup1}{See footnote} \sup 1 + \row + \li + \li overlay + \li + \li \image imagine/images/popup-overlay.png + \li \l {sup1}{See footnote} \sup 1 + \row + \li + \li overlay + \li modal + \li \image imagine/images/popup-overlay-modal.png + \li + \row + \li \l ProgressBar + \li background + \li + \li \image imagine/images/progressbar-background.9.png + \li + \row + \li + \li progress + \li + \li \image imagine/images/progressbar-progress.png + \li + \row + \li + \li mask + \li + \li \image imagine/images/progressbar-mask.9.png + \li + \row + \li \l RadioButton + \li indicator + \li + \li \image imagine/images/radiobutton-indicator.png + \li + \row + \li + \li indicator + \li disabled + \li \image imagine/images/radiobutton-indicator-disabled.png + \li + \row + \li + \li indicator + \li pressed + \li \image imagine/images/radiobutton-indicator-pressed.png + \li + \row + \li + \li indicator + \li checked + \li \image imagine/images/radiobutton-indicator-checked.png + \li + \row + \li + \li indicator + \li checked, focused + \li \image imagine/images/radiobutton-indicator-checked-focused.png + \li + \row + \li + \li indicator + \li checked, hovered + \li \image imagine/images/radiobutton-indicator-checked-hovered.png + \li + \row + \li + \li indicator + \li checked, pressed + \li \image imagine/images/radiobutton-indicator-checked-pressed.png + \li + \row + \li + \li indicator + \li focused + \li \image imagine/images/radiobutton-indicator-focused.png + \li + \row + \li + \li indicator + \li hovered + \li \image imagine/images/radiobutton-indicator-hovered.png + \li + \row + \li \l RadioDelegate + \li background + \li + \li \image imagine/images/radiodelegate-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/radiodelegate-background-disabled.9.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/radiodelegate-background-pressed.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/radiodelegate-background-focused.9.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/radiodelegate-background-hovered.9.png + \li + \row + \li + \li indicator + \li + \li \image imagine/images/radiodelegate-indicator.png + \li + \row + \li + \li indicator + \li disabled + \li \image imagine/images/radiodelegate-indicator-disabled.png + \li + \row + \li + \li indicator + \li pressed + \li \image imagine/images/radiodelegate-indicator-pressed.png + \li + \row + \li + \li indicator + \li checked + \li \image imagine/images/radiodelegate-indicator-checked.png + \li + \row + \li + \li indicator + \li checked, focused + \li \image imagine/images/radiodelegate-indicator-checked-focused.png + \li + \row + \li + \li indicator + \li checked, hovered + \li \image imagine/images/radiodelegate-indicator-checked-hovered.png + \li + \row + \li + \li indicator + \li checked, pressed + \li \image imagine/images/radiodelegate-indicator-checked-pressed.png + \li + \row + \li + \li indicator + \li focused + \li \image imagine/images/radiodelegate-indicator-focused.png + \li + \row + \li + \li indicator + \li hovered + \li \image imagine/images/radiodelegate-indicator-hovered.png + \li + \row + \li \l RangeSlider + \li background + \li vertical + \li \image imagine/images/rangeslider-background-vertical.9.png + \li + \row + \li + \li background + \li horizontal + \li \image imagine/images/rangeslider-background-horizontal.9.png + \li + \row + \li + \li progress + \li vertical + \li \image imagine/images/rangeslider-progress-vertical.9.png + \li + \row + \li + \li progress + \li vertical, disabled + \li \image imagine/images/rangeslider-progress-vertical-disabled.9.png + \li + \row + \li + \li progress + \li horizontal + \li \image imagine/images/rangeslider-progress-horizontal.9.png + \li + \row + \li + \li progress + \li horizontal, disabled + \li \image imagine/images/rangeslider-progress-horizontal-disabled.9.png + \li + \row + \li + \li handle + \li + \li \image imagine/images/rangeslider-handle.png + \li + \row + \li + \li handle + \li disabled + \li \image imagine/images/rangeslider-handle-disabled.png + \li + \row + \li + \li handle + \li focused + \li \image imagine/images/rangeslider-handle-focused.png + \li + \row + \li + \li handle + \li focused, hovered + \li \image imagine/images/rangeslider-handle-focused-hovered.png + \li + \row + \li + \li handle + \li focused, pressed + \li \image imagine/images/rangeslider-handle-focused-pressed.png + \li + \row + \li + \li handle + \li hovered + \li \image imagine/images/rangeslider-handle-hovered.png + \li + \row + \li + \li handle + \li pressed + \li \image imagine/images/rangeslider-handle-pressed.png + \li + \row + \li \l RoundButton + \li background + \li + \li \image imagine/images/roundbutton-background.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/roundbutton-background-disabled.png + \li + \row + \li + \li background + \li disabled, checked + \li \image imagine/images/roundbutton-background-disabled-checked.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/roundbutton-background-focused.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/roundbutton-background-pressed.png + \li + \row + \li + \li background + \li checked + \li \image imagine/images/roundbutton-background-checked.png + \li + \row + \li + \li background + \li checked, focused + \li \image imagine/images/roundbutton-background-checked-focused.png + \li + \row + \li + \li background + \li checked, hovered + \li \image imagine/images/roundbutton-background-checked-hovered.png + \li + \row + \li + \li background + \li highlighted + \li \image imagine/images/roundbutton-background-highlighted.png + \li + \row + \li + \li background + \li highlighted, pressed + \li \image imagine/images/roundbutton-background-highlighted-pressed.png + \li + \row + \li + \li background + \li highlighted, focused + \li \image imagine/images/roundbutton-background-highlighted-focused.png + \li + \row + \li + \li background + \li highlighted, hovered + \li \image imagine/images/roundbutton-background-highlighted-hovered.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/roundbutton-background-hovered.png + \li + \row + \li \l ScrollBar + \li handle + \li + \li \image imagine/images/scrollbar-handle.png + \li + \row + \li + \li handle + \li disabled + \li \image imagine/images/scrollbar-handle-disabled.png + \li + \row + \li + \li handle + \li interactive + \li \image imagine/images/scrollbar-handle-interactive.png + \li + \row + \li + \li handle + \li interactive, disabled + \li \image imagine/images/scrollbar-handle-interactive-disabled.png + \li + \row + \li + \li handle + \li interactive, pressed + \li \image imagine/images/scrollbar-handle-interactive-pressed.png + \li + \row + \li + \li handle + \li interactive, hovered + \li \image imagine/images/scrollbar-handle-interactive-hovered.png + \li + \row + \li \l ScrollIndicator + \li handle + \li + \li \image imagine/images/scrollindicator-handle.png + \li + \row + \li \l Slider + \li background + \li vertical + \li \image imagine/images/slider-background-vertical.9.png + \li + \row + \li + \li background + \li horizontal + \li \image imagine/images/slider-background-horizontal.9.png + \li + \row + \li + \li progress + \li vertical + \li \image imagine/images/slider-progress-vertical.9.png + \li + \row + \li + \li progress + \li vertical, disabled + \li \image imagine/images/slider-progress-vertical-disabled.9.png + \li + \row + \li + \li progress + \li horizontal + \li \image imagine/images/slider-progress-horizontal.9.png + \li + \row + \li + \li progress + \li horizontal, disabled + \li \image imagine/images/slider-progress-horizontal-disabled.9.png + \li + \row + \li + \li handle + \li + \li \image imagine/images/slider-handle.png + \li + \row + \li + \li handle + \li disabled + \li \image imagine/images/slider-handle-disabled.png + \li + \row + \li + \li handle + \li focused + \li \image imagine/images/slider-handle-focused.png + \li + \row + \li + \li handle + \li focused, hovered + \li \image imagine/images/slider-handle-focused-hovered.png + \li + \row + \li + \li handle + \li focused, pressed + \li \image imagine/images/slider-handle-focused-pressed.png + \li + \row + \li + \li handle + \li hovered + \li \image imagine/images/slider-handle-hovered.png + \li + \row + \li + \li handle + \li pressed + \li \image imagine/images/slider-handle-pressed.png + \li + \row + \li \l SpinBox + \li background + \li + \li \image imagine/images/spinbox-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/spinbox-background-disabled.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/spinbox-background-focused.9.png + \li + \row + \li + \li background + \li editable + \li \image imagine/images/spinbox-background-editable.9.png + \li + \row + \li + \li indicator + \li up + \li \image imagine/images/spinbox-indicator-up.9.png + \li + \row + \li + \li indicator + \li up, disabled + \li \image imagine/images/spinbox-indicator-up-disabled.9.png + \li + \row + \li + \li indicator + \li up, pressed + \li \image imagine/images/spinbox-indicator-up-pressed.9.png + \li + \row + \li + \li indicator + \li up, focused + \li \image imagine/images/spinbox-indicator-up-focused.9.png + \li + \row + \li + \li indicator + \li up, mirrored + \li \image imagine/images/spinbox-indicator-up-mirrored.9.png + \li + \row + \li + \li indicator + \li up, hovered + \li \image imagine/images/spinbox-indicator-up-hovered.9.png + \li + \row + \li + \li indicator + \li up, editable + \li \image imagine/images/spinbox-indicator-up-editable.9.png + \li + \row + \li + \li indicator + \li up, editable, pressed + \li \image imagine/images/spinbox-indicator-up-editable-pressed.9.png + \li + \row + \li + \li indicator + \li up, editable, focused + \li \image imagine/images/spinbox-indicator-up-editable-focused.9.png + \li + \row + \li + \li indicator + \li up, editable, mirrored + \li \image imagine/images/spinbox-indicator-up-editable-mirrored.9.png + \li + \row + \li + \li indicator + \li up, editable, hovered + \li \image imagine/images/spinbox-indicator-up-editable-hovered.9.png + \li + \row + \li + \li indicator + \li down + \li \image imagine/images/spinbox-indicator-down.9.png + \li + \row + \li + \li indicator + \li down, disabled + \li \image imagine/images/spinbox-indicator-down-disabled.9.png + \li + \row + \li + \li indicator + \li down, pressed + \li \image imagine/images/spinbox-indicator-down-pressed.9.png + \li + \row + \li + \li indicator + \li down, focused + \li \image imagine/images/spinbox-indicator-down-focused.9.png + \li + \row + \li + \li indicator + \li down, mirrored + \li \image imagine/images/spinbox-indicator-down-mirrored.9.png + \li + \row + \li + \li indicator + \li down, hovered + \li \image imagine/images/spinbox-indicator-down-hovered.9.png + \li + \row + \li + \li indicator + \li down, editable + \li \image imagine/images/spinbox-indicator-down-editable.9.png + \li + \row + \li + \li indicator + \li down, editable, pressed + \li \image imagine/images/spinbox-indicator-down-editable-pressed.9.png + \li + \row + \li + \li indicator + \li down, editable, focused + \li \image imagine/images/spinbox-indicator-down-editable-focused.9.png + \li + \row + \li + \li indicator + \li down, editable, mirrored + \li \image imagine/images/spinbox-indicator-down-editable-mirrored.9.png + \li + \row + \li + \li indicator + \li down, editable, hovered + \li \image imagine/images/spinbox-indicator-down-editable-hovered.9.png + \li + \row + \li \l SwipeDelegate + \li background + \li + \li \image imagine/images/swipedelegate-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/swipedelegate-background-disabled.9.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/swipedelegate-background-pressed.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/swipedelegate-background-focused.9.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/swipedelegate-background-hovered.9.png + \li + \row + \li \l Switch + \li indicator + \li + \li \image imagine/images/switch-indicator.png + \li + \row + \li + \li indicator + \li disabled + \li \image imagine/images/switch-indicator-disabled.png + \li + \row + \li + \li indicator + \li pressed + \li \image imagine/images/switch-indicator-pressed.png + \li + \row + \li + \li indicator + \li checked + \li \image imagine/images/switch-indicator-checked.png + \li + \row + \li + \li indicator + \li checked, focused + \li \image imagine/images/switch-indicator-checked-focused.png + \li + \row + \li + \li indicator + \li checked, hovered + \li \image imagine/images/switch-indicator-checked-hovered.png + \li + \row + \li + \li indicator + \li checked, pressed + \li \image imagine/images/switch-indicator-checked-pressed.png + \li + \row + \li + \li indicator + \li focused + \li \image imagine/images/switch-indicator-focused.png + \li + \row + \li + \li indicator + \li hovered + \li \image imagine/images/switch-indicator-hovered.png + \li + \row + \li + \li handle + \li + \li \image imagine/images/switch-handle.png + \li + \row + \li + \li handle + \li disabled + \li \image imagine/images/switch-handle-disabled.png + \li + \row + \li + \li handle + \li pressed + \li \image imagine/images/switch-handle-pressed.png + \li + \row + \li \l SwitchDelegate + \li background + \li + \li \image imagine/images/switchdelegate-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/switchdelegate-background-disabled.9.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/switchdelegate-background-pressed.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/switchdelegate-background-focused.9.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/switchdelegate-background-hovered.9.png + \li + \row + \li + \li indicator + \li + \li \image imagine/images/switchdelegate-indicator.png + \li + \row + \li + \li indicator + \li disabled + \li \image imagine/images/switchdelegate-indicator-disabled.png + \li + \row + \li + \li indicator + \li pressed + \li \image imagine/images/switchdelegate-indicator-pressed.png + \li + \row + \li + \li indicator + \li checked + \li \image imagine/images/switchdelegate-indicator-checked.png + \li + \row + \li + \li indicator + \li checked, focused + \li \image imagine/images/switchdelegate-indicator-checked-focused.png + \li + \row + \li + \li indicator + \li checked, hovered + \li \image imagine/images/switchdelegate-indicator-checked-hovered.png + \li + \row + \li + \li indicator + \li checked, pressed + \li \image imagine/images/switchdelegate-indicator-checked-pressed.png + \li + \row + \li + \li indicator + \li focused + \li \image imagine/images/switchdelegate-indicator-focused.png + \li + \row + \li + \li indicator + \li hovered + \li \image imagine/images/switchdelegate-indicator-hovered.png + \li + \row + \li + \li handle + \li + \li \image imagine/images/switchdelegate-handle.png + \li + \row + \li + \li handle + \li disabled + \li \image imagine/images/switchdelegate-handle-disabled.png + \li + \row + \li \l TabBar + \li background + \li + \li \image imagine/images/tabbar-background.png + \li + \row + \li \l TabButton + \li background + \li + \li \image imagine/images/tabbutton-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/tabbutton-background-disabled.9.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/tabbutton-background-pressed.9.png + \li + \row + \li + \li background + \li checked + \li \image imagine/images/tabbutton-background-checked.9.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/tabbutton-background-hovered.9.png + \li + \row + \li + \li background + \li disabled, checked + \li \image imagine/images/tabbutton-background-disabled-checked.9.png + \li + \row + \li \l TextArea + \li background + \li + \li \image imagine/images/textarea-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/textarea-background-disabled.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/textarea-background-focused.9.png + \li + \row + \li \l TextField + \li background + \li + \li \image imagine/images/textfield-background.9.png + \li + \row + \li + \li background + \li disabled + \li \image imagine/images/textfield-background-disabled.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/textfield-background-focused.9.png + \li + \row + \li \l ToolBar + \li background + \li + \li \image imagine/images/toolbar-background.png + \li + \row + \li \l ToolButton + \li background + \li + \li \image imagine/images/toolbutton-background.9.png + \li + \row + \li + \li background + \li disabled, checked + \li \image imagine/images/toolbutton-background-disabled-checked.9.png + \li + \row + \li + \li background + \li focused + \li \image imagine/images/toolbutton-background-focused.9.png + \li + \row + \li + \li background + \li pressed + \li \image imagine/images/toolbutton-background-pressed.9.png + \li + \row + \li + \li background + \li checked + \li \image imagine/images/toolbutton-background-checked.9.png + \li + \row + \li + \li background + \li checked, focused + \li \image imagine/images/toolbutton-background-checked-focused.9.png + \li + \row + \li + \li background + \li checked, hovered + \li \image imagine/images/toolbutton-background-checked-hovered.9.png + \li + \row + \li + \li background + \li hovered + \li \image imagine/images/toolbutton-background-hovered.9.png + \li + \row + \li \l ToolSeparator + \li separator + \li horizontal + \li \image imagine/images/toolseparator-separator-horizontal.9.png + \li + \row + \li + \li separator + \li vertical + \li \image imagine/images/toolseparator-separator-vertical.9.png + \li + \row + \li \l ToolTip + \li background + \li + \li \image imagine/images/tooltip-background.9.png + \li + \endtable + + \target sup1 + \sup 1 A 1x1 image containing one color, stretched to fill the control. + + \section2 9-Patch Images + + The Imagine style uses \l + {https://developer.android.com/guide/topics/graphics/2d-graphics.html#nine-patch}{9-patch + images} in order to give designers control over how a particular element + responds to being resized. Here is an example of a 9-patch image that + represents a \l {Button}'s \l {Control::}{background}, alongside a + magnified version (to make it easier to see the 9-patch lines): + + \image qtquickcontrols2-imagine-9-patch-4x.png + + The content of the image is 44 pixels wide by 32 pixels high. Every 9-patch + image needs a one pixel thick line (collectively referred to as + "9-patch lines") around every side, so the actual size of the image becomes + 46 pixels wide by 34 pixels high. Note that the 9-patch lines must be one + pixel thick regardless of the target DPI of the image. For example, + the 9-patch lines for button-background.9.png and button-background@2x.9.png + must both be one pixel thick. + + The 9-patch lines must be black, and the remaining areas must be transparent + or white: + + \image qtquickcontrols2-imagine-9-patch-size.png + + \section3 Stretchable Areas + + The 9-patch lines on the top and left edges determine which parts of the + image are stretched when it is resized. + + Below are examples of the 9-patch image being resized to one and a half + times its original size in various dimensions: + + \image qtquickcontrols2-imagine-9-patch-resized-stretchable.png + + Notice how the the rounded corners keep their original size, as they are + outside the range of the lines. + + \section3 Padding Areas + + The 9-patch lines on the right and bottom edges determine how much space + is available for the control's \l {Control::}{contentItem}, which means it + can also be thought of as controlling the \l {Control::}{padding}. For a + diagram that illustrates padding, see \l {Control Layout}. + + Below are more examples of the 9-patch image being resized, but this time + demonstrating how the padding 9-patch lines work. + + \image qtquickcontrols2-imagine-9-patch-resized-padding.png + + The \c contentItem can take up as much space as it needs within the shaded + areas. If the padding lines are left out, the \c contentItem will take as + much space as it needs without exceeding the stretchable areas. + + \section3 Inset Areas + + In some cases it is necessary for a control to have a drop shadow, for + example. However, if we were to add a drop shadow to the button above, it + would affect its size, which presents problems for both layouting and + mouse/touch input boundaries. + + Inset areas accounts for this by telling the control that a certain area of + the 9-patch image should go outside of the control: + + \image qtquickcontrols2-imagine-9-patch-inset.png + + In the image below, the dashed line represents the button's clickable area, + as well as the space that it will take up in a layout. The shadow is marked + by the striped area behind it: + + \image qtquickcontrols2-imagine-9-patch-inset-boundaries.png + + \section3 Exporting 9-Patch Images + + Various vector and bitmap editors can be used to create 9-patch images + suitable for use with the Imagine style. The following sections briefly + explain the export process for each editor, and the last section explains + how to ensure the exported images are 9-patch-conformant. + + \section4 Illustrator + + See Adobe's + \l {https://helpx.adobe.com/in/illustrator/using/collect-assets-export-for-screens.html#panel} + {Asset Export panel} documentation. + + \section4 Inkscape + + The \l {https://github.com/mitchcurtis/inkscape-9-patch-export} + {Inkscape 9-Patch Export Extension} can be used to export assets with + Inkscape. + + \section4 Photoshop + + See Adobe's + \l {https://helpx.adobe.com/photoshop/using/generate-assets-layers.html} + {Generate image assets from layers} documentation. + + \section4 Sketch + + See Sketch's \l {https://sketchapp.com/docs/exporting/}{Exporting} documentation. + + Qt Quick Controls also provides a + \l {http://code.qt.io/cgit/qt/qtquickcontrols2.git/tree/src/quickcontrols2/imagine/design} + {plugin} for Sketch that automatically fixes the thickness of the 9-patch lines + after the assets are exported. To install this file, double-click on it. + Once Sketch has confirmed that the 9-patch export plugin has been installed, + the plugin will automatically process images when they are exported. + + \section4 Fixing 9-Patch Lines + + When exporting 9-patch images in several DPI variants (\c {@2x}, \c {@3x}, + etc.), the 9-patch lines will typically be scaled up along with the image. + There are several ways to fix this, but perhaps the simplest approach is + to use \l {https://www.imagemagick.org/script/mogrify.php}{ImageMagick's mogrify} + tool. The tool has a \c -shave feature that can be used to crop the image + to reduce the thickness of the 9-patch lines: + + \badcode + mogrify -shave 1x1 -path path/to/images *@2x.9.png + mogrify -shave 2x2 -path path/to/images *@3x.9.png + mogrify -shave 3x3 -path path/to/images *@4x.9.png + \endcode + + Regular DPI images (those without the \c @Nx prefix) are not affected, so it + is only necessary to run the command on images intended for high DPI displays. + + \section2 Animated Images + + The \l {https://developers.google.com/speed/webp/}{WebP} and GIF animated + image formats are supported by the Imagine style. + + \section2 Customization + + \section3 Path + + The Imagine style allows customizing the \l {imagine-path-attached-prop}{path} + that is used to do the image asset selection. The path can be specified for any + window or item, and it automatically propagates to children in the same manner as + \l {Control::font}{fonts}. In the following example, the window and all three radio + buttons appear with dark image assets (files that are located in "qrc:/themes/dark"). + + \table + \row + \li + \qml + import QtQuick 2.12 + import QtQuick.Controls 2.12 + import QtQuick.Controls.Imagine 2.12 + + ApplicationWindow { + visible: true + + Imagine.path: "qrc:/themes/dark" + + Column { + anchors.centerIn: parent + + RadioButton { text: qsTr("Small") } + RadioButton { text: qsTr("Medium"); checked: true } + RadioButton { text: qsTr("Large") } + } + } + \endqml + \li + \image qtquickcontrols2-imagine-customization-dark.png + \endtable + + In addition to specifying the path in QML, it is also possible to specify + it via an \l {imagine-customization-environment-variable}{environment variable} + or in a \l {imagine-customization-configuration-file}{configuration file}. + Attributes specified in QML take precedence over all other methods. + + \section4 Configuration File + \target imagine-customization-configuration-file + + \include qquickimaginestyle.qdocinc conf + + See \l {Qt Quick Controls Configuration File} for more details about the + configuration file. + + \section4 Environment Variables + \target imagine-customization-environment-variable + + \include qquickimaginestyle.qdocinc env + + See \l {Supported Environment Variables in Qt Quick Controls} for the full + list of supported environment variables. + + \section3 Palette + + The Imagine style supports palette customization via the \l {Item::}{palette} + property and the \l {Palette Configuration}{qtquickcontrols2.conf} file. + As with other styles, the exact \l[QML]{Palette}{palette roles} + that the Imagine style uses are style-dependent. However, as most of the visual + appearance of controls (for example: backgrounds) are managed through image assets, + only the roles that are typically used for text will have an effect. + + \section3 Font + + Custom fonts can be set via the \l {Control::}{font} property and the + \l {Font Configuration}{configuration} file. + + \section2 Dependency + + The Imagine style must be separately imported to gain access to the + attributes that are specific to the Imagine style. It should be noted + that regardless of the references to the Imagine style, the same + application code runs with any other style. Imagine-specific attributes + only have an effect when the application is run with the Imagine style. + + If the Imagine style is imported in a QML file that is always loaded, the + Imagine style must be deployed with the application in order to be able + to run the application regardless of which style the application is run with. + By using \l {Using File Selectors with Qt Quick Controls}{file selectors}, + style-specific tweaks can be applied without creating a hard dependency to + a style. + + \b {See also} \l {Styling Qt Quick Controls} + + \section1 Attached Property Documentation + + \styleproperty {Imagine.path} {string} {imagine-path-attached-prop} + \target imagine-path-attached-prop + This attached property holds the path to the image assets... + + \code + Button { + Imagine.path: "qrc:/themes/dark" + } + \endcode + + \endstyleproperty + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls} + \li \l{Qt Quick Controls - Imagine Style Example: Automotive}{Automotive Example} + \li \l{Qt Quick Controls - Imagine Style Example: Music Player}{Music Player Example} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-index.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-index.qdoc new file mode 100644 index 00000000..7b64e776 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-index.qdoc @@ -0,0 +1,204 @@ +/**************************************************************************** +** +** 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 qtquickcontrols-index.html + \keyword Qt Quick Controls 2 + \title Qt Quick Controls + + \brief Provides a set of UI controls for Qt Quick. + + Qt Quick Controls provides a set of controls that can be used + to build complete interfaces in Qt Quick. The module was introduced + in Qt 5.7. + + \image qtquickcontrols2-styles.png + + Qt Quick Controls comes with a selection customizable styles. + See \l {Styling Qt Quick Controls} for more details. + + + \section1 Using the Module + + \section2 QML API + + The \l{Qt Quick Controls QML Types}{QML types} can be imported into your + application using the following import statement in your \c {.qml} file: + + \qml + import QtQuick.Controls + \endqml + + \section2 C++ API + + Using the \l{Qt Quick Controls C++ Classes}{C++ API} requires linking against the module library, + either directly or through other dependencies. + Several build tools have dedicated support for this, including CMake and qmake. + + \section3 Building with CMake + Use the \c find_package() command to locate the needed module components in the Qt6 package: + + \snippet qtquickcontrols2-overview.cmake 0 + + See also the \l{Build with CMake} overview. + + \section3 Building with qmake + To configure the module for building with qmake, + add the module as a value of the QT variable in the project's .pro file: + + \code + QT += quickcontrols2 + \endcode + + \section2 Building From Source + + The \b{Qt Image Formats} module is recommended, but not + required. It provides support for the \c {.webp} format used by the + \l {Animated Images}{Imagine style}. + + \section1 Versions + + Qt Quick Controls 2.0 was introduced in Qt 5.7. Subsequent minor Qt releases + increment the import version of the Qt Quick Controls modules by one, + until Qt 5.12, where the import versions match Qt's minor version. + + In Qt 6, both the major and minor versions match, and version numbers may + be omitted from imports in QML. If the version is omitted, the latest + version will be used. + + The experimental Qt Labs modules use import version 1.0. + + \table + \header + \li \c Qt + \li \l {Qt Quick QML Types}{\c QtQuick} + \li \l {Qt Quick Controls QML Types}{\c QtQuick.Controls},\br + \l {Material Style}{\c QtQuick.Controls.Material},\br + \l {Universal Style}{\c QtQuick.Controls.Universal},\br + \l {Qt Quick Templates 2 QML Types}{\c QtQuick.Templates} + \li \l {Qt Labs Platform QML Types}{\c Qt.labs.platform} + \row + \li 5.7 + \li 2.7 + \li 2.0 + \li 1.0 + \row + \li 5.8 + \li 2.8 + \li 2.1 + \li 1.0 + \row + \li 5.9 + \li 2.9 + \li 2.2 + \li 1.0 + \row + \li 5.10 + \li 2.10 + \li 2.3 + \li 1.0 + \row + \li 5.11 + \li 2.11 + \li 2.4 + \li 1.0 + \row + \li 5.12 + \li 2.12 + \li 2.12 + \li 1.0 + \row + \li 6.0 + \li 6.0 + \li 6.0 + \li 1.0 + \row + \li ... + \li ... + \li ... + \li ... + \endtable + + \section1 Module Evolution + \l{Changes to Qt Quick Controls} lists important changes in the + module API and functionality that were done for the Qt 6 series of Qt. + + \section1 License and Attributions + + Qt Quick Controls is available under commercial licenses from \l{The Qt Company}. + In addition, it is available under the + \l{GNU Lesser General Public License, version 3}, or + the \l{GNU General Public License, version 2}. + See \l{Qt Licensing} for further details. + + Furthermore Qt Quick Controls potentially contains third party + modules under following permissive licenses: + + \generatelist{groupsbymodule attributions-qtquickcontrols} + + \section1 Topics + + \list + \li \l{Getting Started with Qt Quick Controls}{Getting Started} + \li \l{Qt Quick Controls Guidelines}{Guidelines} + \li \l{Styling Qt Quick Controls}{Styling} + \li \l{Icons in Qt Quick Controls}{Icons} + \li \l{Customizing Qt Quick Controls}{Customization} + \li \l{Using File Selectors with Qt Quick Controls}{Using File Selectors} + \li \l{Deploying Qt Quick Controls Applications}{Deployment} + \li \l{Qt Quick Controls Configuration File}{Configuration File} + \li \l{Supported Environment Variables in Qt Quick Controls}{Environment Variables} + \endlist + + \section1 Reference + + \list + \li \l{Qt Quick Controls QML Types}{QML Types} + \li \l{Qt Quick Controls C++ Classes}{C++ Classes} + \endlist + + \section1 Examples + + \list + \li \l{Qt Quick Controls - Gallery}{Gallery} + \li \l{Qt Quick Controls - Chat Tutorial}{Chat Tutorial} + \li \l{Qt Quick Controls - Text Editor}{Text Editor} + \li \l{Qt Quick Controls - Wearable Demo}{Wearable Demo} + \li \l{Qt Quick Controls - Imagine Style Example: Automotive}{Automotive Example} + \li \l{Qt Quick Controls - Imagine Style Example: Music Player}{Music Player Example} + \li \l{Qt Quick Controls Examples}{All Examples} + \endlist + + \section1 Related Modules + + \list + \li \l{Qt Quick} + \li \l{Qt Quick Layouts} + \li \l{Qt Quick Templates 2} + \li \l{Qt Labs Platform} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-indicators.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-indicators.qdoc new file mode 100644 index 00000000..9f9e357b --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-indicators.qdoc @@ -0,0 +1,83 @@ +/**************************************************************************** +** +** 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-indicators.html + \title Indicator Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for indicator controls + + Qt Quick Controls offers a selection of indicator-like controls. + + \annotatedlist qtquickcontrols2-indicators + + Each type of indicator has its own specific target use case. The following + sections offer guidelines for choosing the appropriate type of indicator, + depending on the use case. + + \section1 BusyIndicator Control + + \image qtquickcontrols2-busyindicator.png + + BusyIndicator can be used to show that an operation is in progress, + and that the UI has to wait for the operation to complete. + + \section1 PageIndicator Control + + \image qtquickcontrols2-pageindicator.png + + \l PageIndicator is used to indicate the currently active page in + a container of multiple pages. + + \section1 ProgressBar Control + + \image qtquickcontrols2-progressbar.gif + + \l ProgressBar indicates the progress of an operation. The value should be + updated regularly. + + \section1 ScrollBar Control + + \image qtquickcontrols2-scrollbar.gif + + \l ScrollBar is an interactive bar that indicates the current scroll + position, and can be used to scroll to a specific position in a + \l Flickable. + + \section1 ScrollIndicator Control + + \image qtquickcontrols2-scrollindicator.gif + + \l ScrollIndicator is a non-interactive indicator that indicates the + current scroll position, and can be used to scroll to a specific position in a + \l {Flickable}. + + \section1 Related Information + \list + \li \l {Qt Quick Controls Guidelines} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-input.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-input.qdoc new file mode 100644 index 00000000..6bc037e0 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-input.qdoc @@ -0,0 +1,123 @@ +/**************************************************************************** +** +** 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-input.html + \title Input Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for input controls + + Qt Quick Controls offers a variety of input controls for both numeric + and textual input. + + \annotatedlist qtquickcontrols2-input + + Each type of input control has its own specific target use case. The + following sections offer guidelines for choosing the appropriate type + of input control, depending on the use case. + + \section1 ComboBox Control + + \image qtquickcontrols2-combobox.gif + + \l ComboBox is used to select a value from a static multiple-line drop-down list. + It is not possible to add new values, and only one option can be selected. + + Recommendations: + \list + \li If the number of values is very large, consider applying a filter. + \li If the list is very limited, consider using RadioButton. This has the + advantage that the user can see all options at the same time. + \li Select a default value, the value that will be chosen most often. + \endlist + + \b {See also} \l {CheckBox Control}, \l {Tumbler Control}. + + \section1 Dial Control + + \image qtquickcontrols2-dial.png + + \l Dial is similar to a traditional dial knob that is found on devices such + as stereos or industrial equipment. + + The dial is rotated by clicking and dragging, with the handle indicating the + value of the dial. + + For applications where fast input is important, the circular + \l {Dial::inputMode}{input mode} is useful, as clicking on the dial will + move it directly to that position. + + For applications where precise input is important, the horizontal and + vertical input modes are recommended, as these allow small adjustments to + be made relative to where the dial is clicked. These modes are also better + for dials where large jumps in values could be unsafe, such as a dial that + controls audio volume. + + \b {See also} \l {Tumbler Control}. + + \section1 TextArea Control + + \image qtquickcontrols2-textarea.png + + \l TextArea is a multi-line text editor. + + \section1 TextField Control + + \image qtquickcontrols2-textfield.png + + \l TextField is a single line text editor. + + \b {See also} \l {Tumbler Control}. + + \section1 Slider Control + + \image qtquickcontrols2-slider.gif + + \l Slider is used to select a value by sliding a handle along a track. + + \section1 RangeSlider Control + + \image qtquickcontrols2-rangeslider.gif + + \l RangeSlider is used to select a range specified by two values, + by sliding each handle along a track. + + \b {See also} \l {Slider Control}. + + \section1 Tumbler Control + + \image qtquickcontrols2-tumbler.png + + \l Tumbler is a spinnable wheel of items that can be selected. + + \b {See also} \l {ComboBox Control}. + + \section1 Related Information + \list + \li \l {Qt Quick Controls Guidelines} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-macos.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-macos.qdoc new file mode 100644 index 00000000..382a23a6 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-macos.qdoc @@ -0,0 +1,76 @@ +/**************************************************************************** +** +** Copyright (C) 2021 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-macOS.html + \title macOS Style + + The macOS style is a style that looks native on macOS. + \l {detailed-desc-macOS}{More...} + + \styleimport {QtQuick.Controls.macOS} {Qt 6.0} + + \target detailed-desc-macOS + + The macOS style is a style that looks native on macOS. The controls are drawn run-time using + native frameworks, and is therefore only available for applications running on macOS. + + \note Be aware that the apperance of this style can change from one minor Qt version to the + next, to better blend in with native applications on the platform. + + \table + \row + \li \image qtquickcontrols2-macos-light.png + \caption The macOS style in light theme + \li \image qtquickcontrols2-macos-dark.png + \caption The macOS style in dark theme + \endtable + + To run an application with the macOS style, see + \l {Using Styles in Qt Quick Controls}. + + \section2 Current state + + The macOS style is under development, and some controls are not yet supported. Those + controls are: \l BusyIndicator, \l DelayButton, \l PageIndicator, \l RangeSlider, \l Switch, \l TabBar and + \l Tumbler. Those will fall back to use the \l {Fusion Style}. + + \section2 Customization + + The goal of the macOS style is to for the controls look and feel as similar as possible to the + native controls in UIKit. The style will follow the theme and colors configured globally from + System Preferences, and does not come with a separate customization API on top of that. + + \note If you want to style a control, you should set both the + \l {Control::background}{background} and the \l {Control::contentItem}{contentItem}, rather than + just one of them. This is because the macOS style will in some cases draw both the contents and + the background into the default background item, which will not look good if the application + combines this with a custom contentItem. By setting them both, you are guaranteed that the + control will look the same on all platforms, for all styles. + + \b {See also} \l {Styling Qt Quick Controls} +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-material.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-material.qdoc new file mode 100644 index 00000000..f08c5ec3 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-material.qdoc @@ -0,0 +1,404 @@ +/**************************************************************************** +** +** 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-material.html + \title Material Style + + The Material Style is based on the Google Material Design Guidelines. + \l{detailed-desc-material}{More...} + + \styleimport {QtQuick.Controls.Material 2.12} {Qt 5.7} + + \section1 Attached Properties + + \list + \li \l {material-accent-attached-prop}{\b accent} : color + \li \l {material-background-attached-prop}{\b background} : color + \li \l {material-elevation-attached-prop}{\b elevation} : int + \li \l {material-foreground-attached-prop}{\b foreground} : color + \li \l {material-primary-attached-prop}{\b primary} : color + \li \l {material-theme-attached-prop}{\b theme} : enumeration + \endlist + + \section1 Attached Methods + + \list + \li color \l {material-color-attached-method}{\b color}(enumeration predefined, enumeration shade) + \endlist + + \section1 Detailed Description + \target detailed-desc-material + + The Material style is based on the \l {https://www.google.com/design/spec/material-design/introduction.html} + {Google Material Design Guidelines}. It allows for a unified experience + across platforms and device sizes. + + \table + \row + \li \image qtquickcontrols2-material-light.png + \caption The Material style in light theme + \li \image qtquickcontrols2-material-dark.png + \caption The Material style in dark theme + \endtable + + To run an application with the Material style, see + \l {Using Styles in Qt Quick Controls}. + + \note The Material style is not a native Android style. The Material + style is a 100% cross-platform Qt Quick Controls style implementation that + follows the Google Material Design Guidelines. The style runs on any + platform, and looks more or less identical everywhere. Minor differences + may occur due to differences in available system fonts and font rendering + engines. + + \section2 Customization + + The Material style allows customizing five attributes, \l {material-theme-attached-prop}{theme}, + \l {material-primary-attached-prop}{primary}, \l {material-accent-attached-prop}{accent}, + \l {material-foreground-attached-prop}{foreground}, and \l {material-background-attached-prop}{background}. + + \image qtquickcontrols2-material-attributes.png + + All attributes can be specified for any window or item, and they automatically + propagate to children in the same manner as \l {Control::font}{fonts}. In the + following example, the window and all three radio buttons appear in the dark + theme using a purple accent color: + + \table + \row + \li + \qml + import QtQuick 2.12 + import QtQuick.Controls 2.12 + import QtQuick.Controls.Material 2.12 + + ApplicationWindow { + visible: true + + Material.theme: Material.Dark + Material.accent: Material.Purple + + Column { + anchors.centerIn: parent + + RadioButton { text: qsTr("Small") } + RadioButton { text: qsTr("Medium"); checked: true } + RadioButton { text: qsTr("Large") } + } + } + \endqml + \li + \image qtquickcontrols2-material-purple.png + \endtable + + In addition to specifying the attributes in QML, it is also possible to + specify them via environment variables or in a configuration file. Attributes + specified in QML take precedence over all other methods. + + \section3 Configuration File + + \include qquickmaterialstyle.qdocinc conf + + See \l {Qt Quick Controls Configuration File} for more details about the + configuration file. + + \section3 Environment Variables + + \include qquickmaterialstyle.qdocinc env + + See \l {Supported Environment Variables in Qt Quick Controls} for the full + list of supported environment variables. + + \section2 Dependency + + The Material style must be separately imported to gain access to the + attributes that are specific to the Material style. It should be noted + that regardless of the references to the Material style, the same + application code runs with any other style. Material-specific attributes + only have an effect when the application is run with the Material style. + + If the Material style is imported in a QML file that is always loaded, the + Material style must be deployed with the application in order to be able + to run the application regardless of which style the application is run with. + By using \l {Using File Selectors with Qt Quick Controls}{file selectors}, + style-specific tweaks can be applied without creating a hard dependency to + a style. + + \section2 Pre-defined Material Colors + + Even though primary and accent can be any \l {colorbasictypedocs}{color}, it + is recommended to use one of the pre-defined colors that have been designed + to work well with the rest of the Material style palette: + + Available pre-defined colors: + \value Material.Red \stylecolor {#F44336} {} + \value Material.Pink \stylecolor {#E91E63} {(default accent)} + \value Material.Purple \stylecolor {#9C27B0} {} + \value Material.DeepPurple \stylecolor {#673AB7} {} + \value Material.Indigo \stylecolor {#3F51B5} {(default primary)} + \value Material.Blue \stylecolor {#2196F3} {} + \value Material.LightBlue \stylecolor {#03A9F4} {} + \value Material.Cyan \stylecolor {#00BCD4} {} + \value Material.Teal \stylecolor {#009688} {} + \value Material.Green \stylecolor {#4CAF50} {} + \value Material.LightGreen \stylecolor {#8BC34A} {} + \value Material.Lime \stylecolor {#CDDC39} {} + \value Material.Yellow \stylecolor {#FFEB3B} {} + \value Material.Amber \stylecolor {#FFC107} {} + \value Material.Orange \stylecolor {#FF9800} {} + \value Material.DeepOrange \stylecolor {#FF5722} {} + \value Material.Brown \stylecolor {#795548} {} + \value Material.Grey \stylecolor {#9E9E9E} {} + \value Material.BlueGrey \stylecolor {#607D8B} {} + + When the dark theme is in use, different \l {Pre-defined Shades}{shades} of + the pre-defined colors are used by default: + + \value Material.Red \stylecolor {#EF9A9A} {} + \value Material.Pink \stylecolor {#F48FB1} {(default accent)} + \value Material.Purple \stylecolor {#CE93D8} {} + \value Material.DeepPurple \stylecolor {#B39DDB} {} + \value Material.Indigo \stylecolor {#9FA8DA} {(default primary)} + \value Material.Blue \stylecolor {#90CAF9} {} + \value Material.LightBlue \stylecolor {#81D4FA} {} + \value Material.Cyan \stylecolor {#80DEEA} {} + \value Material.Teal \stylecolor {#80CBC4} {} + \value Material.Green \stylecolor {#A5D6A7} {} + \value Material.LightGreen \stylecolor {#C5E1A5} {} + \value Material.Lime \stylecolor {#E6EE9C} {} + \value Material.Yellow \stylecolor {#FFF59D} {} + \value Material.Amber \stylecolor {#FFE082} {} + \value Material.Orange \stylecolor {#FFCC80} {} + \value Material.DeepOrange \stylecolor {#FFAB91} {} + \value Material.Brown \stylecolor {#BCAAA4} {} + \value Material.Grey \stylecolor {#EEEEEE} {} + \value Material.BlueGrey \stylecolor {#B0BEC5} {} + + \section2 Pre-defined Shades + + There are several different + \l {https://material.google.com/style/color.html#color-color-palette}{shades} + of each \l {Pre-defined Material Colors}{pre-defined color} that can be passed + to the \l {material-color-attached-method}{Material.color()} function: + \value Material.Shade50 + \value Material.Shade100 + \value Material.Shade200 + \value Material.Shade300 + \value Material.Shade400 + \value Material.Shade500 + \value Material.Shade600 + \value Material.Shade700 + \value Material.Shade800 + \value Material.Shade900 + \value Material.ShadeA100 + \value Material.ShadeA200 + \value Material.ShadeA400 + \value Material.ShadeA700 + + \b {See also} \l {Basic Style}, \l {Universal Style} + + \section2 Variants + + The Material style also supports a dense variant, where controls like + buttons and delegates are smaller in height and use smaller font sizes. + It is recommended to use the dense variant on desktop platforms, where + a mouse and keyboard allow more precise and flexible user interaction. + + To use the dense variant, either set the + \c QT_QUICK_CONTROLS_MATERIAL_VARIANT environment variable to \c Dense, + or specify \c Variant=Dense in the + \l {Qt Quick Controls Configuration File}{qtquickcontrols2.conf} file. + The default value in both cases is \c Normal. + + The following images illustrate the differences between some of the + controls when using the normal and dense variants: + + \table + \row + \li + \image qtquickcontrols2-material-variant-normal.png + \li + \image qtquickcontrols2-material-variant-dense.png + \endtable + + Note that the heights shown above may vary based on differences in fonts + across platforms. + + \section1 Attached Property Documentation + + \styleproperty {Material.accent} {color} {material-accent-attached-prop} + \target material-accent-attached-prop + This attached property holds the accent color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The default value is \c Material.Pink. + + In the following example, the accent color of the highlighted button is + changed to \c Material.Orange: + + \table + \row + \li + \snippet qtquickcontrols2-material-accent.qml 1 + \li + \image qtquickcontrols2-material-accent.png + \endtable + + \note Even though the accent can be any \l {colorbasictypedocs}{color}, it is + recommended to use one of the \l {pre-defined Material colors} that have been + designed to work well with the rest of the Material style palette. + + \endstyleproperty + + \styleproperty {Material.background} {color} {material-background-attached-prop} + \target material-background-attached-prop + This attached property holds the background color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The default value is theme-specific (light or dark). + + In the following example, the background color of the button is changed to + \c Material.Teal: + + \table + \row + \li + \snippet qtquickcontrols2-material-background.qml 1 + \li + \image qtquickcontrols2-material-background.png + \endtable + + \endstyleproperty + + \styleproperty {Material.elevation} {int} {material-elevation-attached-prop} + \target material-elevation-attached-prop + This attached property holds the elevation of the control. The higher the + elevation, the deeper the shadow. The property can be attached to any control, + but not all controls visualize elevation. + + The default value is control-specific. + + In the following example, the elevation of the pane is set to \c 6 + in order to achieve the look of an + \l {https://material.google.com/components/cards.html}{elevated card}: + + \table + \row + \li + \snippet qtquickcontrols2-material-elevation.qml 1 + \li + \image qtquickcontrols2-material-elevation.png + \endtable + + \endstyleproperty + + \styleproperty {Material.foreground} {color} {material-foreground-attached-prop} + \target material-foreground-attached-prop + This attached property holds the foreground color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The default value is theme-specific (light or dark). + + In the following example, the foreground color of the button is set to \c + Material.Pink: + + \table + \row + \li + \snippet qtquickcontrols2-material-foreground.qml 1 + \li + \image qtquickcontrols2-material-foreground.png + \endtable + + \endstyleproperty + + \styleproperty {Material.primary} {color} {material-primary-attached-prop} + \target material-primary-attached-prop + This attached property holds the primary color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The primary color is used as the background color of ToolBar by default. + + The default value is \c Material.Indigo. + + \note Even though the primary can be any \l {colorbasictypedocs}{color}, it is + recommended to use one of the \l {pre-defined Material colors} that have been + designed to work well with the rest of the Material style palette. + + \endstyleproperty + + \styleproperty {Material.theme} {enumeration} {material-theme-attached-prop} + \target material-theme-attached-prop + This attached property holds whether the theme is light or dark. The property + can be attached to any window or item. The value is propagated to children. + + Available themes: + \value Material.Light Light theme (default) + \value Material.Dark Dark theme + \value Material.System System theme + + Setting the theme to \c System chooses either the light or dark theme based + on the system theme colors. However, when reading the value of the theme + property, the value is never \c System, but the actual theme. + + In the following example, the theme for both the pane and the button is set + to \c Material.Dark: + + \table + \row + \li + \snippet qtquickcontrols2-material-theme.qml 1 + \li + \image qtquickcontrols2-material-theme.png + \endtable + + \endstyleproperty + + \section1 Attached Method Documentation + + \stylemethod2 {color} {color} {enumeration} {predefined} {enumeration} {shade} {material-color-attached-method} + \target material-color-attached-method + This attached method returns the effective color value of the specified + \l {pre-defined Material colors}{pre-defined Material color} combined with + the given \l {pre-defined shades}{shade}. If omitted, the shade argument + defaults to \c Material.Shade500. + + \qml + Rectangle { + color: Material.color(Material.Red) + } + \endqml + + \endstylemethod2 + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-menus.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-menus.qdoc new file mode 100644 index 00000000..43db2092 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-menus.qdoc @@ -0,0 +1,68 @@ +/**************************************************************************** +** +** 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-menus.html + \title Menu Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for menu controls + + \annotatedlist qtquickcontrols2-menus + + Each type of menu control has its own specific target use case. The + following sections offer guidelines for choosing the appropriate type + of menu control, depending on the use case. + + \section1 Menu Control + + \image qtquickcontrols2-menu.png + + \l Menu control can be used for context menus; for example, after + right-clicking. It can also be used for popup menus; for example, a + menu that is shown after clicking a button. + + \l MenuItem is an item in the Menu control. Each item in a menu: + \list + \li displays text to the user + \li allows checking/unchecking + \li is highlighted (for example, on keyboard navigation) + \li performs some action on activation + \endlist + + \section1 MenuBar Control + + \image qtquickcontrols2-menubar.png + + \l MenuBar control can be used for window menu bars. + + \l MenuBarItem is an item in the MenuBar control. Each item in a menu bar: + \list + \li displays text to the user + \li is highlighted (for example, on keyboard navigation) + \li pops up the respective menu on activation + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-navigation.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-navigation.qdoc new file mode 100644 index 00000000..95928d13 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-navigation.qdoc @@ -0,0 +1,70 @@ +/**************************************************************************** +** +** 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-navigation.html + \title Navigation Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for navigation controls + + Qt Quick Controls offers a selection of navigation models. + + \annotatedlist qtquickcontrols2-navigation + + The following sections offer guidelines for choosing the appropriate type + of navigation model, depending on the use case. + + \section1 StackView Control + + \image qtquickcontrols2-stackview-wireframe.png + + \l StackView provides a stack-based navigation model which can be used + with a set of interlinked pages. StackView works according to a last-in + first-out principle: the page pushed last on the stack is the one visible. + Popping a page removes the last page and makes the previous one visible. + + \section1 SwipeView Control + + \image qtquickcontrols2-swipeview-wireframe.png + + \l SwipeView provides a navigation model that simplifies horizontal paged + scrolling. The page indicator on the bottom shows which is the presently + active page. + + \section1 TabBar Control + + \image qtquickcontrols2-tabbar-wireframe.png + + \l TabBar is a bar with icons or text that allows the user to switch + between different subtasks, views, or modes. + + \section1 TabButton Control + + \image qtquickcontrols2-tabbutton.png + + \l TabButton is a button with a layout suitable for a TabBar control. +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-popups.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-popups.qdoc new file mode 100644 index 00000000..c26b4c4b --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-popups.qdoc @@ -0,0 +1,99 @@ +/**************************************************************************** +** +** 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-popups.html + \title Popup Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for popup controls + + \annotatedlist qtquickcontrols2-popups + + Each type of popup control has its own specific target use case. The + following sections offer guidelines for choosing the appropriate type + of popup control, depending on the use case. + + \section1 Drawer Control + + \image qtquickcontrols2-drawer-expanded-wireframe.png + + \l Drawer provides a swipe-based side panel, similar to those often used + in touch interfaces to provide a central location for navigation. + + The drawer can be positioned at any of the four edges of the screen. It allows + the user to add navigation without taking up valuable screen space. The user can + show and hide the drawer at any time with a simple swipe movement. + + \section1 Menu Control + + \image qtquickcontrols2-menu.png + + The \l Menu control displays a vertical list of items that can be selected. It can + be used for offering a list of actions that can be taken in a given context. + + \b {See also} \l {Drawer Control}. + + \section1 Popup Control + + \image qtquickcontrols2-popup-settings.png + + A \l Popup displays content over other application content. + It prompts the user to make a decision or enter information. + + Popups can be modal or non-modal. A modal popup blocks users from interacting + with the application until they have made a choice and closed the popup. + + A popup can be used for: + + \list + \li communicating a message to the user that they must read and acknowledge. + \li displaying an error message. + \li prompting the user to make a choice and/or enter a value. + \endlist + + \section1 ToolTip Control + + \image qtquickcontrols2-tooltip.png + + \l ToolTip shows a short piece of text that informs the user of a control's + function. It is typically placed above or below the parent control. + + Recommendations: + \list + \li Use a tooltip if a control has little or no descriptive text, or needs + a short explanation. + \li Use a tooltip only if the information on a particular control is not + available elsewhere in the screen. + \li Keep the tooltip text short so that it does not cover other content + while being displayed. + \endlist + + \section1 Related Information + \list + \li \l {Qt Quick Controls Guidelines} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-qmltypes.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-qmltypes.qdoc new file mode 100644 index 00000000..0251a6f9 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-qmltypes.qdoc @@ -0,0 +1,130 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \qmlmodule QtQuick.Controls 2.\QtMinorVersion + \keyword Qt Quick Controls QML Types + \title Qt Quick Controls QML Types + \keyword Qt Quick Controls 2 QML Types + \ingroup qmlmodules + \brief Provides QML types for user interfaces (Qt Quick Controls). + + \l{Qt Quick Controls} provides QML types for creating user interfaces. + These QML types work in conjunction with \l{Qt Quick} and + \l{Qt Quick Layouts}. + + Qt Quick Controls QML types can be imported into your application + using the following import statement in your .qml file: + + \qml + import QtQuick.Controls + \endqml + + \section1 QML Types + \generatelist {qmltypesbymodule QtQuick.Controls} + \noautolist + + \section1 Using Qt Quick Controls types in property declarations + + As mentioned in \l {Qt Quick Templates 2 QML Types}, each type in Qt Quick + Controls is backed by a C++ "template" type. These types are \l {Qt Quick + Templates 2}{non-visual implementations of controls' logic and behavior}. + + For example, the \l Menu type's API and behavior is defined by the C++ + type in Qt Quick Templates. Each \l {Definition of a Style}{style} that + wants to provide a Menu must have a Menu.qml available, and the root + item in that file must be the Menu from Qt Quick Templates. When you + import QtQuick.Controls and create a Menu in QML, the type you get is + actually the QML Menu defined by the style's Menu.qml. + + In order to use a control as the type in a property declaration, you should + use the corresponding type from Qt Quick Templates. For example, suppose + you had a \c PopupOpener component, which was a Button that opened a + Popup: + + \qml + // PopupButton.qml + import QtQuick.Controls + + Button { + required property Popup popup + + onClicked: popup.open() + } + + // main.qml + PopupButton { + popup: saveChangesDialog + } + + Dialog { + id: saveChangesDialog + + // ... + } + \endqml + + Running this code will result in an error: + + \badcode + Unable to assign Dialog_QMLTYPE to Popup_QMLTYPE + \endcode + + This is because of the inheritance hierarchy: + + \badcode + Popup (C++ type in QtQuick.Templates) + │ └── Popup (QML type in QtQuick.Controls) + └── Dialog (C++ type in QtQuick.Templates) + └── Dialog (QML type in QtQuick.Controls) + \endcode + + Dialog from \c QtQuick.Controls does not derive from the Popup from + \c QtQuick.Controls, but from \c QtQuick.Templates. + + Instead, use the Popup from Qt Quick Templates as the property type: + + \qml + // PopupButton.qml + import QtQuick.Controls + import QtQuick.Templates as T + + Button { + required property T.Popup popup + + onClicked: popup.open() + } + \endqml + + For more information on the Qt Quick Controls module, see the + \l {Qt Quick Controls} module documentation. + + \section1 Related Information + \list + \li \l {Qt Quick Controls Guidelines} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-separators.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-separators.qdoc new file mode 100644 index 00000000..481a744e --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-separators.qdoc @@ -0,0 +1,63 @@ +/**************************************************************************** +** +** 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-separators.html + \title Separator Controls + \ingroup qtquickcontrols2-guidelines + \brief Guidelines for separator controls + + Qt Quick Controls offers a selection of separators. + + \annotatedlist qtquickcontrols2-separators + + Each type of separator has its own specific use case. The following + sections offer guidelines for choosing the appropriate type of separator, + depending on the use case. + + \section1 MenuSeparator Control + + \image qtquickcontrols2-menuseparator.png + + \l MenuSeparator should be used to separate items (typically MenuItem + controls) in a Menu. Grouping related menu items together makes it easier + for the user to interact with the menu. For example, a typical desktop + user interface might have \c Undo and \c Redo items in one group, and + \c Cut, \c Copy and \c Paste in another. + + \section1 ToolSeparator Control + + \image qtquickcontrols2-toolseparator.png + + \l ToolSeparator should be used to separate items (typically ToolButton + controls) in a ToolBar. It can be used in horizontal or vertical toolbars. + + \section1 Related Information + \list + \li \l {Qt Quick Controls Guidelines} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-styles.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-styles.qdoc new file mode 100644 index 00000000..12993fbf --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-styles.qdoc @@ -0,0 +1,209 @@ +/**************************************************************************** +** +** 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-styles.html + \title Styling Qt Quick Controls + + \section1 Available Styles + + Qt Quick Controls comes with a selection of styles. + + \section2 Basic Style + + \image qtquickcontrols2-basic-thumbnail.png + The \l {Basic Style} is a simple and light-weight all-round style that offers + the maximum performance for Qt Quick Controls. + + \section2 Fusion Style + + \image qtquickcontrols2-fusion-thumbnail.png + The \l {Fusion Style} is a platform-agnostic style that offers a desktop-oriented + look and feel for Qt Quick Controls. + + \section2 Imagine Style + + \image qtquickcontrols2-imagine-thumbnail.png + The \l {Imagine Style} is based on image assets. The style comes with a default + set of images which can easily be changed by providing a directory + with images using a predefined naming convention. + + \section2 macOS Style + + \image qtquickcontrols2-macos-thumbnail.png + The \l {macOS Style} is a native-looking style for macOS. + \note this style is only available for applications running on macOS. + + \section2 Material Style + + \image qtquickcontrols2-material-thumbnail.png + The \l {Material Style} offers an appealing design based on the + \l {https://www.google.com/design/spec/material-design/introduction.html} + {Google Material Design Guidelines}, but requires more system resources than + the Basic style. + + \section2 Universal Style + + \image qtquickcontrols2-universal-thumbnail.png + The \l {Universal Style} offers an appealing design based on the + \l {https://dev.windows.com/design}{Microsoft Universal Design Guidelines}, + but requires more system resources than the Basic style. + + \section2 Windows Style + + \image qtquickcontrols2-windows-thumbnail.png + The \l {Windows Style} is a native-looking style for Windows. + \note this style is only available for applications running on Windows. + + \section1 Using Styles in Qt Quick Controls + + There are two ways of using styles in Qt Quick Controls: + run-time style selection and compile-time style selection. + + \section2 Compile-Time Style Selection + + Compile-time style selection involves using QML imports to specify the + style. For example, to import the Material style: + + \qml + import QtQuick.Controls.Material + + ApplicationWindow { + // ... + } + \endqml + + Notice that QtQuick.Controls (which is responsible for run-time style + selection) is not imported. The fallback style is specified by the qmldir + of the style: + + \badcode + module QtQuick.Controls.Material + # ... + import QtQuick.Controls.Basic auto + \endcode + + The benefit of compile-time style selection is that the QtQuick.Controls plugin + is not used and therefore does not need to be deployed with the application. + + Explicit imports are also necessary if your application is built + \l {Static Builds}{statically}. + + \section2 Run-Time Style Selection + + Run-time style selection involves importing \c QtQuick.Controls: + + \qml + import QtQuick.Controls + \endqml + + The QtQuick.Controls plugin will import the style and fallback + style that were set at runtime via one of the following approaches: + + \list + \li \l[CPP]{QQuickStyle::setStyle()} + \li The \c -style command line argument + \li The \c QT_QUICK_CONTROLS_STYLE environment variable + \li The \c qtquickcontrols2.conf configuration file + \endlist + + The priority of these approaches follows the order they are listed, + from highest to lowest. That is, using \c QQuickStyle to set the style will + always take priority over using the command line argument, for example. + + The benefit of run-time style selection is that a single application binary + can support multiple styles, meaning that the end user can choose which + style to run the application with. + + \section3 Using QQuickStyle in C++ + + \l[CPP]{QQuickStyle} provides C++ API for configuring a specific + style. The following example runs a Qt Quick Controls application + with the Material style: + + \code + QQuickStyle::setStyle("Material"); + \endcode + + See the detailed description of \l[CPP]{QQuickStyle} for more + details. + + \section3 Command line argument + + Passing a \c -style command line argument is the convenient way to test different + styles. It takes precedence over the other methods listed below. The following + example runs a Qt Quick Controls application with the Material style: + + \code + ./app -style material + \endcode + + \section3 Environment variable + + Setting the \c QT_QUICK_CONTROLS_STYLE environment variable can be used to set + a system-wide style preference. It takes precedence over the configuration file + mentioned below. The following example runs a Qt Quick Controls application with + the Universal style: + + \code + QT_QUICK_CONTROLS_STYLE=universal ./app + \endcode + + See \l {Supported Environment Variables in Qt Quick Controls} for the full list + of supported environment variables. + + \section3 Configuration file + + Qt Quick Controls support a special configuration file, \c :/qtquickcontrols2.conf, + that is built into an application's resources. + + The configuration file can specify the preferred style (may be overridden by either + of the methods described earlier) and certain style-specific attributes. The following + example specifies that the preferred style is the Material style. + + \code + [Controls] + Style=Material + \endcode + + See \l {Qt Quick Controls Configuration File} for more details about the + configuration file. + + \section1 Related Information + \list + \li \l {Basic Style} + \li \l {Fusion Style} + \li \l {Imagine Style} + \li \l {Material Style} + \li \l {Universal Style} + \li \l {Customizing Qt Quick Controls} + \li \l {Using File Selectors with Qt Quick Controls} + \li \l {Deploying Qt Quick Controls Applications} + \li \l {Qt Quick Controls Configuration File} + \li \l {Supported Environment Variables in Qt Quick Controls} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-universal.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-universal.qdoc new file mode 100644 index 00000000..72267050 --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-universal.qdoc @@ -0,0 +1,288 @@ +/**************************************************************************** +** +** 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-universal.html + \title Universal Style + + The Universal Style is based on the Microsoft Universal Design Guidelines. + \l {detailed-desc-universal}{More...} + + \styleimport {QtQuick.Controls.Universal 2.12} {Qt 5.7} + + \section1 Attached Properties + + \list + \li \l {universal-accent-attached-prop}{\b accent} : color + \li \l {universal-background-attached-prop}{\b background} : color + \li \l {universal-foreground-attached-prop}{\b foreground} : color + \li \l {universal-theme-attached-prop}{\b theme} : enumeration + \endlist + + \section1 Attached Methods + + \list + \li color \l {color-attached-method}{\b color}(enumeration predefined) + \endlist + + \section1 Detailed Description + \target detailed-desc-universal + + The Universal style is a device-agnostic style based on the + \l {https://dev.windows.com/design}{Microsoft Universal Design Guidelines}. + The Universal style has been designed to look good on all devices, from + phones and tablets to PCs. + + \table + \row + \li \image qtquickcontrols2-universal-light.png + \caption The Universal style in light theme + \li \image qtquickcontrols2-universal-dark.png + \caption The Universal style in dark theme + \endtable + + To run an application with the Universal style, see + \l {Using Styles in Qt Quick Controls}. + + \note The Universal style is not a native Windows 10 style. The Universal + style is a 100% cross-platform Qt Quick Controls style implementation that + follows the Microsoft Universal Design Guidelines. The style runs on any + platform, and looks more or less identical everywhere. Minor differences + may occur due to differences in available system fonts and font rendering + engines. + + \section2 Customization + + The Universal style allows customizing four attributes, \l {universal-theme-attached-prop}{theme}, + \l {universal-accent-attached-prop}{accent}, \l {universal-foreground-attached-prop}{foreground}, and + \l {universal-background-attached-prop}{background}. + + \image qtquickcontrols2-universal-attributes.png + + Both attributes can be specified for any window or item, and they automatically + propagate to children in the same manner as \l {Control::font}{fonts}. In the + following example, the window and all three radio buttons appear in the dark + theme using a violet accent color: + + \table + \row + \li + \qml + import QtQuick 2.12 + import QtQuick.Controls 2.12 + import QtQuick.Controls.Universal 2.12 + + ApplicationWindow { + visible: true + + Universal.theme: Universal.Dark + Universal.accent: Universal.Violet + + Column { + anchors.centerIn: parent + + RadioButton { text: qsTr("Small") } + RadioButton { text: qsTr("Medium"); checked: true } + RadioButton { text: qsTr("Large") } + } + } + \endqml + \li + \image qtquickcontrols2-universal-violet.png + \endtable + + In addition to specifying the attributes in QML, it is also possible to + specify them via environment variables or in a configuration file. Attributes + specified in QML take precedence over all other methods. + + \section3 Configuration File + + \include qquickuniversalstyle.qdocinc conf + + See \l {Qt Quick Controls Configuration File} for more details about the + configuration file. + + \section3 Environment Variables + + \include qquickuniversalstyle.qdocinc env + + See \l {Supported Environment Variables in Qt Quick Controls} for the full + list of supported environment variables. + + \section2 Dependency + + The Universal style must be separately imported to gain access to the + attributes that are specific to the Universal style. It should be noted + that regardless of the references to the Universal style, the same + application code runs with any other style. Universal-specific attributes + only have an effect when the application is run with the Universal style. + + If the Universal style is imported in a QML file that is always loaded, the + Universal style must be deployed with the application in order to be able + to run the application regardless of which style the application is run with. + By using \l {Using File Selectors with Qt Quick Controls}{file selectors}, + style-specific tweaks can be applied without creating a hard dependency to + a style. + + \section2 Pre-defined Universal Colors + + Available pre-defined colors: + \value Universal.Lime \stylecolor {#A4C400} {} + \value Universal.Green \stylecolor {#60A917} {} + \value Universal.Emerald \stylecolor {#008A00} {} + \value Universal.Teal \stylecolor {#00ABA9} {} + \value Universal.Cyan \stylecolor {#1BA1E2} {} + \value Universal.Cobalt \stylecolor {#3E65FF} {(default accent)} + \value Universal.Indigo \stylecolor {#6A00FF} {} + \value Universal.Violet \stylecolor {#AA00FF} {} + \value Universal.Pink \stylecolor {#F472D0} {} + \value Universal.Magenta \stylecolor {#D80073} {} + \value Universal.Crimson \stylecolor {#A20025} {} + \value Universal.Red \stylecolor {#E51400} {} + \value Universal.Orange \stylecolor {#FA6800} {} + \value Universal.Amber \stylecolor {#F0A30A} {} + \value Universal.Yellow \stylecolor {#E3C800} {} + \value Universal.Brown \stylecolor {#825A2C} {} + \value Universal.Olive \stylecolor {#6D8764} {} + \value Universal.Steel \stylecolor {#647687} {} + \value Universal.Mauve \stylecolor {#76608A} {} + \value Universal.Taupe \stylecolor {#87794E} {} + + \b {See also} \l {Basic Style}, \l {Material Style} + + \section1 Attached Property Documentation + + \styleproperty {Universal.accent} {color} {universal-accent-attached-prop} + \target universal-accent-attached-prop + This attached property holds the accent color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The default value is \c Universal.Cobalt. + + In the following example, the accent color of the highlighted button is + changed to \c Universal.Orange: + + \table + \row + \li + \snippet qtquickcontrols2-universal-accent.qml 1 + \li + \image qtquickcontrols2-universal-accent.png + \endtable + + \note Even though the accent can be any \l {colorbasictypedocs}{color}, it is + recommended to use one of the \l {pre-defined Universal colors} that have been + designed to work well with the rest of the Universal style palette. + + \endstyleproperty + + \styleproperty {Universal.background} {color} {universal-background-attached-prop} + \target universal-background-attached-prop + This attached property holds the background color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The default value is theme-specific (light or dark). + + In the following example, the background color of the pane is changed to + \c Universal.Steel: + + \table + \row + \li + \snippet qtquickcontrols2-universal-background.qml 1 + \li + \image qtquickcontrols2-universal-background.png + \endtable + + \endstyleproperty + + \styleproperty {Universal.foreground} {color} {universal-foreground-attached-prop} + \target universal-foreground-attached-prop + This attached property holds the foreground color of the theme. The property + can be attached to any window or item. The value is propagated to children. + + The default value is theme-specific (light or dark). + + In the following example, the foreground color of the button is set to \c + Universal.Pink: + + \table + \row + \li + \snippet qtquickcontrols2-universal-foreground.qml 1 + \li + \image qtquickcontrols2-universal-foreground.png + \endtable + + \styleproperty {Universal.theme} {enumeration} {universal-theme-attached-prop} + \target universal-theme-attached-prop + This attached property holds whether the theme is light or dark. The property + can be attached to any window or item. The value is propagated to children. + + Available themes: + \value Universal.Light Light theme (default) + \value Universal.Dark Dark theme + \value Universal.System System theme + + Setting the theme to \c System chooses either the light or dark theme based + on the system theme colors. However, when reading the value of the theme + property, the value is never \c System, but the actual theme. + + In the following example, the theme for both the pane and the button is set + to \c Universal.Dark: + + \table + \row + \li + \snippet qtquickcontrols2-universal-theme.qml 1 + \li + \image qtquickcontrols2-universal-theme.png + \endtable + + \endstyleproperty + + \section1 Attached Method Documentation + + \stylemethod {color} {color} {enumeration} {predefined} {color-attached-method} + \target color-attached-method + This attached method returns the effective color value of the specified + \l {pre-defined Universal colors}{pre-defined Universal color}. + + \qml + Rectangle { + color: Universal.color(Universal.Red) + } + \endqml + + \endstylemethod + + \section1 Related Information + + \list + \li \l{Styling Qt Quick Controls} + \endlist +*/ diff --git a/src/quickcontrols2/doc/src/qtquickcontrols2-windows.qdoc b/src/quickcontrols2/doc/src/qtquickcontrols2-windows.qdoc new file mode 100644 index 00000000..8b63703b --- /dev/null +++ b/src/quickcontrols2/doc/src/qtquickcontrols2-windows.qdoc @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** Copyright (C) 2021 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-Windows.html + \title Windows Style + + The Windows style is a style that looks native on Windows. + \l {detailed-desc-Windows}{More...} + + \styleimport {QtQuick.Controls.Windows} {Qt 6.0} + + \target detailed-desc-Windows + + The Windows style is a style that looks native on Windows. The controls are drawn run-time using + native libraries, and is therefore only available for applications running on Windows. + + \note Be aware that the apperance of this style can change from one minor Qt version to the + next, to better blend in with native applications on the platform. + + \table + \row + \li \image qtquickcontrols2-windows.png + \caption The Windows style + \endtable + + To run an application with the Windows style, see + \l {Using Styles in Qt Quick Controls}. + + \section2 Current state + + The Windows style is under development, and some controls are not yet supported. Those + controls are: \l BusyIndicator, \l DelayButton, \l PageIndicator, \l RangeSlider, \l Switch, \l TabBar and + \l Tumbler. Those will fall back to use the \l {Fusion Style}. + + \section2 Customization + + The goal of the Windows style is to for the controls look and feel as similar as possible to the + native controls on Windows. The style will follow the theme and colors configured globally from + Windows Settings, and does not come with a separate customization API on top of that. + + \note If you want to style a control, you should set both the + \l {Control::background}{background} and the \l {Control::contentItem}{contentItem}, rather than + just one of them. This is because the Windows style will in some cases draw both the contents and + the background into the default background item, which will not look good if the application + combines this with a custom contentItem. By setting them both, you are guaranteed that the + control will look the same on all platforms, for all styles. + + \b {See also} \l {Styling Qt Quick Controls} +*/ |