yaxi/lib.rs
1//! This crate provides a high level interface to the x11 [protocol] in pure Rust.
2//!
3//! [protocol]: https://www.x.org/docs/XProtocol/proto.pdf
4//!
5//! # Features
6//! - Clean Interface - yaxi provides a clean interface, making it perfect for both beginners and experienced developers
7//! - Safety - yaxi has safe interface for x11 unlike many other x11 libraries
8//! - Not A Wrapper - yaxi is a pure rust implementation and is NOT a wrapper
9//! - No Release Dependencies - yaxi release builds dont depend on any crates
10//!
11//! # Usage
12//! This crate is on [crates.io](https://crates.io/crates/yaxi) and can be added either through
13//! adding `yaxi` to your dependencies in `Cargo.toml`:
14//! ```toml
15//! [dependencies]
16//! yaxi = "0.1.57"
17//! ```
18//!
19//! Or running the following Cargo command in your project directory:
20//! ```bash
21//! cargo add yaxi
22//! ```
23//!
24//! # [Example: open a window](https://github.com/proxin187/Yaxi/tree/main/examples/minimal)
25//! The following example opens a window and waits for a keyboard press before it quits:
26//!
27//! ```no_run
28//! use yaxi::window::{WindowArguments, ValuesBuilder, WindowKind};
29//! use yaxi::proto::{Event, WindowClass, EventMask};
30//! use yaxi::display;
31//!
32//!
33//! fn main() -> Result<(), Box<dyn std::error::Error>> {
34//! let mut display = display::open(None)?;
35//!
36//! let mut root = display.default_root_window()?;
37//!
38//! let mut window = root.create_window(WindowArguments {
39//! depth: root.depth(),
40//! x: 5,
41//! y: 5,
42//! width: 80,
43//! height: 50,
44//! border_width: 15,
45//! class: WindowClass::InputOutput,
46//! visual: root.visual(),
47//! values: ValuesBuilder::new(vec![]),
48//! })?;
49//!
50//! window.select_input(&[EventMask::KeyPress, EventMask::KeyRelease])?;
51//!
52//! window.map(WindowKind::Window)?;
53//!
54//! let event = display.next_event()?;
55//!
56//! match event {
57//! Event::KeyEvent { kind, coordinates, window, root, subwindow, state, keycode, send_event } => {
58//! let window_copy = display.window_from_id(window)?;
59//!
60//! println!("window from id: {}, keycode: {}", window_copy.id(), keycode);
61//! },
62//! _ => {},
63//! }
64//!
65//! window.destroy(WindowKind::Window)?;
66//!
67//! Ok(())
68//! }
69//! ```
70//!
71//! Note that the functions are appropriately mapped to their respective structure eg. (Window, Display), a feature shy from [most other x11 libraries]().
72//!
73//! For more examples please visit the [repo](https://github.com/proxin187/Yaxi/tree/main/examples)
74//!
75//! # Crate features
76//! By default [yaxi](https://github.com/proxin187/Yaxi) only has the standard x11 protocol, but
77//! with the following crate features the user gets additional functionality:
78//! - `xinerama` - this feature allows the user to interface with [Xinerama](https://en.wikipedia.org/wiki/Xinerama), an extension to the x11 protocol enabling to use two or more physical displays as one shared display
79//! - `clipboard` - extensible builtin clipboard functionality
80//! - `extras` - enables some convencience functions that arent a part of the official protocol
81//! - `ewmh` - enable convencience functions for working with [EWMH](https://specifications.freedesktop.org/wm-spec/1.3/)
82
83#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
84
85pub mod display;
86
87/// proto contains protocol specific code such as opcodes, replies and so on.
88pub mod proto;
89
90/// window contains the core functionality for handling windows
91pub mod window;
92
93/// keyboard contains keysyms and keycodes for x11
94pub mod keyboard;
95
96/// implementation of popular x11 extensions such as xinerama
97pub mod extension;
98
99#[cfg(feature = "clipboard")]
100pub mod clipboard;
101
102/// ewmh defines interactions between window managers, applications, and the utilities that form part of a desktop environment
103
104#[cfg(feature = "ewmh")]
105pub mod ewmh;