QQuickItem: fully document stackBefore() and stackAfter()

Some of the following behavior initially came as a surprise to me:

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);

    QQmlApplicationEngine engine;
    engine.load(QUrl(QStringLiteral("qrc:/main.qml")));

    QObject *window = engine.rootObjects().first();
    // Assume that a and b are rectangles declared in that order, respectively.
    QQuickItem *a = window->property("a").value<QQuickItem*>();
    QQuickItem *b = window->property("b").value<QQuickItem*>();

    // a is rendered below b (assume that rendering happens here)
    qDebug() << "a.z =" << a->z() << "b.z =" << b->z(); // a.z = 0 b.z = 0

    a->stackAfter(b);

    // a is rendered above b
    qDebug() << "a.z =" << a->z() << "b.z =" << b->z(); // a.z = 0 b.z = 0

    b->setZ(1);

    // a is rendered below b
    qDebug() << "a.z =" << a->z() << "b.z =" << b->z(); // a.z = 0 b.z = 1

    a->stackAfter(b);

    // a is rendered below b
    qDebug() << "a.z =" << a->z() << "b.z =" << b->z(); // a.z = 0 b.z = 1

    return app.exec();
}

I would have thought that stackBefore()/stackAfter() would also change
the z value, but it makes sense that it doens't, as z is never really
validated, as such.

Still, we should document the exact behavior, including information
about tab focus ordering.

Change-Id: Iafc45aec402d8461e7b53525f81195171f659dff
Reviewed-by: J-P Nurmi <jpnurmi@theqtcompany.com>

1 files changed, 18 insertions, 2 deletions

diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index e030144676..1865ba9d03 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -2714,7 +2714,15 @@ void QQuickItem::setParentItem(QQuickItem *parentItem)
 
 /*!
     Moves the specified \a sibling item to the index before this item
-    within the visual stacking order.
+    within the list of children. The order of children affects both the
+    visual stacking order and tab focus navigation order.
+
+    Assuming the z values of both items are the same, this will cause \a
+    sibling to be rendered above this item.
+
+    If both items have activeFocusOnTab set to \c true, this will also cause
+    the tab focus order to change, with \a sibling receiving focus after this
+    item.
 
     The given \a sibling must be a sibling of this item; that is, they must
     have the same immediate \l parent.
@@ -2750,7 +2758,15 @@ void QQuickItem::stackBefore(const QQuickItem *sibling)
 
 /*!
     Moves the specified \a sibling item to the index after this item
-    within the visual stacking order.
+    within the list of children. The order of children affects both the
+    visual stacking order and tab focus navigation order.
+
+    Assuming the z values of both items are the same, this will cause \a
+    sibling to be rendered below this item.
+
+    If both items have activeFocusOnTab set to \c true, this will also cause
+    the tab focus order to change, with \a sibling receiving focus before this
+    item.
 
     The given \a sibling must be a sibling of this item; that is, they must
     have the same immediate \l parent.