desktop

README

desktop

A native, pure-Go (CGO=0) desktop-shell demo that composes the whole go-freedesktop + go-widgets stack into one runnable app. Each freedesktop library does its real job against a real Linux filesystem, and the UI is drawn entirely with go-widgets widgets and box layouts.

What each library drives

Feature	Library	What it does here
Dock + launcher	go-freedesktop/desktopentry	Scan() → the app index; ExpandExec → launch argv
Icons	go-freedesktop/icontheme	FindIcon → PNG/JPEG rasterized into go-widgets Image
Application menu	go-freedesktop/menu	Load() → a categorized tree rendered as a go-widgets MenuBar/Menu
"Open with"	go-freedesktop/mime + mimeapps	TypeByNameAndContent + Candidates/DefaultApp
File grid + thumbnails	toolkit/virtual VirtualGrid + go-thumbnail	virtualized gengrid over a directory, thumbnail cache keys per cell
Notifications	go-freedesktop/notifications	a live org.freedesktop.Notifications daemon → go-widgets Toasts

Architecture

Composition/model logic is separated from raw rendering:

• shell/ — pure, side-effect-light model logic with 100% statement coverage (including error branches): the launchable-app index, MIME "open with" resolution, the categorized menu model, the directory listing model and the thumbnail cache-key policy. No rendering surface, so every branch is unit-coverable against temp-dir fixtures.
• render/ — turns those models into a go-widgets widget tree. The shell is a Border layout (menubar north, dock south, launcher west, file grid center) plus a floating Toast stack. State flows through go-widgets/mvvm (Observable search query → ObservableList results → the launcher). Scene.Widget() wraps the whole thing — root plus the toast overlay — as one backend-agnostic toolkit.Widget a windowing backend can drive.
• cmd/desktop/ — the native binary: scans the filesystem, composes the scene and either opens a real window (the default) or renders it to a PNG (-capture).

go-widgets is a pure pixel-blitting toolkit. With no flags the shell opens a real window on the running display server via go-widgets/window — which auto-selects the pure-Go Wayland backend when $WAYLAND_DISPLAY is set, else the pure-Go X11 backend — and drives the widget tree through its Run loop (resize → relayout, window close → quit). Notification toasts render as a floating overlay on top of the live shell. On a headless host, or with -capture, the shell renders into an offscreen framebuffer and -capture writes it to a PNG — the headless "screenshot" path.

Below is the live X11 window (under Xvfb) showing the dock, launcher, file grid and a notification Toast — the live shell (windowed) CI lane captures and pixel-asserts exactly this:

Usage

go run ./cmd/desktop                                        # open a real window (X11/Wayland)
go run ./cmd/desktop -dir ~/Pictures                        # windowed, file grid on a directory
go run ./cmd/desktop -dir ~/Pictures -capture shell.png     # headless: render to PNG
go run ./cmd/desktop -query fire                            # seed launcher filter
go run ./cmd/desktop -launch org.mozilla.firefox            # expand Exec + launch

# Notifications need a session bus (Linux); the toast shows in the window:
dbus-run-session -- go run ./cmd/desktop -notify "Build|Finished"
dbus-run-session -- go run ./cmd/desktop -notify "Build|Finished" -capture toast.png

License

BSD-3-Clause. Copyright (c) 2026 the go-widgets/desktop authors.