Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 66 additions & 0 deletions .github/workflows/kcm.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
name: kcm

# The System Settings module (kcm/): build it warning-free, run its tests (the staging model, the
# controller against tools/mock_plasmaard.py on a private bus, qmllint) and check the translations.

on:
push:
paths:
- "kcm/**"
- "tools/mock_plasmaard*"
- ".github/workflows/kcm.yml"
pull_request:
paths:
- "kcm/**"
- "tools/mock_plasmaard*"
- ".github/workflows/kcm.yml"

jobs:
build:
name: build and test (${{ matrix.image }})
runs-on: ubuntu-latest
container: ${{ matrix.image }}
strategy:
fail-fast: false
matrix:
image: ["ubuntu:26.04", "fedora:latest"]

steps:
- name: Install dependencies (Ubuntu)
if: startsWith(matrix.image, 'ubuntu')
env:
DEBIAN_FRONTEND: noninteractive
run: |
apt-get update
apt-get install -y --no-install-recommends \
ca-certificates cmake ninja-build g++ extra-cmake-modules gettext \
qt6-base-dev qt6-declarative-dev qt6-declarative-dev-tools qt6-tools-dev \
libkf6kcmutils-dev libkf6i18n-dev libkf6coreaddons-dev libkirigami-dev \
qml6-module-org-kde-kirigami qml6-module-org-kde-kcmutils \
qml6-module-qtquick-controls qml6-module-qtquick-layouts \
dbus-daemon python3 python3-gi gir1.2-glib-2.0

- name: Install dependencies (Fedora)
if: startsWith(matrix.image, 'fedora')
run: |
dnf install -y \
cmake ninja-build gcc-c++ extra-cmake-modules gettext \
qt6-qtbase-devel qt6-qtdeclarative-devel qt6-qttools-devel \
kf6-kcmutils-devel kf6-ki18n-devel kf6-kcoreaddons-devel kf6-kirigami-devel \
dbus-daemon dbus-tools python3 python3-gobject-base

- name: Checkout
uses: actions/checkout@v4

- name: Configure
run: cmake -S kcm -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_COMPILE_WARNING_AS_ERROR=ON

- name: Build
run: cmake --build build

- name: Test
run: ctest --test-dir build --output-on-failure

