54 lines
1.7 KiB
Markdown
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);
|
||
|
|
```
|
||
|
|
|
||
|
|
|