# Click Tween voor KDE Plasma 6.7 / 6.8 (Wayland)

De muisaanwijzer krimpt naar 80% in 150 ms wanneer links of rechts wordt
ingedrukt. Hij blijft klein tijdens vasthouden en slepen en groeit in 720 ms
terug na loslaten. Bij beide knoppen tegelijk blijft hij klein totdat beide
los zijn. De middelste knop verandert de animatie niet.

Het effect schaalt KWin's bestaande cursor rond zijn hotspot. Cursorvorm,
zichtbaarheid en positie blijven door KWin beheerd. Het onderschept geen
klikken. Bij uitschakelen en schermvergrendeling wordt de schaal hersteld.

## Instellingen

Open Systeeminstellingen → Bureaubladeffecten → Click Tween en klik op de
instellingenknop. Meld na een plugin-update één keer af en opnieuw aan.
KWin/Qt houdt native plugincode in het geheugen; uit-/aanvinken of alleen
Systeeminstellingen heropenen laadt een vervangen bibliotheek niet opnieuw.
Daarna werken gewone instellingenwijzigingen direct via Toepassen, zonder afmelden.

- Klik-tween-tijd: 0–5000 ms, standaard 150 ms.
- Release-tween-tijd: 0–5000 ms, standaard 720 ms.
- Afzonderlijke easing: standaard easeOutBack voor klik en easeOutElastic voor release.
- 31 keuzes: Linear plus In, Out en InOut voor Sine, Quad, Cubic, Quart,
  Quint, Expo, Circ, Back, Elastic en Bounce, zoals op https://easings.net/.
  De implementatie gebruikt Qt QEasingCurve; curveparameters zijn Qt-standaardwaarden.

0 ms betekent direct. Back en Elastic kunnen voorbij de eindgrootte veren.
Toepassen bewaart de instellingen in `~/.config/kwinrc`, groep
`Effect-clicktween`, en werkt direct voor de volgende animatie.
Standaardinstellingen herstelt de oorspronkelijke tijden en curves.
De klik wordt niet vertraagd: de animatie begint bij het indrukken.

## Installeren

Op Arch (of een Arch-afgeleide) met KWin 6.7.x of 6.8.x:

```bash
git clone https://git.timfalken.com/timfa/click-tween.git
cd click-tween
./install.sh
```