- name: Check translations
run: |
for po in kcm/po/*/*.po; do msgfmt --check --statistics -o /dev/null "$po"; done
34 changes: 34 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -123,3 +123,37 @@ lint:
test:
@echo "Running Solaar tests"
pytest -rs --cov --cov-report=xml

# --- System Settings module (kcm/, see docs/kcm.md) ---------------------------------------------------
# A user install: the plugin, its translations and desktop entry under KCM_PREFIX, plus a Plasma session
# environment script that adds the plugin directory to QT_PLUGIN_PATH (effective at the next login).

KCM_BUILD_DIR ?= kcm/build
KCM_PREFIX ?= $(HOME)/.local
PLASMA_ENV_DIR := $(HOME)/.config/plasma-workspace/env
KCM_ENV_SCRIPT := $(PLASMA_ENV_DIR)/plasmaar-kcm.sh

.PHONY: build_kcm test_kcm install_kcm uninstall_kcm

build_kcm:
cmake -S kcm -B $(KCM_BUILD_DIR) -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=$(KCM_PREFIX)
cmake --build $(KCM_BUILD_DIR) --parallel

test_kcm: build_kcm
ctest --test-dir $(KCM_BUILD_DIR) --output-on-failure

install_kcm: build_kcm
cmake --install $(KCM_BUILD_DIR)
install -D -m 644 $(KCM_BUILD_DIR)/plasmaar-kcm.sh $(KCM_ENV_SCRIPT)
@echo
@echo "Installed. System Settings lists it under Input Devices after you log out and back in."
@echo "To try it right away:"
@echo " sh -c '. $(KCM_ENV_SCRIPT) && exec kcmshell6 kcm_plasmaar'"

uninstall_kcm:
@if [ -f $(KCM_BUILD_DIR)/install_manifest.txt ]; then \
cmake --build $(KCM_BUILD_DIR) --target uninstall; \
else \
echo "$(KCM_BUILD_DIR)/install_manifest.txt not found: nothing installed from this build directory"; \
fi
rm -f $(KCM_ENV_SCRIPT)
164 changes: 164 additions & 0 deletions docs/kcm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
# The System Settings module (KCM)

"Logitech Devices" ("Périphériques Logitech") under System Settings → Input Devices: the settings page of
[Assessment B](ROADMAP.md#assessment-b-the-settings-page-system-settings-module). It is a thin C++ plugin
plus a QML page that talks to `plasmaard` over its [D-Bus API](dbus-api.md); all device work stays in the
service.

| Settings | Buttons | Haptic feedback |
|---|---|---|
| ![Settings](../kcm/screenshots/mx-master-4-settings.png) | ![Buttons](../kcm/screenshots/mx-master-4-buttons.png) | ![Haptics](../kcm/screenshots/mx-master-4-haptics.png) |

More in [`kcm/screenshots/`](../kcm/screenshots): the KDE action picker (`mx-master-4-action-picker`),
the K850 (`k850-settings`), an offline device, write errors, an older plasmaard, plasmaard not running,
and the buttons of the real MX Master 4 read from the running service. They are rendered headless (see
the end of this page), in French.

## What it shows

- **Device header**: picker (switching is locked while there are unapplied changes), name, connection,
battery, model/unit ids and HID++ version.
- **Settings**: every setting of the schema, grouped in sections (scroll wheel, thumb wheel, pointer, …).
`TOGGLE` → switch, `CHOICE` → combo box (long numeric lists such as DPI → stepped slider + spin box,
long named lists → searchable list), `RANGE` → slider + spin box, other kinds read-only, `display: false`
hidden. Descriptions are behind the ⓘ buttons. Per-key settings (`reprogrammable-keys`, `divert-keys`,
`persistent-remappable-keys`, …) form one table: a row per key, a column per setting.
- **Buttons** (Keys for a keyboard): each divertable button's behavior (normal, an action when pressed,
gestures; only the modes it offers) and the KDE actions, chosen from a searchable list of
`ListKdeActions` grouped by component, for the press or each gesture direction including a click.
- **Haptic feedback**: intensity (`haptic-level`), a test button per waveform (`PlayHaptic`, immediate),
and which waveform desktop events play (`GetHapticEvents`/`SetHapticEvent`).
- **plasmaard not running**: a placeholder with a "Start plasmaard" button (systemd `StartUnit`) and the
`systemctl --user start plasmaard` hint. The page comes back by itself when the service appears.

## Build, test, install

Build dependencies (Kubuntu/Debian names): `cmake extra-cmake-modules qt6-base-dev qt6-declarative-dev
libkf6kcmutils-dev libkf6i18n-dev libkf6coreaddons-dev libkirigami-dev gettext`; the tests also use
`qt6-declarative-dev-tools` (qmllint), `dbus-daemon` and `python3-gi`.

```sh
make test_kcm # configure kcm/build, build, run the tests
make install_kcm # install for your user, see below
make uninstall_kcm
```

`make install_kcm` installs into `~/.local` (`KCM_PREFIX=…` to change it): the plugin in
`~/.local/lib/<arch>/plugins/plasma/kcms/systemsettings/`, the French translation and a desktop entry.
Plasma only looks for plugins on `QT_PLUGIN_PATH`, so it also writes
`~/.config/plasma-workspace/env/plasmaar-kcm.sh`, which Plasma sources at login. Until you log in again:

```sh
sh -c '. ~/.config/plasma-workspace/env/plasmaar-kcm.sh && exec kcmshell6 kcm_plasmaar'
```

Without make: `cmake -S kcm -B kcm/build && cmake --build kcm/build && ctest --test-dir kcm/build`.
A plain `cmake --install` to `/usr` needs no environment script.

## Architecture

```
plasmaard ──D-Bus (JSON payloads)── PlasmaarClient ── Controller ── StagedModel ×3 ── QML pages
(async calls, (devices, (settings,
signals, load/save/ buttons,
service watch) defaults) haptic events)
│
PlasmaarKcm (KQuickConfigModule): Apply/Reset/Defaults
```

C++ (`kcm/src/`):

- **`PlasmaarClient`**: every call is a `QDBusPendingCallWatcher` (never blocking the UI; 30 s timeout for
sleeping Bluetooth devices) whose JSON reply is parsed into a `QVariant` and handed to a callback.
It relays `DeviceAdded/Changed/Removed`, `SettingChanged` and `ButtonActionsChanged` with parsed
payloads, and follows the service with a `QDBusServiceWatcher` (Checking → Running ↔ Missing).
- **`StagedModel`**: a list model of entries (settings, buttons or haptic events) with a live value and an
optional staged value per row. QML reads `pending` (staged, else live) and stages edits, also per key of
a map (`stageKey`) or along a path (`stagePath`, for gesture directions). Staging the live value again
unstages the row, so "needs save" really means something would change. Live updates keep the user's
edits: for maps, only the edited keys are kept and the others follow the device. A refresh with the same
entries updates the rows in place (views keep their delegates). It also knows the `default` of each
entry and the write error of each row.
- **`Controller`**: the devices, the selected one, its three models, the KDE actions and waveforms, and
the KCM operations. `load()` drops edits and reloads; `save()` writes the changed rows one after the
other (settings first, with `SetSetting`, or `SetSettingKey` per changed key; then `SetButtonAction`;
then `SetHapticEvent`) and takes each reply as the new live value; a failed write keeps its edit staged
and shows its error inline and in a summary. `defaults()` stages every setting's `default`. Each
optional part has a state: Available, Unavailable (the device has none), NeedsNewerService (the method
is unknown: an older plasmaard), Failed.
- **`PlasmaarKcm`**: the plugin. `needsSave` follows the staged edits; `representsDefaults` is true when
the pending values are the defaults, or when no default is known, which disables the Defaults button.

The C++ types form a static QML module, `io.github.fredaime.plasmaar`, so the QML is typed and qmllint
checks it against the generated `.qmltypes`.

QML (`kcm/ui/`, loaded by `kcmutils_add_qml_kcm`): `main.qml` (header with the device and tabs, service
placeholders, the shared pickers), `DeviceHeader`, `SettingsPage` (sections of `SettingRow`) and
`KeyMapTable`/`KeyCell`, `ButtonsPage`/`ActionField`, `HapticsPage`, `PickerDialog` (a
`Kirigami.SearchDialog`), `SnapshotRunner`. The pages are rebuilt when another device is selected rather
than having all their rows replaced under the form layouts.

### With an older plasmaard

Each addition is optional: an `org.freedesktop.DBus.Error.UnknownMethod` answer hides or explains the part
that needs it. Without `GetButtonActions` the Buttons tab says that a newer plasmaard is needed (if the
device has divertable buttons); without `GetHapticEvents` the haptics page keeps intensity and the test
buttons (waveforms from the `haptic-play` setting); without `"default"` the Defaults button stays off.

## Translations

All strings go through `i18n()`; the domain is `kcm_plasmaar`. `kcm/Messages.sh` extracts them into
`kcm/po/kcm_plasmaar.pot` and merges them into the translations; `kcm/po/fr/kcm_plasmaar.po` is the French
one, installed by `ki18n_install`. Setting labels and descriptions come translated from the service.

## Tests and checks

`ctest` in the build directory runs:

- `stagedmodeltest`: the staging rules (unstaging, per-key edits and live merges, nested paths, defaults,
in-place refresh, errors) and the JSON conversions.
- `controllertest`: the `Controller` against `tools/mock_plasmaard.py` on a private bus
(`dbus-run-session` with `kcm/autotests/isolated-bus.conf`, which has no service activation): loading,
apply, per-key apply, live updates, defaults, write errors, button actions, haptic events, the service
quitting and coming back, and an older service. It refuses to run if a plasmaard already owns the name.
- `qmllint`: `kcm/autotests/qmllint.py` fails on any warning except unqualified access to `kcm` and the
i18n functions, which KCMUtils and KI18n inject as context properties that qmllint cannot see.

`.github/workflows/kcm.yml` builds with warnings as errors and runs these tests in Ubuntu 26.04 and Fedora
containers.

## The mock service and headless snapshots

`tools/mock_plasmaard.py` implements the whole API with data captured from a real MX Master 4, K850 and
MX Anywhere 3S (`tools/mock_plasmaard_data.json`), in memory, with the same signals. Run it only on a
private bus; it refuses to start next to a running plasmaard. `--legacy` emulates a v1-only service,
`--fail NAME` makes writes of a setting fail (`button:<control>`, `haptic:<event>` too), `--delay MS`
slows every answer, `-v` logs calls. Its `io.github.fredaime.PlasmaarMock` interface simulates the
device: `SetDeviceValue`, `SetOnline`, `SetBattery`, and `Quit`.

```sh
dbus-run-session --config-file=kcm/autotests/isolated-bus.conf -- \
sh -c 'python3 tools/mock_plasmaard.py -v & sleep 1; \
QT_PLUGIN_PATH=$PWD/kcm/build/bin kcmshell6 kcm_plasmaar'
```

With `PLASMAAR_KCM_SNAPSHOT=/path/prefix` the module renders each page of each device once the data has
loaded, grows the window to fit, saves `/path/prefix-<device>-<page>.png` and quits. `kcm/run-snapshots.sh`
does it all offscreen (`QT_QPA_PLATFORM=offscreen`, French by default):

```sh
kcm/run-snapshots.sh /tmp/shots/mock # against the mock, private bus
kcm/run-snapshots.sh --legacy /tmp/shots/legacy # an older plasmaard
kcm/run-snapshots.sh --fail smart-shift --scenario apply-errors /tmp/shots/errors
kcm/run-snapshots.sh --no-service /tmp/shots/none # plasmaard not running
kcm/run-snapshots.sh --real /tmp/shots/real # your plasmaard, read-only
```

Snapshot mode never writes to the service; the `apply-errors` scenario, which stages and applies a few
edits, is refused with `--real`.

## Not covered yet

- B8: the advanced kinds (`MULTIPLE_TOGGLE`, `MULTIPLE_RANGE`, `PACKED_RANGE`, …) are shown read-only.
- B9: pairing with Bolt/Unifying receivers.
- Edits are per device: switching devices requires applying or resetting first.
2 changes: 2 additions & 0 deletions kcm/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
/build/
/po/*.pot
64 changes: 64 additions & 0 deletions kcm/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
# SPDX-FileCopyrightText: 2026 plasmaar contributors
# SPDX-License-Identifier: GPL-2.0-or-later

cmake_minimum_required(VERSION 3.22)
project(kcm_plasmaar VERSION 0.1.0 LANGUAGES CXX)

set(QT_MIN_VERSION "6.6.0")
set(KF_MIN_VERSION "6.3.0") # Kirigami.SearchDialog

find_package(ECM ${KF_MIN_VERSION} REQUIRED NO_MODULE)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH})

include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMQmlModule)
include(FeatureSummary)

find_package(Qt6 ${QT_MIN_VERSION} REQUIRED COMPONENTS Core DBus Gui Qml Quick)
find_package(KF6 ${KF_MIN_VERSION} REQUIRED COMPONENTS CoreAddons I18n KCMUtils)

option(BUILD_TESTING "Build the tests" ON)

add_compile_definitions(TRANSLATION_DOMAIN="kcm_plasmaar")
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
# The plugin is a shared object that links the static core library and the object libraries Qt
# generates for its QML module (resources, type registrations): all of them must be PIC. Some
# toolchains (Ubuntu) default to it, others (Fedora) do not.
set(CMAKE_POSITION_INDEPENDENT_CODE ON)

# The D-Bus client, the staging model and the controller: a static QML module, so that the QML is typed
# (qmllint checks it against the generated .qmltypes) and the tests can use it without KCMUtils.
qt_add_library(plasmaar_kcm_core STATIC)
qt_add_qml_module(plasmaar_kcm_core
URI io.github.fredaime.plasmaar
VERSION 1.0
NO_PLUGIN
SOURCES
src/controller.cpp src/controller.h
src/json.cpp src/json.h
src/plasmaarclient.cpp src/plasmaarclient.h
src/stagedmodel.cpp src/stagedmodel.h
)
target_include_directories(plasmaar_kcm_core PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/src)
# The module's resource objects share the include directories, and may compile before AUTOMOC has created
# its include directory: create it up front for -Wmissing-include-dirs (set by KDECompilerSettings).
file(MAKE_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/plasmaar_kcm_core_autogen/include)
target_link_libraries(plasmaar_kcm_core PUBLIC Qt6::Core Qt6::DBus Qt6::Gui Qt6::Qml KF6::I18n)

kcmutils_add_qml_kcm(kcm_plasmaar SOURCES src/plasmaarkcm.cpp src/plasmaarkcm.h)
target_link_libraries(kcm_plasmaar PRIVATE plasmaar_kcm_core KF6::CoreAddons KF6::I18n KF6::KCMUtilsQuick Qt6::Quick)

ki18n_install(po)

# For installs outside the system prefix (make install_kcm): the Plasma session environment script that
# adds the plugin directory to QT_PLUGIN_PATH.
configure_file(plasmaar-kcm.sh.in ${CMAKE_CURRENT_BINARY_DIR}/plasmaar-kcm.sh @ONLY)

if(BUILD_TESTING)
add_subdirectory(autotests)
endif()

feature_summary(WHAT ALL INCLUDE_QUIET_PACKAGES FATAL_ON_MISSING_REQUIRED_PACKAGES)
19 changes: 19 additions & 0 deletions kcm/Messages.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
#!/bin/sh
# SPDX-FileCopyrightText: 2026 plasmaar contributors
# SPDX-License-Identifier: GPL-2.0-or-later
#
# Extracts the module's messages into po/kcm_plasmaar.pot and merges them into the translations:
# kcm/Messages.sh
# (Same keywords as KDE's scripty; QML is read as JavaScript.)
set -e
cd "$(dirname "$0")"
KEYWORDS="-ki18n:1 -ki18nc:1c,2 -ki18np:1,2 -ki18ncp:1c,2,3 -kxi18n:1 -kxi18nc:1c,2 -kxi18np:1,2 -kxi18ncp:1c,2,3 -kkli18n:1 -kkli18nc:1c,2"
COMMON="--from-code=UTF-8 --add-comments=i18n --package-name=kcm_plasmaar --msgid-bugs-address=https://github.com/fredaime/plasmaar/issues"
xgettext $COMMON -C $KEYWORDS -o po/cpp.pot src/*.cpp
xgettext $COMMON -L JavaScript $KEYWORDS -o po/qml.pot ui/*.qml
msgcat --use-first po/cpp.pot po/qml.pot -o po/kcm_plasmaar.pot
rm -f po/cpp.pot po/qml.pot
for po in po/*/kcm_plasmaar.po; do
[ -e "$po" ] || continue
msgmerge --quiet --update --backup=none --no-fuzzy-matching "$po" po/kcm_plasmaar.pot
done
29 changes: 29 additions & 0 deletions kcm/autotests/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# SPDX-FileCopyrightText: 2026 plasmaar contributors
# SPDX-License-Identifier: GPL-2.0-or-later

