Document how opacity affects QGraphicsScene item queries.

Currently, QGraphicsScene::items() and related functions only return
items that are visible. The definition of visible effectively means
any item for whom isVisible() returns false or opacity() returns 0.0.
However, this is not documented anywhere.

Also fixed some typos/grammatical errors.

Change-Id: Ia6d1f7d63024dc9412438fe97748d7a69ee8225b
Reviewed-by: Qt Doc Bot <qt_docbot@qt-project.org>
Reviewed-by: Thomas McGuire <thomas.mcguire@kdab.com>
Reviewed-by: Andreas Aardal Hanssen <andreas@hanssen.name>
Reviewed-by: Geir Vattekar <geir.vattekar@nokia.com>

2 files changed, 51 insertions, 18 deletions

diff --git a/src/widgets/graphicsview/qgraphicsitem.cpp b/src/widgets/graphicsview/qgraphicsitem.cpp
index c4c9fff245..b82190575f 100644
--- a/src/widgets/graphicsview/qgraphicsitem.cpp
+++ b/src/widgets/graphicsview/qgraphicsitem.cpp
@@ -2606,7 +2606,8 @@ void QGraphicsItem::setSelected(bool selected)
     Returns this item's local opacity, which is between 0.0 (transparent) and
     1.0 (opaque). This value is combined with parent and ancestor values into
     the effectiveOpacity(). The effective opacity decides how the item is
-    rendered.
+    rendered and also affects its visibility when queried by functions such as
+    QGraphicsView::items().
 
     The opacity property decides the state of the painter passed to the
     paint() function. If the item is cached, i.e., ItemCoordinateCache or
diff --git a/src/widgets/graphicsview/qgraphicsscene.cpp b/src/widgets/graphicsview/qgraphicsscene.cpp
index 313e713946..07f1119dde 100644
--- a/src/widgets/graphicsview/qgraphicsscene.cpp
+++ b/src/widgets/graphicsview/qgraphicsscene.cpp
@@ -98,7 +98,7 @@
 
     One of QGraphicsScene's greatest strengths is its ability to efficiently
     determine the location of items. Even with millions of items on the scene,
-    the items() functions can determine the location of an item within few
+    the items() functions can determine the location of an item within a few
     milliseconds. There are several overloads to items(): one that finds items
     at a certain position, one that finds items inside or intersecting with a
     polygon or a rectangle, and more. The list of returned items is sorted by
