Taskbar (technical)

Turns COSMIC’s “Minimized Windows” panel applet into a Windows-style taskbar for the current workspace. Built from System76’s source with the patches in taskbar/patches/, installed per user. User overview: taskbar/README.md.

Upstream, the minimize applet lists only minimized windows, from every workspace, and the App List groups windows by app. The patches change the minimize applet (binary cosmic-applet-minimize-ws) and the App List (binary cosmic-app-list-ws). Internal names (binaries, config folder, cache and state folders, systemd units) still say minimize-ws.

What it shows

What it does

How it works

Installed files

taskbar/build.sh (run by ./install.sh taskbar) installs:

Path What
~/.local/bin/cosmic-applet-minimize-ws The patched taskbar applet
~/.local/bin/cosmic-app-list-ws The patched App List
~/.local/share/applications/com.system76.CosmicAppletMinimize.desktop Copy of the system entry with Exec= pointing at the patched applet. A user entry with the same id overrides the system one, so the panel config is unchanged and no system files are touched.
~/.local/share/applications/com.system76.CosmicAppList.desktop Same override for the App List
~/.local/state/minimize-ws/built-commit Upstream commit the applet was built from
~/.cache/minimize-ws/cosmic-applets Upstream source clone

The installer also sets up the daily update check:

Path What
~/.local/lib/minimize-ws Link to taskbar/ in the repo checkout
~/.config/systemd/user/minimize-ws-check.timer 10 min after the session starts, then daily
~/.config/systemd/user/minimize-ws-check.service Runs taskbar/check.sh

./install.sh --uninstall taskbar removes these. The settings files in ~/.config/minimize-ws/ are kept.

Workspace names

COSMIC names pinned workspaces from name: Some("…") in ~/.config/cosmic/com.system76.CosmicComp/v1/pinned_workspaces (cosmic-comp, no settings UI yet). The panel’s workspaces applet, the overview and this taskbar show the name. The compositor reads the file at login only, and rewrites it when a workspace is pinned, unpinned or moved: edit it, then log out straight away. The file is tied to the monitor it was written for. Example names: Mail, Web, Code, Music.

Workspace pins

The pin entry in the window menu edits Workspace Keeper’s pins file, $XDG_CONFIG_HOME/ws-keeper/pins (default ~/.config/ws-keeper/pins): one rule per line, app_id = Workspace Name, split at the first =, # comments, the last rule for an app wins. A pin from the menu replaces or removes that app’s rules, keeps every other line and comment, adds a new rule at the end, and writes the file through a temporary file and a rename. A write error is logged with the path. The name is the workspace’s name, or its number for an unnamed workspace; numbers move when COSMIC removes an empty workspace, so pin named workspaces (see Workspace names). Example:

# apps that always open on one workspace
teams-for-linux = Work
org.example.Mail = Mail

On a top or bottom panel, items of pinned apps carry a small pin (the theme’s pin-symbolic, 12 px, in the item’s text colour) on the top right of their icon. It shows only with Workspace Keeper installed and the icon in the theme. The taskbar reads the file every 2 s when it changed, and at once after its own menu wrote it, so hand edits show too.

Workspace Keeper does the moving: a pinned app’s new windows go to its workspace, and starting a pinned app from another workspace takes you there (see Workspace Keeper).

Code: pins.rs (parse and write, unit tests) and the menu and item code in lib.rs.

Configuration

All files are optional, live in ~/.config/minimize-ws/, and are re-read on change (inotify on the folder; a 2 s poll if inotify fails).

ignore: app ids never shown, one per line, # comments. Both applets read it. Example:

# keep the music player out of the taskbar
org.example.MusicPlayer

sizes: item widths in px, key = value, # comments. Missing keys keep the defaults; a bad line is logged and skipped:

item_width = 220             # widest an item gets
item_min_width = 120         # narrowest before the overflow popup
overflow_item_width = 300
fit_to_title = true          # false: every item item_width wide
fixed_width_apps = firefox   # these apps always item_width (space or comma separated)

fixed_width_apps ignores case and a .desktop suffix; several lines add up.

colors: colours of the focused window item, key = value. A comment is a whole line or follows a value after a space. Missing keys keep the defaults; an invalid value is logged with its key and that key keeps its default:

focused_bg = system       # system: the theme's accent; or #RRGGBB
focused_darken = 0.3      # 0 to 1: how far focused_bg is mixed toward black (0 = unchanged)
focused_text = system     # system: the theme's accent button text colour; or #RRGGBB

detail: second-line rules turned off per app, one app per line, <app-id> -launcher,-media,-count,-split, # comments. See What it shows.

options: parts of the taskbar turned on or off, key = value, # comments. Missing keys keep the defaults; a bad line is logged with its key and skipped:

second_line = true       # false: title on one line, a tab count as "(n) " before it
hover_preview = true     # false: no preview popup on hover, also in the overflow popup

hover_preview = false also stops every window capture for the preview: no live capture, and no thumbnails on a top or bottom panel (a side panel still captures them: they are its items). Click, middle click and the window menu are unchanged. Turned back on, a window has a thumbnail again after its next capture (minimized, or losing focus).

Commands

Build prerequisites (the installer offers to install them):

sudo apt install libxkbcommon-dev libfontconfig-dev libfreetype-dev libwayland-dev pkg-config
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal --no-modify-path
./install.sh taskbar                 build + install + reload the two applets (the panel keeps running)
./install.sh --uninstall taskbar     back to the system applets
taskbar/build.sh                     the build-and-install step alone
taskbar/build.sh --uninstall         the uninstall step alone
taskbar/check.sh --print             the daily check, printed instead of notified

Update check

check.sh (daily timer) sends a desktop notification when:

  1. apt updated cosmic-applets past the commit the applet was built from. It says whether the patch series still applies to the new version.
  2. System76 changed cosmic-applet-minimize or cosmic-app-list on upstream master since the base commit. Each new upstream change is announced once (~/.local/state/minimize-ws/seen-upstream).
  3. One of the two patched applets panicked or hit a Wayland protocol error since the last check (read from the user journal; the first run looks back one day, ~/.local/state/minimize-ws/errors-since holds the last check).
  4. apt updated cosmic-term, cosmic-files or cosmic-applets past the commit the patched terminal, file manager or tray applet was built from (only for add-ons that are installed).

Limits