Doc: add an "Item Ownership" section toStackView's documentation

It's important that users know the circumstances under which the items
managed by StackView will be destroyed.

Task-number: QTBUG-66658
Change-Id: I26e287b3dfed44e441125080443bdae4ee1814b7
Reviewed-by: J-P Nurmi <jpnurmi@qt.io>

2 files changed, 62 insertions, 1 deletions

diff --git a/src/imports/controls/doc/src/includes/qquickstackview.qdocinc b/src/imports/controls/doc/src/includes/qquickstackview.qdocinc
new file mode 100644
index 00000000..20c9bdc3
--- /dev/null
+++ b/src/imports/controls/doc/src/includes/qquickstackview.qdocinc
@@ -0,0 +1,5 @@
+//! [pop-ownership]
+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]
diff --git a/src/quicktemplates2/qquickstackview.cpp b/src/quicktemplates2/qquickstackview.cpp
index 2aa41c0d..090a6d74 100644
--- a/src/quicktemplates2/qquickstackview.cpp
+++ b/src/quicktemplates2/qquickstackview.cpp
@@ -295,6 +295,53 @@ QT_BEGIN_NAMESPACE
           only applies to the root of the item. Using anchors for its children
           works as expected.
 
+    \section1 Item Ownership
+
+    StackView only takes ownership of items that it creates itself. This means
+    that any item pushed onto a StackView will never be destroyed by the
+    StackView; only items that StackView creates from \l {Component}{Components}
+    or \l [QML] {url}{URLs} are destroyed by the StackView. To illustrate this,
+    the messages in the example below will only be printed when the StackView
+    is destroyed, not when the items are popped off the stack:
+
+    \qml
+    Component {
+        id: itemComponent
+
+        Item {
+            Component.onDestruction: print("Destroying second item")
+        }
+    }
+
+    StackView {
+        initialItem: Item {
+            Component.onDestruction: print("Destroying initial item")
+        }
+
+        Component.onCompleted: push(itemComponent.createObject(window))
+    }
+    \endqml
+
+    However, both of the items created from the URL and Component in the
+    following example will be destroyed by the StackView when they are popped
+    off of it:
+
+    \qml
+    Component {
+        id: itemComponent
+
+        Item {
+            Component.onDestruction: print("Destroying second item")
+        }
+    }
+
+    StackView {
+        initialItem: "Item1.qml"
+
+        Component.onCompleted: push(itemComponent)
+    }
+    \endqml
+
     \sa {Customizing StackView}, {Navigation Controls}, {Container Controls}
 */
 
@@ -424,7 +471,10 @@ QQuickItem *QQuickStackView::find(const QJSValue &callback, LoadBehavior behavio
     current.
 
     StackView creates an instance automatically if the pushed item is a \l Component,
-    or a \l [QML] url. The optional \a properties argument specifies a map of initial
+    or a \l [QML] url, and the instance will be destroyed when it is popped
+    off the stack. See \l {Item Ownership} for more information.
+
+    The optional \a properties argument specifies a map of initial
     property values for the pushed item. 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
@@ -544,6 +594,8 @@ void QQuickStackView::push(QQmlV4Function *args)
     items down to (but not including) the first item is popped.
     If not specified, only the current item is popped.
 
+    \include qquickstackview.qdocinc pop-ownership
+
     An \a operation can be optionally specified as the last argument. Supported
     operations:
 
@@ -637,6 +689,8 @@ void QQuickStackView::pop(QQmlV4Function *args)
     item. The item can be an \l Item, \l Component, or a \l [QML] url.
     Returns the item that became current.
 
+    \include qquickstackview.qdocinc pop-ownership
+
     If the \a target argument is specified, all items down to the \target
     item will be replaced. If \a target is \c null, all items in the stack
     will be replaced. If not specified, only the top item will be replaced.
@@ -800,6 +854,8 @@ bool QQuickStackView::isEmpty() const
 
     Removes all items from the stack.
 
+    \include qquickstackview.qdocinc pop-ownership
+
     Since QtQuick.Controls 2.3, a \a transition can be optionally specified. Supported transitions:
 
     \value StackView.Immediate Clear the stack immediately without any transition (default).