x11rb

The x11rb ecosystem uses a code generator based on xcb-proto XML descriptions to produce Rust bindings. The resulting code is split across two main crates:

• x11rb-protocol: Contains the bulk of the generated code (XIDs, structs, enums, etc.).
• x11rb: Provides helper functions to simplify sending requests to the X11 server.
• x11rb-async: Contains asynchronous versions of the generated code, which follow a similar structure to x11rb.

Generated code is located at the beginning of modules (e.g., xproto in x11rb-protocol) and includes necessary imports for serialization (Serialize), parsing (TryParse), and utility functions.

XIDs (X Identifiers) are used to uniquely identify X11 resources, such as windows. In the generated code, XIDs are implemented as type aliases for u32 numbers.

// Example: A Window XID is a u32
pub type Window = u32;

To prevent ParseError when an X11 server sends an undefined value, enumerations are not implemented as Rust enums. Instead, they are implemented as newtypes around numbers (e.g., struct BackingStore(u32)).

Key features:

• Constants: Defined as pub const values on the struct (e.g., BackingStore::ALWAYS).
• Conversions: Implement From and TryFrom for various integer types (u8, u16, u32) and Option<u32>.
• Debug: Uses pretty_print_enum to show the human-readable name of the variant if it matches a known constant.

#[derive(Clone, Copy, Default, PartialEq, Eq)]
pub struct BackingStore(u32);

impl BackingStore {
    pub const NOT_USEFUL: Self = Self(0);
    pub const WHEN_MAPPED: Self = Self(1);
    pub const ALWAYS: Self = Self(2);
}

Bitmask enumerations are used for fields where multiple bits can be set simultaneously. Like 'Real' enums, these are implemented as newtypes around an integer (e.g., struct ConfigWindow(u16)).

Key features:

• Constants: Defined as bit-shifted values (e.g., ConfigWindow::X = Self(1 << 0)).
• Bitwise Operations: The bitmask_binop! macro is used to implement BitOr and BitOrAssign, allowing you to combine flags using the | operator.
• Debug: Uses pretty_print_bitmask to show all active flags in a human-readable format.

#[derive(Clone, Copy, Default, PartialEq, Eq)]
pub struct ConfigWindow(u16);

impl ConfigWindow {
    pub const X: Self = Self(1 << 0);
    pub const Y: Self = Self(1 << 1);
    pub const WIDTH: Self = Self(1 << 2);
    // ...
}

// Allows: let config = ConfigWindow::X | ConfigWindow::Y;
bitmask_binop!(ConfigWindow, u16);

The x11rb_protocol::protocol module contains common code used across the library. It provides enums covering all possible X11 requests, replies, errors, and events. These enums allow you to interact with protocol messages generically. For example, you can use these enums to access common fields like sequence_number from an event without needing to manually match against every specific event type.

use x11rb_protocol::protocol; 
// Example: Accessing common fields via protocol enums
// (Conceptual usage based on documentation description)

Variable-length structs contain lists of other items (e.g., a list of visuals).

• The length field from the X11 protocol is handled implicitly by a Vec<T> in the Rust struct.
• A helper method is generated to retrieve the length of the list (e.g., visuals_len()) to match the protocol's expected field value.
• The Serialize implementation handles the padding and length field required by the X11 wire format.

#[derive(Clone, Default)]
pub struct Depth {
    pub depth: u8,
    pub visuals: Vec<Visualtype>,
}

impl Depth {
    /// Returns the length of the visuals list as a u16.
    pub fn visuals_len(&self) -> u16 {
        self.visuals.len().try_into().unwrap()
    }
}

Fixed-length structs are used as building blocks for requests and events. They implement two key traits:

1. TryParse: Allows the struct to be parsed from raw bytes received from the X11 server.
2. Serialize: Allows the struct to be converted into native-endian bytes to be sent to the server.

If the extra-traits feature is enabled, these structs also implement common traits like Debug, PartialEq, and Hash.

#[derive(Clone, Copy, Default)]
pub struct Point {
    pub x: i16,
    pub y: i16,
}

// Implements TryParse for reading from the server
// Implements Serialize for writing to the server