From e7840895aa712e867009d518d7eacc372a92df71 Mon Sep 17 00:00:00 2001 From: Mitch Curtis Date: Wed, 14 Oct 2015 10:38:49 +0200 Subject: 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 *b = window->property("b").value(); // 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 --- src/quick/items/qquickitem.cpp | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) (limited to 'src/quick') 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. -- cgit v1.2.3