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):

```ini
[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

```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):

```css
/* 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):

```bash
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.