init

2026-02-23 22:34:50 +00:00
commit 603d5b51bd
19 changed files with 1381 additions and 0 deletions
@@ -0,0 +1,87 @@
+# 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. 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.
+3. Start hot reload while editing with `make watch`.
+4. Install a symlinked development version with `make dev-install`.
+5. For a normal local install (non-symlinked), use `make install`.
+6. Check style/lint status with `make lint`.
+7. Format everything with `make format`.
+8. Test in different modes with `make test`, `make test-panel`, `make test-desktop`, or `make test-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.
+- **Install modes:** `make dev-install` creates a symlink for development, while `make install` converts that symlink into a normal installed package.
+- **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