float-clock-wayland 0.2.0

Always-on-top floating desktop clock widget for Wayland compositors.
float-clock-wayland-0.2.0 is not a library.

float-clock-wayland

Crates.io License: MIT Rust Edition 2024 Wayland

A lightweight, always-on-top floating desktop clock widget for Wayland compositors. Built with Rust, GTK 3, gtk-layer-shell, Cairo, and Pango.

Designed for custom Linux desktop setups and rice configurations, float-clock-wayland presents a highly customizable desktop clock overlay that stays anchored above all regular windows. It features smooth drag-and-drop positioning, automatic state saving, and accurate second-aligned time updating.

Inspired by the classic DS Clock utility for Windows, it brings an elegant, minimal clock overlay to modern Wayland desktops (such as Hyprland, Sway, GNOME, and KDE Plasma).

[!NOTE] Designed for Linux Wayland desktop environments supporting gtk-layer-shell.

Preview

Demonstration image of float-clock-wayland

Screenshot

Video Demonstration

https://github.com/user-attachments/assets/87693a23-b6cb-4e57-b933-3bec3301b069

Features

  • 📌 Always-on-Top Floating Clock: Stays visible above normal application windows using Wayland layer-shell protocol (Overlay / Top layers).
  • 🎨 Fully Customizable Appearance: Adjust font family, font weight, size, text color with alpha transparency, outline border color, outline thickness, alignment, and date/time format.
  • 🖱️ Smooth Drag-and-Drop Positioning: Move the widget effortlessly across your screen.
  • ⚡ Native Hyprland IPC & Generic Wayland Fallback: Uses Hyprland's native IPC socket for cursor tracking when available, with an automatic fallback for other Wayland compositors.
  • ⏱️ Zero Timer Drift: Aligns update schedules to exact wall-clock second tick boundaries for precise, jitter-free timekeeping.
  • ✒️ Crisp Vector Text Rendering: Powered by Cairo and Pango for high-DPI crisp text with custom stroke outlines.
  • 💾 Automatic Position Persistence: Automatically saves and restores widget coordinates across sessions.
  • ⚙️ Auto-Generated Configuration: Creates a default config.toml on first launch with instant CLI option overrides.

Installation

From Crates.io

cargo install float-clock-wayland

Build from Source

# Clone repository
git clone https://github.com/Frank-C0/float-clock-wayland.git
cd float-clock-wayland

# Build release binary
cargo build --release

The compiled binary will be located at target/release/float-clock-wayland.

Prerequisites

To build float-clock-wayland from source, ensure you have the necessary development libraries installed:

  • GTK 3 (libgtk-3-dev / gtk3-devel)
  • gtk-layer-shell (libgtk-layer-shell-dev / gtk-layer-shell-devel)
  • Pango & Cairo
  • pkg-config

Most Wayland desktop setups already include these packages.

Usage & Controls

Launch the widget from your terminal or application launcher:

float-clock-wayland

Mouse Controls

Action Mouse Shortcut
Move Widget Hold Left Mouse Button (LMB) & drag
Close Widget Click Right Mouse Button (RMB)

Configuration

On first run, a default configuration file is automatically created at:

~/.config/float-clock-wayland/config.toml

Configuration Options

Setting Type Default Description
size Integer 11 Font size in Pango points.
color String "#00b7ff" HEX text color (supports 8-digit HEX with alpha channel, e.g. #00b7ff88).
border_color String "#000000" HEX outline border color.
thickness Integer 3 Text outline border thickness in pixels.
format String "%H:%M:%S\n%d/%m/%Y" Date/time format layout (chrono syntax). Use \n for line breaks.
font_family String "JetBrains Mono..." System font family stack.
font_weight String "heavy" Pango font weight (thin, light, normal, medium, bold, heavy).
alignment String "center" Text alignment (center, left, right).
layer String "top" Wayland layer depth (top, overlay, bottom, background).
backend String "auto" Cursor tracking backend (auto, hyprland, generic).
save_position Boolean true Save and restore window position between restarts.
demo Boolean false Freeze clock time (09:41:00) for clean desktop screenshots.

Command-Line Overrides

All settings in config.toml can be temporarily overridden via CLI flags:

# Freeze time for a desktop showcase screenshot
float-clock-wayland --demo

# Override font size and color on launch
float-clock-wayland --size 14 --color "#ffffff" --backend generic

View all options with:

float-clock-wayland --help

Desktop Autostart Setup

Hyprland (hyprland.conf)

Add to ~/.config/hypr/hyprland.conf:

exec-once = float-clock-wayland &

Hyprland (Lua Config)

hl.on("hyprland.start", function ()
    hl.exec_cmd("float-clock-wayland &")
end)

Sway (config)

Add to ~/.config/sway/config:

exec float-clock-wayland &

Technical Highlights

  • Language: Written in modern Rust (2024 edition) with strict #![forbid(unsafe_code)].
  • UI Framework: GTK 3 with native gtk-layer-shell integration.
  • Rendering: Cairo vector graphics engine combined with Pango text layout.
  • IPC & Window Positioning: Hyprland IPC listener with mathematical fallback tracking for standard Wayland layer-shell compositors.
  • Standards: Compliant with XDG Base Directory specification.

Contributing

Contributions, bug reports, and pull requests are welcome! Feel free to open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License.