QQuickItem Class

成员函数文档

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

根据给定的parent 创建一个QQuickItem。

该parent 将同时用作visual parent 和QObject 的父项。

[override virtual noexcept] QQuickItem::~QQuickItem()

销毁QQuickItem 。

bool QQuickItem::acceptHoverEvents() const

返回此项目是否接受悬停事件。

默认值为 false。

如果该值为 false，则该项将不会通过hoverEnterEvent()、hoverMoveEvent() 和hoverLeaveEvent() 函数接收任何悬停事件。

另请参阅 setAcceptHoverEvents()。

bool QQuickItem::acceptTouchEvents() const

返回此项目是否接受触摸事件。

默认值为false 。

如果该值为false ，则该项将不会通过touchEvent()函数接收任何触摸事件。

另请参阅 setAcceptTouchEvents()。

Qt::MouseButtons QQuickItem::acceptedMouseButtons() const

返回该项支持的鼠标按钮。

默认值为Qt::NoButton ；即不接受任何鼠标按钮。

如果某个项目不接受特定鼠标事件对应的鼠标按钮，则该鼠标事件不会传递给该项目，而是会传递给项目层次结构中的下一个项目。

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

[virtual] QRectF QQuickItem::boundingRect() const

返回该项在其自身坐标系中的范围：一个从0, 0 到width() 以及height() 的矩形。

[invokable] QQuickItem *QQuickItem::childAt(qreal x, qreal y) const

返回在该项的坐标系内，位于点 (x,y) 处找到的第一个可见子项。

如果不存在此类项，则返回nullptr 。

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

返回该项的子项。

[virtual protected] bool QQuickItem::childMouseEventFilter(QQuickItem *item, QEvent *event)

重写此方法，以过滤该项的子项收到的指针事件。

仅当 `filtersChildMouseEvents()` 的返回值为 `true` 时，才会调用此方法。

如果指定的event 不应传递给指定的子元素item ，则返回true ；否则返回false 。如果您返回true ，还应通过accept 或ignore 设置event ，以指示事件传播应停止还是继续。不过，该event 将始终发送给父链中所有子级 mouseEventFilter。

另请参阅 setFiltersChildMouseEvents()。

[override virtual protected] void QQuickItem::classBegin()

重写了：QQmlParserStatus::classBegin()。

派生类应在向 classBegin 添加自己的操作之前，先调用基类的方法。

[virtual] QRectF QQuickItem::clipRect() const

返回在viewportItem()中当前可见的该项内的矩形区域，前提是存在视口且ItemObservesViewport 标志已设置；否则，返回该项在其自身坐标系中的范围：一个从0, 0 到width()和height()的矩形。 当 `clip ` 为 `true` 时，此区域即为应保持可见的区域。它也可用于 `updatePaintNode()` 中，以限制添加到场景图中的图形。

例如，一个大型绘图或大型文本文档可能会显示在一个仅占据应用程序窗口一部分的 Flickable 中：在这种情况下，Flickable 是视口项，而自定义内容渲染项可以选择省略位于当前可见区域之外的场景图节点。 如果设置了ItemObservesViewport 标志，则每次用户在Flickable中滚动内容时，该区域都会发生变化。

对于嵌套的视口项，clipRect() 是所有设置了 `ItemIsViewport ` 标志的父节点的 `boundingRect` 的交集，并映射到该项的坐标系上。

另请参阅 boundingRect()。

[override virtual protected] void QQuickItem::componentComplete()

重写了：QQmlParserStatus::componentComplete()。

派生类在向 `componentComplete` 添加自己的操作之前，应先调用基类的方法。

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

如果该项包含位于本坐标系中的point ，则返回true ；否则返回false 。

可以重写此函数，以便处理具有自定义形状的项中的点碰撞。默认实现会检查该点是否位于containmentMask()内部（如果已设置），否则检查是否位于包围盒内部。

QCursor QQuickItem::cursor() const

返回该项目的光标形状。

