QGraphicsItem Class

成员函数文档

[explicit] QGraphicsItem::QGraphicsItem(QGraphicsItem *parent = nullptr)

使用给定的parent 项构建一个QGraphicsItem。此操作不会修改QObject::parent()返回的父对象。

如果 `parent ` 为 `nullptr`，则可通过调用 `QGraphicsScene::addItem()` 将该项添加到场景中。此时，该项将成为顶级项。

另请参阅 QGraphicsScene::addItem() 和setParentItem()。

[virtual noexcept] QGraphicsItem::~QGraphicsItem()

删除QGraphicsItem 及其所有子对象。如果该对象当前与某个场景相关联，则在删除该对象之前，会先将其从场景中移除。

bool QGraphicsItem::acceptDrops() const

如果该项支持拖放事件，则返回true ；否则，返回false 。默认情况下，各项不支持拖放事件；对拖放操作而言，各项是透明的。

另请参阅 setAcceptDrops()。

bool QGraphicsItem::acceptHoverEvents() const

如果项目接受悬停事件（QGraphicsSceneHoverEvent ），则返回true ；否则，返回false 。默认情况下，项目不接受悬停事件。

另请参阅 setAcceptHoverEvents() 和setAcceptedMouseButtons()。

bool QGraphicsItem::acceptTouchEvents() const

如果某个项目支持touch events ，则返回true ；否则，返回false 。默认情况下，项目不支持触摸事件。

另请参阅 setAcceptTouchEvents()。

Qt::MouseButtons QGraphicsItem::acceptedMouseButtons() const

返回该项支持接收鼠标事件的鼠标按钮。默认情况下，支持所有鼠标按钮。

如果某个项目接受某个鼠标按钮，当该鼠标按钮触发按下事件时，该项目将成为鼠标抓取对象。但是，如果该项目不接受该按钮，QGraphicsScene 将把鼠标事件转发给其下方第一个接受该按钮的项目。

另请参阅 setAcceptedMouseButtons() 和mousePressEvent()。

[virtual] void QGraphicsItem::advance(int phase)

QGraphicsScene::advance() 插槽会针对所有物品调用此虚拟函数两次。在第一阶段，所有物品都会在phase == 0 的条件下被调用，这表示场景中的物品即将前进；随后，所有物品会在phase == 1 的条件下被调用。若需实现简单的场景控制动画，请重写此函数以更新您的物品。

默认实现不执行任何操作。

此函数专用于动画。另一种方法是继承QObject 和QGraphicsItem 的多重继承，并使用动画框架。

另请参阅 QGraphicsScene::advance() 和QTimeLine 。

[pure virtual] QRectF QGraphicsItem::boundingRect() const

该纯虚函数将项的外边界定义为一个矩形；所有绘制操作都必须限制在项的边界矩形内部。QGraphicsView 通过该函数来判断该项是否需要重绘。

尽管项的形状可以是任意的，但其边界矩形始终为矩形，且不受项的变换影响。

如果要更改项的边界矩形，必须先调用prepareGeometryChange()。 这会通知场景即将发生的更改，以便它能够更新其项目几何体索引；否则，场景将无法识别该项目的新几何体，结果将未定义（通常，视图中会残留渲染瑕疵）。

重写此函数，让QGraphicsView 确定小部件的哪些部分（如有）需要重绘。

注意：对于绘制轮廓/描边的形状，务必将笔宽的一半包含在边界矩形内。不过，无需对抗锯齿进行补偿。

示例：

QRectF CircleItem::boundingRect() const
{
    qreal penWidth = 1;
    return QRectF(-radius - penWidth / 2, -radius - penWidth / 2,
                  diameter + penWidth, diameter + penWidth);
}

另请参阅 boundingRegion()、shape()、contains()、《图形视图坐标系》以及prepareGeometryChange()。

QRegion QGraphicsItem::boundingRegion(const QTransform &itemToDeviceTransform) const

返回该项的边界区域。返回区域的坐标系取决于itemToDeviceTransform 。如果将一个单位坐标系QTransform 作为参数传递，则该函数将返回一个本机坐标区域。

边界区域描述了项目视觉内容的粗略轮廓。虽然其计算成本较高，但比boundingRect() 更精确，并且有助于在项目更新时避免不必要的重绘。对于细长的项目（例如线条或简单多边形），此方法尤其高效。 您可以通过调用setBoundingRegionGranularity() 来调整边界区域的粒度。默认粒度为 0；此时，项的边界区域与其边界矩形相同。

itemToDeviceTransform 是将项目坐标转换为设备坐标的变换。若希望该函数返回场景坐标系下的QRegion ，可将sceneTransform()作为参数传入。

另请参阅 boundingRegionGranularity()。

qreal QGraphicsItem::boundingRegionGranularity() const

返回项目的边界区域粒度；该值介于 0 到 1 之间（包含 0 和 1）。默认值为 0（即最低粒度，此时边界区域与项目的边界矩形相对应）。

另请参阅 setBoundingRegionGranularity()。

QGraphicsItem::CacheMode QGraphicsItem::cacheMode() const

返回该项的缓存模式。默认模式为NoCache （即缓存已禁用，所有绘制操作均立即执行）。

另请参阅 setCacheMode()。

QList<QGraphicsItem *> QGraphicsItem::childItems() const

返回该项的子项列表。

这些项按堆叠顺序排序。该排序同时考虑了项的插入顺序及其 Z 值。

另请参阅 setParentItem()、zValue() 以及Sorting 。

QRectF QGraphicsItem::childrenBoundingRect() const

返回该项后代（即其子项、子项的子项等）在本地坐标系中的边界矩形。该矩形将包含所有后代在映射到本地坐标系后的范围。如果该项没有子项，则该函数返回一个空的QRectF 。

这不包括该项自身的边界矩形；它仅返回其后代的累积边界矩形。若需包含该项自身的边界矩形，可使用 QRectF::operator|() 将boundingRect() 与 childrenBoundingRect() 进行逻辑与运算。

该函数的时间复杂度为线性；它通过遍历所有子元素来确定返回的边界矩形大小。

另请参阅 boundingRect() 和sceneBoundingRect()。

void QGraphicsItem::clearFocus()

从该项移开键盘输入焦点。

如果该项拥有焦点，系统会向该项发送一个focus out event 事件，告知其即将失去焦点。

只有设置了ItemIsFocusable 标志的项目，或者设置了适当焦点策略的控件，才能接受键盘焦点。

另请参阅 setFocus()、hasFocus() 和QGraphicsWidget::focusPolicy 。

QPainterPath QGraphicsItem::clipPath() const

返回该项的剪切路径；如果该项未被剪切，则返回一个空的QPainterPath 。剪切路径限制了该项的外观和交互（即限制了该项可以绘制和接收事件的区域）。

您可以通过设置ItemClipsToShape 或ItemClipsChildrenToShape 标志来启用剪切。该项的剪切路径是通过所有剪切父项形状的交集计算得出的。如果该项设置了ItemClipsToShape ，则最终的剪切路径会与该项自身的形状进行交集运算。

另请参阅 isClipped()、shape() 和setFlags()。

