xcb-studies/docs/XCB_Cheatsheet.md

54 lines
1.7 KiB
Markdown

# XCB
XCB is a library for communicating with the X-Windows system used on
Linux, FreeBSD, and other Unix-like operating systems. XCB's interface
is written in C.
- Connecting, Verifying Connection, and Disconnecting the server.
-
## Connecting.
X-Windows is a server. It listens for events (keyboard events, mouse
events, timer events from connected programs, etc.) and "stores" the
results on a *display*, which is intended to be seen with the human
eye. A display is made up of one or more *screens*. Screens can be
literal (one of the physical devices in a multi-monitor setup) or
virtual (a virtualized desktop where the window manager supports
different "pages" on the same monitor), or even just parts of the same
physical screen space broken up by some logic.
To connect to X via XCB, you use the `xcb_connect` function. It takes two
arguments, a string with the name of the display, and a
pointer-to-int to the preferred screen. It returns an opaque data
structure, 'xcb_connection_t'.
```
xcb_connection_t* xcbConnection = xcb_connect(const char* display, int* screen);
```
There are variants for connection-with-authorization, and
connection-with-file-descriptor.
This function always returns an allocated structure, even on failure.
You _must_ test for failure with:
```
int error = xcb_connection_has_error(xcb_connection_t* xcbConnection);
```
The error is an number defined in `xcb.h`. See that file for the list
of possible failure modes.
## Disconnecting
You _must_ close the connection when you are finished. In the event
of a connection failure, you _must_ still call this function to
free the memory XCB used to report the connection failure:
```
void xcb_disconnect(xcb_connection_t* xcbConnection);
```