当鼠标悬停在此项目上时，鼠标指针将呈现此形状，除非设置了覆盖指针。有关各种有用的形状，请参阅list of predefined cursor objects 。

如果未设置光标形状，则返回具有Qt::ArrowCursor 形状的光标；但如果重叠的项目具有有效的光标，则可能会显示另一种光标形状。

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

[virtual protected] void QQuickItem::dragEnterEvent(QDragEnterEvent *event)

可以在子类中重写此事件处理程序，以接收某项的drag-enter事件。事件信息由event 参数提供。

只有当该项设置了ItemAcceptsDrops 标志时，才会提供拖放事件。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

另请参阅 Drag 和拖放。

[virtual protected] void QQuickItem::dragLeaveEvent(QDragLeaveEvent *event)

可以在子类中重写此事件处理程序，以接收某项的拖动离开事件。事件信息由event 参数提供。

只有当该项设置了ItemAcceptsDrops 标志时，才会提供拖放事件。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

另请参阅 Drag 和拖放。

[virtual protected] void QQuickItem::dragMoveEvent(QDragMoveEvent *event)

可以在子类中重写此事件处理程序，以接收某项的拖动事件。事件信息由event 参数提供。

只有当该项目的ItemAcceptsDrops 标志已设置时，才会提供拖放事件。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

另请参阅 Drag 和拖放。

[virtual protected] void QQuickItem::dropEvent(QDropEvent *event)

可以在子类中重写此事件处理程序，以接收某项的拖放事件。事件信息由event 参数提供。

只有当该项设置了ItemAcceptsDrops 标志时，才会提供拖放事件。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

另请参阅 Drag 和拖放。

[invokable, since 6.3] void QQuickItem::dumpItemTree() const

递归地输出以该项为起点的各项（Items）的视觉树的相关细节。

该函数在 Qt 6.3 中引入。

另请参阅 《调试技巧》以及GammaRay 的Qt Quick 检查器。

[invokable, since 6.3] void QQuickItem::ensurePolished()

调用updatePolish()

这对于布局（或定位器）等控件非常有用，它们会延迟计算其implicitWidth 和implicitHeight ，直到接收到PolishEvent事件为止。

通常情况下，例如当子项被添加到或从布局中移除时，隐式大小不会立即被计算（这是为了优化）。 在某些情况下，可能需要在子项添加后立即查询布局的隐式大小。如果是这种情况，请在查询隐式大小之前调用此函数。

该函数在 Qt 6.3 中引入。

另请参阅 updatePolish() 和polish()。

[override virtual protected] bool QQuickItem::event(QEvent *ev)

重写了：QObject::event(QEvent *e)。

bool QQuickItem::filtersChildMouseEvents() const

返回指示是否应通过该项目过滤针对其子项的指针事件。

如果该项及其子项均已调用 `acceptTouchEvents()`true ，则当发生触摸交互时，该项将过滤该触摸事件。但如果该项或其子项中任一方无法处理触摸事件，则会调用 `childMouseEventFilter()` 并传入一个合成鼠标事件。

另请参阅 setFiltersChildMouseEvents() 和childMouseEventFilter()。

QQuickItem::Flags QQuickItem::flags() const

返回该项目的标志。

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

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

可以在子类中重写此事件处理程序，以接收某项的焦点获得事件。事件信息由event 参数提供。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

如果您确实重写了此函数，则应调用基类的实现。

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

可以在子类中重新实现此事件处理程序，以接收某项的焦点移出事件。事件信息由event 参数提供。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

[invokable] void QQuickItem::forceActiveFocus()

将焦点强制移至该项。

此方法将焦点设置在该项上，并确保对象层次结构中所有祖先FocusScope 对象也获得focus 。

焦点变化的原因将设置为Qt::OtherFocusReason 。请使用重载的方法指定焦点原因，以便更好地处理焦点变化。

另请参阅 activeFocus 。

[invokable] void QQuickItem::forceActiveFocus(Qt::FocusReason reason)

将焦点主动移至具有给定reason 的项上。