[virtual] bool QGraphicsItem::collidesWithItem(const QGraphicsItem *other, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const

如果该对象与other 发生碰撞，则返回true ；否则返回false 。

将mode 应用于other ，然后将生成的形状或边界矩形与该项的形状进行比较。mode 的默认值为Qt::IntersectsItemShape ；如果other 与该项的形状相交、包含该项或被该项包含，则视为与该项发生碰撞（详情请参见Qt::ItemSelectionMode ）。

默认实现基于形状交集，并会调用两个对象的shape()方法。由于任意形状与形状之间的交集运算复杂度会随着形状复杂度的增加而呈数量级增长，因此该操作可能耗时较长。 您可以选择在QGraphicsItem 的子类中重写此函数，以提供自定义算法。这使您能够利用自身项的形状中的自然约束条件，从而提高碰撞检测的性能。例如，通过比较两个未变换的完美圆形项的位置和半径，可以非常高效地确定它们的碰撞情况。

请注意，在重写此函数并在other 上调用shape() 或boundingRect() 时，必须先将返回的坐标映射到该对象的坐标系中，才能进行任何相交检测。

另请参阅 contains() 和shape()。

[virtual] bool QGraphicsItem::collidesWithPath(const QPainterPath &path, Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const

如果该项目与path 发生碰撞，则返回true 。

碰撞由mode 决定。mode 的默认值为Qt::IntersectsItemShape ；若path 与该项的形状相交、包含该项或被该项包含，则视为与该项发生碰撞。

请注意，该函数检查的是该项的形状或边界矩形（取决于mode ）是否包含在path 之中，而非path 是否包含在该项的形状或边界矩形之中。

另请参阅 collidesWithItem()、contains() 和shape()。

QList<QGraphicsItem *> QGraphicsItem::collidingItems(Qt::ItemSelectionMode mode = Qt::IntersectsItemShape) const

返回与该项发生碰撞的所有项的列表。

碰撞检测的方式由对与该项进行比较的其他项应用mode 函数来确定，即检查每个项的形状或边界矩形是否与该项的形状发生碰撞。mode 的默认值为Qt::IntersectsItemShape 。

另请参阅 collidesWithItem()。

QGraphicsItem *QGraphicsItem::commonAncestorItem(const QGraphicsItem *other) const

返回该项与other 之间的最近共同祖先项；若other 中任一项为nullptr ，或不存在共同祖先，则返回nullptr 。

另请参阅 isAncestorOf()。

[virtual] bool QGraphicsItem::contains(const QPointF &point) const

如果该项包含以本地坐标系表示的point ，则返回true ；否则返回false。该函数通常由QGraphicsView 调用，用于确定光标下方的项目是什么，因此该函数的实现应尽可能轻量级。

默认情况下，该函数会调用shape()，但您可以在子类中重写它，以提供（可能更高效的）实现。

另请参阅 shape()、boundingRect() 和collidesWithPath()。

[virtual protected] void QGraphicsItem::contextMenuEvent(QGraphicsSceneContextMenuEvent *event)

可以在子类中重写此事件处理程序，以处理上下文菜单事件。event 参数包含待处理事件的详细信息。

如果忽略该事件（即调用QEvent::ignore()），event 将传播到该项下的任何子项。如果没有任何子项接受该事件，则该事件将被场景忽略并传播到视图。

通常会在接收到上下文菜单事件时，通过调用 `QMenu ()` 来响应该事件。示例：

void CustomItem::contextMenuEvent(QGraphicsSceneContextMenuEvent *event)
{
    QMenu menu;
    QAction *removeAction = menu.addAction("Remove");
    QAction *markAction = menu.addAction("Mark");
    QAction *selectedAction = menu.exec(event->screenPos());
    // ...
}

默认实现会忽略该事件。

另请参阅 sceneEvent()。

QCursor QGraphicsItem::cursor() const

返回该项目的当前光标形状。当鼠标光标悬停在此项目上时，将显示此形状。有关各种有用的形状，请参阅list of predefined cursor objects 。

编辑器项目可能希望使用“I”形光标：

item->setCursor(Qt::IBeamCursor);

如果未设置光标，则使用下方项目的光标。

另请参阅 setCursor()、hasCursor()、unsetCursor()、QWidget::cursor 以及QGuiApplication::overrideCursor()。

QVariant QGraphicsItem::data(int key) const

返回该项针对键key 的自定义数据，格式为QVariant 。

自定义项数据可用于在任何项中存储任意属性。示例：

static const int ObjectName = 0;

QGraphicsItem *item = scene.itemAt(100, 50, transform);
if (item->data(ObjectName).toString().isEmpty()) {
    if (qgraphicsitem_cast<CustomItem *>(item))
        item->setData(ObjectName, "Custom");
}

Qt 不会使用此功能来存储数据；该功能仅为方便用户而提供。

另请参阅 setData()。

QTransform QGraphicsItem::deviceTransform(const QTransform &viewportTransform) const

返回该项的设备变换矩阵，使用viewportTransform 将场景坐标映射到设备坐标。该矩阵可用于将该项的本机坐标系中的坐标和几何形状映射到视口（或任何设备）的坐标系中。若要将坐标从视口映射出来，必须先对返回的矩阵进行求逆。

示例：

QGraphicsRectItem rect;
rect.setPos(100, 100);

rect.deviceTransform(view->viewportTransform()).map(QPointF(0, 0));
// returns the item's (0, 0) point in view's viewport coordinates

rect.deviceTransform(view->viewportTransform()).inverted().map(QPointF(100, 100));
// returns view's viewport's (100, 100) coordinate in item coordinates

该函数的作用等同于将该项的场景变换与视图的视口变换相结合，但它还支持ItemIgnoresTransformations 标志。设备变换可用于对不可变换的项进行精确的坐标映射（以及碰撞检测）。

另请参阅 transform()、setTransform()、scenePos()、《图形视图坐标系》以及itemTransform()。

[virtual protected] void QGraphicsItem::dragEnterEvent(QGraphicsSceneDragDropEvent *event)

该事件处理程序（针对事件event ）可以重新实现，以便接收该项目的拖动进入事件。当光标进入项目区域时，会触发拖动进入事件。

通过接受该事件（即调用QEvent::accept()），该项目除了接收拖动移动和拖动离开事件外，还将接受拖放事件。否则，该事件将被忽略并传播到下层项目。如果接受了该事件，在控制权返回事件循环之前，该项目将收到一个拖动移动事件。

dragEnterEvent 的常见实现会根据event 中关联的 MIME 数据来决定是接受还是忽略event 。示例：

CustomItem::CustomItem()
{
    setAcceptDrops(true);
    //...
}

void CustomItem::dragEnterEvent(QGraphicsSceneDragDropEvent *event)
{
    event->setAccepted(event->mimeData()->hasFormat("text/plain"));
}

默认情况下，项目不会接收拖放事件；要启用此功能，请调用 `setAcceptDrops(true)`。

默认实现不执行任何操作。

另请参阅 dropEvent()、dragMoveEvent() 和dragLeaveEvent()。

[virtual protected] void QGraphicsItem::dragLeaveEvent(QGraphicsSceneDragDropEvent *event)

此事件处理程序（针对event 事件）可以被重新实现，以便接收该项的拖动离开事件。当光标离开该项的区域时，会触发拖动离开事件。大多数情况下，您无需重新实现此函数，但它可用于重置该项的状态（例如，高亮显示）。

在 `event ` 上调用 `QEvent::ignore()` 或 `QEvent::accept()` 不会产生任何效果。

默认情况下，项目不会接收拖放事件；要启用此功能，请调用setAcceptDrops(true) 。

默认实现不执行任何操作。

另请参阅 dragEnterEvent()、dropEvent() 和dragMoveEvent()。

[virtual protected] void QGraphicsItem::dragMoveEvent(QGraphicsSceneDragDropEvent *event)

此事件处理程序（针对event 事件）可以被重新实现，以便接收该项的拖动移动事件。当光标在项的区域内移动时，会生成拖动移动事件。大多数情况下，您无需重新实现此函数；它用于指示仅项的某些部分可以接受拖放操作。

在event 上调用QEvent::ignore()或QEvent::accept()，可切换该项目是否接受来自该事件位置的拖放操作。默认情况下，event 被接受，这表示该项目允许在指定位置进行拖放。

默认情况下，项不会接收拖放事件；要启用此功能，请调用setAcceptDrops(true) 。

默认实现不执行任何操作。

另请参阅 dropEvent()、dragEnterEvent() 和dragLeaveEvent()。

[virtual protected] void QGraphicsItem::dropEvent(QGraphicsSceneDragDropEvent *event)

此事件处理程序（针对event 事件）可以重新实现，以便接收该项目的拖放事件。只有当最后一次拖动事件被接受时，项目才能接收拖放事件。

在event 上调用QEvent::ignore()或QEvent::accept()均无效。

默认情况下，项目不会接收拖放事件；要启用此功能，请调用setAcceptDrops(true) 。

默认实现不执行任何操作。

另请参阅 dragEnterEvent()、dragMoveEvent() 和dragLeaveEvent()。

qreal QGraphicsItem::effectiveOpacity() const

返回该元素的有效不透明度，其取值范围在 0.0（透明）到 1.0（不透明）之间。该值由该元素的本地不透明度及其父元素和祖先元素的不透明度综合决定。有效不透明度决定了该元素的渲染方式。

另请参阅 opacity()、setOpacity()、paint()、ItemIgnoresParentOpacity 以及ItemDoesntPropagateOpacityToChildren 。

void QGraphicsItem::ensureVisible(const QRectF &rect = QRectF(), int xmargin = 50, int ymargin = 50)

如果该项属于由QGraphicsView 所显示的场景的一部分，则此便捷函数将尝试滚动视图，以确保rect 在视图的视口内可见。如果rect 为空矩形（默认值），则QGraphicsItem 将默认为该项的边界矩形。xmargin 和ymargin 分别表示视图应用于边距的像素数。

如果无法到达指定的矩形位置，则将内容滚动到最近的有效位置。

如果该项目未被QGraphicsView 查看，则此函数不执行任何操作。

另请参阅 QGraphicsView::ensureVisible()。

void QGraphicsItem::ensureVisible(qreal x, qreal y, qreal w, qreal h, int xmargin = 50, int ymargin = 50)

此便捷函数等同于调用 ensureVisible(QRectF(x,y,w,h),xmargin,ymargin)。

bool QGraphicsItem::filtersChildEvents() const

如果该项过滤子事件（即原本 intended 发送给其任何子项的所有事件都会转而发送给该项），则返回 `true `；否则返回 `false`。

默认值为 false；不过滤子事件。

另请参阅 setFiltersChildEvents()。

QGraphicsItem::GraphicsItemFlags QGraphicsItem::flags() const

返回该控件的标志。这些标志描述了该控件哪些可配置功能已启用，哪些未启用。例如，如果标志中包含ItemIsFocusable ，则该控件可以接受输入焦点。

默认情况下，未启用任何标志。

另请参阅 setFlags() 和setFlag()。

[virtual protected] void QGraphicsItem::focusInEvent(QFocusEvent *event)

此事件处理程序（针对event 事件）可被重新实现，以便在该项的事件中获取焦点。默认实现会调用ensureVisible()。

另请参阅 focusOutEvent()、sceneEvent() 和setFocus()。

QGraphicsItem *QGraphicsItem::focusItem() const

如果该元素、其子元素或后代元素当前拥有输入焦点，则该函数将返回指向该元素的指针。如果没有任何后代元素拥有输入焦点，则返回nullptr 。

另请参阅 hasFocus()、setFocus() 和QWidget::focusWidget()。

[virtual protected] void QGraphicsItem::focusOutEvent(QFocusEvent *event)

此事件处理程序（针对事件event ）可以被重新实现，以接收该项的焦点移出事件。默认实现不执行任何操作。

另请参阅 focusInEvent()、sceneEvent() 和setFocus()。

QGraphicsItem *QGraphicsItem::focusProxy() const

返回该项的焦点代理，如果该项没有焦点代理，则返回nullptr 。

另请参阅 setFocusProxy()、setFocus() 和hasFocus()。

void QGraphicsItem::grabKeyboard()

捕获键盘输入。

该对象将接收该场景中的所有键盘输入，直到发生以下任一事件为止：

• 该对象变为不可见
• 该对象从场景中移除
• 该对象被删除
• 该对象调用ungrabKeyboard()
• 另一个项调用了`grabKeyboard()`；当该其他项调用`ungrabKeyboard()`时，该项将重新获得键盘控制权。

当一个项获得键盘控制权时，它会收到一个QEvent::GrabKeyboard 事件；当它失去键盘控制权时，会收到一个QEvent::UngrabKeyboard 事件。这些事件可用于检测项在非获得输入焦点的情况下，何时获得或失去键盘控制权。

在 Qt 中几乎无需显式获取键盘控制权，因为 Qt 会合理地自动获取和释放键盘控制权。具体来说，当控件获得输入焦点时，Qt 会获取键盘控制权；当控件失去输入焦点或被隐藏时，Qt 会释放键盘控制权。

请注意，只有可见的控件才能捕获键盘输入。对不可见的控件调用 grabKeyboard() 不会产生任何效果。

键盘事件不受此影响。

另请参阅 ungrabKeyboard()、grabMouse() 和setFocus()。

void QGraphicsItem::grabMouse()

捕获鼠标输入。

该对象将接收场景中的所有鼠标事件，直到发生以下任一事件为止：

• 该项变为不可见
• 该对象从场景中移除
• 该对象被删除
• 该对象调用ungrabMouse()
• 另一个对象调用了 grabMouse()；当该对象调用ungrabMouse() 时，该对象将重新获得鼠标抓取状态。

当项目获得鼠标控制权时，会收到一个 `QEvent::GrabMouse ` 事件；当它失去鼠标控制权时，会收到一个 `QEvent::UngrabMouse ` 事件。这些事件可用于检测项目在未接收鼠标按钮事件的情况下，通过其他方式获得或失去鼠标控制权的情况。

在 Qt 中几乎无需显式捕获鼠标，因为 Qt 会合理地自动捕获和释放鼠标。具体来说，当您按下鼠标按钮时，Qt 会捕获鼠标，并保持捕获状态直到您释放最后一个鼠标按钮。此外，Qt::Popup 控件在显示时会隐式调用 grabMouse()，在隐藏时会隐式调用ungrabMouse()。

请注意，只有可见的控件才能捕获鼠标输入。在不可见的控件上调用 grabMouse() 不会产生任何效果。

键盘事件不受此影响。

另请参阅 QGraphicsScene::mouseGrabberItem()、ungrabMouse() 和grabKeyboard()。

QGraphicsEffect *QGraphicsItem::graphicsEffect() const

如果该项目有效果，则返回指向该效果的指针；否则返回nullptr 。

另请参阅 setGraphicsEffect()。

QGraphicsItemGroup *QGraphicsItem::group() const

返回指向该项目所属项目组的指针；如果该项目不属于任何组，则返回nullptr 。

另请参阅 setGroup()、QGraphicsItemGroup 以及QGraphicsScene::createItemGroup()。

bool QGraphicsItem::hasCursor() const

如果该项目已设置光标，则返回true ；否则返回false。

默认情况下，项目未设置任何光标。cursor() 将返回一个标准的指向箭头光标。

另请参阅 unsetCursor()。

bool QGraphicsItem::hasFocus() const

如果该项处于活动状态，且该项或其focus proxy 拥有键盘输入焦点，则返回true ；否则，返回false 。

另请参阅 focusItem()、setFocus()、QGraphicsScene::setFocusItem() 以及isActive()。

void QGraphicsItem::hide()

隐藏该项目（默认情况下项目是可见的）。

此便捷函数等同于调用setVisible(false) 。

另请参阅 show() 和setVisible()。

[virtual protected] void QGraphicsItem::hoverEnterEvent(QGraphicsSceneHoverEvent *event)

此事件处理程序（针对事件event ）可以被重新实现，以便接收该项的悬停进入事件。默认实现会调用update()；否则不执行任何操作。

在event 上调用QEvent::ignore()或QEvent::accept()均无效。

另请参阅 hoverMoveEvent()、hoverLeaveEvent()、sceneEvent() 和setAcceptHoverEvents()。

[virtual protected] void QGraphicsItem::hoverLeaveEvent(QGraphicsSceneHoverEvent *event)

此事件处理程序（针对event 事件）可以被重新实现，以接收该项的悬停离开事件。默认实现会调用update()；否则不执行任何操作。

在event 上调用QEvent::ignore()或QEvent::accept()不会产生任何效果。

另请参阅 hoverEnterEvent()、hoverMoveEvent()、sceneEvent() 以及setAcceptHoverEvents()。

[virtual protected] void QGraphicsItem::hoverMoveEvent(QGraphicsSceneHoverEvent *event)

此事件处理程序（针对事件event ）可以被重新实现，以接收该项的悬停移动事件。默认实现不执行任何操作。

在event 上调用QEvent::ignore() 或QEvent::accept() 均无效果。

另请参阅 hoverEnterEvent()、hoverLeaveEvent()、sceneEvent() 和setAcceptHoverEvents()。

[virtual protected] void QGraphicsItem::inputMethodEvent(QInputMethodEvent *event)

此事件处理程序（针对event 事件）可以被重新实现，以接收该项的输入法事件。默认实现会忽略该事件。

另请参阅 inputMethodQuery() 和sceneEvent()。

Qt::InputMethodHints QGraphicsItem::inputMethodHints() const

返回该项的当前输入法提示。

输入法提示仅适用于输入控件。输入法会利用这些提示来指示其应如何工作。例如，如果设置了 Qt::ImhNumbersOnly 标志，输入法可能会更改其视觉组件，以反映当前仅允许输入数字。

具体效果可能因输入法实现的不同而有所差异。

另请参阅 setInputMethodHints() 和inputMethodQuery()。

[virtual protected] QVariant QGraphicsItem::inputMethodQuery(Qt::InputMethodQuery query) const

该方法仅适用于输入项。输入法通过该方法查询待处理项的一组属性，以便支持复杂的输入法操作，例如对周边文本的支持和重新转换。query 指定了要查询的属性。

另请参阅 inputMethodEvent() 和QInputMethodEvent 。

void QGraphicsItem::installSceneEventFilter(QGraphicsItem *filterItem)

在filterItem 上为该项安装一个事件过滤器，使得该项的所有事件都会首先经过filterItem 的sceneEventFilter()函数处理。

若要过滤另一个项的事件，请将此项作为事件过滤器安装到该项上。示例：

QGraphicsScene scene;
QGraphicsEllipseItem *ellipse = scene.addEllipse(QRectF(-10, -10, 20, 20));
QGraphicsLineItem *line = scene.addLine(QLineF(-10, -10, 20, 20));

line->installSceneEventFilter(ellipse);
// line's events are filtered by ellipse's sceneEventFilter() function.

ellipse->installSceneEventFilter(line);
// ellipse's events are filtered by line's sceneEventFilter() function.

一个对象只能过滤同一场景中其他对象的事件。此外，对象无法过滤自身的事件；取而代之，您可以直接重写sceneEvent()方法。

项目必须属于某个场景，才能安装和使用场景事件过滤器。

另请参阅 removeSceneEventFilter()、sceneEventFilter() 和sceneEvent()。

bool QGraphicsItem::isActive() const

如果该项处于活动状态，则返回true ；否则返回false 。

只有在场景处于活动状态时，项目才能处于活动状态。如果项目本身是活动面板，或者其父级是活动面板，则该项目处于活动状态。位于非活动面板中的项目不处于活动状态。

当场景中没有活动面板时，不属于任何面板的项将遵循场景的激活状态。

只有活动项才能获得输入焦点。

另请参阅 QGraphicsScene::isActive()、QGraphicsScene::activePanel()、panel() 和isPanel()。

bool QGraphicsItem::isAncestorOf(const QGraphicsItem *child) const

如果该项是child 的祖先（即，如果该项是child 的父项，或者属于child 父项的祖先之一），则返回true 。

另请参阅 parentItem()。

bool QGraphicsItem::isBlockedByModalPanel(QGraphicsItem **blockingPanel = nullptr) const

如果该项被模态面板遮挡，则返回true ；否则返回false。如果blockingPanel 不为零，则blockingPanel 将被设置为遮挡该项的模态面板。如果该项未被遮挡，则该函数不会设置blockingPanel 。

对于不在场景中的项目，此函数始终返回false 。

另请参阅 panelModality()、setPanelModality() 以及PanelModality 。

bool QGraphicsItem::isClipped() const

如果该元素被裁剪，则返回true 。当元素设置了ItemClipsToShape 标志，或者该元素及其任何祖先元素设置了ItemClipsChildrenToShape 标志时，该元素即被视为被裁剪。

裁剪会影响该项的外观（即绘制），以及鼠标和悬停事件的传递。

另请参阅 clipPath()、shape() 和setFlags()。

bool QGraphicsItem::isEnabled() const

如果该项已启用，则返回true ；否则返回false。

另请参阅 setEnabled()。

bool QGraphicsItem::isObscured(const QRectF &rect = QRectF()) const

如果rect 被其上方的任何碰撞物体的不透明形状（即Z值高于该物体的物体）完全遮挡，则返回true 。

另请参阅 opaqueArea()。

bool QGraphicsItem::isObscured(qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 isObscured(QRectF(x,y,w,h))。

[virtual] bool QGraphicsItem::isObscuredBy(const QGraphicsItem *item) const

如果该项的边界矩形被item 的不透明形状完全遮挡，则返回true 。

基础实现会将 `item` 的 `opaqueArea()` 映射到该项的坐标系中，然后检查该项的 `boundingRect()` 是否完全包含在映射后的形状内。

您可以重写此函数，以提供自定义算法来判断该项是否被 `item` 遮挡。

另请参阅 opaqueArea() 和isObscured()。

bool QGraphicsItem::isPanel() const

如果该项是一个面板，则返回true ；否则返回false 。

另请参阅 QGraphicsItem::panel() 和ItemIsPanel 。

bool QGraphicsItem::isSelected() const

如果该项目被选中，则返回true ；否则返回false。

位于组中的项目会继承该组的选中状态。

默认情况下，项目未被选中。

另请参阅 setSelected() 和QGraphicsScene::setSelectionArea()。

bool QGraphicsItem::isUnderMouse() const

如果该项当前位于某个视图中的鼠标光标下方，则返回true ；否则返回false。

另请参阅 QGraphicsScene::views() 和QCursor::pos()。

bool QGraphicsItem::isVisible() const

如果该项目可见，则返回true ；否则返回false。

请注意，该项的一般可见性与其是否实际被QGraphicsView 可视化无关。

另请参阅 setVisible()。

bool QGraphicsItem::isVisibleTo(const QGraphicsItem *parent) const

如果该项对parent 可见，则返回true ；否则返回false。parent 可以是nullptr ，在这种情况下，该函数将返回该项对场景是否可见。

即使isVisible() 返回 true，某个项对它的祖先可能仍不可见；同样，即使isVisible() 返回 false，该项对它的祖先也可能可见。如果任何一个祖先被隐藏，该项本身将被隐式隐藏，此时本函数将返回 false。

另请参阅 isVisible() 和setVisible()。

bool QGraphicsItem::isWidget() const

如果该项是一个小部件（即QGraphicsWidget ），则返回 `true `；否则，返回 `false`。

bool QGraphicsItem::isWindow() const

如果该项是QGraphicsWidget 窗口，则返回true ；否则返回false。

另请参阅 QGraphicsWidget::windowFlags()。

[virtual protected] QVariant QGraphicsItem::itemChange(QGraphicsItem::GraphicsItemChange change, const QVariant &value)

该虚拟函数由QGraphicsItem 调用，用于通知自定义项其状态的某一部分发生了变化。通过重写此函数，您可以对变化做出响应，并在某些情况下（取决于change ），进行相应的调整。

change 是发生变化的项的参数。value 是新值；该值的类型取决于change 。

示例：

QVariant Component::itemChange(GraphicsItemChange change, const QVariant &value)
{
    if (change == ItemPositionChange && scene()) {
        // value is the new position.
        QPointF newPos = value.toPointF();
        QRectF rect = scene()->sceneRect();
        if (!rect.contains(newPos)) {
            // Keep the item inside the scene rect.
            newPos.setX(qMin(rect.right(), qMax(newPos.x(), rect.left())));
            newPos.setY(qMin(rect.bottom(), qMax(newPos.y(), rect.top())));
            return newPos;
        }
    }
    return QGraphicsItem::itemChange(change, value);
}

默认实现不执行任何操作，并返回value 。

注意：在该函数的重写中，某些QGraphicsItem 函数无法被调用；详情请参阅GraphicsItemChange 的文档。

另请参阅 ` GraphicsItemChange`。

QTransform QGraphicsItem::itemTransform(const QGraphicsItem *other, bool *ok = nullptr) const

返回一个QTransform ，该转换将此项的坐标映射到other 。如果ok 不为空，且不存在此类转换，则由ok 指向的布尔值将设置为false；否则将设置为true。

该转换提供了mapToItem() 或mapFromItem() 函数的替代方案，通过返回相应的转换对象，使您能够自行映射形状和坐标。当需要在同一对项目之间反复进行映射时，它还能帮助您编写更高效的代码。

另请参阅 mapToItem()、mapFromItem() 和deviceTransform()。

[virtual protected] void QGraphicsItem::keyPressEvent(QKeyEvent *event)

此事件处理程序（针对event 事件）可被重写，以便接收该项的按键事件。默认实现会忽略该事件。若重写此处理程序，则该事件将默认被接受。

请注意，只有设置了ItemIsFocusable 标志且拥有键盘输入焦点的项目才会接收按键事件。

另请参阅 keyReleaseEvent()、setFocus()、QGraphicsScene::setFocusItem() 以及sceneEvent()。

[virtual protected] void QGraphicsItem::keyReleaseEvent(QKeyEvent *event)

此事件处理程序（针对event 事件）可以被重写，以便接收该项目的键盘释放事件。默认实现会忽略该事件。如果您重写此处理程序，则该事件将默认被接受。

请注意，只有设置了ItemIsFocusable 标志且拥有键盘输入焦点的项目才会接收键事件。

另请参阅 keyPressEvent()、setFocus()、QGraphicsScene::setFocusItem() 以及sceneEvent()。

QPainterPath QGraphicsItem::mapFromItem(const QGraphicsItem *item, const QPainterPath &path) const

将位于item 坐标系中的路径path 映射到该项的坐标系，并返回映射后的路径。

如果item 等于nullptr ，则该函数的返回结果与mapFromScene() 相同。

另请参阅 itemTransform()、mapFromParent()、mapFromScene()、mapToItem() 以及《图形视图坐标系》。

QPointF QGraphicsItem::mapFromItem(const QGraphicsItem *item, const QPointF &point) const

将位于item 坐标系中的点point 映射到该项的坐标系，并返回映射后的坐标。

如果item 就是nullptr ，则该函数的返回值与mapFromScene() 相同。

另请参阅 itemTransform()、mapFromParent()、mapFromScene()、transform()、mapToItem() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapFromItem(const QGraphicsItem *item, const QPolygonF &polygon) const

将位于item 坐标系中的多边形polygon 映射到该项的坐标系，并返回映射后的多边形。

如果item 等于nullptr ，则该函数的返回结果与mapFromScene() 相同。

另请参阅 itemTransform()、mapToItem()、mapFromParent()、transform() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapFromItem(const QGraphicsItem *item, const QRectF &rect) const

将位于item 坐标系中的矩形rect 映射到该项的坐标系中，并将映射后的矩形作为多边形返回。

如果item 等于nullptr ，则该函数的返回结果与mapFromScene() 相同

另请参阅 itemTransform()、mapToItem()、mapFromParent()、transform() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapFromItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapFromItem(item,QRectF(x,y,w,h))。

QPointF QGraphicsItem::mapFromItem(const QGraphicsItem *item, qreal x, qreal y) const

此便捷函数等同于调用 mapFromItem(item,QPointF(x,y))。

QPainterPath QGraphicsItem::mapFromParent(const QPainterPath &path) const

将位于该项父项坐标系中的路径path 映射到该项的坐标系，并返回映射后的路径。

另请参阅 mapFromScene()、mapFromItem()、mapToParent() 以及《图形视图坐标系》。

QPointF QGraphicsItem::mapFromParent(const QPointF &point) const

将位于该项父项坐标系中的点point 映射到该项的坐标系中，并返回映射后的坐标。

另请参阅 mapFromItem()、mapFromScene()、transform()、mapToParent() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapFromParent(const QPolygonF &polygon) const

将位于该项父项坐标系中的多边形polygon 映射到该项的坐标系，并返回映射后的多边形。

另请参阅 mapToParent()、mapToItem()、transform() 以及“图形视图坐标系”。

QPolygonF QGraphicsItem::mapFromParent(const QRectF &rect) const

将位于该项父项坐标系中的矩形rect 映射到该项的坐标系中，并将映射后的矩形作为多边形返回。

另请参阅 mapToParent()、mapFromItem()、transform() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapFromParent(qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用mapFromItem （QRectF （x 、y 、w 、h ））。

QPointF QGraphicsItem::mapFromParent(qreal x, qreal y) const

此便捷函数等同于调用 mapFromParent(QPointF(x,y))。

QPainterPath QGraphicsItem::mapFromScene(const QPainterPath &path) const

将位于该项所属场景坐标系中的路径path 映射到该项的坐标系中，并返回映射后的路径。

另请参阅 mapFromParent()、mapFromItem()、mapToScene() 以及《图形视图坐标系》。

QPointF QGraphicsItem::mapFromScene(const QPointF &point) const

将位于该项场景坐标系中的点point 映射到该项的坐标系，并返回映射后的坐标。

另请参阅 mapFromItem()、mapFromParent()、transform()、mapToScene()，以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapFromScene(const QPolygonF &polygon) const

将位于该项场景坐标系中的多边形polygon 映射到该项的坐标系，并返回映射后的多边形。

另请参阅 mapToScene()、mapFromParent()、transform() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapFromScene(const QRectF &rect) const

将位于该项场景坐标系中的矩形rect 映射到该项的坐标系中，并将映射后的矩形作为多边形返回。

另请参阅 mapToScene()、mapFromItem()、transform() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapFromScene(qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapFromScene(QRectF(x,y,w,h))。

QPointF QGraphicsItem::mapFromScene(qreal x, qreal y) const

此便捷函数等同于调用 mapFromScene(QPointF(x,y))。

QRectF QGraphicsItem::mapRectFromItem(const QGraphicsItem *item, const QRectF &rect) const

将位于item 坐标系中的矩形rect 映射到该项的坐标系中，并将映射后的矩形作为新矩形返回（即结果多边形的边界矩形）。

如果item 等于nullptr ，则该函数的返回结果与mapRectFromScene() 相同。

另请参阅 itemTransform()、mapToParent()、mapToScene()、mapFromItem() 以及《图形视图坐标系》。

QRectF QGraphicsItem::mapRectFromItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapRectFromItem(item,QRectF(x,y,w,h))。

QRectF QGraphicsItem::mapRectFromParent(const QRectF &rect) const

将位于该项父项坐标系中的矩形rect 映射到该项的坐标系中，并将映射后的矩形作为新矩形返回（即结果多边形的边界矩形）。

另请参阅 itemTransform()、mapToParent()、mapToScene()、mapFromItem() 以及《图形视图坐标系》。

QRectF QGraphicsItem::mapRectFromParent(qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapRectFromParent(QRectF(x,y,w,h))。

QRectF QGraphicsItem::mapRectFromScene(const QRectF &rect) const

将场景坐标系中的矩形rect 映射到该项的坐标系，并将映射后的矩形作为新矩形返回（即结果多边形的边界矩形）。

另请参阅 itemTransform()、mapToParent()、mapToScene()、mapFromItem() 以及《图形视图坐标系》。

QRectF QGraphicsItem::mapRectFromScene(qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapRectFromScene(QRectF(x,y,w,h))。

QRectF QGraphicsItem::mapRectToItem(const QGraphicsItem *item, const QRectF &rect) const

将位于该项坐标系中的矩形rect 映射到item 的坐标系中，并将映射后的矩形作为新矩形返回（即生成的多边形的边界矩形）。

如果item 即为nullptr ，则该函数的返回结果与mapRectToScene() 相同。

另请参阅 itemTransform()、mapToParent()、mapToScene()、mapFromItem() 以及“图形视图坐标系”。

QRectF QGraphicsItem::mapRectToItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapRectToItem(item,QRectF(x,y,w,h))。

QRectF QGraphicsItem::mapRectToParent(const QRectF &rect) const

将位于该项坐标系中的矩形rect 映射到其父节点的坐标系中，并将映射后的矩形作为新矩形返回（即生成的多边形的边界矩形）。

另请参阅 itemTransform()、mapToParent()、mapToScene()、mapFromItem() 以及《图形视图坐标系》。

QRectF QGraphicsItem::mapRectToParent(qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapRectToParent(QRectF(x,y,w,h))。

QRectF QGraphicsItem::mapRectToScene(const QRectF &rect) const

将位于该项坐标系中的矩形rect 映射到场景坐标系，并将映射后的矩形作为新矩形返回（即结果多边形的边界矩形）。

另请参阅 itemTransform()、mapToParent()、mapToScene()、mapFromItem() 以及《图形视图坐标系》。

QRectF QGraphicsItem::mapRectToScene(qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapRectToScene(QRectF(x,y,w,h))。

QPainterPath QGraphicsItem::mapToItem(const QGraphicsItem *item, const QPainterPath &path) const

将位于该项坐标系中的路径path 映射到item 的坐标系，并返回映射后的路径。

如果item 就是nullptr ，则该函数的返回结果与mapToScene() 相同。

另请参阅 itemTransform()、mapToParent()、mapToScene()、mapFromItem() 以及《图形视图坐标系》。

QPointF QGraphicsItem::mapToItem(const QGraphicsItem *item, const QPointF &point) const

将位于该项坐标系中的点point 映射到item 的坐标系中，并返回映射后的坐标。

如果item 等于nullptr ，则该函数的返回结果与mapToScene() 相同。

另请参阅 itemTransform()、mapToParent()、mapToScene()、transform()、mapFromItem() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapToItem(const QGraphicsItem *item, const QPolygonF &polygon) const

将位于该项坐标系中的多边形polygon 映射到item 的坐标系，并返回映射后的多边形。

如果item 即为nullptr ，则该函数的返回结果与mapToScene() 相同。

另请参阅 itemTransform()、mapToParent()、mapToScene()、mapFromItem() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapToItem(const QGraphicsItem *item, const QRectF &rect) const

将位于该项坐标系中的矩形rect 映射到item 的坐标系中，并将映射后的矩形作为多边形返回。

如果item 等于nullptr ，则该函数的返回结果与mapToScene() 相同。

另请参阅 itemTransform()、mapToParent()、mapToScene()、mapFromItem()，以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapToItem(const QGraphicsItem *item, qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapToItem(item,QRectF(x,y,w,h))。

QPointF QGraphicsItem::mapToItem(const QGraphicsItem *item, qreal x, qreal y) const

此便捷函数等同于调用 mapToItem(item,QPointF(x,y))。

QPainterPath QGraphicsItem::mapToParent(const QPainterPath &path) const

将位于该项坐标系中的路径path 映射到其父项的坐标系，并返回映射后的路径。如果该项没有父项，则path 将被映射到场景的坐标系。

另请参阅 mapToScene()、mapToItem()、mapFromParent() 以及《图形视图坐标系》。

QPointF QGraphicsItem::mapToParent(const QPointF &point) const

将位于该项坐标系中的点point 映射到其父项的坐标系中，并返回映射后的坐标。如果该项没有父项，则point 将被映射到场景的坐标系中。

另请参阅 mapToItem()、mapToScene()、transform()、mapFromParent() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapToParent(const QPolygonF &polygon) const

将位于该项坐标系中的多边形polygon 映射到其父项的坐标系，并返回映射后的多边形。如果该项没有父项，则polygon 将被映射到场景的坐标系。

另请参阅 mapToScene()、mapToItem()、mapFromParent() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapToParent(const QRectF &rect) const

将位于该项坐标系中的矩形rect 映射到其父项的坐标系中，并将映射后的矩形作为多边形返回。如果该项没有父项，则rect 将被映射到场景的坐标系中。

另请参阅 mapToScene()、mapToItem()、mapFromParent() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapToParent(qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapToParent(QRectF(x,y,w,h))。

QPointF QGraphicsItem::mapToParent(qreal x, qreal y) const

此便捷函数等同于调用 mapToParent(QPointF(x,y))。

QPainterPath QGraphicsItem::mapToScene(const QPainterPath &path) const

将位于该项坐标系中的路径path 映射到场景坐标系，并返回映射后的路径。

另请参阅 mapToParent()、mapToItem()、mapFromScene() 以及《图形视图坐标系》。

QPointF QGraphicsItem::mapToScene(const QPointF &point) const

将位于该项坐标系中的点point 映射到场景坐标系，并返回映射后的坐标。

另请参阅 mapToItem()、mapToParent()、transform()、mapFromScene() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapToScene(const QPolygonF &polygon) const

将位于该项坐标系中的多边形polygon 映射到场景坐标系，并返回映射后的多边形。

另请参阅 mapToParent()、mapToItem()、mapFromScene() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapToScene(const QRectF &rect) const

将位于该项坐标系中的矩形rect 映射到场景坐标系，并将映射后的矩形作为多边形返回。

另请参阅 mapToParent()、mapToItem()、mapFromScene() 以及《图形视图坐标系》。

QPolygonF QGraphicsItem::mapToScene(qreal x, qreal y, qreal w, qreal h) const

此便捷函数等同于调用 mapToScene(QRectF(x,y,w,h))。

QPointF QGraphicsItem::mapToScene(qreal x, qreal y) const

此便捷函数等同于调用 mapToScene(QPointF(x,y))。

[virtual protected] void QGraphicsItem::mouseDoubleClickEvent(QGraphicsSceneMouseEvent *event)

此事件处理程序（针对event 事件）可以被重新实现，以便接收该项的鼠标双击事件。

双击一个项目时，该项目将首先接收一个鼠标按下事件，随后是一个释放事件（即一次单击），然后是一个双击事件，最后是一个释放事件。

在event 上调用QEvent::ignore()或QEvent::accept()没有任何效果。

默认实现会调用mousePressEvent()。若在重写此函数时希望保留基类实现，请在重写版本中调用 QGraphicsItem::mouseDoubleClickEvent()。

请注意，如果项目既不是selectable ，也不是movable ，则不会接收双击事件（在此情况下，单次鼠标点击会被忽略，从而阻止双击事件的生成）。

另请参阅 mousePressEvent()、mouseMoveEvent()、mouseReleaseEvent() 和sceneEvent()。

[virtual protected] void QGraphicsItem::mouseMoveEvent(QGraphicsSceneMouseEvent *event)

此事件处理程序（针对event 事件）可以被重新实现，以接收该项的鼠标移动事件。如果您确实接收到此事件，则可以确定该项也接收到鼠标点击事件，并且该项是当前的鼠标捕获对象。

在 `event ` 上调用 `QEvent::ignore()` 或 `QEvent::accept()` 不会产生任何效果。

默认实现处理了基本项目交互，例如选择和移动。若在重写此函数时希望保留基础实现，请在重写版本中调用 QGraphicsItem::mouseMoveEvent()。

请注意，mousePressEvent() 决定了哪个图形项将接收鼠标事件。详情请参阅mousePressEvent() 的说明。

另请参阅 mousePressEvent()、mouseReleaseEvent()、mouseDoubleClickEvent() 和sceneEvent()。

[virtual protected] void QGraphicsItem::mousePressEvent(QGraphicsSceneMouseEvent *event)

该事件处理程序（针对事件event ）可以被重新实现，以接收该项的鼠标按下事件。鼠标按下事件仅会传递给接受当前被按下的鼠标按钮的项。默认情况下，项会接受所有鼠标按钮，但您可以通过调用setAcceptedMouseButtons() 来更改此设置。

鼠标按下事件决定了哪个项目应成为鼠标捕获器（参见QGraphicsScene::mouseGrabberItem()）。如果您未重写此函数，按下事件将传播到该项目下方任何最顶层的项目，且不会向该项目发送其他鼠标事件。

如果您重写了该函数，则默认会接受event （参见QEvent::accept()），此时该项即成为鼠标捕获项。这使得该项能够接收后续的移动、释放和双击事件。如果您在event 上调用QEvent::ignore()，该项将失去鼠标捕获状态，event 将传播到其下方的任何最顶层项。 除非接收到新的鼠标按下事件，否则将不会向该项传递任何进一步的鼠标事件。

默认实现处理基本的项目交互，例如选择和移动。如果您在重写此函数时希望保留基础实现，请在重写版本中调用 QGraphicsItem::mousePressEvent()。

对于既非movable 也非selectable 的项目，该事件为QEvent::ignore()d。

另请参阅 mouseMoveEvent()、mouseReleaseEvent()、mouseDoubleClickEvent() 以及sceneEvent()。

[virtual protected] void QGraphicsItem::mouseReleaseEvent(QGraphicsSceneMouseEvent *event)

此事件处理程序（针对event 事件）可以重新实现，以便接收该项的鼠标释放事件。

在event 上调用QEvent::ignore()或QEvent::accept()不会产生任何效果。

默认实现处理基本的项目交互，例如选择和移动。如果您在重写此函数时希望保留基类实现，请在重写版本中调用 QGraphicsItem::mouseReleaseEvent()。

请注意，mousePressEvent() 决定哪个图形项接收鼠标事件。详情请参阅mousePressEvent() 的说明。

另请参阅 mousePressEvent()、mouseMoveEvent()、mouseDoubleClickEvent() 和sceneEvent()。

void QGraphicsItem::moveBy(qreal dx, qreal dy)

将该对象在水平方向上移动dx 个点，在垂直方向上移动dy 个点。该函数等同于调用setPos(pos() +QPointF(dx,dy))。

qreal QGraphicsItem::opacity() const

返回该项的本地不透明度，其取值范围在 0.0（透明）到 1.0（不透明）之间。该值将与父项和祖先项的值合并，共同构成 `effectiveOpacity()` 函数的参数。有效不透明度决定了该项的渲染方式，同时也影响其在使用 `QGraphicsView::items()` 等函数进行查询时的可见性。

opacity 属性决定了传递给paint() 函数的绘制器的状态。如果该项目被缓存（即ItemCoordinateCache 或DeviceCoordinateCache ），则在渲染时，该属性将应用于项目的缓存。

默认不透明度为 1.0；即完全不透明。

另请参阅 setOpacity()、paint()、ItemIgnoresParentOpacity 以及ItemDoesntPropagateOpacityToChildren 。

[virtual] QPainterPath QGraphicsItem::opaqueArea() const

此虚拟函数返回一个形状，该形状表示该项不透明的区域。如果某个区域使用不透明画笔或颜色填充（即非透明），则该区域为不透明。

该函数由 `isObscuredBy()` 使用，该函数由底层项目调用，以确定它们是否被该项目遮挡。

默认实现返回一个空的 `QPainterPath`，表示该项完全透明，不会遮挡任何其他项。

另请参见 isObscuredBy()、isObscured() 和shape()。

[pure virtual] void QGraphicsItem::paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = nullptr)

该函数通常由QGraphicsView 调用，用于在本地坐标系中绘制项的内容。

在QGraphicsItem 的子类中重写此函数，以使用painter 提供项的绘制实现。option 参数为项提供样式选项，例如其状态、可见区域及其细节级别提示。widget 参数是可选的。 若提供该参数，则其指向正在进行绘制的控件；否则，该参数值为 0。对于缓存绘制，widget 始终为 0。

void RoundRectItem::paint(QPainter *painter,
                          const QStyleOptionGraphicsItem *option,
                          QWidget *widget)
{
    painter->drawRoundedRect(-10, -10, 20, 20, 5, 5);
}

绘图器的笔宽默认为 0，其笔初始化为来自绘图设备调色板的QPalette::Text 画笔。画笔初始化为QPalette::Window 。

请确保将所有绘制操作限制在boundingRect()的边界内，以避免渲染异常（因为QGraphicsView 不会自动对绘图器进行裁剪）。 特别需要注意的是，当QPainter 使用已分配的QPen 渲染形状轮廓时，轮廓的一半将绘制在渲染形状之外，另一半则绘制在形状之内（例如，当笔宽为2个单位时，必须将轮廓绘制在boundingRect()内部1个单位的位置）。QGraphicsItem 不支持使用宽度不为零的装饰性画笔。

所有绘制操作均在本地坐标系中进行。

另请参阅 setCacheMode()、QPen::width()、项目坐标以及ItemUsesExtendedStyleOption 。

QGraphicsItem *QGraphicsItem::panel() const

返回该项的面板，如果该项没有面板，则返回nullptr 。如果该项本身就是面板，则返回其自身；否则，返回其最近的作为面板的祖先。

另请参阅 isPanel() 和ItemIsPanel 。

QGraphicsItem::PanelModality QGraphicsItem::panelModality() const

返回该项目的模态。

另请参阅 setPanelModality()。

QGraphicsItem *QGraphicsItem::parentItem() const

返回指向该项父项的指针。如果该项没有父项，则返回nullptr 。

另请参阅 setParentItem() 和childItems()。

QGraphicsObject *QGraphicsItem::parentObject() const

返回指向该项父项的指针，并将其强制转换为QGraphicsObject 类型。如果父项不是QGraphicsObject ，则返回nullptr 。

另请参阅 parentItem() 和childItems()。

QGraphicsWidget *QGraphicsItem::parentWidget() const

返回指向该项父控件的指针。该项的父控件是指距离该项最近且为控件的父项。

另请参阅 parentItem() 和childItems()。

QPointF QGraphicsItem::pos() const

返回该项在父级坐标系中的位置。如果该项没有父级，则其位置以场景坐标表示。

该项的位置描述了其在父级坐标系中的原点（本坐标系 (0, 0)）；该函数的返回结果与mapToParent(0, 0) 相同。

为方便起见，您也可以调用scenePos()来确定项目在场景坐标系中的位置，无论其是否有父级。

另请参阅 x()、y()、setPos()、transform()，以及《图形视图坐标系》。

[protected] void QGraphicsItem::prepareGeometryChange()

为项的几何形状变化做准备。在更改项的边界矩形之前，请调用此函数，以确保QGraphicsScene 中的索引保持最新。

如果需要，`prepareGeometryChange()` 会调用 `update()`。

示例：

void CircleItem::setRadius(qreal newRadius)
{
    if (radius != newRadius) {
        prepareGeometryChange();
        radius = newRadius;
    }
}

另请参阅 boundingRect()。

void QGraphicsItem::removeSceneEventFilter(QGraphicsItem *filterItem)

从filterItem 中移除此项上的事件过滤器。

另请参阅 installSceneEventFilter()。

void QGraphicsItem::resetTransform()

将该项的变换矩阵重置为单位矩阵，或将所有变换属性重置为默认值。这相当于调用setTransform(QTransform()) 。

另请参阅 setTransform() 和transform()。

qreal QGraphicsItem::rotation() const

返回围绕 Z 轴顺时针旋转的角度（单位为度）。默认值为 0（即该项未旋转）。

该旋转值将与该项的scale()、transform()和transformations()结合使用，以将该项的坐标系映射到父项。

另请参阅 setRotation()、transformOriginPoint() 和Transformations 。

qreal QGraphicsItem::scale() const

返回该项目的缩放因子。默认缩放因子为 1.0（即该项目未进行缩放）。

该缩放因子将与该项的rotation()、transform()和transformations()函数结合使用，以将该项的坐标系映射到父项。

另请参阅 setScale()、rotation() 和Transformations 。

QGraphicsScene *QGraphicsItem::scene() const

返回该项的当前场景；如果该项未存储在任何场景中，则返回nullptr 。

要将项目添加到场景中或将其在场景中移动，请调用QGraphicsScene::addItem()。

QRectF QGraphicsItem::sceneBoundingRect() const

通过将sceneTransform() 与boundingRect() 结合使用，返回该项在场景坐标系中的边界矩形。

另请参阅 boundingRect() 以及《图形视图坐标系》。

[virtual protected] bool QGraphicsItem::sceneEvent(QEvent *event)

此虚拟函数用于接收发送到该项的事件。重写此函数可在事件被分发至以下专用事件处理程序之前对其进行拦截：contextMenuEvent()、focusInEvent()、focusOutEvent()、hoverEnterEvent()、hoverMoveEvent()、hoverLeaveEvent()、keyPressEvent()、keyReleaseEvent()、mousePressEvent()、mouseReleaseEvent()、mouseMoveEvent() 以及mouseDoubleClickEvent()。

如果事件被识别并处理，则返回true ；否则（例如，如果事件类型未被识别），则返回false。

event 是被拦截的事件。

[virtual protected] bool QGraphicsItem::sceneEventFilter(QGraphicsItem *watched, QEvent *event)

过滤watched 项的事件。event 是经过过滤的事件。

在子类中重写此函数，可使该项作为其他项的事件过滤器，在这些项能够响应之前拦截发送给它们的所有事件。

重写时，必须返回 true 以阻止对给定事件的进一步处理，从而确保该事件不会被传递给被监视的项目；或者返回 false 以指示事件系统应继续传播该事件。

另请参阅 installSceneEventFilter()。

QPointF QGraphicsItem::scenePos() const

返回该项在场景坐标系中的位置。这相当于调用mapToScene(0, 0) 。

另请参阅 pos()、sceneTransform() 以及《图形视图坐标系》。

QTransform QGraphicsItem::sceneTransform() const

返回该对象的场景变换矩阵。该矩阵可用于将该对象本机坐标系中的坐标和几何形状映射到场景坐标系中。若要将坐标从场景坐标系映射回本机坐标系，必须先对返回的矩阵进行求逆。

示例：

QGraphicsRectItem rect;
rect.setPos(100, 100);

rect.sceneTransform().map(QPointF(0, 0));
// returns QPointF(100, 100);

rect.sceneTransform().inverted().map(QPointF(100, 100));
// returns QPointF(0, 0);

与仅返回项目本机变换的 `transform()` 不同，此函数包含该项目（及其任何父对象）的位置以及所有变换属性。

另请参阅 transform()、setTransform()、scenePos()、图形视图坐标系以及Transformations 。

void QGraphicsItem::scroll(qreal dx, qreal dy, const QRectF &rect = QRectF())

rect 滚动由dx 提供的dy 中的内容。如果rect 是一个空矩形（默认值），则滚动该项的边界矩形。

当项目（或项目的一部分）的内容发生垂直或水平偏移时，滚动操作提供了一种比简单重绘更快的替代方案。 根据当前的变换以及绘图设备（即视口）的能力，此操作可能仅需使用 memmove() 将像素从一个位置移动到另一个位置。在大多数情况下，这比重新渲染整个区域更快。

滚动后，该项将针对新暴露的区域发出更新请求。如果不支持滚动（例如，您正在渲染到 OpenGL 视口，而该视口无法从滚动优化中获益），则此函数等同于调用 update(rect)。

rect注意：仅当QGraphicsItem::ItemCoordinateCache 启用时才支持滚动；在所有其他情况下，调用此函数等同于调用update( )。如果您确信该项是不透明的且未被其他项覆盖，则可以将rect 映射到视口坐标并滚动视口。

QTransform xform = item->deviceTransform(view->viewportTransform());
QRect deviceRect = xform.mapRect(rect).toAlignedRect();
view->viewport()->scroll(dx, dy, deviceRect);

另请参阅 boundingRect()。

void QGraphicsItem::setAcceptDrops(bool on)

如果on 为 true，则该项目将接受拖放事件；否则，对拖放事件不作响应。默认情况下，项目不接受拖放事件。

另请参阅 acceptDrops()。

void QGraphicsItem::setAcceptHoverEvents(bool enabled)

如果 `enabled ` 为 true，则该项目将接受悬停事件；否则，将忽略这些事件。默认情况下，项目不接受悬停事件。

当当前没有鼠标抓取项时，会触发悬停事件。这些事件在鼠标光标进入项目、在项目内部移动以及离开项目时被发送。 悬停事件通常用于在鼠标进入项目时突出显示该项目，以及跟踪鼠标光标悬停在项目上的情况（相当于QWidget::mouseTracking ）。

父项会在其子项之前接收悬停进入事件，并在其子项之后接收悬停离开事件。不过，如果光标进入某个子项，父项不会收到悬停离开事件；父项会保持“悬停”状态，直到光标离开其区域（包括其子项的区域）。

如果父项处理子项事件，当光标穿过其子项时，它将接收悬停移动、拖动移动和释放事件，但不会代表其子项接收悬停进入和悬停离开事件，也不会接收拖动进入和拖动离开事件。

带有窗口装饰的QGraphicsWidget 将接受悬停事件，无论acceptHoverEvents()的值为何。

另请参阅 acceptHoverEvents()、hoverEnterEvent()、hoverMoveEvent() 和hoverLeaveEvent()。

void QGraphicsItem::setAcceptTouchEvents(bool enabled)

如果enabled 为真，则该控件将接受touch events ；否则，将忽略这些事件。默认情况下，控件不接受触摸事件。

另请参阅 acceptTouchEvents()。

void QGraphicsItem::setAcceptedMouseButtons(Qt::MouseButtons buttons)

设置该项接受鼠标事件的鼠标buttons 。

默认情况下，所有鼠标按钮均被接受。如果某个项目接受某个鼠标按钮，当该按钮的鼠标按下事件被传递时，该项目将成为鼠标捕获项。但是，如果该项目不接受该鼠标按钮，则QGraphicsScene 会将鼠标事件转发给其下方第一个接受该鼠标按钮的项目。

若要禁用某项的鼠标事件（即使其对鼠标事件透明），请调用 setAcceptedMouseButtons(Qt::NoButton)。

另请参阅 acceptedMouseButtons() 和mousePressEvent()。

void QGraphicsItem::setActive(bool active)

如果 `active ` 为真，且场景处于活动状态，则该项的面板将被激活。否则，面板处于非活动状态。

如果该项不属于当前活动场景，则active 将决定当场景变为活动状态或该项被添加到场景时，其面板会发生什么情况。如果为true，当该项被添加到场景或场景变为活动状态时，该项的面板将被激活。否则，无论场景的活动状态如何，该项都将保持非活动状态。

另请参阅 isPanel()、QGraphicsScene::setActivePanel() 和QGraphicsScene::isActive()。

void QGraphicsItem::setBoundingRegionGranularity(qreal granularity)

将边界区域的粒度设置为granularity ；该值应在 0 到 1 之间（包含 0 和 1）。默认值为 0（即最低粒度，此时边界区域与项的边界矩形相对应）。

boundingRegion() 方法会使用该粒度值来计算该项的边界区域应达到的精细程度。可达到的最高粒度为 1，此时boundingRegion() 将返回针对相应设备所能实现的最精细轮廓（例如，对于QGraphicsView 视口，这将提供像素级精确的边界区域）。 最低粒度为 0。granularity 的值描述了设备分辨率与边界区域分辨率之间的比例（例如，值为 0.25 时，生成的区域中每个分块对应 4×4 个设备单位/像素）。

另请参阅 boundingRegionGranularity()。

void QGraphicsItem::setCacheMode(QGraphicsItem::CacheMode mode, const QSize &logicalCacheSize = QSize())

将该项的缓存模式设置为mode 。

可选参数logicalCacheSize 仅在ItemCoordinateCache 模式下使用，用于描述缓存缓冲区的分辨率；若logicalCacheSize 为(100, 100)，则QGraphicsItem 会将该项适配到图形内存中100x100像素的区域内，无论该项本身的逻辑尺寸如何。默认情况下，QGraphicsItem 使用boundingRect()返回的大小。 对于除ItemCoordinateCache 以外的所有其他缓存模式，logicalCacheSize 将被忽略。

如果您的项目花费大量时间重新绘制自身，缓存可以加快渲染速度。在某些情况下，缓存也会减慢渲染速度，特别是当项目重新绘制所花费的时间比 `QGraphicsItem ` 从缓存中重新绘制所花费的时间更短时。

启用缓存时，项的paint() 函数通常会将内容绘制到离屏像素图缓存中；对于后续的任何重绘请求，Graphics View 框架将从缓存中进行重绘。这种方法在 QGLWidget 上效果尤为显著，因为它将所有缓存都存储为 OpenGL 纹理。

请注意，为获得最佳性能，可能需要调整 `QPixmapCache` 的缓存限制。

您可以在CacheMode 文档中进一步了解不同的缓存模式。

另请参阅 cacheMode()、CacheMode 以及QPixmapCache::setCacheLimit()。

void QGraphicsItem::setCursor(const QCursor &cursor)

将该项的当前光标形状设置为cursor 。当鼠标光标悬停在此项上方时，将显示此形状。有关各种有用的形状，请参阅list of predefined cursor objects 。

编辑器项目可能需要使用“I形光标”：

item->setCursor(Qt::IBeamCursor);

如果未设置光标，则使用下方项目的光标。

另请参阅 cursor()、hasCursor()、unsetCursor()、QWidget::cursor 以及QGuiApplication::overrideCursor()。

void QGraphicsItem::setData(int key, const QVariant &value)

将该项的自定义数据中键为key 的值设置为value 。

自定义项数据可用于存储任何项的任意属性。Qt 不会使用此功能来存储数据；该功能仅为方便用户而提供。

另请参阅 data()。

void QGraphicsItem::setEnabled(bool enabled)

如果enabled 为true，则该控件处于启用状态；否则，处于禁用状态。

禁用的控件虽然可见，但不会接收任何事件，也无法获得焦点或被选中。鼠标事件会被丢弃；除非该控件同时不可见，或者它不接受鼠标事件（参见acceptedMouseButtons()），否则这些事件不会被传播。 禁用的项目无法成为鼠标抓取目标；因此，如果项目在抓取鼠标时被禁用，它将失去抓取状态，这就像它在被禁用时若处于焦点状态，则会失去焦点一样。

传统上，禁用项通常以灰色显示（参见QPalette::Disabled ）。

如果禁用父项，其所有子项也将被禁用。如果启用父项，所有子项都将被启用，除非它们已被显式禁用（即，如果对子项调用 setEnabled(false)，则当其父项被禁用后又被重新启用时，该子项不会被重新启用）。

项目默认处于启用状态。

另请参阅 ` isEnabled()`。

void QGraphicsItem::setFiltersChildEvents(bool enabled)

如果enabled 为true，则该项将被设置为过滤其所有子项的所有事件（即，原本 intended for 其任何子项的所有事件都会被转发至该项）；否则，如果enabled 为false，该项将仅处理其自身的事件。默认值为false。

另请参阅 filtersChildEvents()。

void QGraphicsItem::setFlag(QGraphicsItem::GraphicsItemFlag flag, bool enabled = true)

如果enabled 为真，则项目标志flag 被启用；否则，该标志被禁用。

另请参阅 flags() 和setFlags()。

void QGraphicsItem::setFlags(QGraphicsItem::GraphicsItemFlags flags)

将项目标志设置为flags 。flags 中的所有标志均被启用；flags 中未包含的所有标志均被禁用。

如果该项当前拥有焦点，且flags 未启用ItemIsFocusable ，则调用此函数后该项将失去焦点。同样地，如果该项已被选中，且flags 未启用ItemIsSelectable ，则该项将自动被取消选中。

默认情况下，所有标志均未启用。（QGraphicsWidget 默认启用ItemSendsGeometryChanges 标志，以便跟踪位置变化。）

另请参阅 flags() 和setFlag()。

void QGraphicsItem::setFocus(Qt::FocusReason focusReason = Qt::OtherFocusReason)

将键盘焦点赋予此项。focusReason 参数将被传递给该函数生成的任何focus event 对象；该参数用于说明该项获得焦点的缘由。

只有设置了ItemIsFocusable 标志且处于启用状态的项目才能接受键盘焦点。

如果该控件不可见、非活动状态或未与任何场景关联，则不会立即获得输入焦点。不过，如果它稍后变得可见，它将被注册为其子控件树的首选焦点控件。

调用此函数后，该项将收到一个值为focusReason 的focus in event 。如果另一个项已经获得了焦点，该项将首先收到一个focus out event ，表明它已失去输入焦点。

另请参阅 clearFocus()、hasFocus()、focusItem() 和focusProxy()。

void QGraphicsItem::setFocusProxy(QGraphicsItem *item)

将该项的焦点代理设置为item 。

如果某个项具有焦点代理，当该项获得输入焦点时，焦点代理将接收输入焦点。该项本身仍将拥有焦点（即hasFocus() 将返回 true），但只有焦点代理会接收键盘输入。

一个焦点代理本身也可以拥有另一个焦点代理，以此类推。在这种情况下，键盘输入将由最外层的焦点代理处理。

焦点代理item 必须属于与该项相同的场景。

另请参阅 focusProxy()、setFocus() 和hasFocus()。

void QGraphicsItem::setGraphicsEffect(QGraphicsEffect *effect)

将effect 设置为该项的图形效果。如果该项上已经安装了图形效果，QGraphicsItem 会在安装新的effect 之前删除现有的图形效果。您可以通过调用setGraphicsEffect(nullptr)来删除现有的图形效果。

如果effect 是安装在另一个项目上的效果，setGraphicsEffect()将从该项目上移除该效果，并将其安装到本项目上。

QGraphicsItem 将获得effect 的所有权。

另请参阅 graphicsEffect()。

void QGraphicsItem::setGroup(QGraphicsItemGroup *group)

将该项目添加到项目组group 中。如果group 的值为nullptr ，则该项目将从当前所属的任何组中移除，并作为前一个组的父节点的子节点添加进去。

另请参阅 group() 和QGraphicsScene::createItemGroup()。

void QGraphicsItem::setInputMethodHints(Qt::InputMethodHints hints)

将该项目的当前输入法提示设置为hints 。

另请参阅 inputMethodHints() 和inputMethodQuery()。

void QGraphicsItem::setOpacity(qreal opacity)

设置该元素的本地不透明度（opacity ），取值范围在 0.0（透明）到 1.0（不透明）之间。该元素的本地不透明度将与父元素及祖先元素的不透明度合并，形成effectiveOpacity()。

默认情况下，不透明度从父元素向子元素传播，因此如果父元素的不透明度为 0.5，且子元素的不透明度也是 0.5，则子元素的有效不透明度将为 0.25。

opacity 属性决定了传递给paint() 函数的绘制器的状态。如果项目被缓存（即ItemCoordinateCache 或DeviceCoordinateCache ），则在渲染时，该属性将应用于项目的缓存。

有两个项目标志会影响该项目的不透明度与父项的混合方式：ItemIgnoresParentOpacity 和ItemDoesntPropagateOpacityToChildren 。

另请参阅 opacity()、effectiveOpacity() 和setVisible()。

void QGraphicsItem::setPanelModality(QGraphicsItem::PanelModality panelModality)

将此项目的模态设置为panelModality 。

更改可见项的模态状态将立即生效。

另请参阅 panelModality()。

void QGraphicsItem::setParentItem(QGraphicsItem *newParent)

将该项的父项设置为newParent 。如果该项已有父项，则会先将其从原父项中移除。如果newParent 的值为0，则该项将成为顶级项。

请注意，这会隐式地将该图形项添加到父项的场景中。您不应自行将该项通过 `add ` 添加到场景中。

若在作为 `newParent ` 祖先的项上调用此函数，其行为未定义。

另请参阅 parentItem() 和childItems()。

void QGraphicsItem::setPos(const QPointF &pos)

将项的位置设置为pos ，该坐标位于父级坐标系中。对于没有父级的项，pos 位于场景坐标系中。

项的位置描述了其在父级坐标系中的原点（本坐标系 (0, 0)）。

另请参阅 pos()、scenePos() 以及《图形视图坐标系》。

void QGraphicsItem::setPos(qreal x, qreal y)

此便捷函数相当于调用 setPos(QPointF(x,y))。

void QGraphicsItem::setRotation(qreal angle)

设置沿 Z 轴顺时针旋转angle （单位为度）。默认值为 0（即对象不旋转）。赋值为负数将使对象逆时针旋转。 通常，旋转角度的取值范围为 (-360, 360)，但也可以赋值超出此范围的数值（例如，370 度的旋转与 10 度的旋转效果相同）。

项目围绕其变换原点旋转，默认原点为 (0, 0)。您可以通过调用setTransformOriginPoint() 来选择不同的变换原点。

旋转效果将与该项的scale()、transform() 和transformations() 结合，将该项的坐标系映射到父项。

另请参阅 rotation()、setTransformOriginPoint() 和Transformations 。

void QGraphicsItem::setScale(qreal factor)

设置项目factor 的缩放比例。默认缩放比例为1.0（即项目不进行缩放）。 缩放因子为 0.0 时，项目将缩小为一个点。如果指定负缩放因子，项目将被翻转并镜像（即旋转 180 度）。

项目的缩放以它的变换原点为中心，默认原点为 (0, 0)。您可以通过调用setTransformOriginPoint() 来选择不同的变换原点。

缩放效果将与该元素的rotation()、transform()和transformations()结合，将该元素的坐标系映射到父元素上。

另请参阅 scale()、setTransformOriginPoint() 以及“变换示例”。

void QGraphicsItem::setSelected(bool selected)

如果 `selected ` 为真且该项目可选，则选中该项目；否则，取消选中该项目。

如果该项目属于某个组，则该函数会切换整个组的选中状态。如果该组被选中，则组中的所有项目也被选中；如果该组未被选中，则组中没有任何项目被选中。

只有可见、启用且可选中的项目才能被选中。如果selected 为真，而该项目不可见、已禁用或不可选中，则此函数不执行任何操作。

默认情况下，项目不可选中。要启用选中功能，请设置ItemIsSelectable 标志。

提供此函数是为了方便操作，允许单独切换项目的选中状态。不过，更常见的选中项目的方式是调用 `QGraphicsScene::setSelectionArea()`，该函数会针对场景中指定区域内所有可见、启用且可选中的项目调用此函数。

另请参阅 isSelected() 和QGraphicsScene::selectedItems()。

void QGraphicsItem::setToolTip(const QString &toolTip)

将该项目的工具提示设置为toolTip 。如果toolTip 为空，则该项目的工具提示将被清除。

另请参阅 toolTip() 和QToolTip 。

void QGraphicsItem::setTransform(const QTransform &matrix, bool combine = false)

将该项的当前变换矩阵设置为matrix 。

如果combine 为true，则matrix 将与当前矩阵进行组合；否则，matrix 将替换当前矩阵。combine 默认值为false。

为了简化与使用变换视图的项之间的交互，QGraphicsItem 提供了 mapTo... 和 mapFrom... 函数，可在项的坐标与场景坐标之间进行转换。例如，您可以调用mapToScene() 将项坐标映射到场景坐标，或调用mapFromScene() 将场景坐标映射到项坐标。

变换矩阵与项的rotation()、scale() 和transformations() 结合，形成一个复合变换，将项的坐标系映射到其父级。

另请参阅 transform()、setRotation()、setScale()、setTransformOriginPoint()、图形视图坐标系以及Transformations 。

void QGraphicsItem::setTransformOriginPoint(const QPointF &origin)

设置变换在项目坐标系中的origin 点。

另请参阅 transformOriginPoint() 和Transformations 。

void QGraphicsItem::setTransformOriginPoint(qreal x, qreal y)

设置变换在项坐标系中的原点。这相当于调用 setTransformOriginPoint(QPointF(x,y))。

另请参阅 setTransformOriginPoint() 和Transformations 。

void QGraphicsItem::setTransformations(const QList<QGraphicsTransform *> &transformations)

设置当前应用于该项目的图形列表：transformations （QGraphicsTransform ）。

若您仅需对项目进行旋转或缩放，应调用setRotation() 或setScale() 方法。若需对项目设置任意变换，可调用setTransform() 方法。

QGraphicsTransform 用于对项目应用并控制一系列独立的变换操作。这在动画制作中尤为有用，因为每项变换操作都需要独立地或以不同的方式进行插值。

这些变换会与项目的rotation()、scale() 和transform() 结合使用，将项目的坐标系映射到父项目上。

另请参阅 transformations()、scale()、setTransformOriginPoint() 以及Transformations 。

void QGraphicsItem::setVisible(bool visible)

如果 `visible ` 为真，则该项被设为可见；否则，该项被设为不可见。不可见项不会被绘制，也不会接收任何事件。特别是，鼠标事件会直接穿过不可见项，并传递给可能位于其后方的任何项。 不可见项也无法被选中，无法获得输入焦点，且不会被 `QGraphicsScene` 的项位置函数检测到。

如果一个项目在捕获鼠标状态时（即正在接收鼠标事件时）变为不可见，它将自动失去鼠标捕获状态，且即使将该项目再次设为可见，也不会恢复该捕获状态；必须接收新的鼠标点击事件才能重新获得鼠标捕获状态。

同样，不可见项目无法获得焦点，因此如果项目在变为不可见时拥有焦点，它将失去焦点，且仅通过再次使该项目可见无法恢复焦点。

如果隐藏父项，其所有子项也会被隐藏。如果显示父项，所有子项都会被显示，除非它们已被显式隐藏（即，如果对子项调用 setVisible(false)，即使其父项被隐藏然后再次显示，该子项也不会被重新显示）。

项目默认是可见的；对于新项目，无需调用 setVisible() 方法。

另请参阅 isVisible()、show()、hide() 和setOpacity()。

void QGraphicsItem::setX(qreal x)

设置项目位置的x 坐标。相当于调用setPos(x,y())。

另请参阅 x() 和setPos()。

void QGraphicsItem::setY(qreal y)

设置项目位置的y 坐标。等同于调用setPos(x(), y)。

另请参阅 y()、x() 和setPos()。

void QGraphicsItem::setZValue(qreal z)

将该元素的Z值设置为z 。Z值决定了同级（相邻）元素的堆叠顺序。Z值较高的同级元素将始终显示在Z值较低的同级元素之上。

如果恢复 Z 值，则该项目的插入顺序将决定其堆叠顺序。

Z值不会以任何方式影响对象的大小。

默认 Z 值为 0。

另请参阅 zValue()、Sorting 、stackBefore() 和ItemStacksBehindParent 。

[virtual] QPainterPath QGraphicsItem::shape() const

返回该项在本地坐标系中的形状，类型为QPainterPath 。该形状用于多种用途，包括碰撞检测、命中测试，以及QGraphicsScene::items()函数。

默认实现会调用boundingRect()来返回一个简单的矩形形状，但子类可以重写此函数，为非矩形项目返回更精确的形状。例如，圆形项目可能会选择返回椭圆形，以实现更好的碰撞检测。例如：

QPainterPath RoundItem::shape() const
{
    QPainterPath path;
    path.addEllipse(boundingRect());
    return path;
}

形状的轮廓可能会因绘制时所用画笔的宽度和样式而有所不同。若要将此轮廓包含在对象的形状中，可使用QPainterPathStroker 根据笔画创建形状。

该函数由contains()和collidesWithPath()的默认实现调用。

另请参阅 boundingRect()、contains()、prepareGeometryChange() 以及QPainterPathStroker 。

void QGraphicsItem::show()

显示该项目（项目默认可见）。

此便捷函数等同于调用setVisible(true) 。

另请参阅 hide() 和setVisible()。

void QGraphicsItem::stackBefore(const QGraphicsItem *sibling)

将该项堆叠在“sibling ”之前，这意味着该项将被绘制在同级项的后面。换言之，从视觉上看，该同级项将位于该项之上。

这两个项目必须是同级项目（即它们必须拥有相同的父项目，或者都必须是顶级项目）。sibling 的 Z 值必须与该项目相同，否则调用此函数将无效。

默认情况下，所有同级元素按插入顺序堆叠（即，您添加的第一个元素会先于后续添加的元素渲染）。如果两个元素的 Z 值不同，则 Z 值较高的元素位于上方。当 Z 值相同时，插入顺序将决定堆叠顺序。

另请参阅 setZValue(),ItemStacksBehindParent 以及Sorting 。

QGraphicsObject *QGraphicsItem::toGraphicsObject()

如果该类实际上是一个图形对象，则返回将其转换为QGraphicsObject 的图形项；否则返回0。

const QGraphicsObject *QGraphicsItem::toGraphicsObject() const

如果该类实际上是一个图形对象，则返回将其转换为QGraphicsObject 的图形项；否则返回0。

QString QGraphicsItem::toolTip() const

返回该项目的工具提示；如果未设置工具提示，则返回一个空的QString 。

另请参阅 setToolTip() 和QToolTip 。

QGraphicsItem *QGraphicsItem::topLevelItem() const

返回该项的顶级项。顶级项是指该项的最高层祖先项，其父项为nullptr 。如果某项没有父项，则返回其自身的指针（即，顶级项就是其自身的顶级项）。

另请参阅 parentItem()。

QGraphicsWidget *QGraphicsItem::topLevelWidget() const

返回指向该项顶级小部件的指针（即该项的祖先小部件，其父级为nullptr ，或者其父级不是小部件），如果该项没有顶级小部件，则返回nullptr 。如果该项本身就是顶级小部件，则该函数返回指向该项本身的指针。

QTransform QGraphicsItem::transform() const

返回该项的变换矩阵。

该变换矩阵将与该对象的rotation()、scale()和transformations()组合，形成该对象的综合变换。

默认变换矩阵为单位矩阵。

另请参阅 setTransform() 和sceneTransform()。

QPointF QGraphicsItem::transformOriginPoint() const

返回变换在项坐标系中的原点。

默认值为QPointF(0,0)。

另请参阅 setTransformOriginPoint() 和Transformations 。

QList<QGraphicsTransform *> QGraphicsItem::transformations() const

返回当前应用于该项的一系列图形变换列表。

QGraphicsTransform 用于对项目应用并控制一系列独立的变换操作。这在动画制作中尤为有用，因为每项变换操作都需要独立插值，或采用不同的插值方式。

这些变换将与该项的rotation()、scale()和transform()方法结合使用，以将该项的坐标系映射到父项。

另请参阅 setTransformations()、scale()、rotation()、transformOriginPoint() 以及Transformations 。

[virtual] int QGraphicsItem::type() const

返回一个项目的类型，类型为整数。所有标准图形项目类都与一个唯一的值相关联；参见QGraphicsItem::Type 。qgraphicsitem_cast() 方法会使用此类型信息来区分不同类型。

默认实现（位于QGraphicsItem 中）返回UserType 。

若要使qgraphicsitem_cast() 能与自定义项配合使用，请重写此函数，并声明一个 Type 枚举值，使其等于自定义项的类型。自定义项返回的值必须大于或等于UserType （65536）。

例如：

class Item : public QGraphicsItem
{
public:
   enum { Type = UserType + 1 };

   int type() const override
   {
       // Enable the use of qgraphicsitem_cast with this item.
       return Type;
   }
   //...
};

另请参阅 UserType 。

void QGraphicsItem::ungrabKeyboard()

释放键盘锁定。

另请参阅 grabKeyboard() 和ungrabMouse()。

void QGraphicsItem::ungrabMouse()

释放鼠标抓取。

另请参阅 grabMouse() 和ungrabKeyboard()。

void QGraphicsItem::unsetCursor()

清除该项目的光标。

另请参阅 hasCursor() 和setCursor()。

void QGraphicsItem::update(const QRectF &rect = QRectF())

安排重新绘制该控件中由rect 覆盖的区域。当控件需要重新绘制时（例如外观或大小发生变化时），您可以调用此函数。

此函数不会立即触发绘制；而是安排一个绘制请求，待控制权进入事件循环后由QGraphicsView 处理。只有当该项在任何关联视图中可见时，才会被重新绘制。

作为该项目重新绘制的副作用，与rect 所处理区域重叠的其他项目也可能被重新绘制。

如果该项目不可见（即isVisible() 返回false ），则此函数不执行任何操作。

另请参阅 paint() 和boundingRect()。

void QGraphicsItem::update(qreal x, qreal y, qreal width, qreal height)

此便捷函数等同于调用 update(QRectF(x,y,width,height))。

[protected] void QGraphicsItem::updateMicroFocus()

更新该项目的微焦点。

另请参阅 QInputMethod 。

[virtual protected] void QGraphicsItem::wheelEvent(QGraphicsSceneWheelEvent *event)

此事件处理程序（针对event 事件）可以被重写，以便接收该项目的滚轮事件。如果重写此函数，默认情况下将接受event 。

如果您忽略该事件（即通过调用QEvent::ignore()），该事件将传播到该项下的任何子项。如果没有子项处理该事件，场景将忽略该事件，并将其传播到视图（例如，视图的垂直滚动条）。

默认实现会忽略该事件。

另请参阅 sceneEvent()。

QGraphicsWidget *QGraphicsItem::window() const

返回该项的窗口，如果该项没有窗口，则返回nullptr 。如果该项本身是一个窗口，则返回其自身；否则，返回其最近的窗口祖先。

另请参阅 QGraphicsWidget::isWindow()。

qreal QGraphicsItem::x() const

此便捷函数等同于调用pos().x()。

另请参阅 setX() 和y()。

qreal QGraphicsItem::y() const

此便捷函数等同于调用pos().y()。

另请参阅 setY() 和x()。

qreal QGraphicsItem::zValue() const

返回该元素的 Z 值。Z 值会影响同级（相邻）元素的堆叠顺序。

默认 Z 值为 0。

另请参阅 setZValue(),Sorting,stackBefore() 以及ItemStacksBehindParent 。