X11 Overlay

A lightweight, transparent overlay system for X11 window managers. Create click-through overlays with custom UI components for status displays, HUDs, and desktop enhancements.

Features

• Universal X11 compatibility - Works with any EWMH-compliant window manager
• True transparency - Uses ARGB visuals for seamless integration
• Click-through support - XShape extension allows interaction with windows below
• Text rendering - Cairo-based text rendering with font support and layouts
• Composite components - Status panels, notifications, and progress bars
• Modular architecture - Component-based UI system for easy extensibility
• Minimal dependencies - Lightweight Rust implementation with essential X11 libraries
• Development ready - Pre-commit hooks, clippy, and rustfmt integration

Quick Start

# Clone and build
git clone https://github.com/cinnes/x11-overlay.git
cd x11-overlay
cargo build --release

# Run the overlay
./target/release/x11-overlay

Requirements

• X11 server with ARGB visual support
• XShape extension (standard on modern systems)
• Compositor (picom, compton, etc.) for transparency effects
• Cairo library for text rendering (libcairo2-dev)
• Rust 1.70+ for building from source

Compatibility

Should work with EWMH-compliant window managers:

• i3wm
• awesome
• bspwm
• openbox
• Xfce (xfwm4)
• Others supporting standard X11 protocols

Architecture

src/
├── graphics/     # Rendering system (X11 + Cairo text)
├── ui/          # Component system and composite widgets
├── x11/         # X11 utilities and visual helpers
├── overlay.rs   # Core X11 window management
└── main.rs      # Application entry point

Component System

Create custom overlay elements by implementing the Component trait:

use crate::graphics::{Color, GraphicsContext, Rectangle};
use crate::ui::Component;
use anyhow::Result;

struct StatusBar {
    position: Rectangle,
    color: Color,
}

impl Component for StatusBar {
    fn render(&self, graphics: &mut GraphicsContext) -> Result<()> {
        graphics.renderer().fill_rectangle(self.position, self.color.to_renderer_color())
    }

    fn bounds(&self) -> Rectangle {
        self.position
    }

    fn update(&mut self, _delta_time: f64) -> bool {
        false // No animation needed
    }
}

Built-in Components

• TextComponent - Rendered text with font, color, and alignment options
• StatusPanel - Titled panel with multiple text lines
• NotificationComponent - Auto-fading notifications with icon area
• ProgressBarComponent - Labeled progress bars with customizable colors

Configuration

The overlay uses standard X11 properties and can be configured through window manager rules:

# i3wm example
for_window [class="x11-overlay"] floating enable, border none

Development

Setup

# Install pre-commit hooks
git config core.hooksPath .githooks

# Run quality checks
cargo clippy
cargo fmt
# Note: Test suite is in development

Project Standards

• Error handling: Comprehensive error contexts with anyhow
• Code quality: Clippy lints enforced, rustfmt formatting
• Architecture: Modular design with clear separation of concerns

Status

Current State: Early development with text rendering support

• Core X11 overlay functionality implemented
• Text rendering with Cairo integration
• Component architecture with built-in widgets
• Demo application showing composite components

Performance: Lightweight design optimized for minimal resource usage

Roadmap

• Image/icon support
• Enhanced layout system
• Configuration file support
• Input handling for interactive components
• Wayland compatibility layer

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Code Review Process

1. All changes require pre-commit hook approval
2. Follow established architectural patterns
3. Manual testing required (automated tests in development)

License

Licensed under the MIT License. See LICENSE for details.

Acknowledgments

Built with:

• x11rb - Pure Rust X11 client library
• cairo-rs - Cairo graphics bindings
• anyhow - Flexible error handling

This project follows Google's engineering standards for open source projects.