Gromit-MPX for X11 and XWayland screen annotation

Gromit-MPX targets presentation and instructional annotation

Gromit-MPX solves a specific interaction problem: directing attention to a small interface element during a presentation without repeatedly moving the mouse pointer over it. Its annotation window can cover portions of the active application so the presenter can draw arrows, lines, and freehand marks over a button, control, diagram, or other area of interest.

The project is aimed at people presenting software or explaining a visual interface. The README describes use in presentations, while the repository topics also connect it with desktops such as GNOME, KDE, XFCE, MATE, Cinnamon, LXDE, Enlightenment, Unity, and ROX. Those topics indicate intended environments, but the README does not claim identical feature coverage in every one of them.

Gromit-MPX avoids placing a large permanent control panel over the desktop. Its visible interface is limited to a tray icon when the desktop provides a system tray. Most operation happens through global keyboard shortcuts or command-line controls, allowing the application being demonstrated to remain the main focus. This design is useful during teaching sessions, screen-recorded walkthroughs, and remote demonstrations where annotations need to appear immediately over live content.

X11, compositing, and XWayland define Gromit-MPX's display model

Gromit-MPX is not a browser extension or an annotation layer embedded into one presentation application. It places its drawing surface above other programs. Under X11, it uses the X11 display model and can take advantage of the XCOMPOSITE extension when the desktop compositor provides it. The README states that compositing should be available in contemporary X11 desktop environments and in every Wayland-based session because the application operates through XWayland there.

That distinction matters. The project supports Wayland sessions, but the documented path is XWayland rather than a native Wayland protocol implementation. It therefore occupies an X11 compatibility surface within the session. This explains its desktop independence while also defining its principal platform boundary.

Pointer support comes from the XInput2 extension and its Multi-Pointer-X functionality. This lets Gromit-MPX associate annotation behavior with more than one pointer. A separate pointer and keyboard can form a dedicated annotation control while the primary pointer continues operating the demonstrated application. Pressure-sensitive lines are supported when the input devices are properly configured through XInput, and a Wacom pen can use its other end for erasing when the hardware and configuration support that behavior.

Hotkeys and drawing mode control Gromit-MPX during a live session

By default, Gromit-MPX grabs `F9` and `F8`. The grabbed keys are unavailable to other applications while Gromit-MPX holds them. `F9` toggles painting, while `F8` undoes the latest stroke. Modified forms clear the screen, toggle annotation visibility, or quit the application.

The README does not provide a complete package-manager installation command. It points users to Flathub for the packaged application and states that the binary is named `gromit-mpx`. The documented command-line controls can be inspected by starting the program and using its tray icon or hotkeys. For a session involving a running instance, the README explicitly documents these controls:

gromit-mpx --toggle
gromit-mpx --clear
gromit-mpx --undo
gromit-mpx --redo

These commands toggle pointer capture, clear the annotation surface, undo the latest stroke, or redo the latest undone stroke. The documented interaction has an important cost. While painting is active, the application prevents mouse input from reaching other programs. Turning annotation mode off restores normal mouse use, but it does not remove existing annotations. This makes mode switching part of the presentation itself. A presenter must decide when to capture the pointer and when to release it, particularly when operating menus or controls beneath the annotation layer.

Command-line controls can draw explicit annotation lines

A second `gromit-mpx` invocation can control an already running process. This is more precise than relying only on hotkeys and is useful for scripts or repeated actions. Commands can quit the application, clear the annotation surface, toggle visibility, undo or redo strokes, toggle pointer capture, or draw a straight line with explicit coordinates, color, and thickness.

For example, this documented command draws a diagonal line between two screen coordinates:

gromit-mpx --line 200 200 400 400 '#C4A7E7' 6	

The color is passed as a quoted value, and the final argument sets thickness. Short forms are also documented, including `-q`, `-t`, `-v`, `-c`, `-z`, `-y`, and `-l`.

The annotation layer is not passive. When activated, it prevents other programs from receiving mouse input. The README explains that the next `gromit-mpx --toggle` deactivates Gromit-MPX, allowing normal program use while the painted regions remain visible. Existing marks therefore continue to obscure application content until cleared or hidden.

