# float-clock-wayland
[](https://crates.io/crates/float-clock-wayland)
[](https://opensource.org/licenses/MIT)
[](https://www.rust-lang.org/)
[](https://github.com/wmww/gtk-layer-shell)
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
<img width="1364" height="766" alt="Screenshot of float-clock-wayland running as a floating overlay clock" src="https://github.com/user-attachments/assets/e2bc5de3-891f-4daf-8001-cfbdddd92bbb" />
https://github.com/user-attachments/assets/87693a23-b6cb-4e57-b933-3bec3301b069
## Contents
- [Features](#features)
- [Supported Compositors](#supported-compositors)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage & Controls](#usage--controls)
- [Configuration](#configuration)
- [Autostart](#autostart)
- [Technical Highlights](#technical-highlights)
- [Contributing](#contributing)
- [License](#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
| Hyprland | Native IPC (zero-subprocess cursor tracking) |
| Sway | Generic |
| GNOME | Generic |
| KDE Plasma | Generic |
| River | Generic |
## 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
```bash
cargo install float-clock-wayland
```
### From source
```bash
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
```bash
./target/release/float-clock-wayland
```
| Move widget | Hold **Left Mouse Button** and drag |
| Close widget | Click **Right Mouse Button** |
## Configuration
A default config file is created on first launch at:
```text
~/.config/float-clock-wayland/config.toml
```
| `size` | Integer | `11` | Font size in Pango points. |
| `color` | String | `"#00b7ff"` | Text color, as HEX. Supports an 8-digit alpha channel (e.g. `#00b7ff88`). |
| `border_color` | String | `"#000000"` | Outline border color, as HEX. |
| `thickness` | Integer | `3` | Outline border thickness, in pixels. |
| `format` | String | `"%H:%M:%S\n%d/%m/%Y"` | Time layout, using [chrono strftime syntax](https://docs.rs/chrono/latest/chrono/format/strftime/index.html). 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 the clock at a static time (09:41:00, Jan 9 2007) and stop update scheduling — useful for clean desktop screenshots. |
### CLI overrides
Any setting can be overridden temporarily on the command line:
```bash
./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`
```ini
exec-once = /path/to/bin/float-clock-wayland &
```
### Hyprland — Lua config
```lua
hl.on("hyprland.start", function ()
hl.exec_cmd("/path/to/bin/float-clock-wayland &")
end)
```
### Sway — `config`
```ini
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](https://github.com/Frank-C0/float-clock-wayland).
## License
Licensed under the [MIT License](LICENSE).