此方法将焦点设置在该项上，并确保对象层次结构中所有祖先FocusScope 对象也获得focus 属性。

另请参阅 activeFocus 和Qt::FocusReason 。

[virtual protected, since 6.0] void QQuickItem::geometryChange(const QRectF &newGeometry, const QRectF &oldGeometry)

调用此函数是为了处理该项的几何形状变化，即从 `oldGeometry ` 变为 `newGeometry`。如果这两个几何形状相同，则不执行任何操作。

派生类必须在其实现中调用基类的方法。

该函数于 Qt 6.0 中引入。

QSharedPointer<QQuickItemGrabResult> QQuickItem::grabToImage(const QSize &targetSize = QSize())

将该项目抓取到内存图像中。

抓取操作以异步方式进行，当抓取完成后，将触发QQuickItemGrabResult::ready()信号。

使用targetSize 指定目标图像的大小。默认情况下，结果图像的大小与 item 相同。

如果无法启动抓取，该函数将返回null 。

另请参阅 QQuickWindow::grabWindow()。

[protected] bool QQuickItem::heightValid() const

返回“height”属性是否已被显式设置。

[virtual protected] void QQuickItem::hoverEnterEvent(QHoverEvent *event)

可以在子类中重写此事件处理程序，以接收某项的悬停进入事件。事件信息由event 参数提供。

只有当acceptHoverEvents() 为 true 时，才会提供悬停事件。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

[virtual protected] void QQuickItem::hoverLeaveEvent(QHoverEvent *event)

可以在子类中重新实现此事件处理程序，以接收项目的悬停离开事件。事件信息由event 参数提供。

只有当acceptHoverEvents() 的值为 true 时，才会提供悬停事件。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

[virtual protected] void QQuickItem::hoverMoveEvent(QHoverEvent *event)

可以在子类中重写此事件处理程序，以接收项目的悬停移动事件。事件信息由event 参数提供。

只有当acceptHoverEvents() 的值为 true 时，才会提供悬停事件。

该事件默认会被接受，因此如果您重写此函数，则无需显式地接受该事件。如果您不接受该事件，请调用event->ignore() 。

qreal QQuickItem::implicitWidth() const

返回由其他确定内容的属性所隐含的项的宽度。

另请参阅 ` setImplicitWidth()`。

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

可以在子类中重写此事件处理程序，以接收某项的输入法事件。事件信息由event 参数提供。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

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

此方法仅适用于输入项。

如果该项是输入项，则应重写此方法，以返回给定query 的相关输入法标志。

另请参阅 QWidget::inputMethodQuery()。

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

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

另请参阅 parentItem()。

[protected] bool QQuickItem::isComponentComplete() const

如果 QML 组件的构建已完成，则返回 true；否则返回 false。

通常希望将某些处理推迟到组件加载完成后再进行。

另请参阅 componentComplete()。

bool QQuickItem::isFocusScope() const

如果该项目是聚焦范围，则返回 true；否则返回 false。

[virtual] bool QQuickItem::isTextureProvider() const

如果该项是纹理提供者，则返回 true。默认实现返回 false。

该函数可从任何线程调用。

[virtual protected] void QQuickItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value)

当此项发生change 时调用。

value 在适用时，该方法包含与该变更相关的额外信息。

如果您在子类中重写此方法，请务必在

QQuickItem::itemChange(change, value);

，以确保会发出windowChanged()信号。

bool QQuickItem::keepMouseGrab() const

返回鼠标输入是否应仅限于此项。

另请参阅 setKeepMouseGrab()、QEvent::accept() 和QEvent::ignore()。

bool QQuickItem::keepTouchGrab() const

返回该项抓取的触点是否应专属地保留在此项上。

另请参阅 setKeepTouchGrab()、keepMouseGrab()、QEvent::accept() 以及QEvent::ignore()。

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

可以在子类中重写此事件处理程序，以接收某项的按键事件。事件信息由event 参数提供。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

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

