FCL/sf/mw/qt: comparison src/declarative/graphicsitems/qdeclarativegridview.cpp

equal deleted inserted replaced

-:5dc02b23752f
+:3e2da88830cd
 , cellWidth(100), cellHeight(100), columns(1), requestedIndex(-1), itemCount(0)
 , highlightRangeStart(0), highlightRangeEnd(0), highlightRange(QDeclarativeGridView::NoHighlightRange)
 , highlightComponent(0), highlight(0), trackedItem(0)
 , moveReason(Other), buffer(0), highlightXAnimator(0), highlightYAnimator(0)
 , highlightMoveDuration(150)
+, footerComponent(0), footer(0), headerComponent(0), header(0)
 , bufferMode(BufferBefore | BufferAfter), snapMode(QDeclarativeGridView::NoSnap)
 , ownModel(false), wrap(false), autoHighlight(true)
 , fixCurrentVisibility(false), lazyRelease(false), layoutScheduled(false)
 , deferredRelease(false), haveHighlightRange(false) {}
 void updateUnrequestedPositions();
 void updateTrackedItem();
 void createHighlight();
 void updateHighlight();
 void updateCurrent(int modelIndex);
+void updateHeader();
+void updateFooter();
 void fixupPosition();
 FxGridItem *visibleItem(int modelIndex) const {
 if (modelIndex >= visibleIndex && modelIndex < visibleIndex + visibleItems.count()) {
 for (int i = modelIndex - visibleIndex; i < visibleItems.count(); ++i) {
 return flow == QDeclarativeGridView::LeftToRight ? q->contentY() : q->contentX();
 }
 void setPosition(qreal pos) {
 Q_Q(QDeclarativeGridView);
 if (flow == QDeclarativeGridView::LeftToRight)
-q->setContentY(pos);
+q->QDeclarativeFlickable::setContentY(pos);
 else
-q->setContentX(pos);
+q->QDeclarativeFlickable::setContentX(pos);
 }
 int size() const {
 Q_Q(const QDeclarativeGridView);
 return flow == QDeclarativeGridView::LeftToRight ? q->height() : q->width();
 }
 return item;
 }
 return visibleItems.count() ? visibleItems.first() : 0;
 }
+int lastVisibleIndex() const {
+int lastIndex = -1;
+for (int i = visibleItems.count()-1; i >= 0; --i) {
+FxGridItem *gridItem = visibleItems.at(i);
+if (gridItem->index != -1) {
+lastIndex = gridItem->index;
+break;
+}
+}
+return lastIndex;
+}
 // Map a model index to visibleItems list index.
 // These may differ if removed items are still present in the visible list,
 // e.g. doing a removal animation
 int mapFromModel(int modelIndex) const {
 if (modelIndex < visibleIndex || modelIndex >= visibleIndex + visibleItems.count())
 return -1;
 }
 return -1; // Not in visibleList
 }
-qreal snapPosAt(qreal pos) {
+qreal snapPosAt(qreal pos) const {
+Q_Q(const QDeclarativeGridView);
 qreal snapPos = 0;
 if (!visibleItems.isEmpty()) {
 pos += rowSize()/2;
 snapPos = visibleItems.first()->rowPos() - visibleIndex / columns * rowSize();
 snapPos = pos - fmodf(pos - snapPos, qreal(rowSize()));
+qreal maxExtent = flow == QDeclarativeGridView::LeftToRight ? -q->maxYExtent() : -q->maxXExtent();
+qreal minExtent = flow == QDeclarativeGridView::LeftToRight ? -q->minYExtent() : -q->minXExtent();
+if (snapPos > maxExtent)
+snapPos = maxExtent;
+if (snapPos < minExtent)
+snapPos = minExtent;
 }
 return snapPos;
+}
+FxGridItem *snapItemAt(qreal pos) {
+for (int i = 0; i < visibleItems.count(); ++i) {
+FxGridItem *item = visibleItems[i];
+if (item->index == -1)
+continue;
+qreal itemTop = item->rowPos();
+if (item->index == model->count()-1 || (itemTop+rowSize()/2 >= pos))
+return item;
+}
+if (visibleItems.count() && visibleItems.first()->rowPos() <= pos)
+return visibleItems.first();
+return 0;
 }
 int snapIndex() {
 int index = currentIndex;
 for (int i = 0; i < visibleItems.count(); ++i) {
 if (q->isComponentComplete()) {
 updateGrid();
 scheduleLayout();
 }
 }
+} else if ((header && header->item == item) || (footer && footer->item == item)) {
+updateHeader();
+updateFooter();
 }
 }
 virtual void fixup(AxisData &data, qreal minExtent, qreal maxExtent);
 virtual void flick(AxisData &data, qreal minExtent, qreal maxExtent, qreal vSize,
 MovementReason moveReason;
 int buffer;
 QSmoothedAnimation *highlightXAnimator;
 QSmoothedAnimation *highlightYAnimator;
 int highlightMoveDuration;
+QDeclarativeComponent *footerComponent;
+FxGridItem *footer;
+QDeclarativeComponent *headerComponent;
+FxGridItem *header;
 enum BufferMode { NoBuffer = 0x00, BufferBefore = 0x01, BufferAfter = 0x02 };
 int bufferMode;
 QDeclarativeGridView::SnapMode snapMode;
 bool ownModel : 1;
 listItem = new FxGridItem(item, q);
 listItem->index = modelIndex;
 if (model->completePending()) {
 // complete
 listItem->item->setZValue(1);
-listItem->item->setParentItem(q->viewport());
+listItem->item->setParentItem(q->contentItem());
 model->completeItem();
 } else {
-listItem->item->setParentItem(q->viewport());
+listItem->item->setParentItem(q->contentItem());
 }
 unrequestedItems.remove(listItem->item);
 }
 requestedIndex = -1;
 return listItem;
 void QDeclarativeGridViewPrivate::refill(qreal from, qreal to, bool doBuffer)
 {
 Q_Q(QDeclarativeGridView);
 if (!isValid() || !q->isComponentComplete())
 return;
 itemCount = model->count();
 qreal bufferFrom = from - buffer;
 qreal bufferTo = to + buffer;
 qreal fillFrom = from;
 qreal fillTo = to;
 deferredRelease = false;
 } else {
 deferredRelease = true;
 }
 if (changed) {
+if (header)
+updateHeader();
+if (footer)
+updateFooter();
 if (flow == QDeclarativeGridView::LeftToRight)
 q->setContentHeight(endPosition() - startPosition());
 else
 q->setContentWidth(endPosition() - startPosition());
 } else if (!doBuffer && buffer && bufferMode != NoBuffer) {
 void QDeclarativeGridViewPrivate::layout()
 {
 Q_Q(QDeclarativeGridView);
 layoutScheduled = false;
-if (!isValid()) {
+if (!isValid() && !visibleItems.count()) {
 clear();
 return;
 }
 if (visibleItems.count()) {
 qreal rowPos = visibleItems.first()->rowPos();
 rowPos += rowSize();
 }
 item->setPosition(colPos, rowPos);
 }
 }
+if (header)
+updateHeader();
+if (footer)
+updateFooter();
 q->refill();
 updateHighlight();
 moveReason = Other;
 if (flow == QDeclarativeGridView::LeftToRight) {
 q->setContentHeight(endPosition() - startPosition());
 } else {
 delete highlightContext;
 }
 } else {
 item = new QDeclarativeItem;
-QDeclarative_setParent_noEvent(item, q->viewport());
+QDeclarative_setParent_noEvent(item, q->contentItem());
-item->setParentItem(q->viewport());
+item->setParentItem(q->contentItem());
 }
 if (item) {
-QDeclarative_setParent_noEvent(item, q->viewport());
+QDeclarative_setParent_noEvent(item, q->contentItem());
-item->setParentItem(q->viewport());
+item->setParentItem(q->contentItem());
 highlight = new FxGridItem(item, q);
 highlightXAnimator = new QSmoothedAnimation(q);
 highlightXAnimator->target = QDeclarativeProperty(highlight->item, QLatin1String("x"));
 highlightXAnimator->userDuration = highlightMoveDuration;
 highlightYAnimator = new QSmoothedAnimation(q);
 updateHighlight();
 emit q->currentIndexChanged();
 releaseItem(oldCurrentItem);
 }
