[−][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 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_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 therayon
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 |
behavior | |
client_message_data | This module provides the |
colormap | Provides functionality and structures used to interface with the colormap. |
display | This module defines the |
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 |
event | This module provides the events used to drive the |
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 |
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. |