Awesome

KWayland

KWayland is a Qt-style API to interact with the wayland-client API.

Introduction

The API is Qt-styled removing the needs to interact with a for a Qt developer uncomfortable low-level C-API. For example the callback mechanism from the Wayland API is replaced by signals; data types are adjusted to be what a Qt developer expects, e.g. two arguments of int are represented by a QPoint or a QSize.

KWayland Client

The idea around KWayland Client is to provide a drop-in API for the Wayland client library which at the same time provides convenience Qt-style API. It is not intended to be used as a replacement for the QtWayland QPA plugin, but rather as a way to interact with Wayland in case one needs Qt to use a different QPA plugin or in combination with QtWayland to allow a more low-level interaction without requiring to write C code.

Convenience API

The convenience API in KWayland Client provides one class wrapping a Wayland object. Each class can be casted into the wrapped Wayland type. The API represents events as signals and provides simple method calls for requests.

Classes representing global Wayland resources can be created through the [Registry](@ref KWayland::Client::Registry). This class eases the interaction with the Wayland registry and emits signals whenever a new global is announced or gets removed. The Registry has a list of known interfaces (e.g. common Wayland protocols like wl_compositor or wl_shell) which have dedicated announce/removed signals and objects can be factored by the Registry for those globals.

Many globals function as a factory for further resources. E.g. the Compositor has a factory method for Surfaces. All objects can also be created in a low-level way interacting directly with the Wayland API, but provide convenience factory methods in addition. This allows both an easy usage or a more low level control of the Wayland API if needed.

Integration with QtWayland QPA

If the QGuiApplication uses the QtWayland QPA, KWayland allows to integrate with it. That is one does not need to create a new connection to the Wayland server, but can reuse the one used by Qt. If there is a way to get a Wayland object from Qt, the respective class provides a static method normally called fromApplication. In addition the API allows to get the Surface from a QWindow.

Using KWayland in your application

With CMake

KWayland installs a CMake Config file which allows to use KWayland as imported targets.

To find the package use for example:

find_package(KWayland CONFIG)
set_package_properties(KWayland PROPERTIES TYPE OPTIONAL )
add_feature_info("KWayland" KWayland_FOUND "Required for the awesome Wayland on Qt demo")

Now to link against the Client library use:

add_executable(exampleApp example.cpp)
target_link_libraries(exampleApp Plasma::KWaylandClient)

Please make sure that your project is configured with C++11 support:

CONFIG += c++11