From 3b4f4a5d4f70f35e256260cc4b5d6cae9c0dad66 Mon Sep 17 00:00:00 2001 From: Richard Moe Gustavsen Date: Thu, 22 Apr 2021 16:24:01 +0200 Subject: doc: document the native styles This patch will add documentation for the native styles that was added to Qt 6.0. Fixes: QTBUG-88220 Change-Id: Ib0703b3758d48586cd8465ea9188691b9e377064 Reviewed-by: Mitch Curtis (cherry picked from commit 30cf78d48f6a3778e8b4ec2e2b8924b25fdc85cc) Reviewed-by: Qt Cherry-pick Bot --- .../doc/images/qtquickcontrols2-macos-dark.png | Bin 0 -> 23979 bytes .../doc/images/qtquickcontrols2-macos-light.png | Bin 0 -> 22318 bytes .../images/qtquickcontrols2-macos-thumbnail.png | Bin 0 -> 22504 bytes .../images/qtquickcontrols2-windows-thumbnail.png | Bin 0 -> 12394 bytes .../doc/images/qtquickcontrols2-windows.png | Bin 0 -> 17132 bytes .../controls/doc/src/qtquickcontrols2-macos.qdoc | 76 +++++++++++++++++++++ .../controls/doc/src/qtquickcontrols2-styles.qdoc | 12 ++++ .../controls/doc/src/qtquickcontrols2-windows.qdoc | 74 ++++++++++++++++++++ 8 files changed, 162 insertions(+) create mode 100644 src/imports/controls/doc/images/qtquickcontrols2-macos-dark.png create mode 100644 src/imports/controls/doc/images/qtquickcontrols2-macos-light.png create mode 100644 src/imports/controls/doc/images/qtquickcontrols2-macos-thumbnail.png create mode 100644 src/imports/controls/doc/images/qtquickcontrols2-windows-thumbnail.png create mode 100644 src/imports/controls/doc/images/qtquickcontrols2-windows.png create mode 100644 src/imports/controls/doc/src/qtquickcontrols2-macos.qdoc create mode 100644 src/imports/controls/doc/src/qtquickcontrols2-windows.qdoc diff --git a/src/imports/controls/doc/images/qtquickcontrols2-macos-dark.png b/src/imports/controls/doc/images/qtquickcontrols2-macos-dark.png new file mode 100644 index 00000000..97d8a5a4 Binary files /dev/null and b/src/imports/controls/doc/images/qtquickcontrols2-macos-dark.png differ diff --git a/src/imports/controls/doc/images/qtquickcontrols2-macos-light.png b/src/imports/controls/doc/images/qtquickcontrols2-macos-light.png new file mode 100644 index 00000000..4a598ad4 Binary files /dev/null and b/src/imports/controls/doc/images/qtquickcontrols2-macos-light.png differ diff --git a/src/imports/controls/doc/images/qtquickcontrols2-macos-thumbnail.png b/src/imports/controls/doc/images/qtquickcontrols2-macos-thumbnail.png new file mode 100644 index 00000000..57fd98d6 Binary files /dev/null and b/src/imports/controls/doc/images/qtquickcontrols2-macos-thumbnail.png differ diff --git a/src/imports/controls/doc/images/qtquickcontrols2-windows-thumbnail.png b/src/imports/controls/doc/images/qtquickcontrols2-windows-thumbnail.png new file mode 100644 index 00000000..15408d3b Binary files /dev/null and b/src/imports/controls/doc/images/qtquickcontrols2-windows-thumbnail.png differ diff --git a/src/imports/controls/doc/images/qtquickcontrols2-windows.png b/src/imports/controls/doc/images/qtquickcontrols2-windows.png new file mode 100644 index 00000000..324a0341 Binary files /dev/null and b/src/imports/controls/doc/images/qtquickcontrols2-windows.png differ diff --git a/src/imports/controls/doc/src/qtquickcontrols2-macos.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-macos.qdoc new file mode 100644 index 00000000..382a23a6 --- /dev/null +++ b/src/imports/controls/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/imports/controls/doc/src/qtquickcontrols2-styles.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc index cf4c09dc..12993fbf 100644 --- a/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc +++ b/src/imports/controls/doc/src/qtquickcontrols2-styles.qdoc @@ -52,6 +52,12 @@ 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 @@ -67,6 +73,12 @@ \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: diff --git a/src/imports/controls/doc/src/qtquickcontrols2-windows.qdoc b/src/imports/controls/doc/src/qtquickcontrols2-windows.qdoc new file mode 100644 index 00000000..8b63703b --- /dev/null +++ b/src/imports/controls/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} +*/ -- cgit v1.2.3