1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document how opacity affects QGraphicsScene item queries.

Browse Source 
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>
This commit is contained in:
Mitch Curtis 2012-09-07 10:17:54 +02:00 committed by Qt by Nokia
parent 72ea9e1e94
commit 1b0e279d5b
2 changed files with 51 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
src/widgets/graphicsview/qgraphicsitem.cpp
View File

@ -2606,7 +2606,8 @@ void QGraphicsItem::setSelected(bool selected)
Returns this item's local opacity, which is between 0.0 (transparent) and 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 1.0 (opaque). This value is combined with parent and ancestor values into
the effectiveOpacity(). The effective opacity decides how the item is 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 The opacity property decides the state of the painter passed to the
paint() function. If the item is cached, i.e., ItemCoordinateCache or paint() function. If the item is cached, i.e., ItemCoordinateCache or

64
src/widgets/graphicsview/qgraphicsscene.cpp
View File

@ -98,7 +98,7 @@
One of QGraphicsScene's greatest strengths is its ability to efficiently One of QGraphicsScene's greatest strengths is its ability to efficiently
determine the location of items. Even with millions of items on the scene, 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 milliseconds. There are several overloads to items(): one that finds items
at a certain position, one that finds items inside or intersecting with a 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 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 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. be slow for large scenes.
\sa sceneRect() \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 \brief Returns all visible items that, depending on \a mode, are
either inside or intersect with the rectangle defined by \a x, \a y, 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 \a deviceTransform is the transformation that applies to the view, and needs to
be provided if the scene contains items that ignore transformations. 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 \since 4.6
\brief Returns all visible items that, depending on \a mode, are at \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 The default value for \a mode is Qt::IntersectsItemShape; all items whose
exact shape intersects with \a pos are returned. exact shape intersects with \a pos are returned.
@ -1994,8 +1998,10 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos, Qt::ItemSelecti
\since 4.6 \since 4.6
\brief Returns all visible items that, depending on \a mode, are \brief Returns all visible items that, depending on \a mode, are
either inside or intersect with the specified \a rect and return a either inside or intersect with the specified \a rect, in a
list sorted using \a order. 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 The default value for \a mode is Qt::IntersectsItemShape; all items whose
exact shape intersects with or is contained by \a rect are returned. 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 \since 4.6
\brief Returns all visible items that, depending on \a mode, are \brief Returns all visible items that, depending on \a mode, are
either inside or intersect with the specified \a polygon and return either inside or intersect with the specified \a polygon, in
a list sorted using \a order. 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 The default value for \a mode is Qt::IntersectsItemShape; all items whose
exact shape intersects with or is contained by \a polygon are returned. 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 \since 4.6
\brief Returns all visible items that, depending on \a mode, are \brief Returns all visible items that, depending on \a mode, are
either inside or intersect with the specified \a path and return a either inside or intersect with the specified \a path, in a
list sorted using \a order. 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 The default value for \a mode is Qt::IntersectsItemShape; all items whose
exact shape intersects with or is contained by \a path are returned. 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 contains items that ignore transformations. Use the overload that takes
a QTransform instead. a QTransform instead.
Note: See items() for a definition of which items are considered visible by this function.
\sa items(), collidingItems(), {QGraphicsItem#Sorting}{Sorting} \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 \a deviceTransform is the transformation that applies to the view, and needs to
be provided if the scene contains items that ignore transformations. 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} \sa items(), collidingItems(), {QGraphicsItem#Sorting}{Sorting}
*/ */
QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform &deviceTransform) const QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform &deviceTransform) const
@ -2128,7 +2142,7 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform
\overload \overload
\since 4.6 \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. y), or 0 if there are no items at this position.
\a deviceTransform is the transformation that applies to the view, and needs to \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 This convenience function is equivalent to calling \c
{itemAt(QPointF(x, y), deviceTransform)}. {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 \overload
\obsolete \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. y), or 0 if there are no items at this position.
This convenience function is equivalent to calling \c 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 This function is deprecated and returns incorrect results if the scene
contains items that ignore transformations. Use the overload that takes contains items that ignore transformations. Use the overload that takes
a QTransform instead. 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 This event handler, for event \a contextMenuEvent, can be reimplemented in
a subclass to receive context menu events. The default implementation 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 the position of the event. If no items accept context menu events at this
position, the event is ignored. position, the event is ignored.
Note: See items() for a definition of which items are considered visible by this function.
\sa QGraphicsItem::contextMenuEvent() \sa QGraphicsItem::contextMenuEvent()
*/ */
void QGraphicsScene::contextMenuEvent(QGraphicsSceneContextMenuEvent *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 This event handler, for event \a event, can be reimplemented in a subclass
to receive drag move events for the scene. 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(), \sa QGraphicsItem::dragMoveEvent(), dragEnterEvent(), dragLeaveEvent(),
dropEvent() dropEvent()
*/ */
@ -3679,10 +3701,12 @@ void QGraphicsScene::focusOutEvent(QFocusEvent *focusEvent)
requested. requested.
The default implementation shows the tooltip of the topmost 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 cursor position. If no item has a tooltip set, this function
does nothing. does nothing.
Note: See items() for a definition of which items are considered visible by this function.
\sa QGraphicsItem::toolTip(), QGraphicsSceneHelpEvent \sa QGraphicsItem::toolTip(), QGraphicsSceneHelpEvent
*/ */
void QGraphicsScene::helpEvent(QGraphicsSceneHelpEvent *helpEvent) 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 This event handler, for event \a hoverEvent, can be reimplemented in a
subclass to receive hover enter events. The default implementation 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. 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() \sa QGraphicsItem::hoverEvent(), QGraphicsItem::setAcceptHoverEvents()
*/ */
bool QGraphicsScenePrivate::dispatchHoverEvent(QGraphicsSceneHoverEvent *hoverEvent) 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 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 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 accepts mouse events at the scene position from the event, and
that item promptly becomes the mouse grabber item. 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 selection area is reset, any focus item loses its input focus, and
the event is then ignored. the event is then ignored.
Note: See items() for a definition of which items are considered visible by this function.
\sa QGraphicsItem::mousePressEvent(), \sa QGraphicsItem::mousePressEvent(),
QGraphicsItem::setAcceptedMouseButtons() QGraphicsItem::setAcceptedMouseButtons()
*/ */
@ -4020,6 +4048,8 @@ void QGraphicsScene::mouseReleaseEvent(QGraphicsSceneMouseEvent *mouseEvent)
The default implementation is similar to mousePressEvent(). 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(), \sa QGraphicsItem::mousePressEvent(), QGraphicsItem::mouseMoveEvent(),
QGraphicsItem::mouseReleaseEvent(), QGraphicsItem::setAcceptedMouseButtons() 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 until the event is accepted, or it reaches the scene. If no items accept
the event, it is ignored. the event, it is ignored.
Note: See items() for a definition of which items are considered visible by this function.
\sa QGraphicsItem::wheelEvent() \sa QGraphicsItem::wheelEvent()
*/ */
void QGraphicsScene::wheelEvent(QGraphicsSceneWheelEvent *wheelEvent) void QGraphicsScene::wheelEvent(QGraphicsSceneWheelEvent *wheelEvent)