Crate breadx[][src]

Expand description

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::{prelude::*, 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-io crate to provide non-blocking calls. However, it nearly triples the size of this package’s dependency tree.
  • image-support - Adds the from_image method to the Image class, allowing one to convert a struct of type image::Image from the image crate into this image.
  • sync-display - Enables the SyncDisplay struct, which allows usage of the display in thread-safe contexts. However, it does require importing more dependencies (although some of these dependencies overlap with those of the async feature).

Re-exports

pub use crate::image::Image;
pub use display::*;
pub use error::*;
pub use event::Event;
pub use extension::*;
pub use keyboard::*;
pub use auto::xproto::Arc;
pub use auto::xproto::Atom;
pub use auto::xproto::ColormapAlloc;
pub use auto::xproto::Drawable;
pub use auto::xproto::EventMask;
pub use auto::xproto::Gcontext;
pub use auto::xproto::ImageFormat;
pub use auto::xproto::Pixmap;
pub use auto::xproto::Rectangle;
pub use auto::xproto::Segment;
pub use auto::xproto::Setup;
pub use auto::xproto::VisualClass;
pub use auto::xproto::Visualid;
pub use auto::xproto::Visualtype;
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.

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.

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
image

This module defines the Image struct, as well as procedures for manipulating images.

keyboard
notify_data
render

First-class support for the XRender extension.

Structs

AuthInfo

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

CellXidGenerator

XID Generator, but implemented using Cell

XidGenerator

XID Generator

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.