# Bitcoin Price (Plasma 5 widget)

KDE Plasma 5 widget that shows the bitcoin price in EUR, fetched from the
[CoinGecko API](https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=eur).

## Display styles

Three display styles, configurable in the settings dialog:

| Style | Description |
|---|---|
| *Plain text* | Trend-colored text (green/red/grey) |
| *Split-flap board* | Airport board: white digit flaps, white € sign and a trend arrow in the default font. On a price change all flaps first reset to 0 (swept over ~2 s), then take their new values — the whole cycle spreads over the configured cascade time |
| *Nixie tubes* | Retro amber glowing digits in glass tubes with configurable random flicker, white € sign and a trend arrow in the default font |

In the split-flap and nixie styles a trend arrow sits right of the € sign:
green ▲ when the price went up, red ▼ when it went down. When the price is
unchanged the last arrow stays; on the very first reading (and on API errors)
no arrow is shown. Display style changes apply immediately, without
restarting the shell.

| Situation | Plain text color | Arrow in flip/nixie modes |
|---|---|---|
| Price up | green | green ▲ |
| Price down | red | red ▼ |
| Price unchanged | grey | last arrow stays |
| First reading / API failure | grey / `--` | no arrow |

Format: `68,969 €` (thousands separators follow the system locale, rounded to
whole euros) preceded by the bundled Bitcoin icon in the compact and full
representations.

## Configuration

- **Refresh interval (minutes)** — default 5, minimum **5**, maximum 1440.
  The 5-minute floor exists because the CoinGecko API allows one request per
  5 minutes. A hint text in the config dialog explains this.
- **Split-flap cascade (seconds)** — default 3, range 1–15. Spreads the flip
  animation of a price change evenly over this many seconds (applies to the
  split-flap display style). Only shown when that style is selected.
- **Nixie flicker (0 = off)** — default 40, range 0–100. Random cathode-dropout
  flicker of the nixie tubes; 0 disables it, higher values flicker more often
  and deeper. Only shown when the nixie style is selected.

Configurable via right-click on the widget → *Configure Bitcoin Price…* → *General*.

## Installation

### Graphical
Double-click `bitcoin-price-1.3.0.plasmoid` in Dolphin (Plasma installs it to
`~/.local/share/plasma/plasmoids/` automatically). The latest build is attached
to the [v1.3.0 release](../../releases/tag/v1.2.0).

### Terminal
```bash
kpackagetool5 --type Plasma/Applet --upgrade bitcoin-price-1.3.0.plasmoid
# Then restart the shell if needed:
plasmashell --replace &
```

Upgrading an already-installed widget requires `--upgrade` (`--install` fails
when the plugin id already exists).

Uninstall:
```bash
kpackagetool5 --type Plasma/Applet --remove nl.a14r.bitcoinprice
```

## Notes

- The API URL uses `vs_currencies=eur`. The original request referenced a
  `usd` URL, but the requirement was "price versus the euro" with a €-sign;
  showing a dollar amount under a € sign would be wrong.
- The trend comparison is made against the last known price. After an API
  failure that reference is kept, so the color is correct again as soon as
  fresh data arrives.
- Without a CoinGecko API key the API may occasionally return 429; the widget
  shows `--` until the next successful poll.
- Tested on Plasma 5.27 / Qt 5.15. Plasma 6 is expected to work but is untested.

## Debugging

The widget logs to the plasmashell journal:

```bash
journalctl --user -u plasma-plasmashell.service | grep bitcoinprice
```

Expected lines: `started, refresh interval: N minutes`, `fetched EUR <price>`,
or `fetch failed, HTTP status: <code>`.

## Repository layout

```
metadata.desktop
contents/
├── config/
│   ├── main.xml            # config schema (refreshMinutes, min 5, max 1440)
│   └── config.qml          # config dialog registry (ConfigModel/ConfigCategory)
├── images/bitcoin.svg      # bundled Bitcoin icon
└── ui/
    ├── main.qml             # widget + fetch/compare logic
    └── configGeneral.qml    # interval setting page
```

Repackage yourself:
```bash
zip -r bitcoin-price.plasmoid metadata.desktop contents
```

## License

MIT — see [LICENSE](LICENSE).