Crate x11rb

source ·
Expand description

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::errors::ReplyOrIdError;
use x11rb::protocol::xproto::*;
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::INPUT_OUTPUT,
        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. There are two kinds of feature flags available:

  • Feature flags for specific X11 extensions
  • Feature flags for additional functionality

Feature flags for specific X11 extensions

By default, only the core X11 protocol and X11 extensions that are needed internally are enabled. These are the bigreq, ge and xc_misc extensions. 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, 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.

Feature flags for additional functionality

Additionally, the following flags exist:

  • allow-unsafe-code: Enable features that require unsafe. Without this flag, xcb_ffi::XCBConnection and some support code for it are unavailable.
  • cursor: Enable the code in cursor for loading cursor files.
  • resource_manager: Enable the code in resource_manager for loading and querying the X11 resource database.
  • image: Enable the code in image for working with pixel image data.
  • dl-libxcb: Enabling this feature will prevent from libxcb being linked to the resulting executable. Instead libxcb will be dynamically loaded at runtime. This feature adds the xcb_ffi::load_libxcb function, that allows to load libxcb and check for success or failure.
  • extra-traits: Enable some additional traits for generated code, like Eq, Ord and Hash. This is not needed by default and adds a large amount of code that bloats codegen time
  • request-parsing: Add the ability to parse X11 requests. Not normally needed.
  • extra-traits: Implement extra traits for X11 types. This improves the output of the Debug impl and adds PartialEq, Eq, PartialOrd, Ord, and Hash where possible.

Integrating x11rb with an Event Loop

The event_loop_integration module contains some hints for integrating x11rb with an event loop as doc comments.

Modules

  • connection
    Generic connection-related types and definitions.
  • cookie
    Cookies are handles to future replies or errors from the X11 server.
  • cursor
    Utility functions for working with X11 cursors
  • errors
    This module contains the current mess that is error handling.
  • event_loop_integration
    Integrating x11rb with an Event Loop
  • extension_manager
    Helper for implementing RequestConnection::extension_information().
  • image
    Utility code for working with images.
  • properties
    Utility functions for working with X11 properties
  • protocol
    Bindings to the X11 protocol.
  • reexports
    Reexports of dependencies
  • resource_manager
    X11 resource manager library.
  • rust_connection
    A pure-rust implementation of a connection to an X11 server.
  • utils
    Utility functions that are not specific to X11.
  • wrapper
    Some wrappers around the generated code to simplify use.
  • x11_utils
    Some utilities for working with X11.
  • xcb_ffi
    A FFI-based connection to an X11 server, using libxcb.

Macros

Constants

  • COPY_CLASS_FROM_PARENT
    This constant can be used for the class parameter in create_window. It indicates to use the parent window’s class.
  • COPY_DEPTH_FROM_PARENT
    This constant can be used for the depth parameter in create_window. It indicates to use the parent window’s depth.
  • COPY_FROM_PARENT
    This constant can be used for many parameters in create_window
  • 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 Keysym tables

Functions

  • connect
    Establish a new connection to an X11 server.