[−][src]Crate breadx

breadx is an implementation of the X Window System Protocol. In addition to providing the raw data structures needed to create and parse requests, replies and events, it also provides convenient, functional abstractions over the protocol.

The design goals of breadx include speed, safety, and a reduction in complexity.

Speed - breadx takes advantage of modern languages features to reduce the time spent not sending protocol across the connection. First and foremost, breadx takes advantage of Rust's mutability system to ensure only one thread has access to the connection at once, negating the usual need for computationally expensive mutexes. In addition, breadx keeps as much data as possible on the stack, ensuring an increase in speed on modern computers.
Safety - Rust's safety checking system is world-class in preventing bugs from propogating before they can even happen. breadx abides by these rules by including as little unsafe code as possible. The crate itself is #![forbid(unsafe_code)], and its dependencies either use no unsafe code (tinyvec) or extensively check to ensure its unsafe code is correct (bytemuck).
Simple - breadx tries to be as easy to understand as possible. Its API is well-documented, and it is accessible to both veteran X programmers and people who've never used it before.

In addition, breadx implements Rust's new async system to allow it to be a part of a greater whole when it comes to large, complex systems running on the async runtime. It also implements the standard log logging facade for easy debugging.

Tutorials

The official tutorial series begins here, and covers usage of breadx and the X Window System Protocol.

Example

This example opens a connection to the X server, then creates a basic window titled "Hello World!".

use breadx::{DisplayConnection, Event, WindowClass};
use std::{boxed::Box, error::Error};

fn main() -> Result<(), Box<dyn Error>> {
    // open up the connection
    // note that the connection must be mutable
    let mut conn = DisplayConnection::create(None, None)?;
    
    // create a 640x400 window.
    let root = conn.default_screen().root;
    let window = conn
        .create_window(
            root, // parent
            WindowClass::CopyFromParent, // window class
            None, // depth (none means inherit from parent)
            None, // visual (none means "       "    "    )
            0, // x
            0, // y
            640, // width
            400, // height
            0, // border width
            Default::default() // additional properties
        )?;

    // map the window and set its title
    window.map(&mut conn)?;
    window.set_title(&mut conn, "Hello World!")?;

    // set up the exit protocol, this ensures the window exits when the "X"
    // button is clicked
    let wm_delete_window = conn
        .intern_atom_immediate("WM_DELETE_WINDOW".to_owned(), false)?;
    window.set_wm_protocols(&mut conn, &[wm_delete_window])?;

    'evloop: loop {
        // grab an event from the connection
        let ev = conn.wait_for_event()?;

        // if the event is telling us to close, then close
        if let Event::ClientMessage(cme) = ev {
            // check if the client message indicates the deletion protocol
            if cme.data.longs()[0] == wm_delete_window.xid {
                break 'evloop;
            }
        }
    }

    Ok(())
}

See the examples directory in the repository root for more example breadx programs.

Features

std - Enabled by default. This enables the use of the standard library, and enables DisplayConnection and DisplayConnection::create. This library can be used without the standard library; however, it requires the programmer to provide a connection, rather than building a connection itself.
async - Enables the _async suffix family of functions. These functions and methods are similar to their blocking variants, but they use non-blocking variants of network calls. This uses the async_net crate to provide non-blocking calls. However, it nearly triples the size of this package's dependency tree.
image-support - Coming soon.
nightly-min-specialization - Coming soon.
parallel - Uses the rayon crate to parallelize computationally expensive operations.

Re-exports

pub use crate::image::Image;

pub use colormap::*;

pub use display::*;

pub use error::*;

pub use event::Event;

pub use extension::*;

pub use gcontext::*;

pub use pixmap::*;

pub use window::*;

pub use auto::xproto::Arc;

pub use auto::xproto::EventMask;

pub use auto::xproto::ImageFormat;

pub use auto::xproto::Rectangle;

pub use auto::xproto::Segment;

pub use auto::xproto::Visualid;

pub use auto::xproto::Window;

pub use auto::xproto::WindowClass;

Modules

action
auto	This module contains data formats and functions that were automatically generated from the `XmlXcb` description of the X11 protocol. If you want direct access to the X11 protocol's internals, it's recommended to use these functions, as well as the `Display` object's `send_request`, `resolve_request` and `wait_for_event` functions.
behavior
client_message_data	This module provides the `ClientMessageData` structure, which is the data type returned by the `ClientMessageEvent` object.
colormap	Provides functionality and structures used to interface with the colormap.
display	This module defines the `Display` object, which acts as a connection to the X11 server, and the `Connection` trait, which the `Display` object abstracts itself over. See the documentation for these objects for more information.
drawable	This module contains functions that can be applied to nearly all drawable objects, such as Windows and Pixmaps.
error	This module provides structures used in error handling of `breadx` functions.
event	This module provides the events used to drive the `breadx` event system.
extension
gcontext
image	This module defines the Image struct, as well as procedures for manipulating images.
notify_data
pixmap
tutorials	This module contains tutorials on how to use `breadx` and the X Window System Protocol.
window

Structs

AuthInfo

Information needed to authorize a user to use an X11 connection.

Traits

Request	A request that can be sent as an instruction to the X server.
XidType	A type that acts as a wrapper around an XID.

Type Definitions

Fd
XID	An X11 ID.