plasmoides KDE Store/GitHub (gnome-pager, kMenu, kvitals, windowtitle, claude, launchpad)
This commit is contained in:
Josevi
@@ -0,0 +1,133 @@
|
||||
# Architecture
|
||||
|
||||
KVitals is a KDE Plasma 6 widget (plasmoid) with a modular architecture connecting native **KSysGuard sensors** to a **QML UI** through dedicated sensor components.
|
||||
|
||||
## Data Flow
|
||||
|
||||
|
||||
|
||||
## Sensor Modules (`contents/ui/sensors/`)
|
||||
|
||||
Each system metric has its own QML component under `sensors/`. These components encapsulate all sensor subscriptions, data parsing, and value formatting for their metric.
|
||||
|
||||
| Module | Sensors | Exposed Properties |
|
||||
|---|---|---|
|
||||
| `CpuSensors.qml` | `cpu/all/usage` | `cpuValue` |
|
||||
| `MemorySensors.qml` | `memory/physical/used`, `total` | `ramValue` |
|
||||
| `TempSensors.qml` | `cpu/all/averageTemperature` | `tempValue` |
|
||||
| `GpuSensors.qml` | `gpu/all/usage`, `totalVram`, `usedVram`, `temperature` | `gpuValue`, `gpuRamValue`, `gpuTempValue`, `gpuDisplayValue`, `hasGpuData` |
|
||||
| `BatterySensors.qml` | `power/<device>/chargePercentage`, `chargeRate` | `batValue`, `powerValue` |
|
||||
| `NetworkSensors.qml` | `network/<iface>/download`, `upload` | `netDownValue`, `netUpValue` |
|
||||
|
||||
A shared `Utils.qml` singleton provides formatting helpers (`formatBytes`, `formatRate`) and sensor-reading utilities (`sensorValueOrNaN`, `firstReadyNumber`, `maxReadyNumber`, `firstReadyVramPair`).
|
||||
|
||||
### Performance Benefits
|
||||
|
||||
1. **Zero Subprocesses**: No `bash`, `awk`, or `cat` commands are spawned.
|
||||
2. **Stable File Descriptors**: No CLI pipes need to be kept open, eliminating Plasma 6 Wayland FD-exhaustion crashes.
|
||||
3. **Low Latency**: The widget reads the exact same backend API as the official KDE System Monitor.
|
||||
|
||||
## Orchestrator (`main.qml`)
|
||||
|
||||
`main.qml` acts as a lightweight orchestrator:
|
||||
|
||||
1. **Reads configuration** from `Plasmoid.configuration`
|
||||
2. **Instantiates sensor modules** with the configured `updateInterval`
|
||||
3. **Builds metrics models** using the `orderedKeys` array (derived from the `metricOrder` config)
|
||||
4. **Applies view-specific visibility rules** such as `compactShow*` settings and compact grouping
|
||||
5. **Passes models** to `CompactView` and `FullView` for rendering
|
||||
|
||||
```
|
||||
main.qml
|
||||
├── CpuSensors { id: cpu }
|
||||
├── MemorySensors { id: memory }
|
||||
├── TempSensors { id: temp }
|
||||
├── GpuSensors { id: gpu }
|
||||
├── BatterySensors { id: battery }
|
||||
├── NetworkSensors { id: network }
|
||||
├── compactRepresentation: CompactView { metricsModel: ... }
|
||||
└── fullRepresentation: FullView { metricsModel: ... }
|
||||
```
|
||||
|
||||
## Views
|
||||
|
||||
### CompactView (Panel)
|
||||
|
||||
A `RowLayout` with a `Repeater` that renders each compact-visible metric as:
|
||||
- **Icon** (optional, via `Kirigami.Icon` with `isMask: true`)
|
||||
- **Label** (optional, e.g., "CPU:")
|
||||
- **Value** (always shown, e.g., "26%")
|
||||
- **Separator** (`|` between metrics)
|
||||
|
||||
Visibility of icons/labels is controlled by the `displayMode` property. Metric inclusion is controlled by both the metric-level `show*` settings and the compact-panel `compactShow*` settings, allowing a metric to remain visible in the popup/tooltip while being hidden from the panel.
|
||||
|
||||
The compact panel also supports horizontal and vertical delegates through the `layoutType` setting.
|
||||
|
||||
!!! tip
|
||||
Icons use `isMask: true` to render as monochrome, matching the panel's text color regardless of the icon theme.
|
||||
|
||||
### FullView (Popup)
|
||||
|
||||
A `ColumnLayout` with a `Repeater` showing a detailed row per enabled metric with label and bold value, displayed when clicking the widget.
|
||||
|
||||
### Tooltip
|
||||
|
||||
Multi-line text showing all enabled metrics, displayed on hover. Compact-panel visibility settings do not filter the tooltip.
|
||||
|
||||
## Configuration System
|
||||
|
||||
```
|
||||
config/main.xml ← Config schema (entry names, types, defaults)
|
||||
config/config.qml ← Tab registration (General, Metrics, Icons, Colors)
|
||||
ui/configGeneral.qml ← General tab (display mode, layout, font, interval)
|
||||
ui/configMetrics.qml ← Metrics tab (show/hide toggles, compact panel visibility, metric order, grouping, network interface, battery device)
|
||||
ui/configIcons.qml ← Icons tab (per-metric icon picker)
|
||||
ui/configColors.qml ← Colors tab (font color, warning/critical colors, thresholds)
|
||||
```
|
||||
|
||||
All config values are accessed in `main.qml` via `Plasmoid.configuration.<key>`.
|
||||
|
||||
!!! tip "Adding a New Sensor"
|
||||
1. Create `contents/ui/sensors/NewSensor.qml` exposing formatted value properties
|
||||
2. Register it in `sensors/qmldir`
|
||||
3. Instantiate it in `main.qml`
|
||||
4. Add it to the `orderedKeys` loop in compact/full/tooltip builders
|
||||
5. Add `show*` and `compactShow*` config entries in `main.xml`
|
||||
6. Add the metric and compact panel checkboxes in `configMetrics.qml`
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
kvitals/
|
||||
├── metadata.json # Plasmoid metadata (name, version, id)
|
||||
├── install.sh # Local install script
|
||||
├── install-remote.sh # Remote install (curl/wget)
|
||||
├── CHANGELOG.md # Version history
|
||||
├── docs/ # Documentation
|
||||
│ ├── installation.md
|
||||
│ ├── configuration.md
|
||||
│ ├── architecture.md
|
||||
│ ├── contributing.md
|
||||
│ └── troubleshooting.md
|
||||
└── contents/
|
||||
├── config/
|
||||
│ ├── config.qml # Tab registration
|
||||
│ └── main.xml # Config schema
|
||||
└── ui/
|
||||
├── main.qml # Widget orchestrator
|
||||
├── CompactView.qml # Panel representation
|
||||
├── FullView.qml # Popup representation
|
||||
├── configGeneral.qml # General settings tab
|
||||
├── configMetrics.qml # Metrics settings tab
|
||||
├── configIcons.qml # Icons settings tab
|
||||
├── configColors.qml # Colors settings tab
|
||||
└── sensors/ # Sensor modules
|
||||
├── qmldir # QML module definition
|
||||
├── CpuSensors.qml # CPU usage
|
||||
├── MemorySensors.qml # RAM usage
|
||||
├── TempSensors.qml # CPU temperature
|
||||
├── GpuSensors.qml # GPU usage, VRAM, temp
|
||||
├── BatterySensors.qml # Battery & power
|
||||
├── NetworkSensors.qml # Network speed
|
||||
└── Utils.qml # Shared formatting helpers
|
||||
```
|
||||
Reference in New Issue
Block a user