float-clock-wayland

An always-on-top, floating desktop clock widget for Wayland compositors, built in Rust with GTK 3, Cairo, Pango, and gtk-layer-shell. It stays anchored above every other window, making it a lightweight Linux alternative to the classic Windows utility DS Clock — a natural fit for custom Hyprland, Sway, GNOME, or KDE Plasma setups, status bars, ricing configs, and gaming overlays.

[!NOTE] Built for Wayland desktops that support gtk-layer-shell. Use it as-is or fork it into your own dotfiles.

Preview

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

Contents

• Features
• Supported Compositors
• Prerequisites
• Installation
• Usage & Controls
• Configuration
• Autostart
• Technical Highlights
• Contributing
• License

Features

• Always-on-top overlay — anchored at the highest Wayland layer (overlay / top), so the clock stays visible above every application window.
• Phase-locked time precision — updates are aligned to system wall-clock second boundaries, eliminating drift and skipped seconds.
• Smooth dragging on Wayland — a native Hyprland IPC backend for zero-subprocess cursor tracking, plus a generic drag-compensation loop for Sway, GNOME, KDE, and River.
• Crisp vector rendering — double-buffered Cairo paths and Pango text layout, with stroke outlines that don't clip at high DPI.
• Persistent window position — coordinates are saved to $XDG_STATE_HOME/float-clock-wayland/state.json via atomic POSIX writes.
• Zero-config startup — a default config.toml is generated automatically in $XDG_CONFIG_HOME/float-clock-wayland/ on first run.

Supported Compositors

Prerequisites

The widget binds to native GUI libraries, so building from source requires the corresponding development headers:

• GTK 3 (with GDK Wayland support)
• gtk-layer-shell
• Pango
• Cairo
• pkg-config

If you're already running a Wayland compositor with custom status bars or widgets, most of these are likely installed already. Otherwise, look for packages named libgtk-3-dev / gtk3-devel, libgtk-layer-shell-dev / gtk-layer-shell-devel, and similar in your distro's package manager.

Installation

From crates.io

cargo install float-clock-wayland

From source

git clone https://github.com/Frank-C0/float-clock-wayland.git
cd float-clock-wayland
cargo build --release

The compiled binary is placed at ./target/release/float-clock-wayland.

Usage & Controls

./target/release/float-clock-wayland

Configuration

A default config file is created on first launch at:

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

CLI overrides

Any setting can be overridden temporarily on the command line:

./target/release/float-clock-wayland --demo
./target/release/float-clock-wayland --size 12 --color "#ffffff" --backend generic

Run with --help to list all available flags.

Autostart

Hyprland — hyprland.conf

exec-once = /path/to/bin/float-clock-wayland &

Hyprland — Lua config

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

Sway — config

exec /path/to/bin/float-clock-wayland &

GNOME / KDE Plasma

Add the binary path to your session's Startup Applications (GNOME Tweaks / KDE System Settings → Autostart), since these environments don't use an exec directive in a plain-text config.

Technical Highlights

• Written in modern Rust (2024 edition) with #![forbid(unsafe_code)].
• GTK 3 UI with native gtk-layer-shell layer-shell integration.
• Cairo vector rendering combined with Pango text layout.
• Hyprland IPC listener with a mathematical fallback control loop for standard Wayland compositors.
• Compliant with the XDG Base Directory specification.

Contributing

Contributions, bug reports, and pull requests are welcome — feel free to open an issue or submit a PR on GitHub.

License

Licensed under the MIT License.