QWaylandSurface Class
QWaylandSurface 类表示输出设备上的一个矩形区域。更多内容...
| 头文件： | #include <QWaylandSurface> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS WaylandCompositor) target_link_libraries(mytarget PRIVATE Qt6::WaylandCompositor) |
| qmake： | QT += waylandcompositor |
| 在 QML 中： | WaylandSurface |
| 继承自： | QWaylandObject |
公共类型
| enum | Origin { OriginTopLeft, OriginBottomLeft } |
属性
|
|
公共函数
| QWaylandSurface() | |
| QWaylandSurface(QWaylandCompositor *compositor, QWaylandClient *client, uint id, int version) | |
| virtual | ~QWaylandSurface() override |
| int | bufferScale() const |
| QSize | bufferSize() const |
| QWaylandClient * | client() const |
| QWaylandCompositor * | compositor() const |
| Qt::ScreenOrientation | contentOrientation() const |
| QSize | destinationSize() const |
| void | destroy() |
| void | frameStarted() |
| bool | hasContent() const |
| bool | inhibitsIdle() const |
| void | initialize(QWaylandCompositor *compositor, QWaylandClient *client, uint id, int version) |
| bool | inputRegionContains(const QPoint &p) const |
| bool | inputRegionContains(const QPointF &position) const |
| bool | isCursorSurface() const |
| bool | isDestroyed() const |
| bool | isInitialized() const |
| bool | isOpaque() const |
| void | markAsCursorSurface(bool cursorSurface) |
| QWaylandSurface::Origin | origin() const |
| QWaylandView * | primaryView() const |
| struct wl_resource * | resource() const |
| void | sendFrameCallbacks() |
| void | setPrimaryView(QWaylandView *view) |
| bool | setRole(QWaylandSurfaceRole *role, wl_resource *errorResource, uint32_t errorCode) |
| QRectF | sourceGeometry() const |
| QList<QWaylandView *> | views() const |
| wl_client * | waylandClient() const |
公共槽位
| void | updateSelection() |
信号
| void | bufferScaleChanged() |
| void | bufferSizeChanged() |
| void | childAdded(QWaylandSurface *child) |
| void | contentOrientationChanged() |
| void | cursorSurfaceChanged() |
| void | destinationSizeChanged() |
| void | dragStarted(QWaylandDrag *drag) |
| void | hasContentChanged() |
| void | inhibitsIdleChanged() |
| void | isOpaqueChanged() |
| void | originChanged() |
| void | sourceGeometryChanged() |
| void | surfaceDestroyed() |
静态公共成员
| QWaylandSurface * | fromResource(wl_resource *resource) |
成员类型文档
enum QWaylandSurface::Origin
此枚举类型用于指定QWaylandSurface 的缓冲区源头。
| 常量 | 常量值 | 描述 |
|---|---|---|
QWaylandSurface::OriginTopLeft | 0 | 原点是缓冲区的左上角。 |
QWaylandSurface::OriginBottomLeft | 1 | 原点是缓冲区的左下角。 |
属性文档
[read-only] bufferScale : int
该属性存储QWaylandSurface 的缓冲区比例。缓冲区比例允许客户端提供更高分辨率的缓冲区数据，以便在高分辨率输出中使用。
访问函数：
| int | bufferScale() const |
通知信号：
| void | bufferScaleChanged() |
[read-only] bufferSize : QSize
该属性存储了此QWaylandSurface 当前缓冲区的大小（以像素为单位），而非以表面坐标为单位。
若需获取以表面坐标为单位的尺寸，请改用 `destinationSize `。
访问函数：
| QSize | bufferSize() const |
通知信号：
| void | bufferSizeChanged() |
另请参阅 destinationSize 和bufferScale 。
[read-only] client : QWaylandClient* const
该属性存储了使用此QWaylandSurface 的客户端。
访问函数：
| QWaylandClient * | client() const |
[read-only] contentOrientation : Qt::ScreenOrientation
该属性保存了QWaylandSurface 内容的朝向。
访问函数：
| Qt::ScreenOrientation | contentOrientation() const |
通知信号：
| void | contentOrientationChanged() |
另请参阅 QWaylandOutput::transform 。
cursorSurface : bool
该属性用于确定QWaylandSurface 是否为游标表面。
访问函数：
| bool | isCursorSurface() const |
| void | markAsCursorSurface(bool cursorSurface) |
通知信号：
| void | cursorSurfaceChanged() |
[read-only] destinationSize : QSize
该属性存储了该WaylandSurface 在表面坐标系中的尺寸。
访问函数：
| QSize | destinationSize() const |
通知信号：
| void | destinationSizeChanged() |
另请参阅 bufferScale 和bufferSize 。
[read-only] hasContent : bool
该属性表示该表面当前是否拥有一个已提交且不为空的缓冲区。
访问函数：
| bool | hasContent() const |
通知器信号：
| void | hasContentChanged() |
另请参阅 QWaylandSurface::bufferSize 。
[read-only] inhibitsIdle : bool
该属性用于指定该表面是否旨在阻止合成器的空闲行为，例如屏幕变黑、锁定和屏幕保护。
访问函数：
| bool | inhibitsIdle() const |
通知信号：
| void | inhibitsIdleChanged() |
另请参阅 QWaylandIdleInhibitManagerV1 。
[read-only, since 6.4] isOpaque : bool
无论表面是否完全不透明（由客户端通过 set_opaque_region 请求报告），该属性均成立。
该枚举类型在 Qt 6.4 中引入。
访问函数：
| bool | isOpaque() const |
通知器信号：
| void | isOpaqueChanged() |
[read-only] origin : QWaylandSurface::Origin
该属性存储QWaylandSurface 缓冲区的原点，如果表面没有缓冲区，则存储QWaylandSurface::OriginTopLeft 。
访问函数：
| QWaylandSurface::Origin | origin() const |
通知器信号：
| void | originChanged() |
[read-only] sourceGeometry : QRectF
该属性描述了应绘制在屏幕上的附加 QWaylandBuffer 的部分。坐标以缓冲区的角落为原点，并按bufferScale 进行缩放。
访问函数：
| QRectF | sourceGeometry() const |
通知器信号：
| void | sourceGeometryChanged() |
另请参阅 bufferScale 、bufferSize 以及destinationSize 。
成员函数文档
QWaylandSurface::QWaylandSurface()
构建一个未初始化的 QWaylandSurface。
QWaylandSurface::QWaylandSurface(QWaylandCompositor *compositor, QWaylandClient *client, uint id, int version)
根据给定的compositor 和client ，以及给定的id 和version ，构建并初始化一个QWaylandSurface。
[override virtual noexcept] QWaylandSurface::~QWaylandSurface()
销毁QWaylandSurface 。
[signal] void QWaylandSurface::childAdded(QWaylandSurface *child)
当向曲面添加了一个 wl_subsurface（child ）时，会发出此信号。
QWaylandCompositor *QWaylandSurface::compositor() const
返回此QWaylandSurface 的合成器。
[invokable] void QWaylandSurface::destroy()
销毁QWaylandSurface 。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
[signal] void QWaylandSurface::dragStarted(QWaylandDrag *drag)
当drag 从该表面起飞时，会发出此信号。
[invokable] void QWaylandSurface::frameStarted()
准备所有帧回调以供发送。
注意：此 函数可通过元对象系统以及从 QML 中调用。参见Q_INVOKABLE 。
[static] QWaylandSurface *QWaylandSurface::fromResource(wl_resource *resource)
返回与 Wayland 资源resource 对应的QWaylandSurface 。
[invokable] void QWaylandSurface::initialize(QWaylandCompositor *compositor, QWaylandClient *client, uint id, int version)
使用给定的compositor 和client ，以及给定的id 和version ，初始化QWaylandSurface 。
注意： 可通过元对象系统或从 QML 中调用此 函数。参见Q_INVOKABLE 。
bool QWaylandSurface::inputRegionContains(const QPoint &p) const
如果QWaylandSurface 的输入区域包含点p ，则返回true ；否则返回false 。
bool QWaylandSurface::inputRegionContains(const QPointF &position) const
如果QWaylandSurface 的输入区域包含点position ，则返回true ；否则返回false 。
[invokable] bool QWaylandSurface::isDestroyed() const
如果QWaylandSurface 已被销毁，则返回true。否则返回false。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
bool QWaylandSurface::isInitialized() const
如果QWaylandSurface 已初始化，则返回true。
QWaylandView *QWaylandSurface::primaryView() const
返回此QWaylandSurface 的主视图。
另请参阅 QWaylandView::advance() 和QWaylandSurface::setPrimaryView()。
struct wl_resource *QWaylandSurface::resource() const
返回与该QWaylandSurface 对应的Wayland资源。
[invokable] void QWaylandSurface::sendFrameCallbacks()
发送待处理帧的回调。
注意： 可通过元对象系统和 QML 调用此 函数。参见Q_INVOKABLE 。
void QWaylandSurface::setPrimaryView(QWaylandView *view)
将此QWaylandSurface 的主视图设置为view ，以防该表面存在多个视图。主视图是控制客户端刷新率的视图。它在调用QWaylandView::advance()时负责丢弃缓冲区引用。更多详细信息请参阅QWaylandView::advance()的文档。
在 shell 表面集成（如 QWaylandWlShellIntegration 和 QWaylandXdgShellV5Integration）中，只有当集成拥有该表面的主视图时，客户端发出的最大化及全屏请求才会生效。
另请参阅 primaryView() 和QWaylandView::advance()。
bool QWaylandSurface::setRole(QWaylandSurfaceRole *role, wl_resource *errorResource, uint32_t errorCode)
在表面上设置一个role 。 角色定义了表面在屏幕上的映射方式；若未指定角色，则该表面应被隐藏。一旦为表面分配了角色，该角色即成为其永久角色。此后若调用setRole() 并传入不同的角色，将向errorResource 触发协议错误，并向客户端发送errorCode 。强制执行此要求是表面角色功能的主要目的。
role 通过指针值进行比较。任何两个QWaylandSurfaceRole 对象都将被视为不同的角色，无论其名称如何。
当将一个表面用于特定目的时（例如在shell 扩展中），协议实现会在内部设置该表面的角色。除非您正在开发以这种方式使用表面的扩展，否则不应调用此函数。
如果角色可以被分配，则返回 true；否则返回 false。
[signal] void QWaylandSurface::surfaceDestroyed()
当相应的 wl_surface 被销毁时，会发出此信号。
[slot] void QWaylandSurface::updateSelection()
使用合成器保留的剪贴板选区更新显示区域。虽然当显示区域获得键盘焦点时，系统会自动执行此操作，但对于没有键盘焦点的客户端而言，此函数仍可用于更新显示内容。
QList<QWaylandView *> QWaylandSurface::views() const
返回此QWaylandSurface 的视图。
wl_client *QWaylandSurface::waylandClient() const
使用此链接QWaylandSurface 固定wl_client 。
© 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.
