157 lines
3.4 KiB
Markdown
157 lines
3.4 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
cd /home/trager/Nextcloud/Projekte/C++/gKeyMapper
|
||
```
|
||
|
||
(Alternatively clone the repository or copy the project folder to your own location.)
|
||
|
||
## Build
|
||
|
||
```bash
|
||
make
|
||
```
|
||
|
||
This produces the `gkeymapper` binary and the `.mo` translations under `locale/`.
|
||
|
||
## Rebuild translations
|
||
|
||
```bash
|
||
make translations
|
||
```
|
||
|
||
## Run
|
||
|
||
Normal:
|
||
|
||
```bash
|
||
./gkeymapper
|
||
```
|
||
|
||
With explicit language files (useful for testing from the build directory):
|
||
|
||
```bash
|
||
LANG=de_DE.UTF-8 GKEYMAPPER_LOCALEDIR=$PWD/locale ./gkeymapper
|
||
```
|
||
|
||
Supported languages: German, English, Spanish, French.
|
||
|
||
## Install (optional)
|
||
|
||
```bash
|
||
sudo make install
|
||
```
|
||
|
||
Installs `gkeymapper` to `/usr/local/bin` and the `.mo` files to
|
||
`/usr/local/share/locale`.
|
||
|
||
## Clean
|
||
|
||
```bash
|
||
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](https://github.com/JSubelj/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 # GTK4 GUI
|
||
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:
|
||
|
||
```bash
|
||
sudo apt install -y libgtk-4-dev
|
||
```
|
||
|
||
Then verify:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
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.
|