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

```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           # 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:

```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.