Add a positioning 'mode' to positionViewAtIndex()

Provides more control over where and how the view is positioned.

8 files changed, 209 insertions, 45 deletions

diff --git a/examples/declarative/colorbrowser/colorbrowser.qml b/examples/declarative/colorbrowser/colorbrowser.qml
index 421ae07..d4c21e7 100644
--- a/examples/declarative/colorbrowser/colorbrowser.qml
+++ b/examples/declarative/colorbrowser/colorbrowser.qml
@@ -16,7 +16,7 @@ Rectangle {
                 GridView {
                     id: gridView; model: visualModel.parts.grid; width: mainWindow.width; height: mainWindow.height
                     cellWidth: 160; cellHeight: 160; interactive: false
-                    onCurrentIndexChanged: listView.positionViewAtIndex(currentIndex)
+                    onCurrentIndexChanged: listView.positionViewAtIndex(currentIndex, ListView.Contain)
                 }
             }
 
@@ -25,7 +25,7 @@ Rectangle {
                 ListView {
                     id: listView; model: visualModel.parts.list; orientation: Qt.Horizontal
                     width: mainWindow.width; height: mainWindow.height; interactive: false
-                    onCurrentIndexChanged: gridView.positionViewAtIndex(currentIndex)
+                    onCurrentIndexChanged: gridView.positionViewAtIndex(currentIndex, GridView.Contain)
                     highlightRangeMode: ListView.StrictlyEnforceRange; snapMode: ListView.SnapOneItem
                 }
             }
diff --git a/src/declarative/QmlChanges.txt b/src/declarative/QmlChanges.txt
index 591fb3d..f83dd58 100644
--- a/src/declarative/QmlChanges.txt
+++ b/src/declarative/QmlChanges.txt
@@ -1,6 +1,7 @@
 =============================================================================
 The changes below are pre Qt 4.7.0 alpha
 
+ListView, GridView::positionViewAtIndex() gained a 'mode' parameter
 Flickable: renamed viewportWidth -> contentWidth
 Flickable: renamed viewportHeight -> contentHeight
 Flickable: renamed viewportX -> contentX
diff --git a/src/declarative/graphicsitems/qdeclarativegridview.cpp b/src/declarative/graphicsitems/qdeclarativegridview.cpp
index e66bcf6..b1391f9 100644
--- a/src/declarative/graphicsitems/qdeclarativegridview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativegridview.cpp
@@ -1666,47 +1666,84 @@ void QDeclarativeGridView::moveCurrentIndexRight()
 }
 
 /*!
-    \qmlmethod GridView::positionViewAtIndex(int index)
+    \qmlmethod GridView::positionViewAtIndex(int index, PositionMode mode)
+
+    Positions the view such that the \a index is at the position specified by
+    \a mode:
+
+    \list
+    \o Beginning - position item at the top (or left for TopToBottom flow) of the view.
+    \o Center- position item in the center of the view.
+    \o End - position item at bottom (or right for horizontal orientation) of the view.
+    \o Visible - if any part of the item is visible then take no action, otherwise
+    bring the item into view.
+    \o Contain - ensure the entire item is visible.  If the item is larger than
+    the view the item is positioned at the top (or left for TopToBottom flow) of the view.
+    \endlist
 
-    Positions the view such that the \a index is at the top (or left for horizontal orientation) of the view.
     If positioning the view at the index would cause empty space to be displayed at
-    the end of the view, the view will be positioned at the end.
+    the beginning or end of the view, the view will be positioned at the boundary.
 
     It is not recommended to use contentX or contentY to position the view
     at a particular index.  This is unreliable since removing items from the start
-    of the list does not cause all other items to be repositioned.
+    of the view does not cause all other items to be repositioned.
     The correct way to bring an item into view is with positionViewAtIndex.
 */
