winbar

A from-scratch Windows 11 style taskbar for the COSMIC desktop (Wayland), built
with libcosmic (iced + layer-shell + xdg-popup)
and cosmic-client-toolkit.

Version 1.1.0: tested on Pop!_OS 24.04 with COSMIC 1.9, on two monitors at 90%
fractional scale.

Screenshots

The bar: Start (Pop!_OS logo), Search, Task view and pinned apps on the left, open apps
in the centre, and the tray, Quick Settings, clock and power on the right.


The whole bar on one 1920×1080 monitor: [docs/screenshots/bar.png](docs/screenshots/bar.png).

Features

• 54 px bar at the bottom of every monitor (layer-shell, exclusive zone, blur via ext_background_effect_v1 when available), follows COSMIC's dark/light mode. All sizes are logical pixels (crisp at fractional scales such as 90 %).
• Left group: Start (winbar's Start menu, see below; icon = the Pop!_OS logo by default), Search (COSMIC Launcher), Task view (COSMIC Workspaces), then **pinned apps that aren't open** (launchers).
• Centre group (centred on the output): all open apps, one button per app, with running pills (focused app: longer accent pill). Opening a pinned app moves its button from the left group to the centre; closing its last window moves it back to its pinned slot. Nothing is ever shown twice. If the groups would collide on a narrow output, the centre group shifts (open apps have priority, launchers are dropped first) — they never overlap.
• 32 px app icons in 48 px buttons (app_icon_size, bar_height).
  • Left click: launch / activate / minimise / cycle through the app's windows.
  • Middle click: new instance. Right click: jump-list menu (desktop actions, launch, pin/unpin, close window(s)).
  • Hover (400 ms): live window thumbnails (ext-image-copy-capture, ~1 fps while visible), title, close ×; click a thumbnail to activate that window.
• Right side: ^ hidden-icons grid, up to 4 tray icons (first-registered first; StatusNotifierItem host with dbusmenu rendering), Quick Settings button (network, volume, battery if a system battery exists), stacked clock with calendar flyout (both follow COSMIC's Settings → Time & Language live: 12/24 h, seconds, weekday, date on/off, custom strftime format, first day of the week; names/formats localised from COSMIC's region (LC_TIME via systemd-localed) with ICU, like COSMIC's own time applet; timezone changes, NTP clock steps and resume are picked up immediately), a power button (lock / sign out / sleep / restart / shut down), show-desktop sliver.
• Start menu (a popup above the Start button on the monitor you clicked, 640×720 by default): search field focused on open — typing filters live (name, generic name, keywords, Exec basename; prefix matches first), Enter launches the selected result (the first by default), arrow keys move the selection, Esc closes (first the right-click panel, then the menu), clicking outside closes. Category chips (All, Development, Games, Internet, Multimedia, Office, System, Utilities). Pinned section (start_pinned, seeded from the taskbar pins) above an A–Z grid of every installed app (NoDisplay/Hidden/OnlyShowIn respected; duplicate copies such as Flatpak + distro package collapsed). Right-click an app: Open, Pin/Unpin Start, Pin/Unpin taskbar. Footer: File Explorer, Terminal, Settings, your name and a power menu. Apps are launched like taskbar apps (xdg-activation token, own systemd scope) and the menu closes. use_cosmic_app_library = true makes Start open COSMIC's App Library instead. (The Super key stays with COSMIC; there is no supported way for a client to take it.)
• Quick Settings flyout: Wi-Fi (NetworkManager), Bluetooth (BlueZ), volume slider + mute (PipeWire via pactl, live updates via pactl subscribe), brightness (only if /sys/class/backlight has a device), settings shortcut, power menu (lock, sign out, sleep, restart, shut down — sign out/restart/shut down use COSMIC's own cosmic-osd confirmation dialogs, like the COSMIC power applet).
• All flyouts are real xdg_popups parented on the bar's layer surface; only one is open at a time; clicking outside dismisses them (popup grab), Esc closes them.

Build / install

Needs Rust stable and the usual libcosmic build deps
(libxkbcommon-dev libwayland-dev libfontconfig-dev libfreetype-dev libexpat1-dev libinput-dev libudev-dev libdbus-1-dev clang just). Build output goes to
~/.cache/winbar-target when you build with just (override it with CARGO_TARGET_DIR).
Plain cargo build uses ./target as usual.

just test       # unit + private-bus integration tests
just install    # release build -> ~/.local/bin/winbar, ~/.local/bin/winbar-switch,
                # ~/.config/autostart/winbar.desktop (created with Hidden=true)
just dev        # run from the tree at the TOP edge, alongside COSMIC's panel

Switching COSMIC's panel off/on

winbar-switch on       # back up COSMIC panel entries, set them to [], enable autostart, start winbar
winbar-switch off      # stop winbar, then restore COSMIC's entries exactly as backed up, disable autostart
winbar-switch status

COSMIC's panel reads ~/.config/cosmic/com.system76.CosmicPanel/v1/entries (normally
["Panel"]) and reloads it live, so no logout is needed. The backup lives in
~/.local/state/winbar/cosmic-panel-entries.backup. Both commands are idempotent.

Configuration

~/.config/winbar/config.toml is created on first start; pinned is initialised from
COSMIC's dock favourites (~/.config/cosmic/com.system76.CosmicAppList/v1/favorites).
Pin/unpin from the app context menu rewrites the file. Keys:

The config is read at start-up (restart winbar after hand edits). Clock/date settings
are not in this file: winbar reads COSMIC's own
~/.config/cosmic/com.system76.CosmicAppletTime/v1/* (military_time,
show_seconds, show_weekday, show_date_in_top_panel, first_day_of_week
— 0 = Monday … 5 = Saturday, otherwise Sunday — and format_strftime, which overrides
the rest; %n starts a second line) and follows changes live.

Logs: ~/.local/state/winbar/winbar.log (rotated at 1 MiB to winbar.log.1).
RUST_LOG=debug winbar --stderr for verbose output.

Tray (StatusNotifierItem)

winbar registers as a host with the existing org.kde.StatusNotifierWatcher (on COSMIC
that is the socket-activated cosmic-applet-status-area --status-notifier-watcher
daemon, which exits ~1–2 min after the last COSMIC panel applet goes away). If the name
is free, winbar becomes the watcher itself (RegisterStatusNotifierItem/Host,
Registered* properties and signals, items dropped when their bus name vanishes) and
re-seeds it with the items it already knew. Items that own a conventional
org.kde/org.freedesktop.StatusNotifierItem-* name but aren't registered with the
current watcher (some apps, e.g. FxSound, register only once at start-up and are lost
whenever a watcher restarts) are adopted too. The owner is tracked continuously, so the
switch happens automatically in both directions.

Left click → Activate (or the menu for ItemIsMenu items), right click → the item's
com.canonical.dbusmenu rendered in a winbar popup (Event(id,"clicked")), middle →
SecondaryActivate, wheel → Scroll. An xdg-activation token is passed with
ProvideXdgActivationToken before activations.

winbar-test-sni [--id NAME] [--pixmap] exports a test item with a small menu and logs
every call — handy for checking the tray on the real or a private bus.

Debug IPC

D-Bus interface dev.winbar.Debug at /dev/winbar/Debug on the session bus (bus name
dev.winbar.Winbar, which also enforces a single instance). CLI wrapper:

winbar ctl dump                              # JSON: bars, groups, windows, tray, popup, quick settings
winbar ctl open calendar|quick|power|overflow [OUTPUT]
winbar ctl open tray-menu:steam | app-menu:<group-key> | thumbs:<group-key> [OUTPUT]
winbar ctl close
winbar ctl click start|search|taskview|desktop|app:<key>|tray:<id> [left|right|middle]
winbar ctl menu <id>                         # tray menu item id, or pin|close-all|launch|action:<id>
                                             # for app menus, activate:<win>|close:<win> for thumbnails
winbar ctl quick wifi|bluetooth|mute|volume:N|brightness:N
winbar ctl hover <key> [leave]               # simulate hovering an app button
winbar ctl open start [OUTPUT]               # Start menu
winbar ctl start-query <text>                # type into the Start search
winbar ctl key up|down|left|right|enter|escape
winbar ctl start-icon <name|path|builtin>    # preview a Start icon (not saved)
winbar ctl tray-last [item-bus-name]         # last tray activation (dev.winbar.Tray1), JSON

Group keys are lower-case desktop ids (see dump). Popups opened through the IPC are
created without a grab (there is no input serial), so close them with winbar ctl close.

For app developers: where was my tray icon clicked?

winbar tells tray apps where their icon is, so they can open their own popup above it.
On the session bus winbar owns dev.winbar.Tray, object /dev/winbar/Tray,
interface dev.winbar.Tray1:

GetLastActivation(s item_key) -> (b found, s output,
                                  i icon_x, i icon_y, i icon_w, i icon_h,
                                  i out_x, i out_y, i out_w, i out_h,
                                  i bar_height, s edge, t timestamp_ms)

signal Activated(s item_key, s output, i icon_x, i icon_y, i icon_w, i icon_h)

• item_key: your item's bus name — the unique name (:1.895) or the well-known name you registered (org.kde.StatusNotifierItem-1234-1); the full registered service string also works. "" returns the most recent activation of any item.
• All coordinates are global compositor logical coordinates (the same space XWayland uses; here DP-1 is at x=0 and HDMI-A-1 at x=2133, each 2133×1200 logical). icon_* is the tray icon's rectangle, or the ^ button's rectangle when the item was clicked inside the hidden-icons box. out_* is the monitor, bar_height is in logical px and edge is "bottom" or "top". timestamp_ms is Unix time in ms.
• winbar records the values and emits Activated for every left, middle and right click before it calls Activate / SecondaryActivate / ContextMenu on your item, so querying from inside your Activate handler returns the new values.
• Activate(x, y), SecondaryActivate(x, y) and ContextMenu(x, y) receive the icon's top-centre point (icon_x + icon_w/2, icon_y).

Example: busctl --user call dev.winbar.Tray /dev/winbar/Tray dev.winbar.Tray1 GetLastActivation s ""
or winbar ctl tray-last.

For app developers: window list, focus, capture

winbar also exposes the toplevel windows it tracks. On the session bus it owns
dev.winbar.Windows, object /dev/winbar/Windows, interface
dev.winbar.Windows1:

List() -> a(ssssbbbiiiib)     # one struct per toplevel:
                              #   s id, s app_id, s title, s output,
                              #   b focused, b minimized, b fullscreen,
                              #   i x, i y, i w, i h, b on_active_workspace
GetFocused() -> s id          # "" if no toplevel is activated
Activate(s id) -> b
Minimize(s id) -> b
Close(s id) -> b
CaptureWindow(s id) -> s png_path

signal FocusChanged(s id)     # "" when nothing is focused
signal WindowsChanged()

• ids are winbar's stable per-toplevel ids (a u64 as a decimal string, e.g. "12"), the same id values winbar ctl dump prints under windows. An id is valid for the lifetime of the window and never reused while winbar runs; ids restart from 1 when winbar restarts.
• List returns windows on all workspaces (and minimized ones), in **creation order** (ascending id; windows that existed when winbar started come first in the order the compositor announced them). on_active_workspace tells whether the window is on a currently visible workspace (use it to skip windows that aren't on screen).
• focused is the compositor's activated state. output is the output holding the largest part of the window ("" if none).
• Geometry x, y, w, h is in global compositor logical coordinates (the same space as dev.winbar.Tray1), converted from COSMIC's output-relative zcosmic_toplevel_handle_v1.geometry using the output's logical position. It is -1, -1, 0, 0 when unknown. It is the window's frame as COSMIC places it, including COSMIC's server-side title bar when the window has one.
• Activate / Minimize / Close return false for an unknown id or when the compositor doesn't offer that zcosmic_toplevel_manager_v1 capability; true means the request was sent (the compositor may still ignore it).
• CaptureWindow captures the window at full resolution (ext-image-copy-capture into shared memory), writes $XDG_RUNTIME_DIR/winbar-capture-<id>-<n>.png (mode 0600) and returns the path. The caller owns the file and must delete it. The image is the client surface only (no server-side title bar), in the buffer size the compositor offers, so it can differ from w × h. Minimized windows can be captured. It fails with a D-Bus error (InvalidArgs for an unknown id, Failed otherwise, e.g. after a 2 s timeout).
• Signals are coalesced: after a change winbar waits ~15 ms (so the deactivate/activate pair of a focus switch arrives together), and emits at most once per 100 ms. WindowsChanged covers any add/remove/title/state/geometry/workspace change; when the activated window changed, FocusChanged is sent first. Re-read List / GetFocused after a signal.

Examples:

busctl --user call dev.winbar.Windows /dev/winbar/Windows dev.winbar.Windows1 List
busctl --user call dev.winbar.Windows /dev/winbar/Windows dev.winbar.Windows1 GetFocused
busctl --user call dev.winbar.Windows /dev/winbar/Windows dev.winbar.Windows1 Activate s 12
busctl --user call dev.winbar.Windows /dev/winbar/Windows dev.winbar.Windows1 CaptureWindow s 12
dbus-monitor --session "type='signal',interface='dev.winbar.Windows1'"   # watch the signals

Rendering

winbar renders in software only (libcosmic's tiny-skia renderer through softbuffer), so
every surface uses wl_shm buffers, never dmabuf. Window thumbnails are captured into
wl_shm buffers as well (about 1 fps, only while a thumbnail popup is open). You can
check this with WAYLAND_DEBUG=1 winbar --edge top 2>&1 | grep -E 'linux_buffer_params|create_buffer'.
The only dmabuf-related call is iced binding the zwp_linux_dmabuf_v1 global, which it
never uses to create buffers.

Architecture

src/lib.rs        library (unit tested)
  clock.rs        en-AU time/date formatting, month grid, minute alignment
  config.rs       config.toml load/save, COSMIC favourites import
  desktop.rs      .desktop loading, app_id -> desktop entry matching, Exec parsing
  grouping.rs     window grouping/ordering and click behaviour
  layout.rs       deterministic bar geometry (popup anchoring)
  sni.rs          SNI service parsing, ARGB pixmaps, item props, dbusmenu layout parsing
  watcher.rs      org.kde.StatusNotifierWatcher (bookkeeping + zbus interface)
  tray.rs         SNI host / watcher fail-over service (tokio)
  tray_api.rs     dev.winbar.Tray1 (tray icon activation geometry for apps)
  windows_api.rs  dev.winbar.Windows1 (window list, actions, capture, change signals)
  start.rs        Start menu: app filtering/dedupe, search ranking, categories, icon lookup
  timefmt.rs      clock/calendar text from COSMIC's time settings (ICU4X, jiff strtime)
  ticker.rs       realtime-aligned ticks (timerfd, CANCEL_ON_SET), timezone/locale/resume events
  quick.rs        NetworkManager, BlueZ, pactl, backlight, UPower (event driven)
  wayland.rs      separate Wayland connection thread: cosmic toplevel info/manager,
                  ext-workspace, ext-image-copy-capture thumbnails, xdg-activation
  thumbs.rs       thumbnail scaling
  launch.rs       process spawning (transient systemd scopes), argv building
  ipc.rs          debug D-Bus interface + `winbar ctl`
  logging.rs      capped rotating log file
  test_item.rs    test StatusNotifierItem + dbusmenu
src/ui/           libcosmic application (bar + popup views, styles)
tests/watcher_bus.rs  private dbus-daemon integration test (watcher mode, fail-over)
tests/windows_bus.rs  private dbus-daemon integration test (dev.winbar.Windows1)

Known limitations

• Tray icons are shown on every monitor's bar (Windows shows them on the primary only).
• iced_wgpu is still compiled in, because libcosmic's wayland feature depends on it, but it is never used (the renderer type is iced_tiny_skia::Renderer).
• Window thumbnails refresh about once per second (shared-memory capture, downscaled on the CPU); no dmabuf path.
• Keyboard focus: the bar never takes keyboard focus (so clicking it doesn't steal focus from the app you want to minimise); Esc works in flyouts that receive keyboard focus through their popup grab.
• Drag-and-drop reordering of pinned apps is not implemented (edit pinned instead).
• If more apps are open than fit between the centre and the tray, the extra (non-running pinned first) buttons are hidden.
• No notification centre (COSMIC's notifications daemon keeps working independently).

License

GPL-3.0-only (the design follows COSMIC's GPL-3.0 applets).