find_package(Qt6 ${QT_MIN_VERSION} REQUIRED COMPONENTS Test)
include(ECMAddTests)

ecm_add_test(stagedmodeltest.cpp TEST_NAME stagedmodeltest LINK_LIBRARIES plasmaar_kcm_core Qt6::Test)

# The controller against the mock service, on a private session bus without service activation.
find_program(DBUS_RUN_SESSION dbus-run-session)
find_program(PYTHON3 python3)
if(DBUS_RUN_SESSION AND PYTHON3)
add_executable(controllertest controllertest.cpp)
target_link_libraries(controllertest plasmaar_kcm_core Qt6::Test)
add_test(NAME controllertest
COMMAND ${DBUS_RUN_SESSION} --config-file=${CMAKE_CURRENT_SOURCE_DIR}/isolated-bus.conf -- $<TARGET_FILE:controllertest>)
set_tests_properties(controllertest PROPERTIES
ENVIRONMENT "PLASMAAR_MOCK=${CMAKE_CURRENT_SOURCE_DIR}/../../tools/mock_plasmaard.py;PLASMAAR_PYTHON=${PYTHON3}"
TIMEOUT 300)
else()
message(STATUS "dbus-run-session or python3 missing: controllertest is not built")
endif()

# QML: lint the module's pages against the generated types of the C++ module (also run in CI).
find_program(QMLLINT qmllint PATHS ${QT6_INSTALL_PREFIX}/${QT6_INSTALL_BINS} /usr/lib/qt6/bin /usr/lib64/qt6/bin)
if(QMLLINT AND PYTHON3)
file(GLOB qml_files ${CMAKE_CURRENT_SOURCE_DIR}/../ui/*.qml)
add_test(NAME qmllint COMMAND ${PYTHON3} ${CMAKE_CURRENT_SOURCE_DIR}/qmllint.py ${QMLLINT} ${CMAKE_BINARY_DIR}/bin ${qml_files})
endif()
Loading
Loading