Commit 30122f1e authored by Martin Flöser's avatar Martin Flöser
Browse files

API doc improvements

parent a074f84c
......@@ -35,13 +35,35 @@ namespace Server
class Display;
/**
* @brief Convenient Class which represents a wl_client.
*
* The ClientConnection gets automatically created for a wl_client when a wl_client is
* first used in the context of KWayland::Server. In particular the signal
* @link Display::clientConnected @endlink will be emitted.
*
* @see Display
**/
class KWAYLANDSERVER_EXPORT ClientConnection : public QObject
{
Q_OBJECT
public:
virtual ~ClientConnection();
/**
* Flushes the connection to this client. Ensures that all events are pushed to the client.
**/
void flush();
/**
* Creates a new wl_resource for the provided @p interface.
*
* Thus a convenient wrapper around wl_resource_create
*
* @param interface
* @param version
* @param id
* @returns the created native wl_resource
**/
wl_resource *createResource(const wl_interface *interface, quint32 version, quint32 id);
/**
* Get the wl_resource associated with the given @p id.
......@@ -49,17 +71,56 @@ public:
**/
wl_resource *getResource(quint32 id);
/**
* @returns the native wl_client this ClientConnection represents.
**/
wl_client *client();
/**
* @returns The Display this ClientConnection is connected to
**/
Display *display();
/**
* The pid of the ClientConnection endpoint.
*
* Please note: if the ClientConnection got created with @link Display::createClient @endlink
* the pid will be identical to the process running the KWayland::Server::Display.
*
* @returns The pid of the connection.
**/
pid_t processId() const;
/**
* The uid of the ClientConnection endpoint.
*
* Please note: if the ClientConnection got created with @link Display::createClient @endlink
* the uid will be identical to the process running the KWayland::Server::Display.
*
* @returns The uid of the connection.
**/
uid_t userId() const;
/**
* The gid of the ClientConnection endpoint.
*
* Please note: if the ClientConnection got created with @link Display::createClient @endlink
* the gid will be identical to the process running the KWayland::Server::Display.
*
* @returns The gid of the connection.
**/
gid_t groupId() const;
/**
* Cast operator the native wl_client this ClientConnection represents.
**/
operator wl_client*();
/**
* Cast operator the native wl_client this ClientConnection represents.
**/
operator wl_client*() const;
Q_SIGNALS:
/**
* Signal emitted when the ClientConnection got disconnected from the server.
**/
void disconnected(KWayland::Server::ClientConnection*);
private:
......
......@@ -51,6 +51,11 @@ class ContrastManagerInterface;
class ShellInterface;
class SubCompositorInterface;
/**
* @brief Class holding the Wayland server display loop.
*
* @todo Improve documentation
**/
class KWAYLANDSERVER_EXPORT Display : public QObject
{
Q_OBJECT
......
......@@ -32,12 +32,19 @@ namespace Server
class SeatInterface;
class SurfaceInterface;
/**
* @brief Resource for the wl_keyboard interface.
*
**/
class KWAYLANDSERVER_EXPORT KeyboardInterface : public Resource
{
Q_OBJECT
public:
virtual ~KeyboardInterface();
/**
* @returns the focused SurfaceInterface on this keyboard resource, if any.
**/
SurfaceInterface *focusedSurface() const;
private:
......
......@@ -33,11 +33,19 @@ class Cursor;
class SeatInterface;
class SurfaceInterface;
/**
* @brief Resource for the wl_pointer interface.
*
**/
class KWAYLANDSERVER_EXPORT PointerInterface : public Resource
{
Q_OBJECT
public:
virtual ~PointerInterface();
/**
* @returns the focused SurfaceInterface on this pointer resource, if any.
**/
SurfaceInterface *focusedSurface() const;
/**
......
......@@ -35,17 +35,78 @@ namespace Server
class SurfaceInterface;
/**
* @brief Reference counted representation of a Wayland buffer on Server side.
*
* This class encapsulates a rendering buffer which is normally attached to a SurfaceInterface.
* A client should not render to a Wayland buffer as long as the buffer gets used by the server.
* The server signals whether it's still used. This class provides a convenience access for this
* functionality by performing reference counting and deleting the BufferInterface instance
* automatically once it is no longer accessed.
*
* The BufferInterface is referenced as long as it is attached to a SurfaceInterface. If one wants
* to keep access to the BufferInterface for a longer time ensure to call ref on first usage and
* unref again once access to it is no longer needed.
*
* In Wayland the buffer is an abstract concept and a buffer might represent multiple different
* concrete buffer techniques. This class has direct support for shared memory buffers built and
* provides access to the native buffer for different (e.g. EGL/drm) buffers.
*
* If the EGL display has been registered in the Display the BufferInterface can also provide
* some information about an EGL/drm buffer.
*
* For shared memory buffers a direct conversion to a memory-mapped QImage possible using the
* data method. Please refer to the documentation for notes on the restrictions when using the
* shared memory-mapped QImages.
*
* @see Display
* @see SurfaceInterace
**/
class KWAYLANDSERVER_EXPORT BufferInterface : public QObject
{
Q_OBJECT
public:
virtual ~BufferInterface();
/**
* Reference the BufferInterface.
*
* As long as the reference counting has not reached @c 0 the BufferInterface is valid
* and blocked for usage by the client.
*
* @see unref
* @see isReferenced
**/
void ref();
/**
* Unreference the BufferInterface.
*
* If the reference counting reached @c 0 the BufferInterface is released, so that the
* client can use it again. The instance of this BufferInterface will be automatically
* deleted.
*
* @see ref
* @see isReferenced
**/
void unref();
/**
* @returns whether the BufferInterface is currently referenced
*
* @see ref
* @see unref
**/
bool isReferenced() const;
/**
* @returns The SurfaceInterface this BufferInterface is attached to.
**/
SurfaceInterface *surface() const;
/**
* @returns The native wl_shm_buffer if the BufferInterface represents a shared memory buffer, otherwise @c nullptr.
**/
wl_shm_buffer *shmBuffer();
/**
* @returns the native wl_resource wrapped by this BufferInterface.
**/
wl_resource *resource() const;
/**
......
......@@ -32,18 +32,62 @@ namespace Server
{
class Display;
/**
* @brief Base class for all Globals.
*
* Any class representing a Global should be derived from this base class.
* This class provides common functionality for all globals. A global is an
* object listed as an interface on the registry on client side.
*
* Normally a Global gets factored by the Display. For each Global-derived class there
* is a dedicated factory method. After creating an instance through the factory method
* it is not yet announced on the registry. One needs to call ::create on it. This allows
* to setup the Global before it gets announced, ensuring that the client's state is correct
* from the start.
*
* As an example shown for @link OutputInterface @endlink:
* @code
* Display *display; // The existing display
* auto o = display->createOutput();
* o->setManufacturer(QStringLiteral("The KDE Community"));
* // setup further data on the OutputInterface
* o->create(); // announces OutputInterface
* @endcode
*
* @see Display
*
**/
class KWAYLANDSERVER_EXPORT Global : public QObject
{
Q_OBJECT
public:
virtual ~Global();
/**
* Creates the global by creating a native wl_global and by that announcing it
* to the clients.
**/
void create();
/**
* Destroys the low level wl_global. Afterwards the Global is no longer shown to clients.
**/
void destroy();
/**
* @returns whether the Global got created
**/
bool isValid() const;
/**
* @returns the Display the Global got created on.
*/
Display *display();
/**
* Cast operator to the native wl_global this Global represents.
**/
operator wl_global*();
/**
* Cast operator to the native wl_global this Global represents.
**/
operator wl_global*() const;
protected:
......
......@@ -35,6 +35,14 @@ namespace Server
class ClientConnection;
class Global;
/**
* @brief Represents a bound Resource.
*
* A Resource normally gets created by a @link Global @endlink.
*
* The Resource is a base class for all specific resources and provides
* access to various common aspects.
**/
class KWAYLANDSERVER_EXPORT Resource : public QObject
{
Q_OBJECT
......@@ -42,9 +50,21 @@ public:
virtual ~Resource();
void create(ClientConnection *client, quint32 version, quint32 id);
/**
* @returns the native wl_resource this Resource was created for.
**/
wl_resource *resource();
/**
* @returns The ClientConnection for which the Resource was created.
**/
ClientConnection *client();
/**
* @returns The Global which created the Resource.
**/
Global *global();
/**
* @returns the native parent wl_resource, e.g. the wl_resource bound on the Global
**/
wl_resource *parentResource() const;
/**
* @returns The id of this Resource if it is created, otherwise @c 0.
......
......@@ -31,6 +31,10 @@ namespace Server
class SeatInterface;
/**
* @brief Resource for the wl_touch interface.
*
**/
class KWAYLANDSERVER_EXPORT TouchInterface : public Resource
{
Q_OBJECT
......
Supports Markdown
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