87 lines
4.3 KiB
Markdown
87 lines
4.3 KiB
Markdown
# KDE 6 Widget Starter
|
|
|
|
An all included template for creating KDE 6 widgets.
|
|
|
|
## Features
|
|
|
|
- **Hot Reload**: `make watch` automatically restarts your widget when you modify files.
|
|
- **Standard Structure**: Follows KDE Plasma 6 development standards.
|
|
- **Integrated Build Tools**: Simple `Makefile` for all common tasks.
|
|
- **Testing Environments**: Easily test in panel, desktop, or HiDPI modes.
|
|
- **C++ Bridge Demo**: Includes a Qt6 C++ QML module that can be called directly from QML.
|
|
|
|
## Prerequisites
|
|
|
|
You need the basic KDE and Qt 6 development tools installed on your Linux distribution.
|
|
This also expects you to use clangd as your C++ language server for editor integration along with the clangd VS Code extension.
|
|
|
|
**Arch Linux:** ( approximate list, and you'll likely have these already on KDE )
|
|
|
|
```bash
|
|
sudo pacman -S plasma-sdk inotify-tools kirigami2 qt6-base qt6-declarative
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
1. Clone this repository.
|
|
2. Run `make hooks-install` once to enable Git hooks from `.githooks/`.
|
|
3. If you use VS Code, run `make cpp-build` once to build the C++ bridge and generate IDE metadata for autocomplete. Then install the official QML extension and reload the VS Code window.
|
|
4. Start hot reload while editing with `make watch`.
|
|
5. For a local install into Plasma's package store, use `make install`.
|
|
6. Check style/lint status with `make lint`.
|
|
7. Format everything with `make format`.
|
|
8. Test with `make dev` (default mode) or `make dev MODE=panel|desktop|hidpi`.
|
|
9. Package for distribution with `make package` (creates `build/<widget-id>.plasmoid`, default: `build/org.kde.plasma.starter.plasmoid`). This is just a zip file with a different extension, so you can inspect it with any archive manager.
|
|
|
|
## Editor Setup Notes
|
|
|
|
- **QML IntelliSense (VS Code):** Workspace settings pin `qmlls` to `/usr/lib/qt6/bin/qmlls` and pass `-I/usr/lib/qt6/qml`, `-b${workspaceFolder}/build/cpp`, and `-d/usr/share/doc/qt6`.
|
|
- **Important:** Run `make cpp-build` at least once so the `build/cpp` metadata used by `qmlls` exists.
|
|
- **Generated C++ QML module:** `package/contents/ui/cppbridge/` is created by the C++ build, so editors may warn about `import "cppbridge"` before first build.
|
|
- **Known qmllint false-positive:** `plasmoid.configuration.*` is runtime-injected by Plasma; `main.qml` has a targeted `qmllint` suppression for that property lookup.
|
|
- **C++ editor config:** `clangd` uses `build/cpp/compile_commands.json` (set in `.vscode/settings.json`), with project defaults in `.clangd` and `.clang-format`.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── cpp/ # C++ source and CMake config for the QML bridge module
|
|
│ ├── CMakeLists.txt
|
|
│ └── src/
|
|
│ ├── timebridge.h
|
|
│ └── timebridge.cpp
|
|
├── package/ # The source code of your widget
|
|
│ ├── metadata.json # Widget metadata (name, ID, version)
|
|
│ └── contents/
|
|
│ ├── ui/ # QML User Interface files
|
|
│ │ ├── main.qml # Main widget UI (entry point)
|
|
│ │ ├── configGeneral.qml # UI for the "General" settings tab
|
|
│ │ └── cppbridge/ # Generated Qt6 QML module files (.so + qmldir), built by make cpp-build
|
|
│ └── config/ # Configuration schema
|
|
│ ├── config.qml # Configuration loader (defines the tabs, more of a placeholder file)
|
|
│ └── main.xml # Settings schema (defines variables & defaults)
|
|
├── scripts/
|
|
│ └── watch.sh # Hot reload logic (used by make watch)
|
|
└── Makefile # Command runner
|
|
```
|
|
|
|
## KDE Plasma Quirks: Configuration Logic vs UI
|
|
|
|
KDE Plasma separates **Configuration Logic** (Backend) from **Configuration UI** (frontend). This is why there are two "config" related folders:
|
|
|
|
1. **The Schema (`contents/config/main.xml`)**:
|
|
- This is the **Database Definition**. It defines the variable names, data types (String, Bool), and **Default Values**.
|
|
- It has _no UI logic_. It just defines what can be saved.
|
|
|
|
2. **The View (`contents/ui/configGeneral.qml`)**:
|
|
- This is the **User Interface**. It contains the text fields and checkboxes.
|
|
- It binds to the variables defined in `main.xml`.
|
|
|
|
## Packaging Notes
|
|
|
|
Artifacts produced by `make package` are intended for KDE 6 on Linux x86_64.
|
|
|
|
## License
|
|
|
|
GPL-3.0
|