Show Me The Key

Show Me The Key is split into two components to handle Wayland security requirements:

1. CLI Backend: A custom re-write of libinput-debug-events.c based on libinput, libudev, and libevdev. It runs with superuser permissions to read keyboard events directly from /dev/input/ (evdev interface). It outputs key events as JSON lines.
2. GTK Frontend: A GUI based on GTK that runs the CLI backend as root via pkexec. It displays the key events in a transparent floating window.

Note on Permissions: Because the program reads directly from the evdev interface to support Wayland, it requires root/superuser permissions. Users in the wheel group may skip password authentication via polkit.

Install showmethekey using your distribution's package manager. Recommended methods are provided for AOSC OS, Arch Linux, openSUSE, and Fedora.

### AOSC OS
# apt install showmethekey

### Arch Linux
# pacman -S showmethekey

### openSUSE (Tumbleweed)
# zypper ar https://download.opensuse.org/repositories/home:/AZhou/openSUSE_Tumbleweed/home:AZhou.repo
# zypper in showmethekey showmethekey-lang

### Fedora (COPR)
# sudo dnf copr enable pesader/showmethekey
# sudo dnf install showmethekey

To build from source, ensure you have the following dependencies installed: libevdev, udev (or systemd), libinput, glib2, gtk4, libadwaita, json-glib, cairo, pango, libxkbcommon, polkit, meson, ninja, and gcc.

Follow these steps to clone, configure, and install:

$ git clone https://github.com/AlynxZhou/showmethekey.git
$ cd showmethekey
$ mkdir build && cd build && meson setup --prefix=/usr . .. && meson compile && meson install
$ showmethekey-gtk

The GTK-based graphical interface is initialized via the main function, which sets up localization (locale and text domains) and instantiates the SmtkApp using smtk_app_new(). The application lifecycle is managed by the standard GLib g_application_run loop. To run the application, execute the compiled binary from your terminal.

# Assuming the binary is named 'showmethekey-gtk'
./showmethekey-gtk

The CLI is the backend component of Show Me The Key. It is designed to be run by a frontend (typically with elevated privileges like pkexec) rather than directly by users. It monitors input devices via libinput and outputs key/button events as JSON.

To stop the backend process, send the string stop\n to its stdin.

The CLI backend generates key event data in the following JSON format per line:

{"event_name": "KEYBOARD_KEY", "event_type": 300, "time_stamp": 39869802, "key_name": "KEY_C", "key_code": 46, "state_name": "PRESSED", "state_code": 1}

You can customize the behavior of the showmethekey-gtk application using command-line flags to control the default visibility of the settings and keys windows:

• -k: Show the keys window by default (hides the app/settings window).
• -A: Hide the app/settings window by default.
• -C: Make the keys window click-through by default (useful if you have configured compositor rules for position and layer).

$ showmethekey-gtk -k
$ showmethekey-gtk -A
$ showmethekey-gtk -C

The core of the GTK interface is the SmtkApp object. It is instantiated using the smtk_app_new() function. This object is a GApplication subclass that manages the application's lifecycle and UI components.

g_autoptr(SmtkApp) app = smtk_app_new();

The backend of Show Me The Key outputs keyboard and pointer button events as single-line JSON objects to stdout. This allows other processes (like a frontend) to parse the stream easily. Each event includes the event name, type, timestamp, key/button name, code, and state.

Note: The backend uses fflush(stdout) after every event to ensure real-time delivery when used in a pipe.

{
"event_name": "KEYBOARD_KEY", 
"event_type": %d, 
"time_stamp": %d, 
"key_name": "%s", 
"key_code": %d, 
"state_name": "%s", 
"state_code": %d
}

-- OR --

{
"event_name": "POINTER_BUTTON", 
"event_type": %d, 
"time_stamp": %d, 
"key_name": "%s", 
"key_code": %d, 
"state_name": "%s", 
"state_code": %d
}

The backend returns specific exit codes based on the failure mode:

• 0 (NO_ERROR): Success.
• UDEV_FAILED: Failed to initialize udev.
• LIBINPUT_FAILED: Failed to initialize libinput from udev.
• SEAT_FAILED: Failed to set the seat (defaults to seat0).
• PERMISSION_FAILED: Failed to handle events, likely due to insufficient permissions to access input devices.

The backend CLI supports the following flags:

• -h, --help: Display help information and version, then exit.
• -v, --version: Display the current project version, then exit.

Usage: showmethekey [OPTION…]

Options:
	-h, --help	Display help then exit.
	-v, --version	Display version then exit.