XCBCC-Documentation

XCBCC-Homepage

Overview

All parts of XCBCC live in the namespace xcbcc. X-extensions get its own nested namespace with a name derived from its C name (xcbcc::xv for the XVideo-extension). As XCBCC builds on top of XCB, all XCB header definitions are fully visible. Also all XCB values stored in XCBCC objects are always accessible to allow interfacing with code that relies on XCB.

Structures are simple typedefs to its XCB counterparts without any prefix or postfix (xcb_screen_t becomes screen). Scalar types get a typedef with a _type postfix (xcb_window_t becomes window_type). Enumerations are mapped to anonymous C++ enums, its values are prefixed with the name of the enumeration in C notation. If the XML description defines a value as being a bit, its bit-number is also exported with a _bit postfix (e.g. event_mask_enter_window = 16 and event_mask_enter_window_bit = 4 for the EnterWindow-value of the EventMask-enumeration).

XCBCC makes heavy use of templates. All containers, iterators, exceptions and reply-pointers defined by XCBCC are actually typedefs to templates parametrized with XCB constants, types, and functions.

The `connection` class

XCBCC's connection class owns the actual XCB connection. Besides that it also holds a set of bound protocol objects to propagate events and errors to the actual protocol subsystem, and a set of resource objects to map X-IDs to objects. A static connection set member allows mapping of XCB connection pointers to connection objects.

The `protocol` class

Each extension and also the core protocol is encapsulated in a distinct class that derives from protocol. These objects have to be bound to a connection with connection::bind_protocol() before they can be used. Bound protocols recieve the connection pointer and the extension data from the connection object on connect.

Protocol-derived classes get a name similar to the extension namespace or core. All request wrappers and also event- and error-handling capabilities are part of that automatically generated classes.

Requests and replies

Request wrappers are similar to XCB's functions, but are part of a protocol derived class, take no connection pointer as argument, and have names without prefixes. XCBCC's request wrappers return smart reply pointers instead of cookies. Such a pointer stores the cookie internally and fetches the actual reply if it gets dereferenced. The resulting reply gets freed automatically on destruction.

There exist reply pointers in a checked and unchecked form. They are named like the correponding request with a _reply_ptr postfix appended. XCB's reply and cookie types are available through the reply_type and cookie_type typedefs inside it.

Events

Events are currently not implemented in XCBCC.

Errors

X errors are handled by connection::handle_error() which calls handle_error() on all bound protocol objects until the subsystem to which the error belongs throws the actual C++ exception or eats the error by returning true.

All exception classes for X errors derive from generic_protocol_error which gets thrown if the error type can't be determined properly. Concrete exceptions are actually instantiiations of the protocol_error template which takes the protocol class, the error code, and XCB's error type as arguments. There exist well defined typedefs for all X errors with names that you expect (<x_error_name>_error).

Containers and iterators

Containers and iterators fulfill STL container and forward-iterator requirements. Containers take a const reference to the structure that contains the list as a constructor argument. It may then be traversed like any other STL container.