可以在子类中重写此事件处理程序，以接收某项的键释放事件。事件信息由event 参数提供。

该事件默认会被接受，因此若重写此函数，则无需显式接受该事件。若不接受该事件，请调用event->ignore() 。

[invokable] QPointF QQuickItem::mapFromGlobal(const QPointF &point) const

将全局屏幕坐标系中给定的point 映射到该项坐标系中的等效点，并返回映射后的坐标。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些元素属于不同的场景，则映射中会包含两个场景之间的相对位置。

例如，这对于向Qt Quick 组件添加弹出窗口可能会有所帮助。

另请参阅 Qt Quick 中的“概念 - 视觉坐标”。

[invokable] QPointF QQuickItem::mapFromItem(const QQuickItem *item, const QPointF &point) const

将item 中给定的point 映射到该项坐标系中的等效点，并返回映射后的坐标。

映射过程中会使用该对象的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些项目属于不同的场景，则映射关系中包含这两个场景的相对位置。

如果 `item ` 的值为 `nullptr`，则该映射会根据场景的坐标系对 `point ` 进行映射。

另请参阅 《Qt Quick 》中的“概念 - 视觉坐标”。

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

将场景坐标系中给定的point 映射到该项坐标系中的等效点，并返回映射后的坐标。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些项目属于不同的场景，则映射信息中包含两个场景的相对位置。

另请参阅 Qt Quick 中的“概念 - 视觉坐标”。

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

将item 中给定的rect 映射到该项坐标系内的等效矩形区域，并返回映射后的矩形值。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些项目属于不同的场景，则映射信息中包含两个场景之间的相对位置。

如果item 为nullptr ，则该映射将rect 从场景的坐标系中映射出来。

另请参阅 《Qt Quick 》中的“概念 - 视觉坐标”。

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

将场景坐标系中给定的rect 映射到该项坐标系内的等效矩形区域，并返回映射后的矩形值。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些项目属于不同的场景，则映射中包含两个场景之间的相对位置。

另请参阅 Qt Quick 中的“概念 - 视觉坐标”。

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

将该项坐标系中的给定rect 映射到item 坐标系中的等效矩形区域，并返回映射后的矩形值。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些项目属于不同的场景，则映射结果将包含两个场景之间的相对位置。

如果item 的值为nullptr ，则会将rect 映射到该场景的坐标系中。

另请参阅 《Qt Quick 》中的“概念——视觉坐标”。

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

将该项坐标系中给定的rect 映射到场景坐标系中的等效矩形区域，并返回映射后的矩形值。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些项目属于不同的场景，则映射信息中包含两个场景之间的相对位置。

另请参阅 Qt Quick 中的“概念 - 视觉坐标”。

[invokable] QPointF QQuickItem::mapToGlobal(const QPointF &point) const

将该项坐标系中的给定point 映射到全局屏幕坐标系中的等效点，并返回映射后的坐标。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些元素属于不同的场景，则映射信息中包含两个场景之间的相对位置。

例如，这对于向Qt Quick 组件添加弹出窗口可能会很有帮助。

另请参阅 《Qt Quick 》中的“概念 - 视觉坐标”。

[invokable] QPointF QQuickItem::mapToItem(const QQuickItem *item, const QPointF &point) const

将该项坐标系中给定的坐标point 映射到item 坐标系中的等效点，并返回映射后的坐标。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些项目属于不同的场景，则映射信息中会包含两个场景之间的相对位置。

如果 `item ` 的值为 `nullptr`，则会将 `point ` 映射到该场景的坐标系中。

另请参阅 《Qt Quick 》中的“概念 - 视觉坐标”。

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

将该项坐标系中的给定point 映射到场景坐标系中的等效点，并返回映射后的坐标。

映射过程中会使用该项的以下属性：x 、y 、scale 、rotation 、transformOrigin 以及transform 。

如果这些项目属于不同的场景，则映射将包含两个场景之间的相对位置。

另请参阅 Qt Quick 中的“概念 - 视觉坐标”。