Het script kijkt eerst of er een [release](https://git.timfalken.com/timfa/click-tween/-/releases)
is voor precies jouw KWin-versie. Zo ja, dan downloadt het die build en controleert het de
sha256-checksums én of de release tegen dezelfde Arch-pakketten `kwin` en `qt6-base` is gebouwd
als die bij jou geïnstalleerd zijn. Klopt iets niet, of is er geen release, dan bouwt het lokaal.
Altijd zelf bouwen: `./install.sh --build`.

Daarna vraagt het sudo voor de plugin in de systeemmap en schakelt hem voor de huidige gebruiker
direct en blijvend in, ook bij een herinstallatie. Bestaande animatie-instellingen blijven behouden;
zonder opgeslagen instellingen gelden de bovenstaande standaardwaarden. Bij een update blijft af- en
aanmelden nodig om de nieuwe plugincode te laden. Start het script als je eigen gebruiker, niet met
`sudo ./install.sh`.

### Afhankelijkheden

Bouwen: `gcc`, `pkgconf`, `kwin`, `qt6-base`, `qt6-declarative`, `kcoreaddons`, `kconfig`,
`kcmutils`, `kwindowsystem`, `wayland`, `libepoxy`, `libdrm` en `dbus`:

```bash
sudo pacman -S --needed gcc pkgconf kwin qt6-base qt6-declarative kcoreaddons kconfig kcmutils kwindowsystem wayland libepoxy libdrm dbus
```

De meeste zijn al onderdeel van een Plasma-installatie. Installeren vraagt daarnaast `sudo`,
`kwriteconfig6` en `qdbus6`; downloaden een release `curl` en `git`.

### Alleen bouwen

```bash
./install.sh --build-only
```

Bouwt in `build/` en controleert de pluginfactory en de instellingenmodule (31 curves), zonder iets
te installeren of instellingen te wijzigen. Er is geen CMake: `install.sh` roept `moc` en `g++` direct aan.

### Na een kwin-update

Een KWin-effect gebruikt de interne KWin-API en moet voor elke kwin-versie opnieuw gebouwd worden.
Na `pacman -Syu` met een nieuwe kwin: `./install.sh` opnieuw draaien en daarna af- en aanmelden.

Automatisch kan ook, met de pacman-hook in `hook/`:

```bash
hook/setup.sh
```

Dat installeert `/usr/local/bin/rebuild-clicktween` (met het pad van deze map en jouw gebruikersnaam
ingevuld) en `/etc/pacman.d/hooks/kwin-clicktween.hook`. Na elke installatie of upgrade van `kwin`
bouwt pacman het effect dan opnieuw en vervangt het de plugin. Mislukt het bouwen, dan blijft het oude
effect staan en faalt pacman niet. Log: `/var/log/clicktween-rebuild.log`.

## Uitschakelen of verwijderen

Uitschakelen kan via Systeeminstellingen → Bureaubladeffecten → Click Tween,
of via:

```bash
kwriteconfig6 --file kwinrc --group Plugins --key kwin_effect_clicktweenEnabled false
qdbus6 org.kde.KWin /Effects org.kde.kwin.Effects.unloadEffect kwin_effect_clicktween
```

Volledig verwijderen:

```bash
./install.sh --uninstall
```

## Compatibiliteit en controle

Dit is een experimentele native plugin voor de interne KWin 6.7/6.8 API.
Na een KWin-update voer je het installatiescript opnieuw uit. Andere
KWin-minorversies worden geweigerd totdat de code daarvoor is gecontroleerd.
De plugin draait in KWin zelf; bewaar open werk voordat je de eerste keer
installeert. Gelijktijdige cursor-effecten zoals Shake Cursor of Zoom kunnen
hun eigen cursor tekenen en moeten apart worden gecontroleerd.

Handmatig controleren na installatie:

- Links en rechts: korte klik, vasthouden, slepen en snel herhaald klikken.
- Beide knoppen indrukken; één loslaten mag de cursor niet herstellen.
- Test pijl, tekstcursor en handje, ook in XWayland-apps.
- Controleer op meerdere schermen met verschillende schaalfactoren.
- Uitschakelen tijdens vasthouden moet de oorspronkelijke grootte herstellen.

De buildcontrole controleert compileren, linken, metadata en het laden van
de pluginfactory tegen de lokale KWin-versie. Visueel gedrag moet nog in een
actieve sessie worden getest.

## Pipeline en releases

`blue-ci-cd.yml` draait op BlueGit:

- **Merge request, push naar master, handmatige run:** `build:kwin` bouwt in een `archlinux:latest`-image na
  `pacman -Syu` tegen de nieuwste kwin in de Arch-repo's (`scripts/ci-build.sh`). Faalt die job, dan werkt
  het effect waarschijnlijk niet op de nieuwste kwin. Een nieuwe KWin-minorversie (bv. 6.9) faalt bewust
  op de versiecontrole in `install.sh` tot de code daarvoor is nagekeken.
  Wil je op elk moment controleren of master nog bouwt: start een pipeline op master via de knop.
- **Release (handmatig op master):** de job `release` publiceert via de BlueGit-release-API een release met
  `clicktween-x86_64.tar.gz` (beide `.so`-bestanden, `build-info.txt`, `SHA256SUMS`), het bijbehorende
  `.sha256`-bestand en `build-info.txt`.

### Tagschema

De tag is de KWin-versie waarvoor gebouwd is:

| Tag | Betekenis |
| --- | --- |
| `6.8.1` | eerste release gebouwd tegen KWin 6.8.1 |
| `6.8.1-2`, `6.8.1-3` | fix of herbouw voor dezelfde KWin 6.8.1 (bv. een codefix of een Arch-rebuild van kwin/qt) |

De `release`-job kiest de tag zelf: de KWin-versie waartegen hij net gebouwd heeft, met `-N` erachter als die
tag al bestaat. Met de variabele `RELEASE_TAG` kun je een tag opgeven; die wordt gecontroleerd. Een gepushte
tag start `verify:tag`, die faalt met een duidelijke melding als de tag niet bij de kwin-versie in Arch past.
Arch heeft altijd maar één (de nieuwste) kwin; een release voor een oudere kwin kan dus niet meer gebouwd
worden. In `build-info.txt` staan ook de exacte Arch-pakketversies van `kwin` en `qt6-base`; `install.sh`
gebruikt een release alleen als die overeenkomen met je systeem.

## Licentie

GPL-2.0-or-later, zie `COPYING`.
