kde-6-widget-starter/README.md

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 )

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.

Pling Upload (Experimental)

This repo includes a script for OpenDesktop publishing as part of CI/CD actions.

uv run --env-file .env python scripts/pling_upload.py --dry-run

--dry-run validates login, project edit-page access, and upload endpoint discovery.

Live mode is the default when --dry-run is omitted:

uv run --env-file .env python scripts/pling_upload.py \
  -f build/org.kde.plasma.starter.plasmoid

Important: live mode is destructive by design right now. It first deletes all existing files on the target project, then uploads/registers the provided file(s).

You can pass multiple files by repeating -f:

uv run --env-file .env python scripts/pling_upload.py \
  -f test2.md \
  -f test3.md

Config can be provided by args or environment variables (.env.example): PLING_BASE_URL, PLING_PROJECT_ID, PLING_USERNAME, PLING_PASSWORD, PLING_FILES, PLING_TIMEOUT, PLING_MAX_RETRIES.

License

GPL-3.0