-void QDeclarativeGridView::positionViewAtIndex(int index)
+void QDeclarativeGridView::positionViewAtIndex(int index, int mode)
 {
     Q_D(QDeclarativeGridView);
     if (!d->isValid() || index < 0 || index >= d->model->count())
         return;
+    if (mode < Beginning || mode > Contain)
+        return;
 
-    qreal maxExtent = d->flow == QDeclarativeGridView::LeftToRight ? -maxYExtent() : -maxXExtent();
+    qreal pos = d->position();
     FxGridItem *item = d->visibleItem(index);
-    if (item) {
-        // Already created - just move to top of view
-        int pos = qMin(item->rowPos(), maxExtent);
-        d->setPosition(pos);
-    } else {
-        int pos = d->rowPosAt(index);
+    if (!item) {
+        int itemPos = d->rowPosAt(index);
         // save the currently visible items in case any of them end up visible again
         QList<FxGridItem*> oldVisible = d->visibleItems;
         d->visibleItems.clear();
         d->visibleIndex = index - index % d->columns;
-        d->setPosition(pos);
-        // setPosition() will cause refill.  Adjust if we have moved beyond range
-        if (d->position() > maxExtent)
-            d->setPosition(maxExtent);
+        d->setPosition(itemPos);
         // now release the reference to all the old visible items.
         for (int i = 0; i < oldVisible.count(); ++i)
             d->releaseItem(oldVisible.at(i));
+        item = d->visibleItem(index);
+    }
+    if (item) {
+        qreal itemPos = item->rowPos();
+        switch (mode) {
+        case Beginning:
+            pos = itemPos;
+            break;
+        case Center:
+            pos = itemPos - (d->size() - d->rowSize())/2;
+            break;
+        case End:
+            pos = itemPos - d->size() + d->rowSize();
+            break;
+        case Visible:
+            if (itemPos > pos + d->size())
+                pos = itemPos - d->size() + d->rowSize();
+            else if (item->endRowPos() < pos)
+                pos = itemPos;
+            break;
+        case Contain:
+            if (item->endRowPos() > pos + d->size())
+                pos = itemPos - d->size() + d->rowSize();
+            if (itemPos < pos)
+                pos = itemPos;
+        }
+        qreal maxExtent = d->flow == QDeclarativeGridView::LeftToRight ? -maxYExtent() : -maxXExtent();
+        pos = qMin(pos, maxExtent);
+        qreal minExtent = d->flow == QDeclarativeGridView::LeftToRight ? -minYExtent() : -minXExtent();
+        pos = qMax(pos, minExtent);
+        d->setPosition(pos);
     }
     d->fixupPosition();
 }
 
-
 void QDeclarativeGridView::componentComplete()
 {
     Q_D(QDeclarativeGridView);
diff --git a/src/declarative/graphicsitems/qdeclarativegridview_p.h b/src/declarative/graphicsitems/qdeclarativegridview_p.h
index 8e253e5..f14ec14 100644
--- a/src/declarative/graphicsitems/qdeclarativegridview_p.h
+++ b/src/declarative/graphicsitems/qdeclarativegridview_p.h
@@ -137,6 +137,9 @@ public:
     SnapMode snapMode() const;
     void setSnapMode(SnapMode mode);
 
+    enum PositionMode { Beginning, Center, End, Visible, Contain };
+    Q_ENUMS(PositionMode)
+
     static QDeclarativeGridViewAttached *qmlAttachedProperties(QObject *);
 
 public Q_SLOTS:
@@ -144,7 +147,7 @@ public Q_SLOTS:
     void moveCurrentIndexDown();
     void moveCurrentIndexLeft();
     void moveCurrentIndexRight();
-    void positionViewAtIndex(int index);
+    void positionViewAtIndex(int index, int mode);
 
 Q_SIGNALS:
     void countChanged();
diff --git a/src/declarative/graphicsitems/qdeclarativelistview.cpp b/src/declarative/graphicsitems/qdeclarativelistview.cpp
index b988e6e..9e6a67a 100644
--- a/src/declarative/graphicsitems/qdeclarativelistview.cpp
+++ b/src/declarative/graphicsitems/qdeclarativelistview.cpp
@@ -2180,11 +2180,23 @@ void QDeclarativeListView::decrementCurrentIndex()
 }
 
 /*!
-    \qmlmethod ListView::positionViewAtIndex(int index)
+    \qmlmethod ListView::positionViewAtIndex(int index, PositionMode mode)
+
+    Positions the view such that the \a index is at the position specified by
+    \a mode:
+
+    \list
+    \o Beginning - position item at the top (or left for horizontal orientation) of the view.
+    \o Center- position item in the center of the view.
+    \o End - position item at bottom (or right for horizontal orientation) of the view.
+    \o Visible - if any part of the item is visible then take no action, otherwise
+    bring the item into view.
+    \o Contain - ensure the entire item is visible.  If the item is larger than
+    the view the item is positioned at the top (or left for horizontal orientation) of the view.
+    \endlist
 
-    Positions the view such that the \a index is at the top (or left for horizontal orientation) of the view.
     If positioning the view at the index would cause empty space to be displayed at
-    the end of the view, the view will be positioned at the end.
+    the beginning or end of the view, the view will be positioned at the boundary.
 
     It is not recommended to use contentX or contentY to position the view
     at a particular index.  This is unreliable since removing items from the start
@@ -2192,32 +2204,58 @@ void QDeclarativeListView::decrementCurrentIndex()
     the actual start of the view can vary based on the size of the delegates.
     The correct way to bring an item into view is with positionViewAtIndex.
 */
-void QDeclarativeListView::positionViewAtIndex(int index)
+void QDeclarativeListView::positionViewAtIndex(int index, int mode)
 {
     Q_D(QDeclarativeListView);
     if (!d->isValid() || index < 0 || index >= d->model->count())
         return;
+    if (mode < Beginning || mode > Contain)
+        return;
 
-    qreal maxExtent = d->orient == QDeclarativeListView::Vertical ? -maxYExtent() : -maxXExtent();
+    qreal pos = d->position();
     FxListItem *item = d->visibleItem(index);
-    if (item) {
-        // Already created - just move to top of view
-        int pos = qMin(item->position(), maxExtent);
-        d->setPosition(pos);
-    } else {
-        int pos = d->positionAt(index);
+    if (!item) {
+        int itemPos = d->positionAt(index);
         // save the currently visible items in case any of them end up visible again
         QList<FxListItem*> oldVisible = d->visibleItems;
         d->visibleItems.clear();
-        d->visiblePos = pos;
+        d->visiblePos = itemPos;
         d->visibleIndex = index;
-        d->setPosition(pos);
-        // setPosition() will cause refill.  Adjust if we have moved beyond range.
-        if (d->position() > maxExtent)
-            d->setPosition(maxExtent);
+        d->setPosition(itemPos);
         // now release the reference to all the old visible items.
         for (int i = 0; i < oldVisible.count(); ++i)
             d->releaseItem(oldVisible.at(i));
+        item = d->visibleItem(index);
+    }
+    if (item) {
+        const qreal itemPos = item->position();
+        switch (mode) {
+        case Beginning:
+            pos = itemPos;
+            break;
+        case Center:
+            pos = itemPos - (d->size() - item->size())/2;
+            break;
+        case End:
+            pos = itemPos - d->size() + item->size();
+            break;
+        case Visible:
+            if (itemPos > pos + d->size())
+                pos = itemPos - d->size() + item->size();
+            else if (item->endPosition() < pos)
+                pos = itemPos;
+            break;
+        case Contain:
+            if (item->endPosition() > pos + d->size())
+                pos = itemPos - d->size() + item->size();
+            if (itemPos < pos)
+                pos = itemPos;
+        }
+        qreal maxExtent = d->orient == QDeclarativeListView::Vertical ? -maxYExtent() : -maxXExtent();
+        pos = qMin(pos, maxExtent);
+        qreal minExtent = d->orient == QDeclarativeListView::Vertical ? -minYExtent() : -minXExtent();
+        pos = qMax(pos, minExtent);
+        d->setPosition(pos);
     }
     d->fixupPosition();
 }
diff --git a/src/declarative/graphicsitems/qdeclarativelistview_p.h b/src/declarative/graphicsitems/qdeclarativelistview_p.h
index 1bf9652..0c2677c 100644
--- a/src/declarative/graphicsitems/qdeclarativelistview_p.h
+++ b/src/declarative/graphicsitems/qdeclarativelistview_p.h
@@ -191,10 +191,13 @@ public:
 
     static QDeclarativeListViewAttached *qmlAttachedProperties(QObject *);
 
+    enum PositionMode { Beginning, Center, End, Visible, Contain };
+    Q_ENUMS(PositionMode)
+
 public Q_SLOTS:
     void incrementCurrentIndex();
     void decrementCurrentIndex();
-    void positionViewAtIndex(int index);
+    void positionViewAtIndex(int index, int mode);
 
 Q_SIGNALS:
     void countChanged();
diff --git a/tests/auto/declarative/qdeclarativegridview/tst_qdeclarativegridview.cpp b/tests/auto/declarative/qdeclarativegridview/tst_qdeclarativegridview.cpp
index aaf8291..385d6f5 100644
--- a/tests/auto/declarative/qdeclarativegridview/tst_qdeclarativegridview.cpp
+++ b/tests/auto/declarative/qdeclarativegridview/tst_qdeclarativegridview.cpp
@@ -949,7 +949,7 @@ void tst_QDeclarativeGridView::positionViewAtIndex()
     }
 
     // Position on a currently visible item
-    gridview->positionViewAtIndex(4);
+    gridview->positionViewAtIndex(4, QDeclarativeGridView::Beginning);
     QCOMPARE(gridview->contentY(), 60.);
 
     // Confirm items positioned correctly
@@ -963,7 +963,7 @@ void tst_QDeclarativeGridView::positionViewAtIndex()
     }
 
     // Position on an item beyond the visible items
