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 enablesDisplayConnection
andDisplayConnection::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 theasync-io
crate to provide non-blocking calls. However, it nearly triples the size of this package’s dependency tree.image-support
- Adds thefrom_image
method to theImage
class, allowing one to convert a struct of typeimage::Image
from theimage
crate into this image.sync-display
- Enables theSyncDisplay
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 theasync
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 |
behavior | |
client_message_data | This module provides the |
display | This module defines the |
error | This module provides structures used in error handling of |
event | This module provides the events used to drive the |
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 |
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. |