- Qt 6.10
- Qt Wayland Compositor
- C++ Classes
- QWaylandSurface
- Qt Wayland Compositor | Commercial or GPLv3

# QWaylandSurface Class

The QWaylandSurface class represents a rectangular area on an output device. More...

Header: | `#include <QWaylandSurface>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS WaylandCompositor)` `target_link_libraries(mytarget PRIVATE Qt6::WaylandCompositor)`
qmake: | `QT += waylandcompositor`
In QML: | WaylandSurface
Inherits: | QWaylandObject

- List of all members, including inherited members

## Public Types

enum | Origin { OriginTopLeft, OriginBottomLeft }

## Properties

- bufferScale : const int
- bufferSize : const QSize
- client : QWaylandClient* const
- contentOrientation : const Qt::ScreenOrientation
- cursorSurface : bool
- destinationSize : const QSize

- hasContent : const bool
- inhibitsIdle : const bool
- `(since 6.4)` isOpaque : const bool
- origin : const QWaylandSurface::Origin
- sourceGeometry : const QRectF

## Public Functions

| 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

## Public Slots

void | updateSelection()

## Signals

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()

## Static Public Members

QWaylandSurface * | fromResource(wl_resource *resource)

## Detailed Description

This class encapsulates a rectangular area of pixels that is displayed on an output device. It corresponds to the interface `wl_surface` in the Wayland protocol.

## Member Type Documentation

### enum QWaylandSurface::Origin

This enum type is used to specify the origin of a QWaylandSurface's buffer.

Constant | Value | Description
--- | --- | ---
`QWaylandSurface::OriginTopLeft` | `0` | The origin is the top left corner of the buffer.
`QWaylandSurface::OriginBottomLeft` | `1` | The origin is the bottom left corner of the buffer.

## Property Documentation

### `[read-only]` bufferScale : const int

This property holds the QWaylandSurface's buffer scale. The buffer scale lets a client supply higher resolution buffer data for use on high resolution outputs.

Access functions:

int | bufferScale() const

Notifier signal:

void | bufferScaleChanged()

### `[read-only]` bufferSize : const QSize

This property holds the size of the current buffer of this QWaylandSurface in pixels, not in surface coordinates.

For the size in surface coordinates, use destinationSize instead.

Access functions:

QSize | bufferSize() const

Notifier signal:

void | bufferSizeChanged()

See also destinationSize and bufferScale.

### `[read-only]` client : QWaylandClient* const

This property holds the client using this QWaylandSurface.

Access functions:

QWaylandClient * | client() const

### `[read-only]` contentOrientation : const Qt::ScreenOrientation

This property holds the orientation of the QWaylandSurface's contents.

Access functions:

Qt::ScreenOrientation | contentOrientation() const

Notifier signal:

void | contentOrientationChanged()

See also QWaylandOutput::transform.

### cursorSurface : bool

This property holds whether the QWaylandSurface is a cursor surface.

Access functions:

bool | isCursorSurface() const
void | markAsCursorSurface(bool cursorSurface)

Notifier signal:

void | cursorSurfaceChanged()

### `[read-only]` destinationSize : const QSize

This property holds the size of this WaylandSurface in surface coordinates.

Access functions:

QSize | destinationSize() const

Notifier signal:

void | destinationSizeChanged()

See also bufferScale and bufferSize.

### `[read-only]` hasContent : const bool

This property holds whether the QWaylandSurface has content.

Access functions:

bool | hasContent() const

Notifier signal:

void | hasContentChanged()

### `[read-only]` inhibitsIdle : const bool

This property holds whether this surface is intended to inhibit the idle behavior of the compositor such as screen blanking, locking and screen saving.

Access functions:

bool | inhibitsIdle() const

Notifier signal:

void | inhibitsIdleChanged()

See also QWaylandIdleInhibitManagerV1.

### `[read-only, since 6.4]` isOpaque : const bool

This property holds whether the surface is fully opaque, as reported by the client through the set_opaque_region request.

This property was introduced in Qt 6.4.

Access functions:

bool | isOpaque() const

Notifier signal:

void | isOpaqueChanged()

### `[read-only]` origin : const QWaylandSurface::Origin

This property holds the origin of the QWaylandSurface's buffer, or QWaylandSurface::OriginTopLeft if the surface has no buffer.

Access functions:

QWaylandSurface::Origin | origin() const

Notifier signal:

void | originChanged()

### `[read-only]` sourceGeometry : const QRectF

This property describes the portion of the attached QWaylandBuffer that should be drawn on the screen. The coordinates are from the corner of the buffer and are scaled by bufferScale.

Access functions:

QRectF | sourceGeometry() const

Notifier signal:

void | sourceGeometryChanged()

See also bufferScale, bufferSize, and destinationSize.

## Member Function Documentation

### QWaylandSurface::QWaylandSurface()

Constructs a an uninitialized QWaylandSurface.

### QWaylandSurface::QWaylandSurface(QWaylandCompositor *compositor, QWaylandClient *client, uint id, int version)

Constructs and initializes a QWaylandSurface for the given compositor and client, and with the given id and version.

### `[override virtual noexcept]` QWaylandSurface::~QWaylandSurface()

Destroys the QWaylandSurface.

### `[signal]` void QWaylandSurface::childAdded(QWaylandSurface *child)

This signal is emitted when a wl_subsurface, child, has been added to the surface.

### QWaylandCompositor *QWaylandSurface::compositor() const

Returns the compositor for this QWaylandSurface.

### `[invokable]` void QWaylandSurface::destroy()

Destroys the QWaylandSurface.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[signal]` void QWaylandSurface::dragStarted(QWaylandDrag *drag)

This signal is emitted when a drag has started from this surface.

### `[invokable]` void QWaylandSurface::frameStarted()

Prepares all frame callbacks for sending.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### `[static]` QWaylandSurface *QWaylandSurface::fromResource(wl_resource *resource)

Returns the QWaylandSurface corresponding to the Wayland resource resource.

### `[invokable]` void QWaylandSurface::initialize(QWaylandCompositor *compositor, QWaylandClient *client, uint id, int version)

Initializes the QWaylandSurface with the given compositor and client, and with the given id and version.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### bool QWaylandSurface::inputRegionContains(const QPoint &p) const

Returns `true` if the QWaylandSurface's input region contains the point p. Otherwise returns `false`.

### bool QWaylandSurface::inputRegionContains(const QPointF &position) const

Returns `true` if the QWaylandSurface's input region contains the point position. Otherwise returns `false`.

### `[invokable]` bool QWaylandSurface::isDestroyed() const

Returns true if the QWaylandSurface has been destroyed. Otherwise returns false.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### bool QWaylandSurface::isInitialized() const

Returns true if the QWaylandSurface has been initialized.

### QWaylandView *QWaylandSurface::primaryView() const

Returns this QWaylandSurface's primary view.

See also QWaylandView::advance() and QWaylandSurface::setPrimaryView().

### struct wl_resource *QWaylandSurface::resource() const

Returns the Wayland resource corresponding to this QWaylandSurface.

### `[invokable]` void QWaylandSurface::sendFrameCallbacks()

Sends pending frame callbacks.

Note: This function can be invoked via the meta-object system and from QML. See Q_INVOKABLE.

### void QWaylandSurface::setPrimaryView(QWaylandView *view)

Sets this QWaylandSurface's primary view to view, in case there are multiple views of this surface. The primary view is the view that governs the client's refresh rate. It takes care of discarding buffer references when QWaylandView::advance() is called. See the documentation for QWaylandView::advance() for more details.

In shell surface integrations, such as QWaylandWlShellIntegration and QWaylandXdgShellV5Integration, maximize and fullscreen requests from the client will only have an effect if the integration has the primary view of the surface.

See also primaryView() and QWaylandView::advance().

### bool QWaylandSurface::setRole(QWaylandSurfaceRole *role, wl_resource *errorResource, uint32_t errorCode)

Sets a role on the surface. A role defines how a surface will be mapped on screen; without a role a surface is supposed to be hidden. Once a role is assigned to a surface, this becomes its permanent role. Any subsequent call to `setRole()` with a different role will trigger a protocol error to the errorResource and send an errorCode to the client. Enforcing this requirement is the main purpose of the surface role.

The role is compared by pointer value. Any two objects of QWaylandSurfaceRole will be considered different roles, regardless of their names.

The surface role is set internally by protocol implementations when a surface is adopted for a specific purpose, for example in a shell extension. Unless you are developing extensions which use surfaces in this way, you should not call this function.

Returns true if a role can be assigned; false otherwise.

### `[signal]` void QWaylandSurface::surfaceDestroyed()

This signal is emitted when the corresponing wl_surface is destroyed.

### `[slot]` void QWaylandSurface::updateSelection()

Updates the surface with the compositor's retained clipboard selection. Although this is done automatically when the surface receives keyboard focus, this function is useful for updating clients which do not have keyboard focus.

### QList<QWaylandView *> QWaylandSurface::views() const

Returns the views for this QWaylandSurface.

### wl_client *QWaylandSurface::waylandClient() const

Holds the `wl_client` using this QWaylandSurface.