-    gridview->positionViewAtIndex(21);
+    gridview->positionViewAtIndex(21, QDeclarativeGridView::Beginning);
     QCOMPARE(gridview->contentY(), 420.);
 
     // Confirm items positioned correctly
@@ -977,7 +977,7 @@ void tst_QDeclarativeGridView::positionViewAtIndex()
     }
 
     // Position on an item that would leave empty space if positioned at the top
-    gridview->positionViewAtIndex(31);
+    gridview->positionViewAtIndex(31, QDeclarativeGridView::Beginning);
     QCOMPARE(gridview->contentY(), 520.);
 
     // Confirm items positioned correctly
@@ -991,7 +991,7 @@ void tst_QDeclarativeGridView::positionViewAtIndex()
     }
 
     // Position at the beginning again
-    gridview->positionViewAtIndex(0);
+    gridview->positionViewAtIndex(0, QDeclarativeGridView::Beginning);
     QCOMPARE(gridview->contentY(), 0.);
 
     // Confirm items positioned correctly
@@ -1004,6 +1004,47 @@ void tst_QDeclarativeGridView::positionViewAtIndex()
         QCOMPARE(item->y(), (i/3)*60.);
     }
 
+    // Position at End
+    gridview->positionViewAtIndex(30, QDeclarativeGridView::End);
+    QCOMPARE(gridview->contentY(), 340.);
+
+    // Position in Center
+    gridview->positionViewAtIndex(15, QDeclarativeGridView::Center);
+    QCOMPARE(gridview->contentY(), 170.);
+
+    // Ensure at least partially visible
+    gridview->positionViewAtIndex(15, QDeclarativeGridView::Visible);
+    QCOMPARE(gridview->contentY(), 170.);
+
+    gridview->setContentY(302);
+    gridview->positionViewAtIndex(15, QDeclarativeGridView::Visible);
+    QCOMPARE(gridview->contentY(), 302.);
+
+    gridview->setContentY(360);
+    gridview->positionViewAtIndex(15, QDeclarativeGridView::Visible);
+    QCOMPARE(gridview->contentY(), 300.);
+
+    gridview->setContentY(60);
+    gridview->positionViewAtIndex(20, QDeclarativeGridView::Visible);
+    QCOMPARE(gridview->contentY(), 60.);
+
+    gridview->setContentY(20);
+    gridview->positionViewAtIndex(20, QDeclarativeGridView::Visible);
+    QCOMPARE(gridview->contentY(), 100.);
+
+    // Ensure completely visible
+    gridview->setContentY(120);
+    gridview->positionViewAtIndex(20, QDeclarativeGridView::Contain);
+    QCOMPARE(gridview->contentY(), 120.);
+
+    gridview->setContentY(302);
+    gridview->positionViewAtIndex(15, QDeclarativeGridView::Contain);
+    QCOMPARE(gridview->contentY(), 300.);
+
+    gridview->setContentY(60);
+    gridview->positionViewAtIndex(20, QDeclarativeGridView::Contain);
+    QCOMPARE(gridview->contentY(), 100.);
+
     delete canvas;
 }
 