[virtual protected] void QQuickItem::mouseDoubleClickEvent(QMouseEvent *event)

可以在子类中重写此事件处理程序，以接收某项的鼠标双击事件。事件信息由event 参数提供。

该事件默认会被接受，因此若重写此函数，则无需显式接受该事件。若不接受该事件，请调用event->ignore() 。

[virtual protected] void QQuickItem::mouseMoveEvent(QMouseEvent *event)

可以在子类中重写此事件处理程序，以接收某项的鼠标移动事件。事件信息由event 参数提供。

为了接收鼠标移动事件，必须先接受前一个鼠标按下事件（例如通过重写mousePressEvent() 函数），并且acceptedMouseButtons() 函数必须返回相应的鼠标按钮。

该事件默认被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

[virtual protected] void QQuickItem::mousePressEvent(QMouseEvent *event)

可以在子类中重写此事件处理程序，以接收某项的鼠标点击事件。事件信息由event 参数提供。

为了接收鼠标按下事件，acceptedMouseButtons() 必须返回相应的鼠标按钮。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

[virtual protected] void QQuickItem::mouseReleaseEvent(QMouseEvent *event)

可以在子类中重写此事件处理程序，以接收某项的鼠标释放事件。事件信息由event 参数提供。

为了接收鼠标释放事件，必须先接受先前的鼠标按下事件（例如通过重写mousePressEvent() 函数），并且acceptedMouseButtons() 函数必须返回相应的鼠标按钮。

该事件默认会被接受，因此若重写此函数，则无需显式接受该事件。若不接受该事件，请调用event->ignore() 。

[virtual protected] void QQuickItem::mouseUngrabEvent()

可以在子类中重新实现此事件处理程序，以便在该项目上发生鼠标释放事件时收到通知。

[invokable] QQuickItem *QQuickItem::nextItemInFocusChain(bool forward = true)

返回焦点链中紧邻该项的项。如果forward 的值为true ，或者未提供该参数，则返回向前方向上的下一个项；如果forward 的值为false ，则返回向后方向上的下一个项。

void QQuickItem::polish()

为该项目安排一场波兰活动。

当场景图处理该请求时，它将调用该项上的updatePolish() 方法。

另请参阅 updatePolish()、QQuickTest::qIsPolishScheduled() 和ensurePolished()。

[virtual protected] void QQuickItem::releaseResources()

当某个项需要释放尚未由QQuickItem::updatePaintNode() 返回的节点所管理的图形资源时，会调用此函数。

这种情况发生在项目即将从其先前进行渲染的窗口中移除时。当调用该函数时，可以保证该项目拥有一个 `window `。

该函数在 GUI 线程上被调用，而渲染线程（若已使用）的状态则未知。不应直接删除对象，而应通过QQuickWindow::scheduleRenderJob() 将其排入清理队列。

另请参阅 Graphics Resource Handling 。

QQuickItem *QQuickItem::scopedFocusItem() const

如果该项是焦点范围，则返回其焦点链中当前拥有焦点的项。

如果该项不是焦点范围，则返回nullptr 。

void QQuickItem::setAcceptHoverEvents(bool enabled)

如果enabled 为 true，则该项将接受悬停事件；否则，该项不接受悬停事件。

另请参阅 acceptHoverEvents()。

void QQuickItem::setAcceptTouchEvents(bool enabled)

如果enabled 为真，则将该项设置为接受触摸事件；否则，该项不接受触摸事件。

另请参阅 acceptTouchEvents()。

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

将该项接受的鼠标按钮设置为buttons 。

另请参阅 acceptedMouseButtons()。

void QQuickItem::setCursor(const QCursor &cursor)

为该项目设置cursor 形状。

另请参阅 cursor() 和unsetCursor()。

void QQuickItem::setFiltersChildMouseEvents(bool filter)

设置是否应通过该项过滤针对其子项的指针事件。

如果 `filter ` 为 `true`，则当子项触发指针事件时，将调用 `childMouseEventFilter()`。

