waydock/doc/usage.md

# waydock — användning

## Starta

```bash
waydock                      # normal start
waydock --log debug          # pratigare logg till stderr
waydock --log-file ~/.cache/waydock.log
waydock --config /annan/väg.json
```

Vid första start skapas `~/.config/waydock/config.json` med defaults.
Alla ändringar i filen slår igenom **live** — ingen omstart behövs.

## Dagligt bruk

- **Vänsterklick** på ikon: fokusera appen; klick igen minimerar
  (Plasma-beteende, konfigurerbart)
- **Skroll** på ikon: växla mellan appens fönster
- **Mittklick**: starta ny instans (konfigurerbart)
- **Högerklick** på ikon: kontextmeny (innehållet väljs i configen) —
  minimera, maximera, flytta till skärm ▸, pinna/släpp, stäng
- **Högerklick på tom yta**: Inställningar…, Ladda om config, Avsluta
- **Visa skrivbord-knappen** minimerar allt; klick igen återställer
- **Översikt-knappen** togglar Wayfires scale-vy (kräver ipc-pluginen)
- Grupp-ikoner får en siffra och accentprickar. Fönsterlistan öppnas
  vid klick eller hover (`behavior.group_popup`); hovra en rad i listan
  för peek (bara det fönstret syns, andra tonas ner — kräver Wayfires
  alpha-plugin) eller fokus, enligt `behavior.list_hover`
- Marginalillustrationen i Inställningar → Layout visar vad A/B/C-måtten
  styr för aktuell position

## Settings-GUI

Högerklick på tom yta → **Inställningar…** Ändringar skrivs direkt till
JSON-filen och appliceras live. GUI:t och handredigering kan blandas fritt.

Överst finns **skärmväljaren** med en klickbar förhandsgranskning av
skärmarna och deras barer. "Alla skärmar" (standard) redigerar den
globala configen; välj en skärm för att ge just den egna inställningar —
bara fälten du ändrar sparas som override (`outputs` i JSON:en), resten
följer globala. `*` i förhandsgranskningen = skärmen har egna
inställningar; "Återställ skärmen till globalt" tar bort dem.

## Configreferens (`config.json`)

```jsonc
{
  "position": "bottom",        // bottom | top | left | right
  "alignment": "center",       // center | start | end — var längs kanten ön ligger
  "expand": false,             // true = täck hela kanten (panelen fyller bredden/höjden)
  "margin": 8,                 // A: px från kanten baren ligger mot (minus = utanför)
  "margin_start": 0,           // B: marginal i början av kanten (vänster/topp)
  "margin_end": 0,             // C: marginal i slutet av kanten (höger/botten)
                               // skuggutrymme läggs aldrig på förankrade sidor,
                               // så 0 = verkligen kant i kant
  "layer": "top",              // top | overlay | bottom (always-on-top = overlay)
  "avoid_windows": false,      // true = reservera plats (exclusive zone)

  "appearance": {
    "background": "#222222",   // panelfärg
    "opacity": 0.72,           // paneltransparens 0–1
    "corner_radius": 14,
    "border": { "color": "#ffffff", "opacity": 0.08, "width": 1 },
    "shadow": { "enabled": true, "blur": 18, "opacity": 0.45 },
    "accent": "#c9545d",       // indikatorer, hover, urgency
    "icon_size": 36,
    "icon_spacing": 6,         // px mellan ikoner
    "padding": 6,              // px innanför panelkanten
    "hover_zoom": true,        // liten zoom vid hover
    "animations": true,        // false stänger alla animationer
    "indicator": { "style": "dot", "max": 3 }   // dot | line | none
  },

  "behavior": {
    "click": "focus_or_minimize",  // focus_or_minimize | focus | cycle
    "middle_click": "launch_new",  // launch_new | close | none
    "scroll": "cycle_windows",     // cycle_windows | none
    "group_apps": true,
    "tooltips": true,
    "urgent_pulse": true,
    "scroll_stopped": "none",      // none | launch — skroll på app som inte är igång
    "group_popup": "click",        // click | hover — hur fönsterlistan öppnas
    "list_hover": "peek"           // peek (visa bara det fönstret, tona ner andra)
                                   // | focus (fokusera vid hover) | none
  },

  "context_menu": ["minimize", "maximize", "move_to_output",
                   "pin", "close"],   // ordning & urval styr menyn

  "pins": ["firefox", "org.kde.konsole", "org.kde.dolphin"],
  "special_buttons": { "show_desktop": true, "overview": true },

  "outputs": {                 // per-skärm-överridar (nyckel = connector).
    // VILKET configfält som helst kan läggas här och gäller då bara den
    // skärmen (deep-merge över globala). Extranycklar: "enabled" och
    // "only_this_output" (visa bara fönster på den här skärmen).
    "DP-1": {
      "enabled": true,
      "only_this_output": true,
      "position": "left",
      "pins": ["steam", "discord"],
      "appearance": { "accent": "#5fb878" }
    }
  },

  "autohide": {
    "enabled": false,
    "mode": "dodge",           // dodge (göm vid överlapp, kräver wayfire-ipc)
                               // | always (göm alltid, hot edge väcker)
    "hide_delay_ms": 500,
    "reveal_px": 2,            // sensorbredd vid skärmkanten
    "animation_ms": 200
  },

  "hotspots": {                // action: {"exec": "kommando"} eller {"ipc": "scale/toggle"}
    "dwell_ms": 300,
    "corners": { "top_left": null, "top_right": null,
                 "bottom_left": null, "bottom_right": null },
    "edges":   { "top": null, "bottom": null, "left": null, "right": null }
  },

  "log": { "level": "info", "file": null }
}
```

## Tips

- Wayfires **blur-plugin** kan ge frostat glas bakom panelen —
  transparensen i `appearance.opacity` räcker för blur-effekten.
- Trasig JSON? waydock loggar felet och kör vidare på defaults utan att
  röra din fil — rätta filen så laddas den om automatiskt.
- `pins` använder `.desktop`-id (filnamnet utan `.desktop`,
  t.ex. `org.kde.konsole`). Hitta rätt id:
  `ls /usr/share/applications | grep -i <app>`.