diff --git a/tests/auto/declarative/qdeclarativelistview/tst_qdeclarativelistview.cpp b/tests/auto/declarative/qdeclarativelistview/tst_qdeclarativelistview.cpp
index e5542c2..5b57487 100644
--- a/tests/auto/declarative/qdeclarativelistview/tst_qdeclarativelistview.cpp
+++ b/tests/auto/declarative/qdeclarativelistview/tst_qdeclarativelistview.cpp
@@ -1193,7 +1193,7 @@ void tst_QDeclarativeListView::positionViewAtIndex()
     }
 
     // Position on a currently visible item
-    listview->positionViewAtIndex(3);
+    listview->positionViewAtIndex(3, QDeclarativeListView::Beginning);
     QCOMPARE(listview->contentY(), 60.);
 
     // Confirm items positioned correctly
@@ -1206,7 +1206,7 @@ void tst_QDeclarativeListView::positionViewAtIndex()
     }
 
     // Position on an item beyond the visible items
-    listview->positionViewAtIndex(22);
+    listview->positionViewAtIndex(22, QDeclarativeListView::Beginning);
     QCOMPARE(listview->contentY(), 440.);
 
     // Confirm items positioned correctly
@@ -1219,7 +1219,7 @@ void tst_QDeclarativeListView::positionViewAtIndex()
     }
 
     // Position on an item that would leave empty space if positioned at the top
