1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194
// Copyright John Nunley, 2022.
// Distributed under the Boost Software License, Version 1.0.
// (See accompanying file LICENSE or copy at
// https://www.boost.org/LICENSE_1_0.txt)
//! `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.
//!
//! [X11 client protocol]: https://en.wikipedia.org/wiki/X_Window_System
//! [default connection implementation]: crate::display::BasicDisplay
//! [thread unsafe]: crate::display::CellDisplay
//! [thread safe]: crate::display::SyncDisplay
//! [`tokio`]: crate::rt_support::tokio_support
//! [`async-std`]: crate::rt_support::async_std_support
//!
//! # 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.
//!
//! [`Display`]: crate::display::Display
//! [`DisplayConnection::connect()`]: crate::display::DisplayConnection::connect
//! [`DisplayFunctionsExt`]: crate::display::DisplayFunctionsExt
//!
//! ```rust,no_run
//! use breadx::{prelude::*, display::DisplayConnection, protocol::xproto};
//!
//! # fn main() -> breadx::Result<()> {
//! // 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
//! # _ => {},
//! }
//! }
//! # Ok(()) }
//! ```
//!
//! See the [tutorial](crate::tutorials::introduction) for more information
//! on the usage of `breadx`.
#![no_std]
#![forbid(future_incompatible, unsafe_code, rust_2018_idioms)]
#![warn(clippy::pedantic)]
#![allow(
clippy::module_name_repetitions,
clippy::missing_errors_doc,
clippy::wildcard_imports
)]
extern crate alloc;
#[cfg(feature = "std")]
extern crate std;
#[macro_use]
mod gates;
mod error;
pub use error::*;
mod utils;
pub(crate) use utils::*;
cfg_async! {
pub mod rt_support;
}
mod void;
pub use void::Void;
cfg_std! {
mod name;
pub use name::*;
}
cfg_sync! {
mod mutex;
}
cfg_async! {
pub mod futures;
}
// inline some of x11rb_protocol's docs into ours
#[doc(inline)]
pub use x11rb_protocol::{connect, x11_utils};
/// The protocol used during communication.
pub mod protocol {
#[doc(inline)]
pub use x11rb_protocol::{connection::ReplyFdKind, protocol::*, x11_utils::*, DiscardMode};
}
cfg_std! {
#[doc(inline)]
pub use x11rb_protocol::resource_manager;
}
#[allow(
clippy::cast_possible_truncation,
clippy::let_and_return,
clippy::needless_lifetimes,
clippy::too_many_arguments
)]
pub(crate) mod automatically_generated;
#[doc(inline)]
pub use x11rb_protocol::RawFdContainer as Fd;
pub mod connection;
pub mod display;
mod mutlireply;
pub use mutlireply::*;
/// Contains a set of traits to be automatically imported for full
/// functionality.
pub mod prelude {
pub use super::display::{
Display, DisplayBase, DisplayBaseExt, DisplayExt, DisplayFunctionsExt,
};
cfg_async! {
pub use super::display::{
AsyncDisplay, AsyncDisplayExt, AsyncDisplayFunctionsExt
};
}
}
pub mod tutorials;