Doc: explain popup property propagation

It's not obvious that parent popups do not propagate properties to
their children, but is intended.

Task-number: QTBUG-115322
Task-number: QTBUG-115554
Change-Id: I21b99ee6ea0f2f62bfd4a82e57bd653e823e59d0
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>
(cherry picked from commit e4ba076e43)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

src/quickcontrols/doc/snippets/qtquickcontrols-popup-property-propagation.qml

@@ -0,0 +1,59 @@
+// Copyright (C) 2023 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+//! [file]
+import QtQuick.Controls.Basic
+
+ApplicationWindow {
+    width: 500
+    height: 500
+    visible: true
+    font.pixelSize: 20
+    palette.windowText: "steelblue"
+
+    // This will have a pixelSize of 20 and be "steelblue" in color.
+    header: Label {
+        text: "ApplicationWindow Label"
+        leftPadding: 20
+        topPadding: 20
+    }
+
+    Pane {
+        width: 400
+        height: 400
+        anchors.centerIn: parent
+        palette.window: "#edf3f8"
+        palette.windowText: "tomato"
+
+        // This will have a pixelSize of 20 and be "tomato" in color.
+        Label {
+            text: "Pane Label"
+        }
+
+        Popup {
+            width: 300
+            height: 300
+            anchors.centerIn: parent
+            font.pixelSize: 10
+            visible: true
+
+            // This will have a pixelSize of 10 and "steelblue" in color.
+            Label {
+                text: "Popup Label"
+            }
+
+            Popup {
+                width: 200
+                height: 200
+                anchors.centerIn: parent
+                visible: true
+
+                // This will have a pixelSize of 20 and be "steelblue" in color.
+                Label {
+                    text: "Child Popup Label"
+                }
+            }
+        }
+    }
+}
+//! [file]

src/quicktemplates/qquickpopup.cpp

@@ -251,6 +251,50 @@ Q_LOGGING_CATEGORY(lcPopup, "qt.quick.controls.popup")
     \endlist
 
     \sa {Popup Controls}, {Customizing Popup}, ApplicationWindow
+
+    \section1 Property Propagation
+
+    Popup inherits fonts, palettes and attached properties through its parent
+    window, not its \l {Visual Parent}{object or visual parent}:
+
+    \snippet qtquickcontrols-popup-property-propagation.qml file
+
+    \image qtquickcontrols-basic-popup-property-propagation.png
+
+    In addition, popups do not propagate their properties to child popups. This
+    behavior is modelled on Qt Widgets, where a \c Qt::Popup widget is a
+    top-level window. Top-level windows do not propagate their properties to
+    child windows.
+
+    Certain derived types like ComboBox are typically implemented in such a way
+    that the popup is considered an integral part of the control, and as such,
+    may inherit things like attached properties. For example, in the
+    \l {Material Style}{Material style} ComboBox, the theme and other attached
+    properties are explicitly inherited by the Popup from the ComboBox itself:
+
+    \code
+    popup: T.Popup {
+        // ...
+
+        Material.theme: control.Material.theme
+        Material.accent: control.Material.accent
+        Material.primary: control.Material.primary
+    }
+    \endcode
+
+    So, to ensure that a child popup has the same property values as its parent
+    popup, explicitly set those properties:
+
+    \code
+    Popup {
+        id: parentPopup
+        // ...
+
+        Popup {
+            palette: parentPopup.palette
+        }
+    }
+    \endcode
 */
 
 /*!