Doc: add documentation for new overloads, and mark old overloads that

might lead to incorrect results as obsolete (and explain why).

1 files changed, 57 insertions, 5 deletions

diff --git a/src/gui/graphicsview/qgraphicsscene.cpp b/src/gui/graphicsview/qgraphicsscene.cpp
index 6b6080b..53aea58 100644
--- a/src/gui/graphicsview/qgraphicsscene.cpp
+++ b/src/gui/graphicsview/qgraphicsscene.cpp
@@ -1587,10 +1587,16 @@ QList<QGraphicsItem *> QGraphicsScene::items(Qt::SortOrder order) const
 }
 
 /*!
+    \obsolete
+
     Returns all visible items at position \a pos in the scene. The items are
     listed in descending stacking order (i.e., the first item in the list is the
     top-most item, and the last item is the bottom-most item).
 
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
+
     \sa itemAt()
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos) const
@@ -1600,9 +1606,8 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos) const
 }
 
 /*!
-    \fn QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rectangle, Qt::ItemSelectionMode mode) const
-
     \overload
+    \obsolete
 
     Returns all visible items that, depending on \a mode, are either inside or
     intersect with the specified \a rectangle.
@@ -1610,19 +1615,28 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos) const
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a rectangle are returned.
 
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
+
     \sa itemAt()
 */
-QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelectionMode mode) const
+QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rectangle, Qt::ItemSelectionMode mode) const
 {
     Q_D(const QGraphicsScene);
-    return d->index->items(rect, mode, Qt::AscendingOrder);
+    return d->index->items(rectangle, mode, Qt::AscendingOrder);
 }
 
 /*!
     \fn QList<QGraphicsItem *> QGraphicsScene::items(qreal x, qreal y, qreal w, qreal h, Qt::ItemSelectionMode mode) const
+    \obsolete
     \since 4.3
 
     This convenience function is equivalent to calling items(QRectF(\a x, \a y, \a w, \a h), \a mode).
+    
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
 */
 
 /*!
@@ -1641,6 +1655,7 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelecti
 
 /*!
     \overload
+    \obsolete
 
     Returns all visible items that, depending on \a mode, are either inside or
     intersect with the polygon \a polygon.
@@ -1648,6 +1663,10 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelecti
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a polygon are returned.
 
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
+
     \sa itemAt()
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemSelectionMode mode) const
@@ -1658,6 +1677,7 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemS
 
 /*!
     \overload
+    \obsolete
 
     Returns all visible items that, depending on \a path, are either inside or
     intersect with the path \a path.
@@ -1665,6 +1685,10 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemS
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a path are returned.
 
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
+
     \sa itemAt()
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemSelectionMode mode) const
@@ -1790,11 +1814,18 @@ QList<QGraphicsItem *> QGraphicsScene::collidingItems(const QGraphicsItem *item,
 }
 
 /*!
+    \overload
+    \obsolete
+
     Returns the topmost visible item at the specified \a position, or 0 if
     there are no items at this position.
 
     \note The topmost item is the one with the highest Z-value.
 
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
+
     \sa items(), collidingItems(), QGraphicsItem::setZValue()
 */
 QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position) const
@@ -1804,7 +1835,6 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position) const
 }
 
 /*!
-    \overload
     \since 4.6
 
     Returns the topmost visible item at the specified \a position, or 0
@@ -1825,8 +1855,26 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform
 }
 
 /*!
+    \fn QGraphicsScene::itemAt(qreal x, qreal y, const QTransform &deviceTransform) const
+    \overload
+    \since 4.6
+
+    Returns the topmost item at the position specified by (\a x, \a
+    y), or 0 if there are no items at this position.
+
+    \a deviceTransform is the transformation that applies to the view, and needs to
+    be provided if the scene contains items that ignore transformations.
+
+    This convenience function is equivalent to calling \c
+    {itemAt(QPointF(x, y), deviceTransform)}.
+
+    \note The topmost item is the one with the highest Z-value.
+*/
+
+/*!
     \fn QGraphicsScene::itemAt(qreal x, qreal y) const
     \overload
+    \obsolete
 
     Returns the topmost item at the position specified by (\a x, \a
     y), or 0 if there are no items at this position.
@@ -1834,6 +1882,10 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform
     This convenience function is equivalent to calling \c
     {itemAt(QPointF(x, y))}.
 
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
+
     \note The topmost item is the one with the highest Z-value.
 */