QWaylandQuickItem Class
QWaylandQuickItem 类提供了一个Qt Quick 项目，该项目代表 Wayland 客户端的显示区域。更多内容...
| 头文件： | #include <QWaylandQuickItem> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS WaylandCompositor) target_link_libraries(mytarget PRIVATE Qt6::WaylandCompositor) |
| qmake： | QT += waylandcompositor |
| 在 QML 中： | WaylandQuickItem |
| 继承自： | QQuickItem |
| 被继承自： |
属性
|
|
公共函数
| QWaylandQuickItem(QQuickItem *parent = nullptr) | |
| virtual | ~QWaylandQuickItem() override |
| bool | allowDiscardFrontBuffer() const |
| QWaylandCompositor * | compositor() const |
| bool | focusOnClick() const |
| bool | inputEventsEnabled() const |
| bool | inputRegionContains(const QPointF &localPosition) const |
| bool | isBufferLocked() const |
| bool | isPaintEnabled() const |
| QPointF | mapFromSurface(const QPointF &point) const |
| QPointF | mapToSurface(const QPointF &point) const |
| QWaylandSurface::Origin | origin() const |
| QWaylandOutput * | output() const |
| void | setAllowDiscardFrontBuffer(bool discard) |
| void | setBufferLocked(bool locked) |
| void | setFocusOnClick(bool focus) |
| void | setInputEventsEnabled(bool enabled) |
| void | setOutput(QWaylandOutput *output) |
| void | setPrimary() |
| void | setSubsurfaceHandler(QObject *) |
| void | setSurface(QWaylandSurface *surface) |
| void | setTouchEventsEnabled(bool enabled) |
| QObject * | subsurfaceHandler() const |
| QWaylandSurface * | surface() const |
| bool | touchEventsEnabled() const |
| QWaylandView * | view() const |
重新实现的公共函数
| virtual QSGTextureProvider * | textureProvider() const override |
公共插槽
| void | setPaintEnabled(bool paintEnabled) |
| virtual void | takeFocus(QWaylandSeat *device = nullptr) |
信号
| void | allowDiscardFrontBufferChanged() |
| void | bufferLockedChanged() |
| void | compositorChanged() |
| void | focusOnClickChanged() |
| void | inputEventsEnabledChanged() |
| void | originChanged() |
| void | outputChanged() |
| void | paintEnabledChanged() |
| void | subsurfaceHandlerChanged() |
| void | surfaceChanged() |
| void | surfaceDestroyed() |
| void | touchEventsEnabledChanged() |
详细说明
在编写Qt Quick 中的QWaylandCompositor 时，可以使用该类将客户端的内容显示在输出设备上，并将用户输入传递给客户端。
属性文档
allowDiscardFrontBuffer : bool
默认情况下，该项会锁定当前缓冲区，直到有新的缓冲区可用且调用了updatePaintNode()方法为止。将此属性设置为true，可让Qt在节流视图不再使用该缓冲区时立即释放它。这对更新间隔较长的项非常有用。
访问函数：
| bool | allowDiscardFrontBuffer() const |
| void | setAllowDiscardFrontBuffer(bool discard) |
通知器信号：
| void | allowDiscardFrontBufferChanged() |
bufferLocked : bool
该属性表示该项的缓冲区当前是否被锁定。只要缓冲区处于锁定状态，就不会被释放并返回给客户端。
默认值为 false。
访问函数：
| bool | isBufferLocked() const |
| void | setBufferLocked(bool locked) |
通知器信号：
| void | bufferLockedChanged() |
[read-only] compositor : QWaylandCompositor*
该属性存储由该QWaylandQuickItem 渲染的曲面的合成器。
访问函数：
| QWaylandCompositor * | compositor() const |
通知器信号：
| void | compositorChanged() |
focusOnClick : bool
此属性指定当单击或触摸QWaylandQuickItem 时，它是否应获得焦点。
默认值为true 。
访问函数：
| bool | focusOnClick() const |
| void | setFocusOnClick(bool focus) |
通知器信号：
| void | focusOnClickChanged() |
inputEventsEnabled : bool
该属性用于指定是否为该控件启用输入事件。
当true 时，该项将处理并响应输入事件（如键盘和鼠标事件）；当false 时，输入事件将被忽略。
访问函数：
| bool | inputEventsEnabled() const |
| void | setInputEventsEnabled(bool enabled) |
通知器信号：
| void | inputEventsEnabledChanged() |
[read-only] origin : QWaylandSurface::Origin
该属性反映了表面当前缓冲区的原点，即缓冲区的哪个角对应坐标 (0, 0)。
访问函数：
| QWaylandSurface::Origin | origin() const |
通知信号：
| void | originChanged() |
另请参阅 QWaylandSurface::origin 。
output : QWaylandOutput*
此属性保存用于显示该项目的输出内容。
访问函数：
| QWaylandOutput * | output() const |
| void | setOutput(QWaylandOutput *output) |
通知信号：
| void | outputChanged() |
paintEnabled : bool
将此属性设置为false 将停止渲染该项。与通过将visible 设置为false 来隐藏该项不同，此操作不会阻止鼠标或键盘输入到达该项。
访问函数：
| bool | isPaintEnabled() const |
| void | setPaintEnabled(bool paintEnabled) |
通知器信号：
| void | paintEnabledChanged() |
subsurfaceHandler : QObject*
该属性提供了一种覆盖默认子表面行为的方法。
默认情况下，Qt 会创建一个新的 `QWaylandQuickItem ` 作为该项的子项，并保持正确的位置。
要覆盖默认行为，请为该属性分配一个处理程序对象。该处理程序必须实现handleSubsurfaceAdded(QWaylandSurface*) 方法。
该属性的默认值为nullptr 。
访问函数：
| QObject * | subsurfaceHandler() const |
| void | setSubsurfaceHandler(QObject *) |
Notifier 信号：
| void | subsurfaceHandlerChanged() |
surface : QWaylandSurface*
该属性保存了由该QWaylandQuickItem 渲染的表面。
访问函数：
| QWaylandSurface * | surface() const |
| void | setSurface(QWaylandSurface *surface) |
通知器信号：
| void | surfaceChanged() |
touchEventsEnabled : bool
如果触摸事件被转发到客户端界面，则该属性值为 `true `；否则，其值为 `false `。
访问函数：
| bool | touchEventsEnabled() const |
| void | setTouchEventsEnabled(bool enabled) |
通知信号：
| void | touchEventsEnabledChanged() |
成员函数文档
QWaylandQuickItem::QWaylandQuickItem(QQuickItem *parent = nullptr)
使用给定的parent 实例化一个QWaylandQuickItem。
[override virtual noexcept] QWaylandQuickItem::~QWaylandQuickItem()
bool QWaylandQuickItem::inputRegionContains(const QPointF &localPosition) const
如果该项曲面的输入区域包含由 `localPosition` 指定的位置，则返回 `true `。
[invokable] QPointF QWaylandQuickItem::mapFromSurface(const QPointF &point) const
将 Wayland 表面坐标系中的给定point 映射到该项坐标系中的等效点，并返回映射后的坐标。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] QPointF QWaylandQuickItem::mapToSurface(const QPointF &point) const
将该项坐标系中的给定point 映射到Wayland表面坐标系中的等效点，并返回映射后的坐标。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[invokable] void QWaylandQuickItem::setPrimary()
将此QWaylandQuickItem 的视图设为该表面的主视图。
注意： 可通过元对象系统或从 QML 中调用此 函数。参见Q_INVOKABLE 。
另请参阅 QWaylandSurface::primaryView 。
[signal] void QWaylandQuickItem::surfaceDestroyed()
当客户端销毁了与QWaylandQuickItem 关联的wl_surface 时，会发出此信号。此信号的处理程序应立即销毁QWaylandQuickItem ，或者启动一个关闭动画，然后销毁该Item。
如果启动了动画，应将 `bufferLocked ` 设置为确保该项在动画结束前保持其内容不变
另请参阅 QWaylandQuickItem::bufferLocked 。
[virtual slot] void QWaylandQuickItem::takeFocus(QWaylandSeat *device = nullptr)
调用此函数会使该项获得输入框device 的焦点。
[override virtual] QSGTextureProvider *QWaylandQuickItem::textureProvider() const
重写：QQuickItem::textureProvider() const。
返回此 `QWaylandQuickItem` 的纹理提供程序。
QWaylandView *QWaylandQuickItem::view() const
返回由该QWaylandQuickItem 渲染的视图。
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