另请参阅 filtersChildMouseEvents()。

void QQuickItem::setFlag(QQuickItem::Flag flag, bool enabled = true)

如果enabled 为true，则为该项目启用指定的flag ；如果enabled 为false，则该标志被禁用。

这些标志为该项目提供了各种提示；例如，ItemClipsChildrenToShape 标志表示该项目的所有子项都应被裁剪以适应项目区域。

void QQuickItem::setFlags(QQuickItem::Flags flags)

为该项目启用指定的flags 。

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

void QQuickItem::setFocusPolicy(Qt::FocusPolicy policy)

将此项的焦点策略设置为policy 。

另请参阅 focusPolicy()。

void QQuickItem::setKeepMouseGrab(bool keep)

设置鼠标输入是否应仅保留在此项目上。

此功能对于希望在执行预定义手势后捕获并保留鼠标交互的项目非常有用。例如，一个关注鼠标水平移动的项目，一旦超过阈值，即可将keepMouseGrab 设置为true。一旦keepMouseGrab 被设置为true，过滤项将不再响应鼠标事件。

如果 `keep ` 为 `false`，过滤项可能会抢占鼠标控制权。例如，当 `Flickable ` 检测到用户开始移动视口时，可能会尝试抢占鼠标控制权。

另请参阅 keepMouseGrab()。

void QQuickItem::setKeepTouchGrab(bool keep)

用于设置该控件抓取的触点是否应专属地保留给该控件。

此功能适用于希望在执行预定义手势后抓取并保留特定触点的位置。例如，若某个位置希望获取水平方向的触点移动，可在触点位置超过阈值后将 setKeepTouchGrab 设置为 true。一旦 setKeepTouchGrab 被设置为 true，过滤位置将不再对相关触点作出反应。

如果 `keep ` 为 false，过滤项可能会“抢占”该抓取操作。例如，当 `Flickable ` 检测到用户开始移动视口时，可能会尝试抢占该触点抓取操作。

另请参阅 keepTouchGrab() 和setKeepMouseGrab()。

void QQuickItem::setSize(const QSizeF &size)

将项的大小设置为size 。此方法会保留宽度和高度上现有的绑定；因此，任何触发绑定再次执行的更改都会覆盖所设的值。

另请参阅 size 、setWidth 和setHeight 。

QSizeF QQuickItem::size() const

返回该项的大小。

另请参阅 setSize 、width 和height 。

void QQuickItem::stackAfter(const QQuickItem *sibling)

将该项目移动到子项列表中指定同级项目之后的索引位置。子项的顺序既影响视觉堆叠顺序，也影响Tab键焦点导航顺序。

假设这两个项目的 z 值相同，这将导致sibling 被渲染在该项目下方。

如果两个项目的activeFocusOnTab 均设置为true ，这也会导致Tab键焦点顺序发生变化，此时sibling 将比该项目更早获得焦点。

指定的sibling 必须是该元素的同级元素；也就是说，它们必须具有相同的直接parent 。

另请参阅 “概念 - 视觉父元素”中的Qt Quick 。

void QQuickItem::stackBefore(const QQuickItem *sibling)

将该项目移动到子项列表中指定同级项目之前的索引位置。子项的顺序既影响视觉堆叠顺序，也影响Tab键焦点导航顺序。

假设这两个项目的 z 值相同，这将导致 `sibling ` 渲染在该项目之上。

如果两个项目的activeFocusOnTab 属性均设置为true ，这也会导致Tab键焦点顺序发生变化，此时sibling 将在本项目之后获得焦点。

指定的sibling 必须是该项的同级元素；也就是说，它们必须具有相同的直接父元素（parent ）。

另请参阅 “概念 - 视觉父元素”中的Qt Quick 。

[virtual] QSGTextureProvider *QQuickItem::textureProvider() const

返回某项的纹理提供程序。默认实现返回nullptr 。

此函数只能在渲染线程上调用。

[virtual protected] void QQuickItem::touchEvent(QTouchEvent *event)

