Crate breadx 

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]>.