vasilito
cf12defd28
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
# 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
|