@@ -1915,7 +1915,7 @@ void QGraphicsScene::setSortCacheEnabled(bool enabled)
 
 /*!
     Calculates and returns the bounding rect of all items on the scene. This
-    function works by iterating over all items, and because if this, it can
+    function works by iterating over all items, and because of this, it can
     be slow for large scenes.
 
     \sa sceneRect()
@@ -1960,7 +1960,9 @@ QList<QGraphicsItem *> QGraphicsScene::items(Qt::SortOrder order) const
 
     \brief Returns all visible items that, depending on \a mode, are
     either inside or intersect with the rectangle defined by \a x, \a y,
-    \a w and \a h, in a list sorted using \a order.
+    \a w and \a h, in a list sorted using \a order. In this case, "visible" defines items for which:
+    isVisible() returns true, effectiveOpacity() returns a value greater than 0.0
+    (which is fully transparent) and the parent item does not clip it.
 
     \a deviceTransform is the transformation that applies to the view, and needs to
     be provided if the scene contains items that ignore transformations.
@@ -1971,7 +1973,9 @@ QList<QGraphicsItem *> QGraphicsScene::items(Qt::SortOrder order) const
     \since 4.6
 
     \brief Returns all visible items that, depending on \a mode, are at
-    the specified \a pos in a list sorted using \a order.
+    the specified \a pos in a list sorted using \a order. In this case, "visible" defines items for which:
+    isVisible() returns true, effectiveOpacity() returns a value greater than 0.0
+    (which is fully transparent) and the parent item does not clip it.
 
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with \a pos are returned.
@@ -1994,8 +1998,10 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos, Qt::ItemSelecti
     \since 4.6
 
     \brief Returns all visible items that, depending on \a mode, are
-    either inside or intersect with the specified \a rect and return a
-    list sorted using \a order.
+    either inside or intersect with the specified \a rect, in a
+    list sorted using \a order. In this case, "visible" defines items for which:
+    isVisible() returns true, effectiveOpacity() returns a value greater than 0.0
+    (which is fully transparent) and the parent item does not clip it.
 
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a rect are returned.
@@ -2018,8 +2024,10 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelecti
     \since 4.6
 
     \brief Returns all visible items that, depending on \a mode, are
-    either inside or intersect with the specified \a polygon and return
-    a list sorted using \a order.
+    either inside or intersect with the specified \a polygon, in
+    a list sorted using \a order. In this case, "visible" defines items for which:
+    isVisible() returns true, effectiveOpacity() returns a value greater than 0.0
+    (which is fully transparent) and the parent item does not clip it.
 
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a polygon are returned.
@@ -2042,8 +2050,10 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemS
     \since 4.6
 
     \brief Returns all visible items that, depending on \a mode, are
-    either inside or intersect with the specified \a path and return a
-    list sorted using \a order.
+    either inside or intersect with the specified \a path, in a
+    list sorted using \a order. In this case, "visible" defines items for which:
+    isVisible() returns true, effectiveOpacity() returns a value greater than 0.0
+    (which is fully transparent) and the parent item does not clip it.
 
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a path are returned.
@@ -2102,6 +2112,8 @@ QList<QGraphicsItem *> QGraphicsScene::collidingItems(const QGraphicsItem *item,
     contains items that ignore transformations. Use the overload that takes
     a QTransform instead.
 
+    Note: See items() for a definition of which items are considered visible by this function.
+
     \sa items(), collidingItems(), {QGraphicsItem#Sorting}{Sorting}
 */
 
