diff options
Diffstat (limited to 'src/quickcontrols/doc/src')
21 files changed, 456 insertions, 204 deletions
diff --git a/src/quickcontrols/doc/src/includes/container-currentindex.qdocinc b/src/quickcontrols/doc/src/includes/container-currentindex.qdocinc index 9fcf43e168..776e39dcfc 100644 --- a/src/quickcontrols/doc/src/includes/container-currentindex.qdocinc +++ b/src/quickcontrols/doc/src/includes/container-currentindex.qdocinc @@ -6,4 +6,10 @@ of each control. To do this without breaking bindings, avoid setting \c currentIndex directly, and instead use \l {Container::}{setCurrentIndex()}, for example. See \l {Managing the Current Index} for more information. + +To perform an action when \c currentIndex changes, use the +\c onCurrentIndexChanged +\l {Property Change Signal Handlers}{property change signal handler}: + +\snippet qtquickcontrols-container-oncurrentindexchanged.qml 1 //! [file] diff --git a/src/quickcontrols/doc/src/includes/qquickcontrol-focusreason.qdocinc b/src/quickcontrols/doc/src/includes/qquickcontrol-focusreason.qdocinc deleted file mode 100644 index b69e9e60ec..0000000000 --- a/src/quickcontrols/doc/src/includes/qquickcontrol-focusreason.qdocinc +++ /dev/null @@ -1,15 +0,0 @@ -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/quickcontrols/doc/src/includes/qquickheaderview.qdocinc b/src/quickcontrols/doc/src/includes/qquickheaderview.qdocinc new file mode 100644 index 0000000000..fdc191be3f --- /dev/null +++ b/src/quickcontrols/doc/src/includes/qquickheaderview.qdocinc @@ -0,0 +1,104 @@ +//! [detailed-description] +A \1 provides a styled table header. +It can either be used as an independent view or header for a \l TableView. + +You can add a header for a TableView by assigning a \1 +to the \l {TableView::syncView} property. The header and the table will +then be kept in sync while flicking. + +By default, \1 displays +\l {QAbstractItemModel::headerData()}{header data} +from the \l {TableView::syncView}{sync view's} \l {TableView::model}{model}. +If you don't wish to use this model, you can assign a different model to the +\l {TableView::model}{model} property. If you assign a model that is a +QAbstractItemModel, its header data will be used. Otherwise the data in +the model will be used directly (for example, if you assign a model that +is simply an array of strings). + +\note In order to show the header data of a QAbstractItemModel, \1 +will internally wrap the model's header data in an independent proxy +model. This model shares no model items with the \l {TableView::model}{application model}. +This means that if you call functions such as \l {TableView::index()}{index()}, the model +index you get back will belong to the proxy model and not the application model. + +By default, \l textRole is set to \c "display", meaning that data from the +model's \l {Qt::ItemDataRole}{Qt::DisplayRole} will be used. You can set +this to another role name in order to have that data displayed instead. + +The application is responsible for placing the header at the +correct location in the scene. You can add as many headers as you +want to a single TableView, which can be useful if you for example want +to place headers on all four sides of the table. + +The following snippet shows how you can add a horizontal and vertical header +view to a table view: + +\snippet qtquickcontrols-headerview.qml 0 + +A \1 will have +\l {TableView::resizableColumns}{resizableColumns} set to \c true by default. +//! [detailed-description] + +//! [syncView] +This property holds the TableView to synchronize with. + +Once this property is bound to another TableView, both header and table +will synchronize with regard to column widths, column spacing, and flicking +\1. + +If the \l model is not explicitly set, then the header will use the syncView's +model to label the columns. + +\sa model TableView +//! [syncView] + +//! [model] +This property holds the model providing data for the \1 header view. + +When model is not explicitly set, the header will use the syncView's +model once syncView is set. + +If model is a QAbstractTableModel, its \1 headerData() will +be accessed. + +If model is a QAbstractItemModel other than QAbstractTableModel, model's data() +will be accessed. + +Otherwise, the behavior is same as setting TableView::model. + +\sa TableView {TableView::model} {model} QAbstractTableModel +//! [model] + +//! [textRole] +This property holds the model role used to display text in each header cell. + +When the model has multiple roles, textRole can be set to determine which +role should be displayed. + +If model is a QAbstractItemModel then it will default to "display"; otherwise +it is empty. + +A warning is given if the model's \l {QAbstractItemModel::}{roleNames()} +doesn't provide the role specified in \l textRole. +The warning can be silenced by setting the \l textRole. + +\sa QAbstractItemModel::roleNames() +//! [textRole] + +//! [movableColumns] +This property allows the user to move columns in the view. The default value is +\c false. + +\note If this property is set, the HorizontalHeaderView allows the user to drag +and drop columns at the required position. When syncView is enabled, +any change will be applied to the corresponding view item. +//! [movableColumns] + +//! [movableRows] +This property allows the user to move rows in the view. The default value is \c +false. + +\note If this property is set, the VerticalHeaderView allows the user to drag +and drop rows at the required position. When syncView is enabled, +any change will be applied to the corresponding view item. +//! [movableRows] diff --git a/src/quickcontrols/doc/src/includes/qquickmaterialstyle.qdocinc b/src/quickcontrols/doc/src/includes/qquickmaterialstyle.qdocinc index 803425a88b..dc02dffe39 100644 --- a/src/quickcontrols/doc/src/includes/qquickmaterialstyle.qdocinc +++ b/src/quickcontrols/doc/src/includes/qquickmaterialstyle.qdocinc @@ -77,3 +77,8 @@ for example \c "Grey". \endtable //! [env] + +//! [placeholder-text-multiple-lines] +As per the Material guidelines, placeholder text should be kept short and not +take up multiple lines. +//! [placeholder-text-multiple-lines] diff --git a/src/quickcontrols/doc/src/includes/qquickmenu.qdocinc b/src/quickcontrols/doc/src/includes/qquickmenu.qdocinc new file mode 100644 index 0000000000..86a65338e5 --- /dev/null +++ b/src/quickcontrols/doc/src/includes/qquickmenu.qdocinc @@ -0,0 +1,4 @@ +//! [non-native-only-property] +\note This property is only supported when using a +\l {Native Menus}{non-native Menu}. +//! [non-native-only-property] diff --git a/src/quickcontrols/doc/src/includes/qquickstackview.qdocinc b/src/quickcontrols/doc/src/includes/qquickstackview.qdocinc index 20c9bdc369..16d4e7374c 100644 --- a/src/quickcontrols/doc/src/includes/qquickstackview.qdocinc +++ b/src/quickcontrols/doc/src/includes/qquickstackview.qdocinc @@ -3,3 +3,29 @@ 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] + +//! [operation-values] +An \a operation can be optionally specified as the last argument. Supported +operations: + +\value StackView.Immediate An immediate operation without transitions. +\value StackView.PushTransition An operation with push transitions. +\value StackView.ReplaceTransition An operation with replace transitions. +\value StackView.PopTransition An operation with pop transitions. +//! [operation-values] + +//! [optional-properties-after-each-item] +The optional properties arguments come after each item, and specify a +map of initial property values. For dynamically created items, these values +are applied before the creation is finalized. This is more efficient than +setting property values after creation, particularly where large sets of +property values are defined, and also allows property bindings to be set +up (using \l{Qt::binding}{Qt.binding()}) before the item is created. +//! [optional-properties-after-each-item] + +//! [replaceCurrentItem] +Pops \l currentItem from the stack and pushes \a \1. If the optional +\a operation is specified, the relevant transition will be used. If the +optional \a properties are specified, they will be applied to the item. +Returns the item that became current. +//! [replaceCurrentItem] diff --git a/src/quickcontrols/doc/src/includes/style-screenshots.qdocinc b/src/quickcontrols/doc/src/includes/style-screenshots.qdocinc new file mode 100644 index 0000000000..b7cd902937 --- /dev/null +++ b/src/quickcontrols/doc/src/includes/style-screenshots.qdocinc @@ -0,0 +1,9 @@ +//! [file] +\table + \row + \li \image qtquickcontrols-\2-light.png + \caption The light theme of the \1 style. + \li \image qtquickcontrols-\2-dark.png + \caption The dark theme of the \1 style. +\endtable +//! [file] diff --git a/src/quickcontrols/doc/src/qtquickcontrols-configuration.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-configuration.qdoc index 26fab0a2ce..7cc61b5701 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-configuration.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-configuration.qdoc @@ -80,17 +80,12 @@ \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: + in each style's section in the configuration file: \code [Basic] Font\Family=Open Sans Font\PixelSize=20 - - [Material\Font] - Family=Open Sans - PixelSize=20 \endcode Supported font attributes: @@ -137,13 +132,6 @@ 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 @@ -164,12 +152,39 @@ 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 + Finally, the \c .qrc file must be listed in the application's build file. + For example: + + \if defined(onlinedocs) + \tab {build-qt-app}{tab-cmake}{CMakeLists.txt (CMake)}{checked} + \tab {build-qt-app}{tab-qmake}{.pro (qmake)}{} + \tabcontent {tab-cmake} + \else + \section2 Using CMake + \endif + \badcode + set(CMAKE_AUTORCC ON) + qt_add_executable(my_app + application.qrc + main.cpp + ... + ) \endcode + \if defined(onlinedocs) + \endtabcontent + \tabcontent {tab-qmake} + \else + \section2 Using qmake + \endif + \badcode + RESOURCES = application.qrc + ... + \endcode + \if defined(onlinedocs) + \endtabcontent + \endif + + See also: \l {Build System Integration} \section1 Related Information diff --git a/src/quickcontrols/doc/src/qtquickcontrols-customize.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-customize.qdoc index 19a2619164..1f12b72822 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-customize.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-customize.qdoc @@ -183,27 +183,58 @@ \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: + Sometimes you may need to use C++ to extend your custom style. \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(): + \li If the style that uses the type is the only style used by an + application, register the type with the QML engine by adding the QML_ELEMENT + macro and making the file part of your QML module: + \br + \br + + \if defined(onlinedocs) + \tab {expose-cpp-to-qml}{tab-cmake}{CMake}{checked} + \tab {expose-cpp-to-qml}{tab-qmake}{qmake}{} + \tabcontent {tab-cmake} + \else + \section3 Using CMake + \endif + \badcode + qt_add_qml_module(ACoolItem + URI MyItems + VERSION 1.0 + SOURCES + acoolcppitem.cpp acoolcppitem.h + ) + \endcode + \if defined(onlinedocs) + \endtabcontent + \tabcontent {tab-qmake} + \else + \section3 Using QMake + \endif + \code + CONFIG += qmltypes + QML_IMPORT_NAME = MyItems + QML_IMPORT_MAJOR_VERSION = 1 + \endcode + + If the header the class is declared in is not accessible from your + project's include path, you may have to amend the include path so + that the generated registration code can be compiled. \code - qmlRegisterType<ACoolCppItem>("MyApp", 1, 0, "ACoolItem"); + INCLUDEPATH += MyItems \endcode + \if defined(onlinedocs) + \endtabcontent + \endif - See \l {Using C++ Data From QML} for more information about this. + See \l {Defining QML Types from C++} and \l {Building a QML application} + for more information. \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. + application, consider putting each style into a separate module. The + modules will then be loaded on demand. \endlist \section3 Considerations for custom styles @@ -433,9 +464,9 @@ Next, we add a drop shadow to the \l {Control::}{background} delegate of the Button: - \code + \qml // ... - import QtGraphicalEffects + import QtQuick.Effects import MyStyle // ... @@ -443,14 +474,15 @@ // ... 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 + layer.effect: MultiEffect { + shadowEnabled: true + shadowHorizontalOffset: 3 + shadowVerticalOffset: 3 + shadowColor: control.visualFocus ? "#330066ff" : "#aaaaaa" + shadowBlur: control.pressed ? 0.8 : 0.4 } } - \endcode + \endqml Note that we: @@ -525,7 +557,7 @@ \code import QtQuick - import QtQuick.Controls + import QtQuick.Controls.Basic ApplicationWindow { visible: true @@ -590,46 +622,21 @@ \snippet qtquickcontrols-combobox-custom.qml file As explained in \l {ComboBox Model Roles}, ComboBox supports multiple - types of models. If you know that your ComboBox instances will only - ever use one particular type of model, then it is possible to simplify - the code above. + types of models. - For example, if your models will only ever be derived from - \l QAbstractItemModel and have more than one role, the following - binding is sufficient: + Since \l {qml-data-models}{all the models provide an anonymous property} + with \c modelData, the following expression retrieves the right text in + all cases: \code text: model[control.textRole] \endcode - However, if you want to support all standard models, the more complex - binding is necessary, and is explained in detail below. - - \quotefromfile qtquickcontrols-combobox-custom.qml - \skipto control.textRole - \printto Array.isArray - - The first line checks if the \l {ComboBox::}{textRole} property has - been set. It is only necessary to set this property if the model - has more than one role. - - \printline Array.isArray - - If \c textRole has been set, the next step is to check if the model - is an array. - - If it is an array, the \c modelData context property will be available, - and so it must be used. Square bracket notation is used to access - the property of modelData since the property name is not known ahead - of time. - - If it is not an array, the \c model context property must be used - instead. - - \printline modelData - - Finally, if \c textRole has not been set, then the model only has one - role, and so it is sufficient to use the value of \c modelData. + When you provide a specific \c textRole and a model with structured + data that provides the selected role, this is expression is a regular + property lookup. When you provide a model with singular data, such as + a list of strings, and an empty \c textRole, this expression retrieves + the \c modelData. \section2 Customizing DelayButton @@ -721,7 +728,7 @@ \quotefromfile qtquickcontrols-menu-custom.qml \skipto import QtQuick - \printuntil import QtQuick.Controls + \printuntil import QtQuick.Controls.Basic \skipto Menu \printto eof @@ -736,7 +743,7 @@ \quotefromfile qtquickcontrols-menubar-custom.qml \skipto import QtQuick - \printuntil import QtQuick.Controls + \printuntil import QtQuick.Controls.Basic \skipto MenuBar \printto eof @@ -768,7 +775,7 @@ \quotefromfile qtquickcontrols-popup-custom.qml \skipto import QtQuick - \printuntil import QtQuick.Controls + \printuntil import QtQuick.Controls.Basic \codeline \skipto Popup \printuntil { @@ -786,6 +793,9 @@ \snippet qtquickcontrols-progressbar-custom.qml file + Above, the content item is also animated to represent an + \l {ProgressBar::}{indeterminate} progress bar state. + \section2 Customizing RadioButton @@ -1003,7 +1013,7 @@ \quotefromfile qtquickcontrols-tooltip-custom.qml \skipto import QtQuick - \printuntil import QtQuick.Controls + \printuntil import QtQuick.Controls.Basic \skipto ToolTip \printuntil } \printuntil } diff --git a/src/quickcontrols/doc/src/qtquickcontrols-examples.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-examples.qdoc index 8cd6e7f914..76812bcbbe 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-examples.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-examples.qdoc @@ -3,7 +3,6 @@ /*! \group qtquickcontrols-examples - \ingroup all-examples \keyword Qt Quick Controls Examples \title Qt Quick Controls Examples \keyword Qt Quick Controls 2 Examples diff --git a/src/quickcontrols/doc/src/qtquickcontrols-fileselectors.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-fileselectors.qdoc index 01c9b26bd2..a03970d1d8 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-fileselectors.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-fileselectors.qdoc @@ -8,7 +8,7 @@ \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. + (Capitalized) 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, @@ -77,7 +77,7 @@ \code // +Material/CustomButton.qml import QtQuick - import QtGraphicalEffects + import QtQuick.Effects import QtQuick.Controls import QtQuick.Controls.Material @@ -93,11 +93,12 @@ radius: width / 2 layer.enabled: control.enabled - layer.effect: DropShadow { - verticalOffset: 1 - color: Material.dropShadowColor - samples: control.pressed ? 20 : 10 - spread: 0.5 + layer.effect: MultiEffect { + shadowEnabled: true + shadowHorizontalOffset: 3 + shadowVerticalOffset: 3 + shadowColor: Material.dropShadowColor + shadowBlur: control.pressed ? 0.8 : 0.4 } } } diff --git a/src/quickcontrols/doc/src/qtquickcontrols-focus.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-focus.qdoc index c39773020f..f3c1d208bb 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-focus.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-focus.qdoc @@ -10,7 +10,7 @@ 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 + \l [QML] {Item::}{focusPolicy} property can be used to control the ways in which a control receives focus. \section1 Focus Scope Controls diff --git a/src/quickcontrols/doc/src/qtquickcontrols-fusion.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-fusion.qdoc index d3c4199e7d..a2db843039 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-fusion.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-fusion.qdoc @@ -11,7 +11,11 @@ look and feel. It implements the same design language as the \l {Qt Widget Gallery}{Fusion style for Qt Widgets}. - \image qtquickcontrols-fusion.png + The Fusion style automatically switches dark and light themes according to + the system settings. For information on how to set custom theme colors, + refer to the \l {customize-fusion-style}{Customization} section. + + \include style-screenshots.qdocinc {file} {Fusion} {fusion} To run an application with the Fusion style, see \l {Using Styles in Qt Quick Controls}. @@ -22,17 +26,18 @@ rendering engines. \section2 Customization + \target customize-fusion-style The Fusion style uses the standard system \l[QtQuick]{Palette} to provide colors that match the desktop environment. \image qtquickcontrols-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: + You can specify custom palettes 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 diff --git a/src/quickcontrols/doc/src/qtquickcontrols-imagine.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-imagine.qdoc index 2e476c3b24..0f48f3f6a4 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-imagine.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-imagine.qdoc @@ -129,7 +129,7 @@ \li .9.png (or .png) \row \li \l Dial - \li background + \li background\sup{1} \li disabled, pressed, focused, mirrored, hovered \li .9.png (or .png) \row @@ -469,6 +469,10 @@ \li .9.png (or .png) \endtable + \note \sup{1}) The Imagine style Dial does not yet support the + \l {Dial::}{startAngle} and \l {Dial::}{endAngle} properties that were + introduced in Qt 6.6, and instead uses a fixed background image. + \section2 Asset Examples The following table lists examples of assets (taken from the @@ -2489,7 +2493,7 @@ \section1 Attached Property Documentation - \styleproperty {Imagine.path} {string} {imagine-path-attached-prop} + \styleproperty {Imagine.path} {string} \target imagine-path-attached-prop This attached property holds the path to the image assets... @@ -2506,6 +2510,5 @@ \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/quickcontrols/doc/src/qtquickcontrols-index.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-index.qdoc index ae16f75078..b3e49e7309 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-index.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-index.qdoc @@ -105,6 +105,31 @@ \li ... \endtable + \section2 Revisions + + Due to how Qt Quick Controls are implemented, new properties that are added + may clash with any user-defined properties of the same name. For example, + the following snippet will result in an error: + + \qml + import QtQuick.Controls 2.13 + + ApplicationWindow { + // ... + + ComboBox { + anchors.centerIn: parent + + // As currentValue was added in 2.14, the versioned import above + // should cause this property to be used, but instead an error is produced: + // "Cannot override FINAL property" + property int currentValue: 0 + } + } + \endqml + + These properties should be renamed to avoid the conflict. + \section1 Module Evolution Qt Quick Controls was originally written with touch interfaces as the @@ -138,7 +163,6 @@ \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 diff --git a/src/quickcontrols/doc/src/qtquickcontrols-ios.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-ios.qdoc index 2c90552d20..9e107eecd2 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-ios.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-ios.qdoc @@ -10,12 +10,6 @@ \styleimport {QtQuick.Controls.iOS} {Qt 6.4} - \section1 Attached Properties - - \list - \li \l {ios-theme-attached-prop}{\b theme} : enumeration - \endlist - \section1 Detailed Description \target detailed-desc-iOS @@ -32,22 +26,15 @@ and iOS and should look the same on both platforms, besides minor differences that may occur due to differences in available system fonts and font rendering engines. - \table - \row - \li \image qtquickcontrols-ios-light.png - \caption The iOS style in light theme - \li \image qtquickcontrols-ios-dark.png - \caption The iOS style in dark theme - \endtable + \include style-screenshots.qdocinc {file} {iOS} {ios} To run an application with the iOS style, see \l {Using Styles in Qt Quick Controls}. \section2 Current state - The iOS style is currently in Tech Preview and is under development. Some controls are not - yet supported. Those controls are: \l BusyIndicator, \l DelayButton, \l Dialog, \l DialogButtonBox, - \l SelectionRectangle and \l Tumbler. Those will fall back to use the \l {Basic Style}. + The \l Tumbler control is not yet implemented for the iOS style and will fall back + to use the \l {Basic Style}. \section2 Customization diff --git a/src/quickcontrols/doc/src/qtquickcontrols-macos.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-macos.qdoc index 97d79c6278..c024b7fb82 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-macos.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-macos.qdoc @@ -18,13 +18,7 @@ \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 qtquickcontrols-macos-light.png - \caption The macOS style in light theme - \li \image qtquickcontrols-macos-dark.png - \caption The macOS style in dark theme - \endtable + \include style-screenshots.qdocinc {file} {macOS} {macos} To run an application with the macOS style, see \l {Using Styles in Qt Quick Controls}. diff --git a/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc index 450cbb151c..4052337ef8 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-material.qdoc @@ -32,17 +32,11 @@ \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} + The Material style is based on the \l {https://m3.material.io} {Google Material Design Guidelines}. It allows for a unified experience across platforms and device sizes. - \table - \row - \li \image qtquickcontrols-material-light.png - \caption The Material style in light theme - \li \image qtquickcontrols-material-dark.png - \caption The Material style in dark theme - \endtable + \include style-screenshots.qdocinc {file} {Material} {material} To run an application with the Material style, see \l {Using Styles in Qt Quick Controls}. @@ -54,26 +48,43 @@ may occur due to differences in available system fonts and font rendering engines. + \note As the Material Design Guidelines change over time, this style may + change certain padding or font values, for example, in order to maintain + consistency with the guidelines. + \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}. + The Material style supports several customizable attributes. Some of these + attributes \l {QQuickAttachedPropertyPropagator}{propagate} to children in + the same manner as \l {Control::font}{fonts}: + + \list + \li \l {material-theme-attached-prop}{theme} + \li \l {material-primary-attached-prop}{primary} + \li \l {material-accent-attached-prop}{accent} + \li \l {material-foreground-attached-prop}{foreground} + \li \l {material-background-attached-prop}{background} + \endlist \image qtquickcontrols-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: + The remaining attributes do not propagate to children: + \list + \li \l {material-elevation-attached-prop}{elevation} + \li \l {material-roundedScale-attached-prop}{roundedScale} + \li \l {material-containerStyle-attached-prop}{containerStyle} + \endlist + + 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 + import QtQuick + import QtQuick.Controls + import QtQuick.Controls.Material ApplicationWindow { visible: true @@ -84,9 +95,16 @@ Column { anchors.centerIn: parent - RadioButton { text: qsTr("Small") } - RadioButton { text: qsTr("Medium"); checked: true } - RadioButton { text: qsTr("Large") } + RadioButton { + text: qsTr("Small") + } + RadioButton { + text: qsTr("Medium") + checked: true + } + RadioButton { + text: qsTr("Large") + } } } \endqml @@ -95,8 +113,8 @@ \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. + specify some of them via environment variables or in a configuration file. + Attributes specified in QML take precedence over all other methods. \section3 Configuration File @@ -227,9 +245,34 @@ Note that the heights shown above may vary based on differences in fonts across platforms. + \section2 Control-Specific Notes + + \target material-control-specific-notes-textarea + \section3 TextArea + + TextArea supports two + \l {material-containerStyle-attached-prop}{containerStyles}: \c Filled and + \c Outlined. Outlined TextAreas have floating placeholder text that sits at + the top of the control. This requires the placeholder text to go outside + the bounds of the control, which can cause it to be + clipped when the TextArea or the Flickable it's a child of sets + \l {Item::}{clip} to \c true. To avoid this, \l {Control::}{topInset} is + set to an appropriate value in these cases. + + \include qquickmaterialstyle.qdocinc placeholder-text-multiple-lines + + \section3 TextField + + The same \l {material-control-specific-notes-textarea}{issue with clipping} + explained above for TextArea can also occur with \l TextField. To avoid + this, \l {Control::}{topInset} is set to an appropriate value when the + TextField sets clip to \c true. + + \include qquickmaterialstyle.qdocinc placeholder-text-multiple-lines + \section1 Attached Property Documentation - \styleproperty {Material.accent} {color} {material-accent-attached-prop} + \styleproperty {Material.accent} {color} \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. @@ -253,7 +296,7 @@ \endstyleproperty - \styleproperty {Material.background} {color} {material-background-attached-prop} + \styleproperty {Material.background} {color} \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. @@ -273,17 +316,18 @@ \endstyleproperty - \styleproperty {Material.elevation} {int} {material-elevation-attached-prop} + \styleproperty {Material.elevation} {int} \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. + but not all controls visualize elevation. The value is not propagated to + children. 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}: + \l {https://m3.material.io/components/cards/overview}{elevated card}: \table \row @@ -295,7 +339,7 @@ \endstyleproperty - \styleproperty {Material.foreground} {color} {material-foreground-attached-prop} + \styleproperty {Material.foreground} {color} \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. @@ -315,7 +359,7 @@ \endstyleproperty - \styleproperty {Material.primary} {color} {material-primary-attached-prop} + \styleproperty {Material.primary} {color} \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. @@ -330,7 +374,7 @@ \endstyleproperty - \styleproperty {Material.theme} {enumeration} {material-theme-attached-prop} + \styleproperty {Material.theme} {enumeration} \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. @@ -357,11 +401,12 @@ \endstyleproperty - \styleproperty {Material.roundedScale} {enumeration} {material-roundedScale-attached-prop} + \styleproperty {Material.roundedScale} {enumeration} \target material-roundedScale-attached-prop This attached property holds the radius of rounded corners used on the target control. The property can be attached to any window or item, but - only some controls support it. + only some controls support it. The value is not propagated to + children. The default value is control-specific. @@ -380,17 +425,18 @@ \endstyleproperty - \styleproperty {Material.containerStyle} {enumeration} {material-containerStyle-attached-prop} + \styleproperty {Material.containerStyle} {enumeration} \target material-containerStyle-attached-prop This attached property holds the style of the container used by the target control. The property can be attached to any window or item, but - only TextField and TextArea support it by default. + only TextField and TextArea support it by default. The value is not + propagated to children. The default value is control-specific. - Available scales: - \value Material.Filled Square corners - \value Material.Outlined Extra small rounded corners + Available styles: + \value Material.Filled Use the filled container variant if available + \value Material.Outlined Use the outlined container variant if available This property was added in Qt 6.5. @@ -400,7 +446,7 @@ \section1 Attached Method Documentation - \stylemethod2 {color} {color} {enumeration} {predefined} {enumeration} {shade} {material-color-attached-method} + \stylemethod2 {color} {color} {enumeration} {predefined} {enumeration} {shade} \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 diff --git a/src/quickcontrols/doc/src/qtquickcontrols-styles.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-styles.qdoc index 351732c9a3..38174ab09a 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-styles.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-styles.qdoc @@ -11,38 +11,44 @@ \section2 Basic Style - \image qtquickcontrols-basic-thumbnail.png + \image qtquickcontrols-basic.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 qtquickcontrols-fusion-thumbnail.png + \include style-screenshots.qdocinc {file} {Fusion} {fusion} + 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 qtquickcontrols-imagine-thumbnail.png + \image qtquickcontrols-imagine.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 qtquickcontrols-macos-thumbnail.png + \include style-screenshots.qdocinc {file} {macOS} {macos} + The \l {macOS Style} is a native-looking style for macOS. \note this style is only available for applications running on macOS. - \section2 iOS Style + \include style-screenshots.qdocinc {file} {iOS} {ios} + The \l {iOS Style} is a native-looking style for iOS based on image assets. \note this style is only available for applications running on iOS. \section2 Material Style - \image qtquickcontrols-material-thumbnail.png + \include style-screenshots.qdocinc {file} {Material} {material} + 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 @@ -50,14 +56,16 @@ \section2 Universal Style - \image qtquickcontrols-universal-thumbnail.png + \include style-screenshots.qdocinc {file} {Universal} {universal} + 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 qtquickcontrols-windows-thumbnail.png + \image qtquickcontrols-windows.png + The \l {Windows Style} is a native-looking style for Windows. \note this style is only available for applications running on Windows. @@ -101,12 +109,19 @@ 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. + The benefit of compile-time style selection is that the + \l {The QML script compiler}{QML compiler} knows which specific style + is in use and can generate C++ code for bindings. + + Another benefit 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}. + A disadvantage of compile-time style selection is that one executable + cannot support multiple styles, as each style requires its own. + \section2 Run-Time Style Selection Run-time style selection is a way of specifying a style to use by importing @@ -116,24 +131,44 @@ 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: + The QtQuick.Controls plugin will import the style that was 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 + \li The \l {Supported Environment Variables in Qt Quick Controls} + {QT_QUICK_CONTROLS_STYLE environment variable} + \li The \l {Qt Quick Controls Configuration File}{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. + Similarly, the fallback style can be set via one of the following methods: + \list + \li \l[CPP]{QQuickStyle::setFallbackStyle()} + \li The \l {Supported Environment Variables in Qt Quick Controls} + {QT_QUICK_CONTROLS_FALLBACK_STYLE environment variable} + \li The \l {Qt Quick Controls Configuration File}{qtquickcontrols2.conf + configuration file} + \endlist + + \note you can only dynamically choose the fallback style if it hasn't been + chosen statically in the main style's qmldir file. + 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. + A disadvantage of this approach is that \l {The QML script compiler} + {QML compiler} can't know which specific style is in use and therefore + cannot generate C++ code for bindings on properties of Qt Quick Controls + types. This does not affect the QML compiler's abilities to generate C++ + for bindings on types from other modules. + \section3 Using QQuickStyle in C++ \l[CPP]{QQuickStyle} provides C++ API for configuring a specific diff --git a/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc index 4c8db816d7..eba367061f 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-universal.qdoc @@ -33,13 +33,7 @@ The Universal style has been designed to look good on all devices, from phones and tablets to PCs. - \table - \row - \li \image qtquickcontrols-universal-light.png - \caption The Universal style in light theme - \li \image qtquickcontrols-universal-dark.png - \caption The Universal style in dark theme - \endtable + \include style-screenshots.qdocinc {file} {Universal} {universal} To run an application with the Universal style, see \l {Using Styles in Qt Quick Controls}. @@ -152,7 +146,7 @@ \section1 Attached Property Documentation - \styleproperty {Universal.accent} {color} {universal-accent-attached-prop} + \styleproperty {Universal.accent} {color} \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. @@ -176,7 +170,7 @@ \endstyleproperty - \styleproperty {Universal.background} {color} {universal-background-attached-prop} + \styleproperty {Universal.background} {color} \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. @@ -196,7 +190,7 @@ \endstyleproperty - \styleproperty {Universal.foreground} {color} {universal-foreground-attached-prop} + \styleproperty {Universal.foreground} {color} \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. @@ -214,7 +208,7 @@ \image qtquickcontrols-universal-foreground.png \endtable - \styleproperty {Universal.theme} {enumeration} {universal-theme-attached-prop} + \styleproperty {Universal.theme} {enumeration} \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. @@ -243,7 +237,7 @@ \section1 Attached Method Documentation - \stylemethod {color} {color} {enumeration} {predefined} {color-attached-method} + \stylemethod {color} {color} {enumeration} {predefined} \target color-attached-method This attached method returns the effective color value of the specified \l {pre-defined Universal colors}{pre-defined Universal color}. diff --git a/src/quickcontrols/doc/src/qtquickcontrols-windows.qdoc b/src/quickcontrols/doc/src/qtquickcontrols-windows.qdoc index fee2ffa98f..dd14b45f90 100644 --- a/src/quickcontrols/doc/src/qtquickcontrols-windows.qdoc +++ b/src/quickcontrols/doc/src/qtquickcontrols-windows.qdoc @@ -29,9 +29,9 @@ \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}. + The Windows style is under development, and some controls are not yet supported. Those controls + are: \l BusyIndicator, \l DelayButton, \l Menu, \l MenuBar, \l PageIndicator, \l RangeSlider, + \l Switch, \l TabBar and \l Tumbler. Those will fall back to use the \l {Fusion Style}. \section2 Customization |