[−][src]Crate x11rb
X11 rust bindings.
This library allows to interact with an X11 server from rust code. A connection to an X11
server is represented by an implementation of the Connection
trait.
The client can interact with the server by sending requests. The server can answer requests and can also generate events.
The examples that come with this library might be a good starting point for new users.
Getting started with X11
X11 is a big protocol. I would claim that most of it is not actually that complicated, but it is still difficult to get into it. A good starting point might be some libxcb tutorial. This tutorial was adapted in this crate as an example. A more in-depth look at the X11 protocol can be gained from the protocol reference manual, but this requires some existing basic understanding of X11. If you want to figure out what some specific request does, be sure to look it up in the specification!
Most extensions can be understood by reading their specification. Most of them can be found here. For example, the specification of Composite 0.4 consists of about six pages of text.
The notable exception is the X keyboard extension, which is documented in a PDF file with 168 pages which I am never going to read completely.
Getting started with x11rb
Most code in this code is automatically generated from an XML description of the protocol. This is the same approach as taken by libxcb (and in fact this uses the same XML description). This means that if you know your way around X11, most things should be obvious to you.
For example, here is how to create a new window with x11rb:
use x11rb::connection::Connection; use x11rb::generated::xproto::*; use x11rb::errors::ReplyOrIdError; use x11rb::COPY_DEPTH_FROM_PARENT; fn main() -> Result<(), Box<dyn std::error::Error>> { let (conn, screen_num) = x11rb::connect(None).unwrap(); let screen = &conn.setup().roots[screen_num]; let win_id = conn.generate_id()?; conn.create_window(COPY_DEPTH_FROM_PARENT, win_id, screen.root, 0, 0, 100, 100, 0, WindowClass::InputOutput, 0, &CreateWindowAux::new().background_pixel(screen.white_pixel))?; conn.map_window(win_id)?; conn.flush(); loop { println!("Event: {:?}", conn.wait_for_event()?); } }
More examples can be found in the examples directory.
Feature flags
This crate uses feature flags to reduce the amount of compiled code. By default, only the core X11 protocol and X11 extensions that are needed internally are enabled. Further extensions need to be explicitly enabled via their feature flag:
composite
, damage
, dpms
, dri2
, dri3
, glx
, present
, randr
, record
, render
,
res
, screensaver
, shape
, shm
, sync
, xevie
, xf86dri
, xf86vidmode
, xfixes
,
xinerama
, xinput
, xkb
, xprint
, xproto
, xselinux
, xtest
, xv
, xvmc
.
If you want to take the "I do not want to think about this"-approach, you can enable the
all-extensions
feature to just enable, well, all extensions.
Additionally, the following flags are enabled by default:
vendor-xcb-proto
: Use a copy ofxcb-proto
that comes with x11rb. Without this flag,pkg-config
is used to findxcb-proto
on the host system.allow-unsafe-code
: Enable features that requireunsafe
. Without this flag,x11rb::xcb_ffi::XCBConnection
and some support code for it are unavailable.
Modules
connection | Generic connection-related types and definitions. |
cookie | Cookies are handles to future replies or errors from the X11 server. |
errors | This module contains the current mess that is error handling. |
extension_information | Helper for implementing |
generated | |
rust_connection | A pure-rust implementation of a connection to an X11 server. |
utils | |
wrapper | Some wrappers around the generated code to simplify use. |
x11_utils | |
xcb_ffi | A FFI-based connection to an X11 server, using libxcb. |
Macros
atom_manager | A helper macro for managing atoms |
Constants
COPY_CLASS_FROM_PARENT | This constant can be used for the class parameter in |
COPY_DEPTH_FROM_PARENT | This constant can be used for the depth parameter in |
COPY_FROM_PARENT | This constant can be used for many parameters in |
CURRENT_TIME | This constant can be used in most request that take a timestamp argument |
NONE | The universal null resource or null atom parameter value for many core X requests |
NO_SYMBOL | This constant can be used to fill unused entries in |
Functions
connect | Establish a new connection to an X11 server. |