libawm 0.1.0

the library that powers awm - forked from penrose
Documentation 
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

//! Helpers and utilities for using x11rb as a back end for penrose
//!
//! Docs for the `X11` core protocol can be found [here][1]. x11rb is a thin facade over this. For
//! X11 extensions, there are usually separate documentations. For example, the RandR extension is
//! documented in [2].
//!
//! [1]: https://www.x.org/releases/X11R7.6/doc/xproto/x11protocol.html
//! [2]: https://gitlab.freedesktop.org/xorg/proto/randrproto/-/blob/master/randrproto.txt

use crate::{
    core::{
        config::Config,
        hooks::{Hook, Hooks},
        manager::WindowManager,
        xconnection::{XError, Xid},
    },
    ErrorHandler,
};

#[cfg(feature = "x11rb-xcb")]
use x11rb::xcb_ffi::XCBConnection;
use x11rb::{
    connection::Connection,
    errors::{ConnectError, ConnectionError, ReplyError, ReplyOrIdError},
    rust_connection::RustConnection,
    x11_utils::X11Error,
};

pub(crate) mod atom;
pub(crate) mod event;
pub mod xconn;

#[doc(inline)]
pub use xconn::X11rbConnection;

/// Result type for fallible methods using x11rb
pub type Result<T> = std::result::Result<T, X11rbError>;

/// Helper type for when you are defining your [Hook] vector in your main.rs when using
/// the default x11rb impls
pub type X11rbHooks = Hooks<X11rbConnection<RustConnection>>;

/// Construct a penrose [WindowManager] backed by the [x11rb][crate::x11rb] backend using
/// [x11rb::rust_connection::RustConnection].
pub fn new_x11rb_rust_backed_window_manager(
    config: Config,
    hooks: Vec<Box<dyn Hook<X11rbConnection<RustConnection>>>>,
    error_handler: ErrorHandler,
) -> crate::Result<WindowManager<X11rbConnection<RustConnection>>> {
    let (conn, _) = RustConnection::connect(None).map_err(X11rbError::from)?;
    new_x11rb_backed_window_manager(conn, config, hooks, error_handler)
}

/// Construct a penrose [WindowManager] backed by the [x11rb][crate::x11rb] backend using
/// [x11rb::xcb_ffi::XCBConnection].
#[cfg(feature = "x11rb-xcb")]
pub fn new_x11rb_xcb_backed_window_manager(
    config: Config,
    hooks: Vec<Box<dyn Hook<X11rbConnection<XCBConnection>>>>,
    error_handler: ErrorHandler,
) -> crate::Result<WindowManager<X11rbConnection<XCBConnection>>> {
    let (conn, _) = XCBConnection::connect(None).map_err(X11rbError::from)?;
    new_x11rb_backed_window_manager(conn, config, hooks, error_handler)
}

/// Construct a penrose [WindowManager] backed by the [x11rb][crate::x11rb] backend using
/// the given connection.
pub fn new_x11rb_backed_window_manager<C: Connection>(
    connection: C,
    config: Config,
    hooks: Vec<Box<dyn Hook<X11rbConnection<C>>>>,
    error_handler: ErrorHandler,
) -> crate::Result<WindowManager<X11rbConnection<C>>> {
    let conn = X11rbConnection::new_for_connection(connection)?;
    let mut wm = WindowManager::new(config, conn, hooks, error_handler);
    wm.init()?;

    Ok(wm)
}

/// Enum to store the various ways that operations can fail inside of the
/// x11rb implementations of penrose traits.
#[derive(thiserror::Error, Debug)]
pub enum X11rbError {
    /// Unable to establish a connection to the X11 server
    #[error(transparent)]
    Connect(#[from] ConnectError),

    /// The X11 connection broke
    #[error(transparent)]
    Connection(#[from] ConnectionError),

    /// Could not get the reply to an X11 request
    #[error(transparent)]
    ReplyError(#[from] ReplyError),

    /// Could not get the reply to an X11 request or failed to allocate an Xid
    #[error(transparent)]
    ReplyOrIdError(#[from] ReplyOrIdError),

    /// A requested client property was empty
    #[error("'{0}' prop is not set for client {1}")]
    MissingProp(String, Xid),

    /// Something was not valid UTF8
    #[error("Something was expected to be UTF8, but is not")]
    NonUtf8(#[from] std::string::FromUtf8Error),

    /// Property data returned for the target window was in an invalid format
    #[error("invalid property data: {0}")]
    InvalidPropertyData(String),

    /// A query via the randr API was unsuccessful
    #[error("randr query failed: {0}")]
    Randr(String),

    /// Wrapper around low level X11 errors
    #[error("X11 error: {0:?}")]
    X11Error(X11Error),
}

macro_rules! from_error {
    ($type:ident) => {
        impl From<$type> for XError {
            fn from(error: $type) -> Self {
                X11rbError::from(error).into()
            }
        }
    };
}

from_error!(ConnectError);
from_error!(ConnectionError);
from_error!(ReplyError);
from_error!(ReplyOrIdError);