Commit 33c2ae4e authored by David Edmundson's avatar David Edmundson
Browse files

Add some hopefully useful documentation for people creating new interfaces

The generated classes don't really have documentation for the generated
methods. This hopes to provide some context.
parent ba37b38f
# History
We started out with one method of generting classes. We then ported to a new approach of using QtWaylandScanner to reduce a lot of boiler plate.
New classes should use the new approach.
# New Approach
A public facing PIMPL class which should inherit from QObject.
A private class that should inherit from QtWaylandServer::interface_name which is auto-generated. This will manage individual resources, handle callbacks and QString conversions.
Class Names should map to the interface name in UpperCamelCase.
Where a V1 exists in the interface name, this should be mirrored in the file and class name.
An implementation should handle all versions of a given interface, but not different interfaces which represent different versions.
(i.e zxdg_output_manager_v1 versions 1 2 and 3 would be wrapped in one class XdgOutputManagerV1Interface. A zxdg_output_manager_v2 protocol would be exposed as a new public class XdgOutputManagerV2Interface)
# Implementations
There are 3 modes of operation happening within the exported classes of KWaylandServer
The generated classes can behave in all these modes, it is up to our implementation to use the correct methods.
## Globals
e.g BlurManager
This represents an object listed by the Display class.
Use the interface_name::(wl_display*, int version) constructor within the private class to create an instance.
## Server-managed multicasting resources
e.g XdgOutput
This is where one QObject represents multiple Resources.
Use the method
```cpp
QtWaylandServer::interface_name::add(client, id, version)
```
to create a a new Resource instance managed by this object.
Use the event method with the wl_resource* overload to send events.
```cpp
for (auto resource : resourceMap())
{
send_some_method(resource->handle, arg1, arg2);
}
```
methods to send requests to all clients.
## Client-owned Resources:
e.g BlurInterface
This is where one instance of our public class represents a single resource. Typically the lifespan of the exported class matches our resource.
In the private class use the QtWaylandServer::interface_name(wl_resource*) constructor to create a wrapper bound to a specific resource.
Use
```cpp
send_some_method(arg1, args2)
```
methods of the privateClass to send events to the resource set in the constructor
## Other hooks
`_bind_resource` is called whenever a resource is bound. This exists for all generated classes in all the operating modes
`_destroy_resource` is a hook called whenever a resource has been unbound.
Note one should not call wl_resource_destroy in this hook.
## Resource destructors
destructors (tagged with type="destructor" in the XML) are not handled specially in QtWayland it is up to the class implementation to implement the event handler and call
```cpp
wl_resource_destroy(resource->handle)
```
in the relevant method
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment