doc: Clarify usage of palette; testable snippets

- color groups are better shown with copyable monospace syntax rather
  than capitalized
- clarify that using palette grouped-property syntax does not imply
  that you must define every color
- Window has a palette property, inited from SystemPalette: it's
  not only ApplicationWindow
- testable snippets
- reuse part of the windowPalette snippet for the Window.active
  property (switching colors might be the main use case)
- make more links

Pick-to: 6.2 6.5
Change-Id: I5974351ba66fc9aeec34cb6a4aba1eb85289f536
Reviewed-by: Oliver Eftevaag <oliver.eftevaag@qt.io>

5 files changed, 98 insertions, 17 deletions

diff --git a/src/quick/doc/snippets/qml/windowPalette.qml b/src/quick/doc/snippets/qml/windowPalette.qml
new file mode 100644
index 0000000000..0638213c57
--- /dev/null
+++ b/src/quick/doc/snippets/qml/windowPalette.qml
@@ -0,0 +1,38 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+//![entire]
+import QtQuick
+import QtQuick.Controls
+
+//![declaration-and-color]
+Window {
+    visible: true
+
+    // here we use the Window.active and Window.palette ordinary properties
+    color: active ? palette.active.window : palette.inactive.window
+//![declaration-and-color]
+
+    // colors that are not customized here come from SystemPalette
+    palette.active.window: "peachpuff"
+    palette.windowText: "brown"
+
+    Text {
+        anchors.centerIn: parent
+        // here we use the Window.active attached property and the Item.palette property
+        color: Window.active ? palette.active.windowText : palette.inactive.windowText
+        text: Window.active ? "active" : "inactive"
+    }
+
+    Button {
+        text: "Button"
+        anchors {
+            bottom: parent.bottom
+            bottomMargin: 6
+            horizontalCenter: parent.horizontalCenter
+        }
+    }
+//![closing-brace]
+}
+//![closing-brace]
+//![entire]
diff --git a/src/quick/items/qquickpalette.cpp b/src/quick/items/qquickpalette.cpp
index c0973a43ad..463dd8a926 100644
--- a/src/quick/items/qquickpalette.cpp
+++ b/src/quick/items/qquickpalette.cpp
@@ -50,8 +50,8 @@ static constexpr bool is_valid(QPalette::ColorGroup cg) noexcept
     \ingroup qtquick-visual
     \brief Contains color groups for each QML item state.
 
-    A palette consists of three color groups: Active, Disabled, and Inactive.
-    Active color group is the default group, its colors are used for other groups
+    A palette consists of three color groups: \c active, \c disabled, and \c inactive.
+    The \c active color group is the default group: its colors are used for other groups
     if colors of these groups aren't explicitly specified.
 
     In the following example, color is applied for all color groups:
@@ -93,18 +93,14 @@ static constexpr bool is_valid(QPalette::ColorGroup cg) noexcept
     \endcode
 
     It is also possible to specify colors like this:
-    \code
-    palette {
-        buttonText: "azure"
-        button: "khaki"
 
-        disabled {
-            buttonText: "lavender"
-            button: "coral"
-        }
-    }
-    \endcode
-    This approach is convenient when you need to specify a whole palette with all color groups.
+    \snippet qtquickcontrols-custom-palette-buttons.qml palette
+
+    This approach is especially convenient when you need to specify a whole
+    palette with all color groups; but as with the other cases above, the
+    colors that are not specified are intialized from SystemPalette.
+
+    \sa Window::palette, Item::palette, Popup::palette, SystemPalette
 */
 
 /*!
diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index 54e73abc91..6a0c405be3 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -3552,6 +3552,9 @@ void QQuickWindow::endExternalCommands()
 
     The active status of the window.
 
+    \snippet qml/windowPalette.qml declaration-and-color
+    \snippet qml/windowPalette.qml closing-brace
+
     \sa requestActivate()
  */
 
@@ -4190,10 +4193,11 @@ void QQuickWindow::setTextRenderType(QQuickWindow::TextRenderType renderType)
     palette which serves as a default for all application windows. You can also set the default palette
     for windows by passing a custom palette to QGuiApplication::setPalette(), before loading any QML.
 
-    ApplicationWindow propagates explicit palette properties to child controls. If you change a specific
-    property on the window's palette, that property propagates to all child controls in the window,
+    Window propagates explicit palette properties to child items and controls,
     overriding any system defaults for that property.
 
+    \snippet qml/windowPalette.qml entire
+
     \sa Item::palette, Popup::palette, ColorGroup, SystemPalette
     //! internal \sa QQuickAbstractPaletteProvider, QQuickPalette
 */
diff --git a/src/quick/util/qquicksystempalette.cpp b/src/quick/util/qquicksystempalette.cpp
index 9874d8c7d6..00d62f3fdb 100644
--- a/src/quick/util/qquicksystempalette.cpp
+++ b/src/quick/util/qquicksystempalette.cpp
@@ -27,8 +27,8 @@ public:
     The SystemPalette type provides access to the Qt application
     palettes. This provides information about the standard colors used
     for application windows, buttons and other features. These colors
-    are grouped into three \e {color groups}: \c Active, \c Inactive,
-    and \c Disabled.  See the QPalette documentation for details about
+    are grouped into three \e {color groups}: \c active, \c inactive,
+    and \c disabled.  See the QPalette documentation for details about
     color groups and the properties provided by SystemPalette.
 
     This can be used to color items in a way that provides a more
diff --git a/src/quickcontrols/doc/snippets/qtquickcontrols-custom-palette-buttons.qml b/src/quickcontrols/doc/snippets/qtquickcontrols-custom-palette-buttons.qml
new file mode 100644
index 0000000000..3b72207d87
--- /dev/null
+++ b/src/quickcontrols/doc/snippets/qtquickcontrols-custom-palette-buttons.qml
@@ -0,0 +1,43 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+//![entire]
+import QtQuick
+import QtQuick.Controls
+import QtQuick.Layouts
+
+ApplicationWindow {
+    visible: true
+
+    //![palette]
+    palette {
+        buttonText: "red"
+        button: "khaki"
+
+        disabled {
+            buttonText: "lavender"
+            button: "coral"
+        }
+    }
+    //![palette]
+
+    ColumnLayout {
+        id: layout
+        anchors.fill: parent
+        anchors.margins: 3
+        Button {
+            text: qsTr("Disabled button")
+            enabled: false
+        }
+
+        Button {
+            text: qsTr("Enabled button")
+        }
+
+        TextField {
+            Layout.fillWidth: true
+            placeholderText: "type something here"
+        }
+    }
+}
+//![entire]