XPP is a header only C++11 RAII wrapper around X protocol C-language Binding (XCB). Pointers to dynamically allocated memory, such as events and errors are wrapped in std::shared_ptr.
Furthermore, interfaces for connection and resource types are provided to facilitate the creation of custom classes. For convenience, a connection class and several basic resource type classes are readily available.
XPP makes widespread use of the Curiously Recurring Template Pattern (CRTP) to avoid overhead through dynamic dispatch. Hence, most interfaces are implicitly defined.
- Python 3
- GCC >= 4.8 (or Clang >= 3.3, untested)
- libxcb
git clone https://github.com/jrk-/xpp
cd xpp
make
make examples
cd src/examples
for demo in demo_*; do ./${demo}; done
The bindings can be generated by calling make in the top level directory. If
this fails, check the XCBGEN and
PROTODIR variables in
include/proto/Makefile. These need to point to the xcbgen
python package and the xml protocol description respectively.
Once the bindings are generated they can be used by including
include/xpp.hpp. If an extensions is required, it needs to be
included additionally. For example, the RandR extension is available through
proto/randr.hpp, the Damage extension through proto/damage.hpp, etc.
Recent (and working) examples can be found in src/examples.
To compile them, call make examples in the xpp directory or just make in
src/examples.
Requests obey this naming scheme: xpp:: ExtensionName :: RequestName.
Core X protocol:
MapWindow: xcb_map_window{,_checked} -> xpp::x::map_window{,_checked}
InternAtom: xcb_intern_atom{,_checked} -> xpp::x::intern_atom{,_unchecked}
RandR protocol:
SelectInput: xcb_randr_select_input{,_checked} -> xpp::randr::select_input{,_checked}
QueryVersion: xcb_randr_query_version{,_unchecked} -> xpp::randr::query_version{,_unchecked}
All xcb_timestamp_t parameters are alternatively available with a default
value of XCB_TIME_CURRENT_TIME.
Requests which take a list of values as parameters can be used with any STL container by passing in Iterators. Example:
std::string string_example = "example string";
// std::list<char> list_example = { 'a', 'b', 'c' };
// std::map<int, char> map_example = { {0, 'a'}, {1, 'b'}, {2, 'c'} };
xpp::x::change_property_checked(c, XCB_PROP_MODE_REPLACE, window,
atom, XCB_ATOM_STRING, 8,
string_example.begin(), string_example.end());
// list_example.begin(), list_example.end());
// for associative containers the value (std::pair<..>::second_type) will be used
// map_example.begin(), map_example.end());
XCB returns replies only when they are explicitely queried. With XPP this is not necessary anymore, because the operators for accessing the reply are overloaded.
For example, getting the reply for the InternAtom request is as simple as this:
auto reply = xpp::x::intern_atom(connection, true, "MY_ATOM_NAME");
// do some other stuff ..
// latency hiding is still effective, because the call to
// xcb_intern_atom_reply happens but now in operator->()
xcb_atom_t atom = reply->atom;
Primitive types like xcb_window_t, xcb_atom_t, etc. can be accessed either
directly through the overloaded operator->() or via a method which has the
same name as the member. These methods are templated with a default template
type of the native type. Any type which is default constructible from the native
type or a connection and the native type can be specified as template argument.
Examples:
xcb_window_t w1 = reply->member;
xcb_window_t w2 = reply.member(); // default template parameter is xcb_window_t
xpp::window w3 = reply.member<xpp::window>();
Lists (e.g. the result for QueryTree) are accessible through iterators. The
value type is templated, with the default being the native data type.
Example:
auto tree = xpp::x::query_tree(c, window);
// default template type: xcb_window_t
for (auto && child : tree.children()) {
// child has type xcb_window_t
}
// xpp::window is constructible with a connection and xcb_window_t
// other types which are default-constructible with either the value type
// (e.g. xcb_window_t) or a connection & the value type are possible, too
for (auto && child : tree.children<xpp::window>()) {
// child has type xpp::window
}
Caveat: Some requests (in particular GetProperty) return an untyped array of
bytes (void *). To access the desired data type, a template type must be
specified. For constructible types a type trait must be implemented, like so:
struct my_type {
my_type(const xcb_window_t &);
// ..
};
namespace xpp { namespace generic {
struct traits<my_type> {
typedef xcb_atom_t type;
};
}; }; // namespace xpp::generic
XCB offers four different variants of request functions.
-
Error delivered through event queue:
xcb_void_cookie_t xcb_request(...) -
Error can be checked immediately with
xcb_request_check(xcb_connection_t *, xcb_void_cookie_t):xcb_void_cookie_t xcb_request_checked(...)
-
Error can be checked when getting the reply:
xcb_request_reply_t * xcb_request_reply(xcb_connection_t *, xcb_request_cookie_t, xcb_generic_error_t **):xcb_request_cookie_t xcb_request(...) -
Error delivered through event queue:
xcb_request_cookie_t xcb_request_unchecked(...)
For more information on this, refer to xcb-requests (3).
With xpp errors are either thrown as std::shared_ptr<xcb_generic_error_t> or
typed as xpp:: extension ::error:: error_type, e.g. xpp::x::error::value.
The latter are based upon xpp::generic::error (which inherits from
std::runtime_error) and come with a textual error description which is
accessible through the what() method.
For typed errors it is necessary to use a connection class which implements the
appropriate error dispatching. The supplied xpp::connection class already does
this. If no error dispatcher are available (e.g. when used with
xcb_connection_t *), then a simply std::shared_ptr<xcb_generic_error_t>
will be thrown.
Events returned by the event producing methods (wait_for_event,
poll_for_event, etc.) from xpp::core and xpp::connection are encapsulated
as std::shared_ptr<xcb_generic_event_t>.
For additional convenience typed events are available. An event type is based on
xpp::generic::event. The general structure for a typed event is
xpp:: Extension ::event:: EventName
Examples:
xpp::x::event::key_press
xpp::randr::event::notify
xpp::damage::event::notify
Events can be converted from std::shared_ptr<xcb_generic_event_t> to a typed
event by either using an event dispatcher functor (e.g.
xpp::x::event::dispatcher) or by using the event registry described below.
The event registry xpp::event::registry<Connection, Extensions ...> can be
used to connect events and event handlers.
First, a registry object for the desired Connection type and Extensions is
necessary.
Then, arbitrary objects, which implement the xpp::event::sink<..> interface
need to be attached for event handling by calling the attach() method.
It takes two parameters. The first one specifies the priority, in case there are
more than one event handler for this event. Handlers with lower priorities are
called first. The second one is a pointer to an object which implements the
xpp::event::sink<..> interface.
For a detailed example, take a look at this demo.
Interfaces for creating custom types are available.
For every extension a "connection" interface, called
xpp:: ExtensionName ::interface<typename Derived, typename Connection>
is available.
These encapsulate every request for a particular extension. The Derived
template parameter specifies the class which wants to derive from the interface.
The Derived class must provide a method Connection connection();.
Examples:
xpp::x::interface<typename Derived, typename Connection>
xpp::randr::interface<typename Derived, typename Connection>
xpp::damage::interface<typename Derived, typename Connection>
etc.
For a customizable default implementation, take a look at the xpp::connection
class described here.
In addition, interfaces for basic resource types like xcb_window_t,
xcb_atom_t, xcb_gcontext_t, etc. are available.
Again, the naming scheme follows the format
xpp:: ExtensionName :: XidType <typename Derived, typename Connection>
Despite the connection() method described here,
Derived needs to implement a resource() method which returns a xid which
will be passed as parameter to the encapsulated requests.
Examples:
xpp::x::window<typename Derived, typename Connection>
xpp::randr::output<typename Derived, typename Connection>
xpp::render::glyphset<typename Derived, typename Connection>
etc.
xpp::connection<Extensions ...> provides a default
implementation of the core connection methods, the core
X protocol and error handling facilities. In addition, it is implicitly
convertible to xcb_connection_t *, hence it can be used seamlessly with XCB
functions. The connection can be augmented with additional extension methods, by
specifying the desired extensions as template parameters.
Example:
typedef xpp::connection<xpp::randr::extension, xpp::damage::extension> my_connection;
For the basic resource types like Drawable, Window, Pixmap, Atom,
Colormap, Cursor, Font, Fontable and GContext wrapper types exist.
They are named xpp::drawable, xpp::window, etc.
Each is based upon xpp::generic::resource and provides the core X protocol
interface for the encapsulated resource type. If the resource can be acquired
from the X server (e.g. with CreateWindow) then a named constructor is
available (e.g. create_window for xpp::window).
Resources acquired through the named constructors are reference counted. When their lifetime expires, the resource handle will automatically be freed on the server. No call to destroy or free functions is necessary.