kdedock

An animated, macOS-style application dock for KDE Plasma 6 (Wayland), written in C++20 and Qt 6.8. It sits at the bottom of your screen as a layer-shell panel, with smooth icon magnification, pinned launchers, auto-hide, and a built-in settings window.

Features

• Icon magnification — cosine or Gaussian falloff curves with configurable radius, max scale, and easing (Out Cubic or custom Bezier)
• Customization — panel color, opacity, border width, border color, icon size, and bar padding
• Auto-hide — timer-based hide/reveal; dock slides down after 2 seconds of inactivity and reappears when you touch the bottom edge
• Pinned apps — persistently pin .desktop launchers; reorder via ~/.config/kdedockrc
• Context menu — right-click to open Dock Settings
• Settings window — standalone QML window launched via the context menu
• HiDPI aware — respects Plasma 6 native fractional scaling; warns if legacy QT_SCALE_FACTOR env vars are set

Requirements

• KDE Plasma 6.x running a Wayland session
• Qt 6.8+ (Quick, QuickControls2, WaylandClient, Test)
• KF6 (Config, Service, KIO, IconThemes, WindowSystem, JobWidgets)
• LayerShellQt
• libtaskmanager (Plasma task management library)
• CMake 3.25+
• Debian 13 (trixie) or a distribution with equivalent packages

kdedock will refuse to start on X11 or non-Wayland platforms.

Building

Install the prerequisites (Debian/Ubuntu example):

sudo apt install \
    cmake ninja-build \
    qt6-base-dev qt6-declarative-dev qt6-wayland-dev \
    liblayershellqtinterface-dev \
    libtaskmanager-dev \
    libkf6config-dev libkf6service-dev libkf6kio-dev \
    libkf6iconthemes-dev libkf6windowsystem-dev libkf6jobwidgets-dev \
    extra-cmake-modules

Build:

cmake -B build -G Ninja
cmake --build build

Installation

Install to ~/.local (user) or /usr (system):

cmake --install build --prefix ~/.local

This installs:

• ~/.local/bin/kdedock
• ~/.local/share/applications/kdedock.desktop
• ~/.local/share/icons/hicolor/scalable/apps/kdedock.svg

The .desktop file includes the X-KDE-Wayland-Interfaces=org_kde_plasma_window_management key, which authorizes the dock to bind the Plasma window management protocol.

To autostart on login, enable it in the settings window or copy the desktop file to ~/.config/autostart/.

Configuration

Open the settings window:

kdedock --settings

Or right-click any dock icon and choose Dock settings….

Settings are stored in ~/.config/kdedockrc (KConfig format). Available options:

Option	Default	Range
Panel color	#1D1F24D9	any RGBA
Panel opacity	0.85	0.20 – 1.00
Border width	1 px	0 – 8
Border color	#66FFFFFF	any RGBA
Icon size	48 px	24 – 96
Max scale	1.6x	1.0 – 2.0
Zoom radius	120 px	40 – 300
Falloff	Cosine	Cosine / Gaussian
Easing	Out Cubic	Out Cubic / Bezier
Auto-hide	off	on / off
Autostart	off	on / off

Click Reset to defaults to restore factory settings.

Architecture

kdedock is split into C++ backends and a QML frontend.

C++ backends (registered as QML singletons):

• ZoomEngine — computes per-icon scale factors from cursor distance using cosine or Gaussian curves
• DockConfig — reads/writes kdedockrc, exposes all tunable properties as QML-bound Q_PROPERTYs
• PinnedStore — persists pinned .desktop names via KConfig; supports reordering and default seeding
• DockTasksModel — wraps TaskManager::TasksModel to provide running windows + pinned launchers as a unified model
• IconImageProvider — async image provider for app icons resolved through KIO / KIconThemes
• InputRegionManager — shapes the input region: bar-only when idle, full surface when hovered; toggles exclusive zone for auto-hide

QML frontend:

• Main.qml — root Window with transparent background, layer-shell sizing, hover tracking, auto-hide timers, and the centered bar Rectangle
• DockIcon.qml — individual icon delegate with magnification binding and click handling
• DockContextMenu.qml — right-click menu for pin/unpin/close/settings actions
• SettingsWindow.qml — standalone ApplicationWindow with color dialogs, sliders, and checkboxes

main.cpp bootstraps the application: it routes Qt windows through the wlr-layer-shell backend, sets up alpha buffers, registers all singletons, configures LayerShellQt::Window as a full-width bottom LayerTop panel, and handles screen-change resilience.

Testing

Run the unit tests with CTest:

ctest --test-dir build --output-on-failure

Tests cover:

• ZoomEngine math (scale-for-distance with cosine and Gaussian falloff)
• DockConfig load/save round-trips and default values
• PinnedStore pin/unpin/reorder persistence

Lint QML files:

qmllint qml/Main.qml qml/DockIcon.qml qml/DockContextMenu.qml qml/SettingsWindow.qml

End-to-end QA script (requires a running Wayland session and spectacle):

bash scripts/e2e.sh

The script builds, installs, verifies the .desktop protocol entry, launches the dock idle, takes a screenshot, and simulates a hover event.

Known Limitations

• PlasmaWindowManagement protocol requires an exclusive bind. plasmashell already holds it, so running-window features (thumbnails, window grouping, minimize/raise) only work if the compositor frees the protocol or kdedock binds it first. The .desktop file declares X-KDE-Wayland-Interfaces=org_kde_plasma_window_management for authorization.
• Auto-hide is timer-based (2 s idle → hide, 1 s bottom-edge hover → reveal). It does not use true window-overlap detection.
• Single screen — the dock attaches to the primary screen at launch and re-attaches on primary screen changes, but multi-monitor pinning is not yet supported.

License

GPL-3.0-or-later

Contributing

Pull requests and issues are welcome. Please keep changes focused and match the existing C++/QML style. Run ctest and qmllint before submitting.