A second MPX pointer enables dedicated annotation control

Gromit-MPX supports a dedicated annotation device arrangement in which one pointer controls the application being demonstrated and another pointer activates drawing. The README recommends creating an additional master pointer with `xinput`, inspecting the assigned identifiers, and reattaching selected devices.

The documented setup sequence is:

xinput --create-master two
xinput --list
xinput --reattach <slave-id> <master-id-of-'two'>

The first command creates a second master named `two`. The second lists master and slave identifiers. The third requires the reader to replace `<slave-id>` and `<master-id-of-'two'>` with the values shown by `xinput --list`.

Attaching a keyboard slave to the second master allows that keyboard's hotkey to activate annotation mode for its associated pointer. This can preserve normal control through the primary pointer while annotating through another. Gromit-MPX also accepts `--toggle <device-number>`, but the number is its internal device number, not the XInput identifier. Confusing those two numbering systems is a practical setup risk. The README suggests the graphical `input-device-manager` as an alternative for arranging the MPX configuration.

Configuration is persistent, but history and key assignment have limits

Gromit-MPX uses `gromit-mpx.cfg` inside the directory selected by `$XDG_CONFIG_HOME`. The README identifies `~/.config` as the usual location and gives `~/.var/app/net.christianbeier.Gromit-MPX/config/` for the Flatpak installation. Key bindings and drawing tools are configurable through this file.

The main and undo keys can also be selected at startup. Each assignment accepts one keysym, not a full key combination. An empty value or `none` prevents Gromit-MPX from grabbing that key. This design offers limited customization, but it also means operators cannot express arbitrary multi-key chords through the documented command-line options.

Opacity is intentionally separate from `gromit-mpx.cfg`. The README describes it as a canvas property and says it is retained across restarts. It can be set from `0` to `1`:

gromit-mpx -o <opacity as real value in [0,1]>

Undo and redo are cumulative, but the maximum history is only four strokes. Two undo commands remove the last two strokes. That is a significant boundary for annotation-heavy sessions because the application does not provide the long stroke history users may expect from a general-purpose drawing package.

Native Wayland support, licensing, and upgrades frame adoption

The main limitation is the protocol boundary. Gromit-MPX supports GNOME, KDE, XFCE, and other Unix desktops under X11, while its Wayland support depends on XWayland. A workflow that requires a native Wayland annotation surface, or that prevents X11 compatibility applications from being used, falls outside the documented scope.

The project is licensed under `GPL-2.0`. The repository includes `COPYING`, which is the named license source. Teams planning to redistribute a modified or bundled version need to review that license and preserve the applicable notices and obligations. This article does not interpret what a particular deployment legally requires.

The repository is not archived, and the last push was on 2026-09-01. Releases listed in the repository are `1.7.0` from 2024-09-09, `1.8.0` from 2025-11-11, and `1.9.0` from 2026-03-18. The README directs returning users to `NEWS.md`, which is the appropriate place to check upgrade changes. Because `gromit-mpx.cfg` and remembered canvas opacity persist across restarts, operators should review configuration compatibility when moving between releases.

A real alternative is an application-native annotation feature, which avoids the global overlay and pointer-capture model. Gromit-MPX instead offers a desktop-wide layer and MPX-specific input arrangements, at the cost of an X11-oriented display model. The README mentions Epic Pen only as a repository topic and does not document a direct comparison, so specific feature differences beyond that architectural distinction cannot be confirmed.

Editorial conclusion

Gromit-MPX is a practical choice for presenters who need portable annotation across X11 and XWayland desktops, especially when multiple pointers or pressure-sensitive input matter. It is less suitable for users who require a native Wayland overlay or an unlimited undo history. Before adoption, verify hotkey availability, pointer behavior under your desktop, and whether the four-stroke undo limit fits your workflow.

Frequently asked questions

Official sources

1. bk138/gromit-mpx on GitHub
2. Issues
3. License: GPL-2.0
4. README
5. Releases