可以在子类中重写此事件处理程序，以接收某项的触摸事件。事件信息由event 参数提供。

该事件默认会被接受，因此若重写此函数，则无需显式接受该事件。若不接受该事件，请调用event->ignore() 。

[virtual protected] void QQuickItem::touchUngrabEvent()

可以在子类中重新实现此事件处理程序，以便在该项目上发生“触摸释放”事件时收到通知。

void QQuickItem::unsetCursor()

清除该项目的光标形状。

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

[slot] void QQuickItem::update()

为该项目安排一次对updatePaintNode() 的调用。

如果该项正在QQuickWindow 中显示，则一定会调用QQuickItem::updatePaintNode()。

只有指定了QQuickItem::ItemHasContents 的项目才允许调用QQuickItem::update()。

[protected] void QQuickItem::updateInputMethod(Qt::InputMethodQueries queries = Qt::ImQueryInput)

如有必要，请在查询值更新后通知输入法。queries 指明了发生变化的属性。

[virtual protected] QSGNode *QQuickItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *updatePaintNodeData)

当需要将项的状态与场景图同步时，该函数会在渲染线程中被调用。

如果用户在该项上设置了QQuickItem::ItemHasContents 标志，则该函数会作为QQuickItem::update()的返回结果被调用。

该函数应返回该项场景图子树的根节点。大多数实现会返回一个QSGGeometryNode ，其中包含该项的视觉表示。oldNode 是上次调用该函数时返回的节点。updatePaintNodeData 提供了一个指向与该QQuickItem 关联的QSGTransformNode 的指针。

QSGNode *MyItem::updatePaintNode(QSGNode *node, UpdatePaintNodeData *)
{
    QSGSimpleRectNode *n = static_cast<QSGSimpleRectNode *>(node);
    if (!n) {
        n = new QSGSimpleRectNode();
        n->setColor(Qt::red);
    }
    n->setRect(boundingRect());
    return n;
}

在执行此函数期间，主线程会被阻塞，因此可以在主线程中安全地读取QQuickItem 实例及其他对象的值。

如果未调用 QQuickItem::updatePaintNode() 导致实际的场景图变化（例如QSGNode::markDirty() 或添加及移除节点），则底层实现可能会决定不再渲染该场景，因为视觉效果是相同的。

另请参阅 QSGMaterial 、QSGGeometryNode 、QSGGeometry 、QSGFlatColorMaterial 、QSGTextureMaterial 、QSGNode::markDirty() 以及Graphics Resource Handling 。

[virtual protected] void QQuickItem::updatePolish()

该函数应根据该项的需求执行相应的布局操作。

当调用polish()时，场景图会为该项安排一个polish事件。当场景图准备渲染该项时，它会调用updatePolish()，在渲染下一帧之前按需执行任何项布局操作。

另请参阅 ensurePolished()。

QQuickItem *QQuickItem::viewportItem() const

如果设置了ItemObservesViewport 标志，则返回具有ItemIsViewport 标志的最近父级。如果未设置该标志，或者未找到其他视口项，则返回窗口的contentItem。

仅当不存在视口项且该项未在窗口中显示时，才返回 `nullptr `。

另请参阅 clipRect()。

[virtual protected] void QQuickItem::wheelEvent(QWheelEvent *event)

可以在子类中重写此事件处理程序，以接收某项的滚轮事件。事件信息由event 参数提供。

该事件默认会被接受，因此如果您重写此函数，则无需显式接受该事件。如果您不接受该事件，请调用event->ignore() 。

[protected] bool QQuickItem::widthValid() const

返回“width”属性是否已被显式设置。

QQuickWindow *QQuickItem::window() const

返回渲染此项的窗口。

在该项被分配到场景之前，它没有窗口。windowChanged() 信号会在该项进入场景和从场景中移除时分别发出通知。

[signal] void QQuickItem::windowChanged(QQuickWindow *window)

当该项的window 发生变化时，会触发此信号。