+void QDeclarativeGridViewPrivate::updateFooter()
+{
+Q_Q(QDeclarativeGridView);
+if (!footer && footerComponent) {
+QDeclarativeItem *item = 0;
+QDeclarativeContext *context = new QDeclarativeContext(qmlContext(q));
+QObject *nobj = footerComponent->create(context);
+if (nobj) {
+QDeclarative_setParent_noEvent(context, nobj);
+item = qobject_cast<QDeclarativeItem *>(nobj);
+if (!item)
+delete nobj;
+} else {
+delete context;
+}
+if (item) {
+QDeclarative_setParent_noEvent(item, q->contentItem());
+item->setParentItem(q->contentItem());
+item->setZValue(1);
+QDeclarativeItemPrivate *itemPrivate = static_cast<QDeclarativeItemPrivate*>(QGraphicsItemPrivate::get(item));
+itemPrivate->addItemChangeListener(this, QDeclarativeItemPrivate::Geometry);
+footer = new FxGridItem(item, q);
+}
+}
+if (footer) {
+if (visibleItems.count()) {
+qreal endPos = endPosition();
+if (lastVisibleIndex() == model->count()-1) {
+footer->setPosition(0, endPos);
+} else {
+qreal visiblePos = position() + q->height();
+if (endPos <= visiblePos || footer->endRowPos() < endPos)
+footer->setPosition(0, endPos);
+}
+} else {
+qreal endPos = 0;
+if (header) {
+endPos += flow == QDeclarativeGridView::LeftToRight
+? header->item->height()
+: header->item->width();
+}
+footer->setPosition(0, endPos);
+}
+}
+}
+void QDeclarativeGridViewPrivate::updateHeader()
+{
+Q_Q(QDeclarativeGridView);
+if (!header && headerComponent) {
+QDeclarativeItem *item = 0;
+QDeclarativeContext *context = new QDeclarativeContext(qmlContext(q));
+QObject *nobj = headerComponent->create(context);
+if (nobj) {
+QDeclarative_setParent_noEvent(context, nobj);
+item = qobject_cast<QDeclarativeItem *>(nobj);
+if (!item)
+delete nobj;
+} else {
+delete context;
+}
+if (item) {
+QDeclarative_setParent_noEvent(item, q->contentItem());
+item->setParentItem(q->contentItem());
+item->setZValue(1);
+QDeclarativeItemPrivate *itemPrivate = static_cast<QDeclarativeItemPrivate*>(QGraphicsItemPrivate::get(item));
+itemPrivate->addItemChangeListener(this, QDeclarativeItemPrivate::Geometry);
+header = new FxGridItem(item, q);
+}
+}
+if (header) {
+if (visibleItems.count()) {
+qreal startPos = startPosition();
+qreal headerSize = flow == QDeclarativeGridView::LeftToRight
+? header->item->height()
+: header->item->width();
+if (visibleIndex == 0) {
+header->setPosition(0, startPos - headerSize);
+} else {
+if (position() <= startPos || header->rowPos() > startPos - headerSize)
+header->setPosition(0, startPos - headerSize);
+}
+} else {
+header->setPosition(0, 0);
+}
+}
+}
 void QDeclarativeGridViewPrivate::fixupPosition()
 {
 moveReason = Other;
 if (flow == QDeclarativeGridView::LeftToRight)
 fixupY();
 fixupX();
 }
 void QDeclarativeGridViewPrivate::fixup(AxisData &data, qreal minExtent, qreal maxExtent)
 {
-Q_Q(QDeclarativeGridView);
 if ((flow == QDeclarativeGridView::TopToBottom && &data == &vData)
 || (flow == QDeclarativeGridView::LeftToRight && &data == &hData))
 return;
 int oldDuration = fixupDuration;
 fixupDuration = moveReason == Mouse ? fixupDuration : 0;
-if (haveHighlightRange && highlightRange == QDeclarativeGridView::StrictlyEnforceRange) {
+if (snapMode != QDeclarativeGridView::NoSnap) {
+FxGridItem *topItem = snapItemAt(position()+highlightRangeStart);
+FxGridItem *bottomItem = snapItemAt(position()+highlightRangeEnd);
+qreal pos;
+if (topItem && bottomItem && haveHighlightRange && highlightRange == QDeclarativeGridView::StrictlyEnforceRange) {
+qreal topPos = qMin(topItem->rowPos() - highlightRangeStart, -maxExtent);
+qreal bottomPos = qMax(bottomItem->rowPos() - highlightRangeEnd, -minExtent);
+pos = qAbs(data.move + topPos) < qAbs(data.move + bottomPos) ? topPos : bottomPos;
+} else if (topItem) {
+pos = qMax(qMin(topItem->rowPos() - highlightRangeStart, -maxExtent), -minExtent);
+} else if (bottomItem) {
+pos = qMax(qMin(bottomItem->rowPos() - highlightRangeStart, -maxExtent), -minExtent);
+} else {
+fixupDuration = oldDuration;
+return;
+}
+if (currentItem && haveHighlightRange && highlightRange == QDeclarativeGridView::StrictlyEnforceRange) {
+updateHighlight();
+qreal currPos = currentItem->rowPos();
+if (pos < currPos + rowSize() - highlightRangeEnd)
+pos = currPos + rowSize() - highlightRangeEnd;
+if (pos > currPos - highlightRangeStart)
+pos = currPos - highlightRangeStart;
+}
+qreal dist = qAbs(data.move + pos);
+if (dist > 0) {
+timeline.reset(data.move);
+if (fixupDuration)
+timeline.move(data.move, -pos, QEasingCurve(QEasingCurve::InOutQuad), fixupDuration/2);
+else
+timeline.set(data.move, -pos);
+vTime = timeline.time();
+}
+} else if (haveHighlightRange && highlightRange == QDeclarativeGridView::StrictlyEnforceRange) {
 if (currentItem) {
 updateHighlight();
 qreal pos = currentItem->rowPos();
 qreal viewPos = position();
 if (viewPos < pos + rowSize() - highlightRangeEnd)
 if (viewPos > pos - highlightRangeStart)
 viewPos = pos - highlightRangeStart;
 timeline.reset(data.move);
 if (viewPos != position()) {
-if (fixupDuration) {
+if (fixupDuration)
 timeline.move(data.move, -viewPos, QEasingCurve(QEasingCurve::InOutQuad), fixupDuration/2);
-} else {
+else
-data.move.setValue(-viewPos);
+timeline.set(data.move, -viewPos);
-q->viewportMoved();
-}
-}
-vTime = timeline.time();
-}
-} else if (snapMode != QDeclarativeGridView::NoSnap) {
-qreal pos = -snapPosAt(-(data.move.value() - highlightRangeStart)) + highlightRangeStart;
-pos = qMin(qMax(pos, maxExtent), minExtent);
-qreal dist = qAbs(data.move.value() - pos);
-if (dist > 0) {
-timeline.reset(data.move);
-if (fixupDuration) {
-timeline.move(data.move, pos, QEasingCurve(QEasingCurve::InOutQuad), fixupDuration/2);
-} else {
-data.move.setValue(pos);
-q->viewportMoved();
 }
 vTime = timeline.time();
 }
 } else {
 QDeclarativeFlickablePrivate::fixup(data, minExtent, maxExtent);
 void QDeclarativeGridViewPrivate::flick(AxisData &data, qreal minExtent, qreal maxExtent, qreal vSize,
 QDeclarativeTimeLineCallback::Callback fixupCallback, qreal velocity)
 {
 Q_Q(QDeclarativeGridView);
 moveReason = Mouse;
 if ((!haveHighlightRange || highlightRange != QDeclarativeGridView::StrictlyEnforceRange)
 && snapMode == QDeclarativeGridView::NoSnap) {
 QDeclarativeFlickablePrivate::flick(data, minExtent, maxExtent, vSize, fixupCallback, velocity);
 return;
 v = maxVelocity;
 }
 qreal accel = deceleration;
 qreal v2 = v * v;
 qreal overshootDist = 0.0;
-if (maxDistance > 0.0 && v2 / (2.0f * maxDistance) < accel) {
+if ((maxDistance > 0.0 && v2 / (2.0f * maxDistance) < accel) || snapMode == QDeclarativeGridView::SnapOneRow) {
 // + rowSize()/4 to encourage moving at least one item in the flick direction
 qreal dist = v2 / (accel * 2.0) + rowSize()/4;
+dist = qMin(dist, maxDistance);
 if (v > 0)
 dist = -dist;
 data.flickTarget = -snapPosAt(-(data.move.value() - highlightRangeStart) + dist) + highlightRangeStart;
 qreal adjDist = -data.flickTarget + data.move.value();
 if (qAbs(adjDist) > qAbs(dist)) {
 \qmlclass GridView QDeclarativeGridView
 \since 4.7
 \inherits Flickable
 \brief The GridView item provides a grid view of items provided by a model.
-The model is typically provided by a QAbstractListModel "C++ model object",
+A GridView displays data from models created from built-in QML elements like ListModel
-but can also be created directly in QML.
+and XmlListModel, or custom model classes defined in C++ that inherit from
+QAbstractListModel.
-The items are laid out top to bottom (vertically) or left to right (horizontally)
-and may be flicked to scroll.
+A GridView has a \l model, which defines the data to be displayed, and
+a \l delegate, which defines how the data should be displayed. Items in a
-The below example creates a very simple grid, using a QML model.
+GridView are laid out horizontally or vertically. Grid views are inherently flickable
+as GridView inherits from \l Flickable.
-\image gridview.png
+For example, if there is a simple list model defined in a file \c ContactModel.qml like this:
-\snippet doc/src/snippets/declarative/gridview/gridview.qml 3
+\snippet doc/src/snippets/declarative/gridview/ContactModel.qml 0
-The model is defined as a ListModel using QML:
-\quotefile doc/src/snippets/declarative/gridview/dummydata/ContactModel.qml
+Another component can display this model data in a GridView, like this:
-In this case ListModel is a handy way for us to test our UI.  In practice
+\snippet doc/src/snippets/declarative/gridview/gridview.qml import
-the model would be implemented in C++, or perhaps via a SQL data source.
+\codeline
+\snippet doc/src/snippets/declarative/gridview/gridview.qml classdocs simple
+\image gridview-simple.png
+Here, the GridView creates a \c ContactModel component for its model, and a \l Column element
+(containing \l Image and \ Text elements) for its delegate. The view will create a new delegate
+for each item in the model. Notice the delegate is able to access the model's \c name and
+\c portrait data directly.
+An improved grid view is shown below. The delegate is visually improved and is moved
+into a separate \c contactDelegate component. Also, the currently selected item is highlighted
+with a blue \l Rectangle using the \l highlight property, and \c focus is set to \c true
+to enable keyboard navigation for the grid view.
+\snippet doc/src/snippets/declarative/gridview/gridview.qml classdocs advanced
+\image gridview-highlight.png
 Delegates are instantiated as needed and may be destroyed at any time.
 State should \e never be stored in a delegate.
-\bold Note that views do not enable \e clip automatically.  If the view
+\note Views do not enable \e clip automatically.  If the view
 is not clipped by another item or the screen, it will be necessary
 to set \e {clip: true} in order to have the out of view items clipped
 nicely.
+\sa {declarative/modelviews/gridview}{GridView example}
 */
 QDeclarativeGridView::QDeclarativeGridView(QDeclarativeItem *parent)
 : QDeclarativeFlickable(*(new QDeclarativeGridViewPrivate), parent)
 {
 Q_D(QDeclarativeGridView);
 {
 Q_D(QDeclarativeGridView);
 d->clear();
 if (d->ownModel)
 delete d->model;
+delete d->header;
+delete d->footer;
 }
 /*!
 \qmlattachedproperty bool GridView::isCurrentItem
-This attched property is true if this delegate is the current item; otherwise false.
+This attached property is true if this delegate is the current item; otherwise false.
 It is attached to each instance of the delegate.
 */
 /*!
 until an animation completes.
 The example below ensures that the animation completes before
 the item is removed from the grid.
-\code
+\snippet doc/src/snippets/declarative/gridview/gridview.qml delayRemove
-Component {
-id: myDelegate
-Item {
-id: wrapper
-GridView.onRemove: SequentialAnimation {
-PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: true }
-NumberAnimation { target: wrapper; property: "scale"; to: 0; duration: 250; easing.type: Easing.InOutQuad }
-PropertyAction { target: wrapper; property: "GridView.delayRemove"; value: false }
-}
-}
-}
-\endcode
 */
 /*!
 \qmlattachedsignal GridView::onAdd()
 This attached handler is called immediately after an item is added to the view.
 /*!
 \qmlproperty model GridView::model
 This property holds the model providing data for the grid.
-The model provides a set of data that is used to create the items
+The model provides the set of data that is used to create the items
-for the view.  For large or dynamic datasets the model is usually
+in the view. Models can be created directly in QML using \l ListModel, \l XmlListModel
-provided by a C++ model object.  The C++ model object must be a \l
+or \l VisualItemModel, or provided by C++ model classes. If a C++ model class is
-{QAbstractItemModel} subclass, a VisualModel, or a simple list.
+used, it must be a subclass of \l QAbstractItemModel or a simple list.
 \sa {qmlmodels}{Data Models}
 */
 QVariant QDeclarativeGridView::model() const
 {
 if (d->currentIndex >= d->model->count() || d->currentIndex < 0) {
 setCurrentIndex(0);
 } else {
 d->moveReason = QDeclarativeGridViewPrivate::SetIndex;
 d->updateCurrent(d->currentIndex);
+if (d->highlight && d->currentItem) {
+d->highlight->setPosition(d->currentItem->colPos(), d->currentItem->rowPos());
+d->updateTrackedItem();
+}
+d->moveReason = QDeclarativeGridViewPrivate::Other;
 }
 }
 connect(d->model, SIGNAL(itemsInserted(int,int)), this, SLOT(itemsInserted(int,int)));
 connect(d->model, SIGNAL(itemsRemoved(int,int)), this, SLOT(itemsRemoved(int,int)));
 connect(d->model, SIGNAL(itemsMoved(int,int,int)), this, SLOT(itemsMoved(int,int,int)));
 The number of elements in the delegate has a direct effect on the
 flicking performance of the view.  If at all possible, place functionality
 that is not needed for the normal display of the delegate in a \l Loader which
 can load additional elements when needed.
-Note that the GridView will layout the items based on the size of the root item
+The GridView will layout the items based on the size of the root item
 in the delegate.
-Here is an example delegate:
+\note Delegates are instantiated as needed and may be destroyed at any time.
-\snippet doc/src/snippets/declarative/gridview/gridview.qml 0
+State should \e never be stored in a delegate.
 */
 QDeclarativeComponent *QDeclarativeGridView::delegate() const
 {
 Q_D(const QDeclarativeGridView);
 if (d->model) {
 dataModel->setDelegate(delegate);
 if (isComponentComplete()) {
 refill();
 d->moveReason = QDeclarativeGridViewPrivate::SetIndex;
 d->updateCurrent(d->currentIndex);
+if (d->highlight && d->currentItem) {
+d->highlight->setPosition(d->currentItem->colPos(), d->currentItem->rowPos());
+d->updateTrackedItem();
+}
+d->moveReason = QDeclarativeGridViewPrivate::Other;
 }
 emit delegateChanged();
 }
 }
 /*!
 \qmlproperty int GridView::currentIndex
 \qmlproperty Item GridView::currentItem
-\c currentIndex holds the index of the current item.
+The \c currentIndex property holds the index of the current item, and
-\c currentItem is the current item.  Note that the position of the current item
+\c currentItem holds the current item.
-may only be approximate until it becomes visible in the view.
+If highlightFollowsCurrentItem is \c true, setting either of these
+properties will smoothly scroll the GridView so that the current
+item becomes visible.
+Note that the position of the current item
+may only be approximate until it becomes visible in the view.
 */
 int QDeclarativeGridView::currentIndex() const
 {
 Q_D(const QDeclarativeGridView);
 return d->currentIndex;
 Q_D(QDeclarativeGridView);
 if (d->requestedIndex >= 0) // currently creating item
 return;
 if (isComponentComplete() && d->isValid() && index != d->currentIndex && index < d->model->count() && index >= 0) {
 d->moveReason = QDeclarativeGridViewPrivate::SetIndex;
-cancelFlick();
 d->updateCurrent(index);
 } else if (index != d->currentIndex) {
 d->currentIndex = index;
 emit currentIndexChanged();
 }
 }
 /*!
 \qmlproperty Item GridView::highlightItem
-\c highlightItem holds the highlight item, which was created
+This holds the highlight item created from the \l highlight component.
-from the \l highlight component.
 The highlightItem is managed by the view unless
 \l highlightFollowsCurrentItem is set to false.
 \sa highlight, highlightFollowsCurrentItem
 /*!
 \qmlproperty Component GridView::highlight
 This property holds the component to use as the highlight.
-An instance of the highlight component will be created for each view.
+An instance of the highlight component is created for each view.
-The geometry of the resultant component instance will be managed by the view
+The geometry of the resulting component instance will be managed by the view
 so as to stay with the current item, unless the highlightFollowsCurrentItem property is false.
-The below example demonstrates how to make a simple highlight:
-\snippet doc/src/snippets/declarative/gridview/gridview.qml 1
 \sa highlightItem, highlightFollowsCurrentItem
 */
 QDeclarativeComponent *QDeclarativeGridView::highlight() const
 {
 /*!
 \qmlproperty bool GridView::highlightFollowsCurrentItem
 This property sets whether the highlight is managed by the view.
-If highlightFollowsCurrentItem is true, the highlight will be moved smoothly
+If this property is true (the default value), the highlight is moved smoothly
-to follow the current item.  If highlightFollowsCurrentItem is false, the
+to follow the current item.  Otherwise, the
-highlight will not be moved by the view, and must be implemented
+highlight is not moved by the view, and any movement must be implemented
-by the highlight component, for example:
+by the highlight.
-\code
+Here is a highlight with its motion defined by a \l {SpringAnimation} item:
-Component {
-id: myHighlight
+\snippet doc/src/snippets/declarative/gridview/gridview.qml highlightFollowsCurrentItem
-Rectangle {
-id: wrapper; color: "lightsteelblue"; radius: 4; width: 320; height: 60
-SpringFollow on y { source: wrapper.GridView.view.currentItem.y; spring: 3; damping: 0.2 }
-SpringFollow on x { source: wrapper.GridView.view.currentItem.x; spring: 3; damping: 0.2 }
-}
-}
-\endcode
 */
 bool QDeclarativeGridView::highlightFollowsCurrentItem() const
 {
 Q_D(const QDeclarativeGridView);
 return d->autoHighlight;
 /*!
 \qmlproperty real GridView::preferredHighlightBegin
 \qmlproperty real GridView::preferredHighlightEnd
 \qmlproperty enumeration GridView::highlightRangeMode
-These properties set the preferred range of the highlight (current item)
+These properties define the preferred range of the highlight (for the current item)
-within the view.
+within the view. The \c preferredHighlightBegin value must be less than the
+\c preferredHighlightEnd value.
-Note that this is the correct way to influence where the
-current item ends up when the view scrolls. For example, if you want the
+These properties affect the position of the current item when the view is scrolled.
-currently selected item to be in the middle of the list, then set the
+For example, if the currently selected item should stay in the middle of the
-highlight range to be where the middle item would go. Then, when the view scrolls,
+view when it is scrolled, set the \c preferredHighlightBegin and
-the currently selected item will be the item at that spot. This also applies to
+\c preferredHighlightEnd values to the top and bottom coordinates of where the middle
-when the currently selected item changes - it will scroll to within the preferred
+item would be. If the \c currentItem is changed programmatically, the view will
-highlight range. Furthermore, the behaviour of the current item index will occur
+automatically scroll so that the current item is in the middle of the view.
-whether or not a highlight exists.
+Furthermore, the behavior of the current item index will occur whether or not a
+highlight exists.
-If highlightRangeMode is set to \e GridView.ApplyRange the view will
-attempt to maintain the highlight within the range, however
+Valid values for \c highlightRangeMode are:
-the highlight can move outside of the range at the ends of the list
-or due to a mouse interaction.
+\list
+\o GridView.ApplyRange - the view attempts to maintain the highlight within the range.
-If highlightRangeMode is set to \e GridView.StrictlyEnforceRange the highlight will never
+However, the highlight can move outside of the range at the ends of the view or due
-move outside of the range.  This means that the current item will change
+to mouse interaction.
-if a keyboard or mouse action would cause the highlight to move
+\o GridView.StrictlyEnforceRange - the highlight never moves outside of the range.
-outside of the range.
+The current item changes if a keyboard or mouse action would cause the highlight to move
+outside of the range.
-The default value is \e GridView.NoHighlightRange.
+\o GridView.NoHighlightRange - this is the default value.
+\endlist
-Note that a valid range requires preferredHighlightEnd to be greater
-than or equal to preferredHighlightBegin.
 */
 qreal QDeclarativeGridView::preferredHighlightBegin() const
 {
 Q_D(const QDeclarativeGridView);
 return d->highlightRangeStart;
 /*!
 \qmlproperty enumeration GridView::flow
 This property holds the flow of the grid.
-Possible values are \c GridView.LeftToRight (default) and \c GridView.TopToBottom.
+Possible values:
-If \a flow is \c GridView.LeftToRight, the view will scroll vertically.
+\list
-If \a flow is \c GridView.TopToBottom, the view will scroll horizontally.
+\o GridView.LeftToRight (default) - Items are laid out from left to right, and the view scrolls vertically
+\o GridView.TopToBottom - Items are laid out from top to bottom, and the view scrolls horizontally
+\endlist
 */
 QDeclarativeGridView::Flow QDeclarativeGridView::flow() const
 {
 Q_D(const QDeclarativeGridView);
 return d->flow;
 /*!
 \qmlproperty bool GridView::keyNavigationWraps
 This property holds whether the grid wraps key navigation
-If this property is true then key presses to move off of one end of the grid will cause the
+If this is true, key navigation that would move the current item selection
-selection to jump to the other side.
+past one end of the view instead wraps around and moves the selection to
+the other end of the view.
+By default, key navigation is not wrapped.
 */
 bool QDeclarativeGridView::isWrapEnabled() const
 {
 Q_D(const QDeclarativeGridView);
 return d->wrap;
 /*!
 \qmlproperty int GridView::cellWidth
 \qmlproperty int GridView::cellHeight
-These properties holds the width and height of each cell in the grid
+These properties holds the width and height of each cell in the grid.
 The default cell size is 100x100.
 */
 int QDeclarativeGridView::cellWidth() const
 {
 }
 }
 /*!
 \qmlproperty enumeration GridView::snapMode
-This property determines where the view will settle following a drag or flick.
+This property determines how the view scrolling will settle following a drag or flick.
-The allowed values are:
+The possible values are:
 \list
-\o GridView.NoSnap (default) - the view will stop anywhere within the visible area.
+\o GridView.NoSnap (default) - the view stops anywhere within the visible area.
-\o GridView.SnapToRow - the view will settle with a row (or column for TopToBottom flow)
+\o GridView.SnapToRow - the view settles with a row (or column for \c GridView.TopToBottom flow)
 aligned with the start of the view.
-\o GridView.SnapOneRow - the view will settle no more than one row (or column for TopToBottom flow)
+\o GridView.SnapOneRow - the view will settle no more than one row (or column for \c GridView.TopToBottom flow)
 away from the first visible row at the time the mouse button is released.
 This mode is particularly useful for moving one page at a time.
 \endlist
 */
 Q_D(QDeclarativeGridView);
 if (d->snapMode != mode) {
 d->snapMode = mode;
 emit snapModeChanged();
 }
+}
+/*!
+\qmlproperty Component GridView::footer
+This property holds the component to use as the footer.
+An instance of the footer component is created for each view.  The
+footer is positioned at the end of the view, after any items.
+\sa header
+*/
+QDeclarativeComponent *QDeclarativeGridView::footer() const
+{
+Q_D(const QDeclarativeGridView);
+return d->footerComponent;
+}
+void QDeclarativeGridView::setFooter(QDeclarativeComponent *footer)
+{
+Q_D(QDeclarativeGridView);
+if (d->footerComponent != footer) {
+if (d->footer) {
+delete d->footer;
+d->footer = 0;
+}
+d->footerComponent = footer;
+d->updateFooter();
+d->updateGrid();
+emit footerChanged();
+}
+}
+/*!
+\qmlproperty Component GridView::header
+This property holds the component to use as the header.
+An instance of the header component is created for each view.  The
+header is positioned at the beginning of the view, before any items.
+\sa footer
+*/
+QDeclarativeComponent *QDeclarativeGridView::header() const
+{
+Q_D(const QDeclarativeGridView);
+return d->headerComponent;
+}
+void QDeclarativeGridView::setHeader(QDeclarativeComponent *header)
+{
+Q_D(QDeclarativeGridView);
+if (d->headerComponent != header) {
+if (d->header) {
+delete d->header;
+d->header = 0;
+}
+d->headerComponent = header;
+d->updateHeader();
+d->updateFooter();
+d->updateGrid();
+emit headerChanged();
+}
+}
+void QDeclarativeGridView::setContentX(qreal pos)
+{
+Q_D(QDeclarativeGridView);
+// Positioning the view manually should override any current movement state
+d->moveReason = QDeclarativeGridViewPrivate::Other;
+QDeclarativeFlickable::setContentX(pos);
+}
+void QDeclarativeGridView::setContentY(qreal pos)
+{
+Q_D(QDeclarativeGridView);
+// Positioning the view manually should override any current movement state
+d->moveReason = QDeclarativeGridViewPrivate::Other;
+QDeclarativeFlickable::setContentY(pos);
 }
 bool QDeclarativeGridView::event(QEvent *event)
 {
 Q_D(QDeclarativeGridView);
 {
 Q_D(const QDeclarativeGridView);
 if (d->flow == QDeclarativeGridView::TopToBottom)
 return QDeclarativeFlickable::minYExtent();
 qreal extent = -d->startPosition();
+if (d->header && d->visibleItems.count())
+extent += d->header->item->height();
 if (d->haveHighlightRange && d->highlightRange == StrictlyEnforceRange) {
 extent += d->highlightRangeStart;
 extent = qMax(extent, -(d->rowPosAt(0) + d->rowSize() - d->highlightRangeEnd));
 }
 return extent;
 {
 Q_D(const QDeclarativeGridView);
 if (d->flow == QDeclarativeGridView::TopToBottom)
 return QDeclarativeFlickable::maxYExtent();
 qreal extent;
-if (d->haveHighlightRange && d->highlightRange == StrictlyEnforceRange) {
+if (!d->model || !d->model->count()) {
+extent = 0;
+} else if (d->haveHighlightRange && d->highlightRange == StrictlyEnforceRange) {
 extent = -(d->rowPosAt(d->model->count()-1) - d->highlightRangeStart);
 if (d->highlightRangeEnd != d->highlightRangeStart)
 extent = qMin(extent, -(d->endPosition() - d->highlightRangeEnd + 1));
 } else {
 extent = -(d->endPosition() - height());
 }
+if (d->footer)
+extent -= d->footer->item->height();
 const qreal minY = minYExtent();
 if (extent > minY)
 extent = minY;
 return extent;
 }
 {
 Q_D(const QDeclarativeGridView);
 if (d->flow == QDeclarativeGridView::LeftToRight)
 return QDeclarativeFlickable::minXExtent();
 qreal extent = -d->startPosition();
+if (d->header && d->visibleItems.count())
+extent += d->header->item->width();
 if (d->haveHighlightRange && d->highlightRange == StrictlyEnforceRange) {
 extent += d->highlightRangeStart;
 extent = qMax(extent, -(d->rowPosAt(0) + d->rowSize() - d->highlightRangeEnd));
 }
 return extent;
 {
 Q_D(const QDeclarativeGridView);
 if (d->flow == QDeclarativeGridView::LeftToRight)
 return QDeclarativeFlickable::maxXExtent();
 qreal extent;
-if (d->haveHighlightRange && d->highlightRange == StrictlyEnforceRange) {
+if (!d->model || !d->model->count()) {
+extent = 0;
+} if (d->haveHighlightRange && d->highlightRange == StrictlyEnforceRange) {
 extent = -(d->rowPosAt(d->model->count()-1) - d->highlightRangeStart);
 if (d->highlightRangeEnd != d->highlightRangeStart)
 extent = qMin(extent, -(d->endPosition() - d->highlightRangeEnd + 1));
 } else {
-extent = -(d->endPosition() - height());
+extent = -(d->endPosition() - width());
 }
+if (d->footer)
+extent -= d->footer->item->width();
 const qreal minX = minXExtent();
 if (extent > minX)
 extent = minX;
 return extent;
 }
 \qmlmethod GridView::moveCurrentIndexUp()
 Move the currentIndex up one item in the view.
 The current index will wrap if keyNavigationWraps is true and it
 is currently at the end.
+\bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativeGridView::moveCurrentIndexUp()
 {
 Q_D(QDeclarativeGridView);
 if (d->flow == QDeclarativeGridView::LeftToRight) {
 \qmlmethod GridView::moveCurrentIndexDown()
 Move the currentIndex down one item in the view.
 The current index will wrap if keyNavigationWraps is true and it
 is currently at the end.
+\bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativeGridView::moveCurrentIndexDown()
 {
 Q_D(QDeclarativeGridView);
 if (d->flow == QDeclarativeGridView::LeftToRight) {
 \qmlmethod GridView::moveCurrentIndexLeft()
 Move the currentIndex left one item in the view.
 The current index will wrap if keyNavigationWraps is true and it
 is currently at the end.
+\bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativeGridView::moveCurrentIndexLeft()
 {
 Q_D(QDeclarativeGridView);
 if (d->flow == QDeclarativeGridView::LeftToRight) {
 \qmlmethod GridView::moveCurrentIndexRight()
 Move the currentIndex right one item in the view.
 The current index will wrap if keyNavigationWraps is true and it
 is currently at the end.
+\bold Note: methods should only be called after the Component has completed.
 */
 void QDeclarativeGridView::moveCurrentIndexRight()
 {
 Q_D(QDeclarativeGridView);
 if (d->flow == QDeclarativeGridView::LeftToRight) {
 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 GridView.Beginning - position item at the top (or left for \c GridView.TopToBottom flow) of the view.
-\o Center- position item in the center of the view.
+\o GridView.Center - position item in the center of the view.
-\o End - position item at bottom (or right for horizontal orientation) of the view.
+\o GridView.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
+\o GridView.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
+\o GridView.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.
+the view the item is positioned at the top (or left for \c GridView.TopToBottom flow) of the view.
 \endlist
 If positioning the view at the index would cause empty space to be displayed at
 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
+It is not recommended to use \l {Flickable::}{contentX} or \l {Flickable::}{contentY} to position the view
 at a particular index.  This is unreliable since removing items from the start
 of the view does not cause all other items to be repositioned.
-The correct way to bring an item into view is with positionViewAtIndex.
+The correct way to bring an item into view is with \c positionViewAtIndex.
+\bold Note: methods should only be called after the Component has completed.  To position
+the view at startup, this method should be called by Component.onCompleted.  For
+example, to position the view at the end:
+\code
+Component.onCompleted: positionViewAtIndex(count - 1, GridView.Beginning)
+\endcode
 */
 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;
+if (d->layoutScheduled)
+d->layout();
 qreal pos = d->position();
 FxGridItem *item = d->visibleItem(index);
 if (!item) {
 int itemPos = d->rowPosAt(index);
 // save the currently visible items in case any of them end up visible again
 }
 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->moveReason = QDeclarativeGridViewPrivate::Other;
+cancelFlick();
 d->setPosition(pos);
 }
 d->fixupPosition();
 }
 coordinates.  If there is no item at the point specified, or the item is
 not visible -1 is returned.
 If the item is outside the visible area, -1 is returned, regardless of
 whether an item will exist at that point when scrolled into view.
+\bold Note: methods should only be called after the Component has completed.
 */
 int QDeclarativeGridView::indexAt(int x, int y) const
 {
 Q_D(const QDeclarativeGridView);
 for (int i = 0; i < d->visibleItems.count(); ++i) {
 Q_D(QDeclarativeGridView);
 QDeclarativeFlickable::componentComplete();
 d->updateGrid();
 if (d->isValid()) {
 refill();
+d->moveReason = QDeclarativeGridViewPrivate::SetIndex;
 if (d->currentIndex < 0)
 d->updateCurrent(0);
 else
 d->updateCurrent(d->currentIndex);
+if (d->highlight && d->currentItem) {
+d->highlight->setPosition(d->currentItem->colPos(), d->currentItem->rowPos());
+d->updateTrackedItem();
+}
+d->moveReason = QDeclarativeGridViewPrivate::Other;
 d->fixupPosition();
 }
 }
 void QDeclarativeGridView::trackedPositionChanged()
 {
 Q_D(QDeclarativeGridView);
 if (!d->trackedItem || !d->currentItem)
 return;
-if (!d->flickingHorizontally && !d->flickingVertically && !d->movingHorizontally && !d->movingVertically
+if (d->moveReason == QDeclarativeGridViewPrivate::SetIndex) {
-&& d->moveReason == QDeclarativeGridViewPrivate::SetIndex) {
 const qreal trackedPos = d->trackedItem->rowPos();
 const qreal viewPos = d->position();
+qreal pos = viewPos;
 if (d->haveHighlightRange) {
 if (d->highlightRange == StrictlyEnforceRange) {
-qreal pos = viewPos;
 if (trackedPos > pos + d->highlightRangeEnd - d->rowSize())
 pos = trackedPos - d->highlightRangeEnd + d->rowSize();
 if (trackedPos < pos + d->highlightRangeStart)
 pos = trackedPos - d->highlightRangeStart;
-d->setPosition(pos);
 } else {
-qreal pos = viewPos;
 if (trackedPos < d->startPosition() + d->highlightRangeStart) {
 pos = d->startPosition();
 } else if (d->trackedItem->endRowPos() > d->endPosition() - d->size() + d->highlightRangeEnd) {
 pos = d->endPosition() - d->size();
 if (pos < d->startPosition())
 pos = trackedPos - d->highlightRangeStart;
 } else if (trackedPos > viewPos + d->highlightRangeEnd - d->rowSize()) {
 pos = trackedPos - d->highlightRangeEnd + d->rowSize();
 }
 }
-d->setPosition(pos);
 }
 } else {
 if (trackedPos < viewPos && d->currentItem->rowPos() < viewPos) {
-d->setPosition(d->currentItem->rowPos() < trackedPos ? trackedPos : d->currentItem->rowPos());
+pos = d->currentItem->rowPos() < trackedPos ? trackedPos : d->currentItem->rowPos();
 } else if (d->trackedItem->endRowPos() > viewPos + d->size()
 && d->currentItem->endRowPos() > viewPos + d->size()) {
-qreal pos;
 if (d->trackedItem->endRowPos() < d->currentItem->endRowPos()) {
 pos = d->trackedItem->endRowPos() - d->size();
 if (d->rowSize() > d->size())
 pos = trackedPos;
 } else {
 pos = d->currentItem->endRowPos() - d->size();
 if (d->rowSize() > d->size())
 pos = d->currentItem->rowPos();
 }
-d->setPosition(pos);
+}
 }
+if (viewPos != pos) {
+cancelFlick();
+d->setPosition(pos);
 }
 }
 }
 void QDeclarativeGridView::itemsInserted(int modelIndex, int count)
 }
 if (removedVisible && d->visibleItems.isEmpty()) {
 d->timeline.clear();
 d->setPosition(0);
-if (d->itemCount == 0)
+if (d->itemCount == 0) {
+d->updateHeader();
+d->updateFooter();
 update();
+}
 }
 emit countChanged();
 }
 Q_D(QDeclarativeGridView);
 d->clear();
 refill();
 d->moveReason = QDeclarativeGridViewPrivate::SetIndex;
 d->updateCurrent(d->currentIndex);
+if (d->highlight && d->currentItem) {
+d->highlight->setPosition(d->currentItem->colPos(), d->currentItem->rowPos());
+d->updateTrackedItem();
+}
+d->moveReason = QDeclarativeGridViewPrivate::Other;
 emit countChanged();
 }
 void QDeclarativeGridView::createdItem(int index, QDeclarativeItem *item)
 {

changeset 33	3e2da88830cd
parent 30	5dc02b23752f
child 37	758a864f9613