364 lines
23 KiB
Markdown
364 lines
23 KiB
Markdown
# AGENTS.md
|
||
|
||
## What this is
|
||
A pure GTK4 C++ GUI plus a background daemon for remapping the G1–G9 keys of a
|
||
Logitech G910. The GUI edits and persists mappings; the daemon reads the G-keys
|
||
and replays the configured action. Hardware G-key detection and action execution
|
||
live in the daemon, not the GUI. Code is split across `src/` (GUI), `shared/`
|
||
(common) and `daemon/`.
|
||
|
||
## Build / run / verify
|
||
- `make` — builds the `gkeymapper` GUI, the `gkeymapper-daemon` and the `.mo`
|
||
catalogs. Needs `g++` (C++17), `make`, `gettext`, `libgtk-4-dev`,
|
||
`libusb-1.0-0-dev`, `libxkbcommon-dev` and `libglib2.0-dev` (see README for
|
||
`apt install` on a fresh machine). `libglib2.0-dev` also provides
|
||
`glib-compile-resources`, which generates the icons embedded into the GUI.
|
||
- `make daemon` — builds only `gkeymapper-daemon` (needs libusb, xkbcommon and
|
||
gio-2.0, not GTK).
|
||
- `make translations` — only runs `msgfmt` on the existing `.po` files.
|
||
- `make run` — builds, then runs with `GKEYMAPPER_LOCALEDIR=$PWD/locale` and
|
||
`GKEYMAPPER_ASSETS_DIR=$PWD/assets` so the working-tree translations are used.
|
||
Plain `./gkeymapper` works too (assets fall back to `./assets`). The window
|
||
icon itself is compiled into the binary, so it never depends on these.
|
||
- `make clean` — deletes the binaries and the generated `locale/` and `build/`
|
||
trees.
|
||
- No tests and no CI. Verify changes by building and running the app.
|
||
|
||
## i18n — easy to get wrong
|
||
- English is the source language (the `msgid`) **and** also has an explicit
|
||
identity catalog `po/en.po`. Languages: `de`, `en`, `es`, `fr`.
|
||
- `make translations` does **not** regenerate the `.pot`. When you add or change
|
||
a UI string, edit `po/gkeymapper.pot` and `po/*.po` by hand, then run
|
||
`make translations`; validate with `msgfmt --check -o /dev/null po/<lang>.po`.
|
||
- Never edit the generated `.mo` files under `locale/` (gitignored). Delete any
|
||
`po/*.po~` backups before committing.
|
||
- All documentation and source comments are English. German appears only inside
|
||
`po/de.po`.
|
||
|
||
## Code layout and conventions
|
||
- Modules under `src/` (GUI), `shared/` (used by both binaries) and `daemon/`
|
||
(the background service). Shared API lives in `namespace gkeymapper`.
|
||
`shared/mapping` owns the mappings file format, `shared/keys` the canonical
|
||
key-name table (lowercase GDK names -> Linux `KEY_*`), `shared/ipc_ids.h` the
|
||
app id, the version and the D-Bus names both sides use.
|
||
- The Makefile globs sources: `make` builds the GUI (`src/*.cpp` + `shared/*.cpp`
|
||
+ the generated `build/gresources.c`, see Assets) **and** the daemon
|
||
(`daemon/*.cpp` + `shared/*.cpp`, needs `libusb-1.0-0-dev`,
|
||
`libxkbcommon-dev` and `libglib2.0-dev`). `make daemon` builds only the daemon.
|
||
- The daemon is split into: `device_tables` (raw HID report tables per model plus
|
||
`decode_gkey_state`, the report → pressed-bitmap decoder), `g910_device` (libusb
|
||
open/detach/claim/read), `uinput_keyboard` (virtual keyboard), `action`
|
||
(dispatch `key`/`command`/`disabled`/`keyhold`), `config_watch` (inotify auto-reload of
|
||
the mappings file) and `ipc_dbus` (the GDBus service). `shared/keymap` does the
|
||
layout lookups for both sides. The hot path never touches the GUI: D-Bus is
|
||
control plane only and is pumped once per loop.
|
||
- G-key decoding is **state-based**, not per-key matching: the macro report holds
|
||
a bitmap (byte 4 = G1–G8, low bit of byte 5 = G9), so the daemon fires a key on
|
||
a 0 → 1 transition. That is what suppresses the repeats of a held key and makes
|
||
a chord fire every key in it. Media/memory keys and command/LED answers are
|
||
rejected by report length and header; keep it that way instead of
|
||
re-introducing exact-report matching.
|
||
- `keyhold` uses the **falling** edge too: `run_mapping(..., hold=true)` calls
|
||
`ActionRunner::begin_hold()`, and the 1 → 0 transition of that bit calls
|
||
`end_hold(index)` (a no-op for every other type). The held codes are stored per
|
||
G key in `ActionRunner::held_`, so a code that two G keys hold is released only
|
||
when the *last* one comes up. `release_held()` runs on device loss and on
|
||
shutdown, otherwise a key whose release report never arrived would stay down in
|
||
the whole session. `ActionRunner::run()` (the `TestMapping` path) taps a hold
|
||
mapping, because a D-Bus call cannot wait for a release. Only a single step can
|
||
be held; a sequence is replayed as a tap with a log line, and `keyhold:` on an
|
||
unresolvable name does nothing.
|
||
- Auto-repeat of a held key comes from the **X server / compositor**, not from the
|
||
virtual device: it sets no `EV_REP` bits, so the kernel repeats nothing, but X
|
||
does (measured: release+press pairs every ~40 ms after 660 ms). That matches a
|
||
physical key, so do not "fix" it by filtering.
|
||
- The daemon runs **without** a keyboard: `open()` failing (or a read error) only
|
||
logs the absence once, reports `DeviceChanged(false)` and the loop retries every
|
||
2 s while D-Bus and the config watch keep running. Never make it exit on a
|
||
missing device — that would drop the bus name and make the GUI look like the
|
||
daemon died. `GKeyDevice::open(quiet)` exists so those retries stay out of the
|
||
journal (libusb-level errors always log).
|
||
- `make install` (PREFIX default `/usr/local`) also installs the packaging
|
||
files from `data/`: the udev rule, the `modules-load.d` fragment, the
|
||
systemd **user** unit and the D-Bus activation file. Both contain an
|
||
`@BINDIR@` placeholder that the Makefile substitutes with `$(PREFIX)/bin`.
|
||
Keep it a user service — it needs the session for `/dev/uinput` and
|
||
`DISPLAY`.
|
||
- Daemon config reload: `config_watch` watches the config **directory** (so an
|
||
atomic save via `rename` is caught) and reports a change at most once per loop
|
||
iteration, which is the coalescing window. `SIGHUP`/`SIGUSR1` remain as a
|
||
fallback. A failed reload keeps the previous mappings on purpose.
|
||
- `main.cpp` keeps the `rows` vector (one `KeyRow` per G key, widget pointers)
|
||
in an anonymous namespace; `src/mappings.cpp` is GUI glue that moves data
|
||
between the widgets and the shared `MappingSet`. `build_ui()` loads
|
||
`default_config_path()` into the rows as soon as they exist (a missing file is
|
||
not an error), so a save from a fresh window rewrites the file instead of
|
||
emptying it. App id:
|
||
`dev.rager.gkeymapper` (`ipc::kAppId`); the About dialog uses `ipc::kVersion`.
|
||
- GUI ↔ daemon is D-Bus on the session bus, GDBus (GIO) on both sides:
|
||
`src/daemonclient.{h,cpp}` is the client, `daemon/ipc_dbus.{h,cpp}` the
|
||
service. The daemon owns `dev.rager.gkeymapper.Daemon`, **not** the plain app
|
||
id — `GtkApplication` owns that itself to detect a second GUI instance, so a
|
||
daemon on the same name would make every GUI start look like a duplicate and
|
||
exit. All names live in `shared/ipc_ids.h`.
|
||
- Exactly one GUI runs, and it is the one that was just started: `main()` calls
|
||
`replace_running_instance()` (`src/singleinstance.{h,cpp}`) **before** it
|
||
creates the `GtkApplication`. It asks the instance that owns `ipc::kAppId` to
|
||
quit over D-Bus (the `quit` action `GApplication` exports as
|
||
`org.gtk.Actions` at the app-id path, added in `on_activate`) and waits for the
|
||
name; an instance from an older build has no such action, so it is terminated
|
||
with `SIGTERM` after checking that the bus name really belongs to a
|
||
`gkeymapper` process. Only then does the new process become the primary,
|
||
because otherwise `GtkApplication` would hand over to the old process and its
|
||
window — possibly one from an older build — would stay on screen. Row edits
|
||
that were not saved are gone with the replaced window; there is no implicit
|
||
save.
|
||
- `on_activate` presents the window that is already there
|
||
(`gtk_application_get_windows()`), it does not build a second one: a remote
|
||
activation — an older build starting next to a new one — would otherwise add a
|
||
second window to the running process.
|
||
- Except for that startup takeover, the GUI never does a blocking D-Bus call:
|
||
`DaemonClient` uses async calls and signal subscriptions, which arrive on the
|
||
GTK main loop, and it follows `NameOwnerChanged` so the footer reacts when the
|
||
daemon starts or stops.
|
||
- `DaemonService::pump()` dispatches messages once per daemon loop iteration, so
|
||
a control call is answered within one read timeout (≤500 ms) and outgoing
|
||
signals are flushed then too. Keep it off the keypress path.
|
||
- The daemon refuses to start when the name is taken (`DO_NOT_QUEUE` + exit 0
|
||
with a message): two instances would fight over the device and create two
|
||
virtual keyboards. That check runs **before** the device is opened.
|
||
- The daemon status line is a plain `GtkLabel` in the window footer, updated with
|
||
a single `gtk_label_set_text()`. It is deliberately **not** a `GtkStatusbar`:
|
||
that needs message pop/push bookkeeping per context id, and GTK4 exposes it
|
||
over AT-SPI as a generic `filler`, not as a "statusbar" role, so it buys
|
||
nothing here.
|
||
- The Type dropdown index is meaningful everywhere: `0=Key`, `1=Command`,
|
||
`2=Disabled`, `3=Key (hold)`, matching the `key`/`command`/`disabled`/`keyhold`
|
||
tokens in the file. Keep that order (`ActionType` appends new values at the end
|
||
— `Disabled, Key, Command, KeyHold` — so an existing value never changes
|
||
meaning; the GUI maps indices explicitly).
|
||
- The capture dialog's `CaptureSession` is heap-allocated and freed only by the
|
||
window's `"destroy"` handler. Always close the dialog with
|
||
`gtk_window_destroy` so the session is released.
|
||
- Use GTK4 API only: `gtk_editable_set_text` / `gtk_editable_get_text` (there is
|
||
no `gtk_entry_set_text`), `gtk_window_destroy` (no `gtk_dialog_run`),
|
||
`G_APPLICATION_FLAGS_NONE`.
|
||
- The main window is intentionally **non-resizable** and has **no**
|
||
`GtkScrolledWindow` (one collapsed the rows earlier). Keep the fixed widths
|
||
(Type dropdown 150 px, target entry 440 px min, action button 180 px) so rows
|
||
do not jump when the language changes.
|
||
- Because it is pure GTK4 it follows the system theme (Mint-Y ships a
|
||
`gtk-4.0` theme). Do **not** add the `suggested-action` CSS class — Mint-Y
|
||
tints it green and it clashes with the rest of the layout.
|
||
|
||
## Config file format
|
||
`Save mappings` writes `~/.config/gKeyMapper/mappings.conf`; Export/Import use
|
||
the same format:
|
||
|
||
```
|
||
G1=key:ctrl+c,ctrl+v
|
||
G2=command:/usr/bin/firefox
|
||
G3=disabled:
|
||
G4=keyhold:ctrl+w
|
||
```
|
||
|
||
`<type>:<target>`, one line per key. `key` is a captured sequence (lowercase
|
||
`gdk_keyval_name` output; modifiers joined with `+`, steps joined with `,`),
|
||
`command` is a program path or command line, `disabled` is inactive, and
|
||
`keyhold` presses one step and keeps it down while the G key is held. The
|
||
canonical modifier order is `ctrl`, `alt`, `shift`, `super`, `altgr`
|
||
(`format_shortcut_step()`; parsing accepts any order).
|
||
|
||
Key names are **layout independent**: `shared/keymap` resolves a name like `z`
|
||
to the key that produces `z` on the active layout (read from
|
||
`/etc/default/keyboard`, `XKBLAYOUT`) via xkbcommon — on a German keyboard `z` is
|
||
evdev 21, not the US position 44. `shared/keys` maps names to the US positions
|
||
and is only the fallback. When you add key names, keep them lowercase GDK keysym
|
||
names. `parse_shortcut()` takes an optional resolver for this (the daemon passes
|
||
one).
|
||
|
||
The capture dialog stores the **base (level 0) key**: it uses
|
||
`Keymap::base_key_name(keycode)` instead of GDK's shifted keyval, so
|
||
`Shift`+ß becomes `shift+ssharp` (not `shift+question`, which would double the
|
||
shift). `format_shortcut_step()` — not the dialog — renders a step from a
|
||
`ModifierBit` mask, so the order stays in one place.
|
||
|
||
AltGr (level 3) is recorded as the `altgr` modifier plus the base key
|
||
(`AltGr`+7 → `altgr+7`). GTK4 dropped the `GDK_MOD5_MASK` name, so the dialog
|
||
tracks `ISO_Level3_Shift` / `Mode_switch` through its own key press/release
|
||
(`CaptureSession::altGrHeld`) instead of a state bit. On the replay side
|
||
`kModAltGr` maps to `KEY_RIGHTALT`.
|
||
|
||
## Assets
|
||
The icons (`assets/icon.png`, `assets/icon.svg`) are compiled into the GUI:
|
||
`data/icons.gresource.xml` is turned into the generated `build/gresources.c` by
|
||
`glib-compile-resources` and linked into `gkeymapper`, so the window has its icon
|
||
with nothing installed. The resource prefix mirrors the app id
|
||
(`/dev/rager/gkeymapper`) and the `icons/` subtree mirrors the hicolor layout, so
|
||
`gtk_icon_theme_add_resource_path()` also answers
|
||
`gtk_window_set_icon_name("gkeymapper")` from the binary. The daemon embeds no
|
||
resource (it has no UI).
|
||
|
||
`make_icon_image()` and the About dialog take the embedded copy first and fall
|
||
back to `find_asset()`, which resolves `$GKEYMAPPER_ASSETS_DIR` → `./assets` →
|
||
compiled-in `ASSETS_DIR` (`/usr/local/share/gkeymapper/assets`). Because the
|
||
resource is built from `assets/` it cannot go stale, and it deliberately wins
|
||
over any installed file; the file lookup remains only as a safety net.
|
||
|
||
## Driving the daemon for manual checks
|
||
- The process name is truncated by the kernel to 15 chars, so `pkill -x
|
||
gkeymapper-daemon` and `pgrep -x gkeymapper-daemon` **never match**. Use
|
||
`pkill -x gkeymapper-daem` / `pgrep -x gkeymapper-daem` (or `pkill -f
|
||
'./gkeymapper-daemon'`).
|
||
- Run it in the background with `setsid nohup ./gkeymapper-daemon [config]
|
||
> /tmp/daemon.log 2>&1 < /dev/null &`; it survives across shell calls. It
|
||
takes an optional config path as `argv[1]` (default
|
||
`~/.config/gKeyMapper/mappings.conf`).
|
||
- `SIGHUP`/`SIGUSR1` reload the mappings
|
||
(`kill -HUP $(pgrep -x gkeymapper-daem)`). Normally you do not need them: the
|
||
config file is watched, so saving in the GUI reloads within about half a
|
||
second. Use `SIGHUP` to check the signal path after touching it.
|
||
- If the systemd user service is enabled, **stop it first**
|
||
(`systemctl --user stop gkeymapper-daemon`) before starting the repo build by
|
||
hand: the daemon refuses to run when the bus name is taken (a second instance
|
||
would fight over the device). Restore it afterwards with
|
||
`systemctl --user start gkeymapper-daemon`. Note that the installed unit runs
|
||
`/usr/local/bin/gkeymapper-daemon`, so *that* binary is the old one until the
|
||
next `sudo make install`.
|
||
- D-Bus control channel (the daemon owns `dev.rager.gkeymapper.Daemon`):
|
||
|
||
```bash
|
||
D=dev.rager.gkeymapper.Daemon; O=/dev/rager/gkeymapper/Daemon
|
||
gdbus call --session --dest $D --object-path $O --method $D.GetStatus
|
||
gdbus call --session --dest $D --object-path $O --method $D.Reload
|
||
gdbus call --session --dest $D --object-path $O --method $D.TestMapping 0
|
||
gdbus monitor --session --dest $D # KeyPressed / ConfigReloaded / ...
|
||
```
|
||
|
||
`TestMapping` runs the same path as a real keypress, so it verifies a mapping
|
||
without hardware (index is 0-based, `0` = G1). A `TestMapping` for a
|
||
`disabled:`/empty row fails with `G_n_ has no usable mapping`. `busctl --user`
|
||
also works.
|
||
- The config watch is testable without the device: `daemon/config_watch.cpp` has
|
||
a standalone test shape (create a `ConfigWatcher`, `poll_events()` then
|
||
`take_change()` per simulated loop iteration), and `ConfigReloaded` on the
|
||
`gdbus monitor` above reports when a save was applied. A GUI save triggers two
|
||
reloads on purpose — the file watch and the explicit `Reload()` call.
|
||
- Decoding and the whole loop are also testable **without** the keyboard, which is
|
||
the fastest way to check hot-plug and the GUI footer states (plan §9):
|
||
- compile `daemon/device_tables.cpp` standalone and feed `decode_gkey_state()`
|
||
synthetic reports: single keys, a chord, a repeated (held) report, the release
|
||
report, and the families that must be rejected (memory keys `11 ff 09` /
|
||
`11 ff 0a`, command `11 ff 08 2e` and LED answers); cover `decode_media_key()`
|
||
with the `02 <bit>` presses, the release, a padded report and the same
|
||
families, which must *not* decode as media keys (see the bit table above);
|
||
- build the daemon with a **fake** `GKeyDevice`: keep the header, script
|
||
`open()`/`read_report()`, link `daemon/*.cpp` **without** `g910_device.cpp`
|
||
and without libusb. That runs the real loop, so it covers "no keyboard at
|
||
start", "device lost" and the reopen, emits real D-Bus signals and never
|
||
claims the real device — nothing touches the keyboard and no key is injected
|
||
into the focused window. Use a config with `command:` mappings only (a helper
|
||
script that dumps its environment is also how you check that a `command`
|
||
action sees `DISPLAY`); with `key:` mappings the fake would inject keys into
|
||
whatever window is focused.
|
||
Two details when the fake has to exercise `key:`/`keyhold:` mappings:
|
||
- **Copy `main.cpp` next to the fake**, e.g. `/tmp/…/fakesrc/main.cpp`, and put
|
||
the fake `g910_device.h` in an include directory. `#include "g910_device.h"`
|
||
searches the *including file's* directory first, so compiling the real
|
||
`daemon/main.cpp` would always pick up the real header (its inline
|
||
`is_open()` needs libusb).
|
||
- **Give the fake its own session bus** (`dbus-daemon --session --address=
|
||
unix:path=/tmp/…/fake_bus --fork --print-pid=1`, then
|
||
`DBUS_SESSION_BUS_ADDRESS=unix:path=…` for the fake). Otherwise it refuses
|
||
to start while the real daemon is running, and stopping the user service for
|
||
a test loses the media keys and the GUI footer.
|
||
- **Read the events back over X**, not from `/dev/input`: the event node of an
|
||
own uinput device has **no ACL** for the user (`/dev/uinput` does, its
|
||
children do not), so `open()` fails with `EACCES`. `xinput test <id>` works
|
||
without root; identify the new device by diffing `xinput list` ids before and
|
||
after (the name is the same as the installed daemon's virtual keyboard). X
|
||
keycodes are evdev + 8, and `xinput test` shows no `EV_SYN`, so
|
||
simultaneity of a chord cannot be read that way — the press/release order
|
||
and the durations can.
|
||
- Use inert keys: `f13`–`f24` are **not** in this layout (`Keymap::key_code`
|
||
returns -1), `pause` and `kp_equal` are. A held Shift for a few 100 ms is
|
||
harmless, a held Ctrl is not.
|
||
- D-Bus activation is only testable in a real setup: the installed
|
||
`share/dbus-1/services/dev.rager.gkeymapper.Daemon.service` needs
|
||
`sudo make install`. For a quick check without root, drop a file with
|
||
`Exec=<repo>/gkeymapper-daemon` (no `SystemdService=`) into
|
||
`~/.local/share/dbus-1/services/` — the session bus picks it up without a
|
||
restart — then call a method with no daemon running and watch it appear.
|
||
Remove that file afterwards, or it shadows the installed one.
|
||
- `make install DESTDIR=/tmp/stage` stages the packaging files; inspect
|
||
`/tmp/stage/usr/local/lib/...` and
|
||
`/tmp/stage/usr/local/share/dbus-1/services/...` to verify the `@BINDIR@`
|
||
substitution. `systemd-analyze --user verify <unit>` checks the unit. There is
|
||
no `udevadm verify` on systemd 249, so the udev rule is checked by eye against
|
||
the reference project's rule.
|
||
- Starting it detaches the kernel driver from the vendor interface and creates a
|
||
`/dev/uinput` keyboard. Warn the user first: `key` mappings are injected into
|
||
the **focused** window. The media keys are *not* affected: the keyboard reports
|
||
mute/volume/play only on that very interface (`…/input1`, measured — see below),
|
||
so the daemon replays those reports unchanged through its virtual keyboard.
|
||
Deleting that passthrough in `daemon/main.cpp` silently kills the media keys
|
||
while the daemon runs. Note that they are deliberately *not* a mapping and not
|
||
going to become one: making them remappable is decided against (plan §11), so do
|
||
not turn `mediaKeys` into config rows or GUI fields without that decision being
|
||
revisited first.
|
||
- Media keys cannot be observed over the keyboard's usual event node: with the
|
||
daemon stopped they appear on `event11` (`Phys …/input1`, created when `usbhid`
|
||
owns the interface), not on `event10` (`…/input0`); *both* nodes advertise the
|
||
consumer usages in their HID descriptors, so the capability bitmap proves
|
||
nothing. The authoritative data is the raw report on the `hidraw` node of
|
||
interface `1.1` (`usb-…-5.4.3/input1`, exists only while `usbhid` owns it):
|
||
`02 <bit>` per press with bit 0 `01` next, `02` previous, `04` stop, `08`
|
||
play/pause, `10` volume up, `20` volume down, `40` mute, and `02 00` for the
|
||
release. Verify the passthrough by reading `/tmp/daemon.log`: a press logs
|
||
`media -> mute` / `media -> volume up` / … and the desktop reacts as usual.
|
||
The bit table lives in `g910MediaKeys()` (`daemon/device_tables.cpp`).
|
||
- The keyboard is `046d:c32b` (also handle `046d:c335`); on this machine the USB
|
||
device and `/dev/uinput` already carry ACLs for the user, so no root is needed.
|
||
- Verify decoding by pressing G keys and reading `/tmp/daemon.log` (it logs
|
||
`G1 -> key:...` per press). Verify what the virtual keyboard emits at the X
|
||
level with `xinput test <keyboard-id>` (`gKeyMapper virtual keyboard` shows up
|
||
as both a pointer and a keyboard — use the **keyboard** id). X keycodes are
|
||
evdev codes + 8. There is no `xdotool`/`wtype`.
|
||
|
||
## Driving the GUI for manual checks
|
||
There is no `xdotool`/`wtype` on this machine, and the capture-dialog buttons
|
||
(`Clear`/`Cancel`/`Done`) expose an empty AT-SPI accessible name — the text is in
|
||
a child `label` node, so target the button by its child label. `pyatspi`
|
||
(`queryAction().doAction(0)`) plus `Xlib`'s `xtest.fake_input` can click buttons
|
||
and inject keys. Warn the user before synthesizing keystrokes or stealing window
|
||
focus.
|
||
|
||
The one-instance behavior needs no hardware: start the GUI twice and check that
|
||
one process (`pgrep -x gkeymapper`) and one window (`wmctrl -l`) are left. The
|
||
replaced process exits `0` when it was closed through the D-Bus `quit` action, or
|
||
`143` (`SIGTERM`) when it came from a build without that action — build such an
|
||
instance from an older commit (`git worktree add /tmp/legacy <commit>`), start it
|
||
and then start the current build next to it. Starting the GUI twice also covers
|
||
the `activate` guard: without it the second start adds a second window to the
|
||
running process.
|
||
|
||
The footer's daemon line is a plain `GtkLabel`, so its text can be read back over
|
||
AT-SPI: `<app> → frame → panel → label` whose name starts with the translated
|
||
`Daemon:` string. To pick the right window, filter the application whose tree
|
||
contains that label. A stale instance is not a problem any more: starting the
|
||
binary under test closes whatever is running (see the single-instance notes
|
||
above) before it shows its window, so it is safe to start it while an older GUI
|
||
is up. Three notes for tests:
|
||
- Clicking `Save mappings` writes `~/.config/gKeyMapper/mappings.conf` for real.
|
||
Since M5 the window loads that file at startup, so the rows show the saved
|
||
mappings and a save rewrites the same content; back the file up anyway (or skip
|
||
the click and call `Reload` over D-Bus instead).
|
||
- The `GtkEntry` texts are **not** readable over AT-SPI here (their text interface
|
||
answers with an empty string), so verify what the rows hold with a screenshot:
|
||
`import -window $(wmctrl -l | grep 'gKeyMapper – Logitech' | awk '{print $1}')
|
||
/tmp/gui.png`. The footer label works over AT-SPI (its accessible *name* is the
|
||
text), but a screenshot of the cropped footer is easier and shows what the user
|
||
sees.
|
||
- `XTest`-synthesized clicks need the window mapped and focused; the `Save`
|
||
button is `push button` + name `Mappings speichern` in the German locale.
|