Variadic template to wrap an xcb request. More...

#include <xcbutils.h>

Public Types
typedef Reply	reply_type
	The type returned by the xcb reply function.

typedef Cookie	cookie_type
	The type returned by the xcb request function.

typedef std::tuple< Args... >	argument_types
	Variadic arguments combined as a std::tuple.

typedef Cookie(*	request_func) (xcb_connection_t *, Args...)
	The function pointer definition for the xcb request function.

typedef Reply (	reply_func) (xcb_connection_t , Cookie, xcb_generic_error_t *)
	The function pointer definition for the xcb reply function.

Static Public Attributes
static constexpr std::size_t	argumentCount = sizeof...(Args)
	Number of variadic arguments.

Detailed Description

template<typename Reply, typename Cookie, typename... Args>
struct KWin::Xcb::WrapperData< Reply, Cookie, Args >

Variadic template to wrap an xcb request.

This struct is part of the generic implementation to wrap xcb requests and fetching their reply. Each request is represented by two templated elements: WrapperData and Wrapper.

The WrapperData defines the following types:

reply_type of the xcb request
cookie_type of the xcb request
function pointer type for the xcb request
function pointer type for the reply This uses variadic template arguments thus it can be used to specify any xcb request.

As the WrapperData does not specify the actual function pointers one needs to derive another struct which specifies the function pointer requestFunc and the function pointer replyFunc as static constexpr of type reply_func and reply_type respectively. E.g. for the command xcb_get_geometry:

struct GeometryData : public WrapperData< xcb_get_geometry_reply_t, xcb_get_geometry_cookie_t, xcb_drawable_t >
{
   static constexpr request_func requestFunc = &xcb_get_geometry_unchecked;
   static constexpr reply_func replyFunc = &xcb_get_geometry_reply;
};

To simplify this definition the macro XCB_WRAPPER_DATA is provided. For the same xcb command this looks like this:

XCB_WRAPPER_DATA(GeometryData, xcb_get_geometry, xcb_drawable_t)

XCB_WRAPPER_DATA

#define XCB_WRAPPER_DATA(__NAME__, __REQUEST__,...)

Macro to create the WrapperData subclass.

Definition xcbutils.h:553

The derived WrapperData has to be passed as first template argument to Wrapper. The other template arguments of Wrapper are the same variadic template arguments as passed into WrapperData. This is ensured at compile time and will cause a compile error in case there is a mismatch of the variadic template arguments passed to WrapperData and Wrapper. Passing another type than a struct derived from WrapperData to Wrapper will result in a compile error. The following code snippets won't compile:

XCB_WRAPPER_DATA(GeometryData, xcb_get_geometry, xcb_drawable_t)
// fails with "static assertion failed: Argument miss-match between Wrapper and WrapperData"
class IncorrectArguments : public Wrapper<GeometryData, uint8_t>
{
public:
    IncorrectArguments() = default;
    IncorrectArguments(xcb_window_t window) : Wrapper<GeometryData, uint8_t>(window) {}
};
 
// fails with "static assertion failed: Data template argument must be derived from WrapperData"
class WrapperDataDirectly : public Wrapper<WrapperData<xcb_get_geometry_reply_t, xcb_get_geometry_request_t, xcb_drawable_t>, xcb_drawable_t>
{
public:
    WrapperDataDirectly() = default;
    WrapperDataDirectly(xcb_window_t window) : Wrapper<WrapperData<xcb_get_geometry_reply_t, xcb_get_geometry_request_t, xcb_drawable_t>, xcb_drawable_t>(window) {}
};
 
// fails with "static assertion failed: Data template argument must be derived from WrapperData"
struct FakeWrapperData
{
    typedef xcb_get_geometry_reply_t reply_type;
    typedef xcb_get_geometry_cookie_t cookie_type;
    typedef std::tuple<xcb_drawable_t> argument_types;
    typedef cookie_type (*request_func)(xcb_connection_t*, xcb_drawable_t);
    typedef reply_type *(*reply_func)(xcb_connection_t*, cookie_type, xcb_generic_error_t**);
    static constexpr std::size_t argumentCount = 1;
    static constexpr request_func requestFunc = &xcb_get_geometry_unchecked;
    static constexpr reply_func replyFunc = &xcb_get_geometry_reply;
};
class NotDerivedFromWrapperData : public Wrapper<FakeWrapperData, xcb_drawable_t>
{
public:
    NotDerivedFromWrapperData() = default;
    NotDerivedFromWrapperData(xcb_window_t window) : Wrapper<FakeWrapperData, xcb_drawable_t>(window) {}
};

The Wrapper provides an easy to use RAII API which calls the WrapperData's requestFunc in the ctor and fetches the reply the first time it is used. In addition the dtor takes care of freeing the reply if it got fetched, otherwise it discards the reply. The Wrapper can be used as if it were the reply_type directly.

There are several command wrappers defined which either subclass Wrapper to add methods to simplify the usage of the result_type or use a typedef. To add a new typedef one can use the macro XCB_WRAPPER which creates the WrapperData struct as XCB_WRAPPER_DATA does and the typedef. E.g:

XCB_WRAPPER(Geometry, xcb_get_geometry, xcb_drawable_t)

XCB_WRAPPER

#define XCB_WRAPPER(__NAME__, __REQUEST__,...)

Macro to create Wrapper typedef and WrapperData.

Definition xcbutils.h:572

creates a typedef Geometry and the struct GeometryData.

Overall this allows to simplify the Xcb usage. For example consider the following xcb code snippet:

xcb_window_t w; // some window
xcb_connection_t *c = connection();
const xcb_get_geometry_cookie_t cookie = xcb_get_geometry_unchecked(c, w);
// do other stuff
xcb_get_geometry_reply_t *reply = xcb_get_geometry_reply(c, cookie, nullptr);
if (reply) {
    reply->x; // do something with the geometry
}
free(reply);

With the help of the Wrapper class this can be simplified to:

xcb_window_t w; // some window
Xcb::Geometry geo(w);
if (!geo.isNull()) {
    geo->x; // do something with the geometry
}

See also: XCB_WRAPPER_DATA; XCB_WRAPPER; Wrapper; WindowAttributes; OverlayWindow; WindowGeometry; Tree; CurrentInput; TransientFor

Definition at line 185 of file xcbutils.h.