Crate breadx

Expand description

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.

Modules§

connect: Contains utilities for connection to the X11 server.
connection: Implementation of the Connection type, which is used as a byte transport for the actual X11 protocol.
display: Displays, used to connect to the X11 server.
futures: Futures that are used throughout the program.
prelude: Contains a set of traits to be automatically imported for full functionality.
protocol: The protocol used during communication.
resource_manager: X11 resource manager library.
rt_support: This module contains runtime support for the most common runtimes: tokio and async-std.
tutorials: This module contains a tutorial for the X Window System Protocol, specifically from the perspective of using breadx.
x11_utils: Utility functions for X11 things.

Structs§

Error: An error that may occur during operation of this crate.
Fd: A simple wrapper around RawFd that closes the fd on drop.
NameConnection: A connection that can be derived from a parsed display name.

Enums§

SetupFailure: The setup for the connection failed.

Traits§

Multireply: A reply that can have more than one reply.
Void: A type that can be used in the “void” position.

Type Aliases§

Result: A convenience type that is equivalent to Result<T, [Error]>.