How whysobad/hyprland-preview-share-picker works
Based on our analysis of the provided file tree and README, this project is an alternative share picker for the Hyprland window manager that integrates with xdg-desktop-portal-hyprland. It is written in Rust and clearly separates the core logic (located in the lib subproject) from the application aspects (in the src directory). The library encapsulates the toolkit-independent and Wayland/Hyprland-specific logic (e.g., handling protocols and image processing), while the application layer handles the configuration, command-line interface, and GTK4-based GUI creation.
Main Components & Their Roles
• Application Layer:
• Represented by the src directory files (main.rs, app.rs, cli.rs, config.rs, util.rs, and the views subdirectory). This is responsible for initializing the GUI (via GTK4 and gtk4-layer-shell integration) and handling user interactions.
• The CLI and configuration management (reading the YAML config file, applying style customizations and setting window properties) are also processed here.
• Core Library (lib subproject):
• Contains the protocol implementations, image processing, error handling, frame/buffer management, and other toolkit-independent logic.
• Examined in lib/src folder, it provides the abstraction over Hyprland protocols (see the protocols directory for hyprland_toplevel_export_v1.rs and mod.rs) and encapsulates the essential functionality that can be reused in custom frontends.
• External Services & Dependencies:
• GTK4 and gtk4-layer-shell: used for rendering the GUI widgets and managing the front-end layout.
• xdg-desktop-portal-hyprland: the protocol integration ensures that the share picker is invoked as part of the Hyprland ecosystem.
• hyprland itself, as well as the external tool “slurp” (for region selection via command-line call).
• Build and Packaging Components:
• The Cargo.toml files in both the project root and the lib subproject, along with build.rs, manage dependencies and build configuration. The PKGBUILD (in README) also describes how the tool is packaged and installed in Arch Linux environments.
Relationships and Interactions
• The Application Layer acts as the orchestrator: It starts up the GUI application (src/main.rs) and uses the CLI and configuration modules (src/cli.rs and src/config.rs) to load settings.
• The GUI interacts with the Core Library to display previews for windows and outputs. For example, image processing modules (src/image.rs and lib/src/image.rs) are responsible for resizing images and rendering them in the view.
• The lib subproject, being consumed as a Git submodule and compiled with the main binary, provides a clear interface to Hyprland protocols (handled in lib/src/protocols) that are crucial for integration with the Wayland-based environment.
• There is a clear separation between platform-independent logic (in lib) and the GTK frontend (in src), which allows for potential custom frontends if desired.
Architectural Patterns and Technologies
• Layered Architecture:
• Presentation/GUI Layer (GTK4-based).
• Business/Domain Logic Layer (Core functionalities in lib).
• Configuration and CLI Layer – handling application settings and command-line invocations.
• Modularity: The separation into "lib" and "src" shows that the application is designed to allow easy reuse of non-UI logic, consistent with good modular design principles.
• External Integration: The use of standard tools like “slurp” for region capture, xdg-desktop-portal configurations, and Nightly Rust toolchain indicate reliance on external dependencies and careful configuration management.
Key Architectural Patterns to Emphasize
• Separation of concerns via distinct modules for business logic and UI.
• Modularity with a clear API between the lib subproject (which can be reused in custom frontends) and the UI.
• Integration with external systems (Wayland protocols, xdg-desktop-portal configuration, and external tools like “slurp”) as clearly defined components.