doc: Clarify that automatic transient parent relies on visual parent

As part of 16023fc77c423a267fcc48894ff942e94cf35b86, the behavior
of declaratively and imperatively setting the visible property of
a window was made consistent, which is an important property of
QML.

Both methods now respect the presence of an Item or Window parent
for the Window, and resolve a possible transient parent from the
parent Item or Window. The transient parent magic behavior is
active as long as the transientParent property is not set by
the user explicitly.

Seeing as transient child windows should not be shown before their
transient parent windows, this means that as long as we can possibly
have a transient parent, we don't show the window.

And since an Item may not initially be part of a scene, it may not
have an initial window, and we have to wait to show the child window.

What this means is that an Item parent hierarchy of a Window needs
to be in a scene, so that the direct Item parent of a Window gets
a window, which we can then use to determine whether to show the
transient child window or not.

This matches the behavior of an Item added as a property to another
item. It will not be rendered until it's included in the scene by
setting the visual parent of the item to some item that's in the
scene.

[ChangeLog][QtQuick][Window] Windows that automatically pick up
a transient parent window from its Item parent will not be shown
unless the item is part of a scene.

Fixes: QTBUG-121197
Change-Id: Iae050cd5f0a4e11ef9c397494dac9bbac8d00cdd
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
(cherry picked from commit 6db942a87db172f6d707afa0bfaf1278cb5db965)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 11 insertions, 7 deletions

diff --git a/src/quick/items/qquickwindow.cpp b/src/quick/items/qquickwindow.cpp
index 0ee809e7f4..591b666236 100644
--- a/src/quick/items/qquickwindow.cpp
+++ b/src/quick/items/qquickwindow.cpp
@@ -3642,17 +3642,21 @@ void QQuickWindow::endExternalCommands()
     shown, that minimizing the parent window will also minimize the transient
     window, and so on; however results vary somewhat from platform to platform.
 
-    Declaring a Window inside an Item or inside another Window, either via the
+    Declaring a Window inside an Item or another Window, either via the
     \l{Window::data}{default property} or a dedicated property, will automatically
-    set up a transient parent relationship to the containing Item or Window,
+    set up a transient parent relationship to the containing window,
     unless the \l transientParent property is explicitly set. This applies
     when creating Window items via \l [QML] {QtQml::Qt::createComponent()}
     {Qt.createComponent} or \l [QML] {QtQml::Qt::createQmlObject()}
-    {Qt.createQmlObject} as well, if an Item or Window is passed as the
-    \c parent argument.
+    {Qt.createQmlObject} as well, as long as an Item or Window is passed
+    as the \c parent argument.
 
     A Window with a transient parent will not be shown until its transient
-    parent is shown, even if the \l visible property is \c true. Setting
+    parent is shown, even if the \l visible property is \c true. This also
+    applies for the automatic transient parent relationship described above.
+    In particular, if the Window's containing element is an Item, the window
+    will not be shown until the containing item is added to a scene, via its
+    \l{Concepts - Visual Parent in Qt Quick}{visual parent hierarchy}. Setting
     the \l transientParent to \c null will override this behavior:
 
     \snippet qml/nestedWindowTransientParent.qml 0
diff --git a/src/quick/items/qquickwindowmodule.cpp b/src/quick/items/qquickwindowmodule.cpp
index 585b1043ac..5c22585bf4 100644
--- a/src/quick/items/qquickwindowmodule.cpp
+++ b/src/quick/items/qquickwindowmodule.cpp
@@ -210,8 +210,8 @@ void QQuickWindowQmlImpl::applyWindowVisibility()
             // Handle deferred visibility due to possible transient parent
             auto *itemParent = qmlobject_cast<QQuickItem *>(QObject::parent());
             if (!d->transientParentPropertySet && itemParent && !itemParent->window()) {
-                qCDebug(lcTransient) << "Waiting for parent Item to resolve"
-                                        "its transient parent. Deferring visibility";
+                qCDebug(lcTransient) << "Waiting for parent" << itemParent << "to resolve"
+                                     << "its window. Deferring visibility";
                 return;
             }