@@ -2114,6 +2126,8 @@ QList<QGraphicsItem *> QGraphicsScene::collidingItems(const QGraphicsItem *item,
     \a deviceTransform is the transformation that applies to the view, and needs to
     be provided if the scene contains items that ignore transformations.
 
+    Note: See items() for a definition of which items are considered visible by this function.
+
     \sa items(), collidingItems(), {QGraphicsItem#Sorting}{Sorting}
 */
 QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform &deviceTransform) const
@@ -2128,7 +2142,7 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform
     \overload
     \since 4.6
 
-    Returns the topmost item at the position specified by (\a x, \a
+    Returns the topmost visible 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
@@ -2136,6 +2150,8 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform
 
     This convenience function is equivalent to calling \c
     {itemAt(QPointF(x, y), deviceTransform)}.
+
+    Note: See items() for a definition of which items are considered visible by this function.
 */
 
 /*!
@@ -2143,7 +2159,7 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform
     \overload
     \obsolete
 
-    Returns the topmost item at the position specified by (\a x, \a
+    Returns the topmost visible item at the position specified by (\a x, \a
     y), or 0 if there are no items at this position.
 
     This convenience function is equivalent to calling \c
@@ -2152,6 +2168,8 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform
     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: See items() for a definition of which items are considered visible by this function.
 */
 
 /*!
@@ -3455,10 +3473,12 @@ bool QGraphicsScene::eventFilter(QObject *watched, QEvent *event)
 /*!
     This event handler, for event \a contextMenuEvent, can be reimplemented in
     a subclass to receive context menu events. The default implementation
-    forwards the event to the topmost item that accepts context menu events at
+    forwards the event to the topmost visible item that accepts context menu events at
     the position of the event. If no items accept context menu events at this
     position, the event is ignored.
 
+    Note: See items() for a definition of which items are considered visible by this function.
+
     \sa QGraphicsItem::contextMenuEvent()
 */
 void QGraphicsScene::contextMenuEvent(QGraphicsSceneContextMenuEvent *contextMenuEvent)
@@ -3505,6 +3525,8 @@ void QGraphicsScene::dragEnterEvent(QGraphicsSceneDragDropEvent *event)
     This event handler, for event \a event, can be reimplemented in a subclass
     to receive drag move events for the scene.
 
+    Note: See items() for a definition of which items are considered visible by this function.
+
     \sa QGraphicsItem::dragMoveEvent(), dragEnterEvent(), dragLeaveEvent(),
     dropEvent()
 */
@@ -3679,11 +3701,13 @@ void QGraphicsScene::focusOutEvent(QFocusEvent *focusEvent)
     requested.
 
     The default implementation shows the tooltip of the topmost
-    item, i.e., the item with the highest z-value, at the mouse
+    visible item, i.e., the item with the highest z-value, at the mouse
     cursor position. If no item has a tooltip set, this function
     does nothing.
 
-   \sa QGraphicsItem::toolTip(), QGraphicsSceneHelpEvent
+    Note: See items() for a definition of which items are considered visible by this function.
+
+    \sa QGraphicsItem::toolTip(), QGraphicsSceneHelpEvent
 */
 void QGraphicsScene::helpEvent(QGraphicsSceneHelpEvent *helpEvent)
 {
@@ -3733,9 +3757,11 @@ bool QGraphicsScenePrivate::itemAcceptsHoverEvents_helper(const QGraphicsItem *i
 /*!
     This event handler, for event \a hoverEvent, can be reimplemented in a
     subclass to receive hover enter events. The default implementation
-    forwards the event to the topmost item that accepts hover events at the
+    forwards the event to the topmost visible item that accepts hover events at the
     scene position from the event.
 
+    Note: See items() for a definition of which items are considered visible by this function.
+
     \sa QGraphicsItem::hoverEvent(), QGraphicsItem::setAcceptHoverEvents()
 */
 bool QGraphicsScenePrivate::dispatchHoverEvent(QGraphicsSceneHoverEvent *hoverEvent)
@@ -3911,7 +3937,7 @@ void QGraphicsScene::keyReleaseEvent(QKeyEvent *keyEvent)
 
     The default implementation depends on the state of the scene. If
     there is a mouse grabber item, then the event is sent to the mouse
-    grabber. Otherwise, it is forwarded to the topmost item that
+    grabber. Otherwise, it is forwarded to the topmost visible item that
     accepts mouse events at the scene position from the event, and
     that item promptly becomes the mouse grabber item.
 
@@ -3919,6 +3945,8 @@ void QGraphicsScene::keyReleaseEvent(QKeyEvent *keyEvent)
     selection area is reset, any focus item loses its input focus, and
     the event is then ignored.
 
+    Note: See items() for a definition of which items are considered visible by this function.
+
     \sa QGraphicsItem::mousePressEvent(),
     QGraphicsItem::setAcceptedMouseButtons()
 */
@@ -4020,6 +4048,8 @@ void QGraphicsScene::mouseReleaseEvent(QGraphicsSceneMouseEvent *mouseEvent)
 
     The default implementation is similar to mousePressEvent().
 
+    Note: See items() for a definition of which items are considered visible by this function.
+
     \sa QGraphicsItem::mousePressEvent(), QGraphicsItem::mouseMoveEvent(),
     QGraphicsItem::mouseReleaseEvent(), QGraphicsItem::setAcceptedMouseButtons()
 */
@@ -4038,6 +4068,8 @@ void QGraphicsScene::mouseDoubleClickEvent(QGraphicsSceneMouseEvent *mouseEvent)
     until the event is accepted, or it reaches the scene. If no items accept
     the event, it is ignored.
 
+    Note: See items() for a definition of which items are considered visible by this function.
+
     \sa QGraphicsItem::wheelEvent()
 */
 void QGraphicsScene::wheelEvent(QGraphicsSceneWheelEvent *wheelEvent)