# 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)
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
### Screenshot
<img width="1364" height="766" alt="Screenshot of float-clock-wayland on desktop" src="https://github.com/user-attachments/assets/e2bc5de3-891f-4daf-8001-cfbdddd92bbb" />
### 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
```bash
cargo install float-clock-wayland
```
### Build from Source
```bash
# 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:
```bash
float-clock-wayland
```
### Mouse Controls
| **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
| `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](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 clock time (09:41:00) for clean desktop screenshots. |
### Command-Line Overrides
All settings in `config.toml` can be temporarily overridden via CLI flags:
```bash
# 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:
```bash
float-clock-wayland --help
```
---
## Desktop Autostart Setup
### Hyprland (`hyprland.conf`)
Add to `~/.config/hypr/hyprland.conf`:
```ini
exec-once = float-clock-wayland &
```
### Hyprland (Lua Config)
```lua
hl.on("hyprland.start", function ()
hl.exec_cmd("float-clock-wayland &")
end)
```
### Sway (`config`)
Add to `~/.config/sway/config`:
```ini
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](https://github.com/Frank-C0/float-clock-wayland).
---
## License
This project is licensed under the [MIT License](LICENSE).
