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

#1 in #breadx

Download history 238/week @ 2023-10-31 115/week @ 2023-11-07 175/week @ 2023-11-14 147/week @ 2023-11-21 194/week @ 2023-11-28 80/week @ 2023-12-05 97/week @ 2023-12-12 69/week @ 2023-12-19 210/week @ 2023-12-26 76/week @ 2024-01-02 70/week @ 2024-01-09 76/week @ 2024-01-16 101/week @ 2024-01-23 216/week @ 2024-01-30 58/week @ 2024-02-06 257/week @ 2024-02-13

650 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
~287K SLoC