gKeyMapper/README.md

gKeyMapper

GTK4 application (C++) for remapping the G keys G1–G9 of a Logitech G910 to other keys or commands (Linux Mint / Ubuntu).

The current focus is on the GUI only (no actual key capture/command execution yet).

Documentation and source comments are written in English.

Requirements

• Linux Mint / Ubuntu
• g++ (C++17)
• pkg-config
• gettext (for translations, msgfmt)
• GTK 4 development files

Install dependencies

sudo apt update
sudo apt install -y build-essential gettext libgtk-4-dev

Afterwards pkg-config --modversion gtk4 should print a version (e.g. 4.6.x).

Setting up the project

Change to the project directory:

cd /home/trager/Nextcloud/Projekte/C++/gKeyMapper

(Alternatively clone the repository or copy the project folder to your own location.)

Build

make

This produces the gkeymapper binary and the .mo translations under locale/.

Rebuild translations

make translations

Run

Normal:

./gkeymapper

With explicit language files (useful for testing from the build directory):

LANG=de_DE.UTF-8 GKEYMAPPER_LOCALEDIR=$PWD/locale ./gkeymapper

Supported languages: German, English, Spanish, French.

Install (optional)

sudo make install

Installs gkeymapper to /usr/local/bin and the .mo files to /usr/local/share/locale.

Clean

make clean

Removes the binary and the generated locale/ directory.

Capturing key sequences

For rows of type Key, the action button opens a capture dialog:

• Press keys one after another; each press becomes one step.
• Modifier keys (Ctrl, Alt, Shift, Super) held during a press are recorded as part of that step.
• The live preview shows the sequence. Clear resets it, Done writes it into the row, Cancel discards it.

The sequence uses the same format as g910-gkey-macro-support: modifiers are joined with +, steps are separated with , (e.g. ctrl+c,ctrl+v or shift+f4,super+t).

Configuration format

Save mappings writes ~/.config/gKeyMapper/mappings.conf:

# gKeyMapper mappings (G1..G9)
G1=key:ctrl+c,ctrl+v
G2=command:/usr/bin/firefox
G3=disabled:

The same format is used by Export/Import. key holds a captured shortcut sequence, command a program or file path, disabled ignores the G key (similar to the shortcut / run / nothing hotkey types of the reference project above; a native C++ daemon for G-key detection and replay is planned next, no Python involved).

Project structure

src/main.cpp           # app actions + GUI
src/keyrow.h           # KeyRow / kNumKeys
src/mappings.{h,cpp}   # mappings.conf read/write
src/capturedialog.{h,cpp} # key-capture dialog
po/                    # Translations (pot/po/mo targets)
Makefile               # Build via pkg-config + gettext
.vscode/tasks.json     # VS Code tasks for make
README.md

Troubleshooting

Package gtk4 was not found

The GTK 4 development files are missing. Install them:

sudo apt install -y libgtk-4-dev

Then verify:

pkg-config --modversion gtk4

pkg-config cannot find .pc files (wrong search path)

In some environments PKG_CONFIG_PATH must be set explicitly. Standard path on Ubuntu/Mint:

export PKG_CONFIG_PATH=/usr/lib/x86_64-linux-gnu/pkgconfig:/usr/share/pkgconfig:/usr/lib/pkgconfig

Planned next steps

• Real capture of key presses (evdev/uinput or libinput).
• Execution of commands when a G key is pressed.
• Loading and saving profiles.
• Autostart service / background daemon.