-    listview->positionViewAtIndex(28);
+    listview->positionViewAtIndex(28, QDeclarativeListView::Beginning);
     QCOMPARE(listview->contentY(), 480.);
 
     // Confirm items positioned correctly
@@ -1232,7 +1232,7 @@ void tst_QDeclarativeListView::positionViewAtIndex()
     }
 
     // Position at the beginning again
-    listview->positionViewAtIndex(0);
+    listview->positionViewAtIndex(0, QDeclarativeListView::Beginning);
     QCOMPARE(listview->contentY(), 0.);
 
     // Confirm items positioned correctly
@@ -1244,6 +1244,47 @@ void tst_QDeclarativeListView::positionViewAtIndex()
         QCOMPARE(item->y(), i*20.);
     }
 
+    // Position at End
+    listview->positionViewAtIndex(20, QDeclarativeListView::End);
+    QCOMPARE(listview->contentY(), 100.);
+
+    // Position in Center
+    listview->positionViewAtIndex(15, QDeclarativeListView::Center);
+    QCOMPARE(listview->contentY(), 150.);
+
+    // Ensure at least partially visible
+    listview->positionViewAtIndex(15, QDeclarativeListView::Visible);
+    QCOMPARE(listview->contentY(), 150.);
+
+    listview->setContentY(302);
+    listview->positionViewAtIndex(15, QDeclarativeListView::Visible);
+    QCOMPARE(listview->contentY(), 302.);
+
+    listview->setContentY(320);
+    listview->positionViewAtIndex(15, QDeclarativeListView::Visible);
+    QCOMPARE(listview->contentY(), 300.);
+
+    listview->setContentY(85);
+    listview->positionViewAtIndex(20, QDeclarativeListView::Visible);
+    QCOMPARE(listview->contentY(), 85.);
+
+    listview->setContentY(75);
+    listview->positionViewAtIndex(20, QDeclarativeListView::Visible);
+    QCOMPARE(listview->contentY(), 100.);
+
+    // Ensure completely visible
+    listview->setContentY(120);
+    listview->positionViewAtIndex(20, QDeclarativeListView::Contain);
+    QCOMPARE(listview->contentY(), 120.);
+
+    listview->setContentY(302);
+    listview->positionViewAtIndex(15, QDeclarativeListView::Contain);
+    QCOMPARE(listview->contentY(), 300.);
+
+    listview->setContentY(85);
+    listview->positionViewAtIndex(20, QDeclarativeListView::Contain);
+    QCOMPARE(listview->contentY(), 100.);
+
     delete canvas;
 }