reterminal-dm4/emmc-provisioning/cloud-init/TASKBAR-THEME.md

Taskbar (wf-panel-pi) editing and custom theme

You can edit the taskbar to your liking and create a custom theme. The panel is wf-panel-pi (GTK3); configuration is in ~/.config/wf-panel-pi/wf-panel-pi.ini and optional custom CSS via the css_path option.

---

1. Editing the taskbar (INI config)

Config file: ~/.config/wf-panel-pi/wf-panel-pi.ini (user pi). If the file is empty or missing, the panel uses built-in defaults. Options (from panel-pi.xml):

Option	Type	Default	Description
css_path	string	(empty)	Path to a custom CSS file for the panel (GTK CSS).
widgets_left	string	smenu spacing0 spacing4 launchers spacing8 window-list	Widget names for the left section (space-separated).
widgets_center	string	none	Widgets in the center.
widgets_right	string	tray power ejecter updater ... clock ... batt squeek	Widgets on the right.
icon_size	int	32	Icon size in pixels.
minimal_height	int	24	Panel height (min).
autohide	bool	false	Hide panel until cursor touches edge.
autohide_duration	int	300	Animation duration (ms) when showing/hiding.
position	string	top	top or bottom.
background_color	string	#EDECEBFF	Panel background (ARGB hex).
layer	string	bottom	top, bottom, overlay, background.
monitor	string	0	Monitor index.
edge_offset	int	20	Pixels from edge to trigger autohide.
gestures_touch_only	bool	false	Restrict gestures to touch.

Widget names (for widgets_left / _center / _right)

• Left: smenu (start menu), spacing0 … spacing8 (spacers), launchers, window-list
• Right: tray, power, ejecter, updater, connect, bluetooth, netman, volumepulse, clock, batt, squeek, plus spacing2 etc.

Example: minimal left (only menu + window list), right (clock + tray only):

[panel]
widgets_left = smenu spacing4 window-list
widgets_center = none
widgets_right = spacing2 clock spacing2 tray
icon_size = 28
minimal_height = 28
position = bottom
background_color = #2D2D2DFF

Save as ~/.config/wf-panel-pi/wf-panel-pi.ini for user pi, then restart the panel: pkill wf-panel-pi (session will respawn it, or log out/in).

---

2. Custom theme (CSS + INI)

The panel supports GTK 3 CSS via css_path. You can:

1. Set css_path in wf-panel-pi.ini to a full path to your .css file (e.g. ~/.config/wf-panel-pi/panel-theme.css).
2. Use GTK CSS to style the panel window and its children (colors, borders, font, padding, etc.).

INI

[panel]
css_path = /home/pi/.config/wf-panel-pi/panel-theme.css
background_color = #1E1E1EFF
icon_size = 28
minimal_height = 28

Example CSS (panel-theme.css)

GTK panel often uses a single top-level window; you can target it and inner boxes. Example (dark, rounded, with padding):

/* Custom taskbar theme – dark, subtle border */
window {
  background-color: transparent;
}

/* Main panel box */
window box {
  background-color: rgba(30, 30, 30, 0.95);
  border-radius: 12px;
  margin: 4px;
  padding: 2px 8px;
  border: 1px solid rgba(255, 255, 255, 0.08);
  box-shadow: 0 2px 12px rgba(0, 0, 0, 0.4);
}

/* Buttons / plugin containers */
button,
button:hover,
button:active {
  background: transparent;
  border: none;
  border-radius: 6px;
  padding: 4px;
  color: #e0e0e0;
}

button:hover {
  background: rgba(255, 255, 255, 0.08);
}

/* Labels (e.g. clock) */
label {
  color: #e0e0e0;
  font-size: 11pt;
}

Paths: use an absolute path in css_path (e.g. /home/pi/.config/wf-panel-pi/panel-theme.css). Expand ~ yourself when writing the INI (the panel may not expand it).

---

3. Deploying a custom theme via first-boot

To apply a custom taskbar theme on every provisioned device:

1. On the file server (e.g. first-boot folder): add:

   • wf-panel-pi.ini – INI with your [panel] options and css_path pointing to the CSS file path on the device.
   • panel-theme.css – your GTK CSS.

2. In first-boot (or a one-shot script): for user pi:

   • Create ~/.config/wf-panel-pi/ if needed.
   • Copy or download wf-panel-pi.ini to ~/.config/wf-panel-pi/wf-panel-pi.ini.
   • Copy or download panel-theme.css to e.g. ~/.config/wf-panel-pi/panel-theme.css.
   • In the INI, set css_path = /home/pi/.config/wf-panel-pi/panel-theme.css (or use $PI_HOME in the script).
   • chown -R pi:pi ~/.config/wf-panel-pi.

3. Restart panel after first login (or rely on next login): pkill wf-panel-pi (optional in script; session often restarts it).

Example first-boot snippet (run as root, after $PI_HOME is set):

PANEL_CONF="$PI_HOME/.config/wf-panel-pi"
mkdir -p "$PANEL_CONF"
curl -fsSL "${FILE_SERVER}/wf-panel-pi.ini" -o "$PANEL_CONF/wf-panel-pi.ini"
curl -fsSL "${FILE_SERVER}/panel-theme.css" -o "$PANEL_CONF/panel-theme.css"
sed -i "s|/home/pi|$PI_HOME|g" "$PANEL_CONF/wf-panel-pi.ini"
chown -R "$PI_USER:$PI_USER" "$PANEL_CONF"

Ensure the INI uses the same path as where you save the CSS (e.g. css_path = /home/pi/.config/wf-panel-pi/panel-theme.css or $PI_HOME/... if you substitute in the script).

Example theme files in this repo: config-files/wf-panel-pi.ini and config-files/panel-theme.css (dark, rounded panel). Host them on the file server and deploy with the snippet above.

---

4. Summary

Goal	Where	How
Change layout (widgets, position, size)	~/.config/wf-panel-pi/wf-panel-pi.ini	Edit [panel] options.
Change colors / style	Same INI + custom CSS	Set css_path and write GTK CSS.
Custom theme on all devices	File server + first-boot	Deploy wf-panel-pi.ini and panel-theme.css and copy to ~/.config/wf-panel-pi/ for pi.

After any change, restart the panel (pkill wf-panel-pi) or log out and back in so the new theme is applied.