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

Side panel

Taskbar on a left panel: square items with pin and count badges, and the hover card

Less tested than the top and bottom panel: we do not use a side panel every day, so bugs there are less likely to be noticed by us. Please report what you find.

On a left or right panel (patch 0047) each window is a square item with its app icon, as large as the panel’s icons. The focused window gets the same solid background as on a top or bottom panel. Two badges sit on the item:

Hovering an item opens a card beside the panel (right of a left panel, left of a right panel), centred on the item: the app icon, the title and the second line in the item styles above the live preview. It moves from item to item like the preview popup on a top or bottom panel, and a click on the item raises the window. With hover_preview = false the card shows only its header and no window is captured; with second_line = false the header has only the title (the badge keeps the count).

Windows that do not fit go to the overflow popup as the same square items, with the card beside them. Tab files, launcher entries, media players and the pins file are read on side panels too.

Code: side_item.rs (badge choice, square layout, unit tests), the Header card in preview.rs, and side_item() in lib.rs.

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

Always open on “Work” in the window menu, and the pin on a pinned app's icon

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; on a side panel, on the top right of the square item. 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 (side panel: the card keeps its header)

hover_preview = false also stops every window capture for the preview: no live capture, and no thumbnails, on any panel. 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. The taskbar patches moved to a new base (taskbar/patches/BASE, after a git pull) but the applet was not rebuilt yet. A newer cosmic-applets from apt alone is no reason to notify.
  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. The same for the patched terminal, file manager, Text Editor and tray applet (only for those that are installed).

Limits