#x11 #connection #async-io #protocols #client #user #default

no-std breadx

Pure-Rust X11 connection implementation with a focus on adaptability

31 releases (7 stable)

3.1.0 Jul 1, 2022
2.0.0 Sep 14, 2021
1.2.1 Jul 21, 2021
0.3.0 Jun 11, 2021
0.1.0 Nov 30, 2020

#71 in #x11

Download history 10/week @ 2023-12-25 30/week @ 2024-01-01 4/week @ 2024-01-29 8/week @ 2024-02-05 7/week @ 2024-02-12 22/week @ 2024-02-19 104/week @ 2024-02-26 14/week @ 2024-03-04 23/week @ 2024-03-11 20/week @ 2024-03-18

162 downloads per month
Used in 8 crates

BSL-1.0 license

2MB
57K SLoC

breadx is a comprehensive implementation of the X11 client protocol with an aim to be featureful and powerful, but also easy to use.

breadx aims to be a minimal implementation of the X11 protocol that can be used in any case where a client is needed. breadx comes built in with the following features:

  • Comprehensive: breadx has first class support for all X11 protocol extensions. These extensions can be enabled and disabled as features.
  • Lock-free: The default connection implementation uses no locks and no waiting outside of standard I/O primitives. The goal is to ensure that there are as few layers as possible between the user's intended goal and actually sending data to the server.
  • Safe: breadx has #[forbid(unsafe_code)], which means that there never will be any unsafe code in breadx. This means that breadx will never be the cause of any undefined behavior.
  • Versatile: For cases where sharing the connection is necessary, breadx provides thread unsafe and thread safe variants.
  • no_std: By disabling the std feature, breadx can be used without depending on the standard library.
  • Asynchronous: With the async feature enabled, breadx's primitives can be used in asynchronous contexts. By default, breadx is runtime-agnostic, but support can be enabled for tokio and async-std.
  • Simple: With all of this, a client can be created and used in breadx in very few lines of code.

Features that breadx does not provide:

  • Data Manipulation - APIs to make image manipulation/ICCCM/etc easier are located in other crates.
  • Interfacing with Xlib/XCB - breadx does not provide a way to interact with Xlib/XCB directly.

Usage

All functions in breadx exist in the context of a Display. There are many ways to create a Display, but in most cases, DisplayConnection::connect() will connect to the currently running X11 server without any fuss.

From there, most functions that are actually used in breadx exist on the DisplayFunctionsExt extension trait.

use breadx::{prelude::*, display::DisplayConnection, protocol::xproto};

// establish a connection to the X11 server
let mut connection = DisplayConnection::connect(None)?;

// create a window
// note the "_checked" suffix, this indicates that the result of the
// function will be checked by the server after it is run
// also note that we need to create an XID for the window ahead of time
let wid = connection.generate_xid()?;
connection.create_window_checked(
    0, // depth
    wid,
    connection.default_screen().root, // parent
    0, // x
    0, // y
    600, // width
    400, // height
    0, // border width
    xproto::WindowClass::COPY_FROM_PARENT,
    0, // visual
    xproto::CreateWindowAux::new()
        .background_pixel(connection.default_screen().white_pixel)
)?;

// map the window to the screen
// note the lack of _checked here
connection.map_window(wid)?;

// primary event loop
loop {
    let event = connection.wait_for_event()?;

    match event {
        // match on the Event struct in here
        # _ => {},
    }
}

See the tutorial for more information on the usage of breadx.

Dependencies

~7–21MB
~288K SLoC