{"id":13436620,"url":"https://github.com/bk138/gromit-mpx","last_synced_at":"2025-05-14T18:05:10.794Z","repository":{"id":10025955,"uuid":"12067072","full_name":"bk138/gromit-mpx","owner":"bk138","description":"Gromit-MPX is an on-screen annotation tool that works with any Unix desktop environment under X11 as well as Wayland.","archived":false,"fork":false,"pushed_at":"2025-05-04T21:22:38.000Z","size":4723,"stargazers_count":1116,"open_issues_count":40,"forks_count":88,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-05-04T22:31:10.544Z","etag":null,"topics":["annotation","annotation-tool","cinnamon","drawing","enlightenment","epic-pen-alternative","gnome","kde","lxde","mate","multi-pointer","on-screen","rox","screen-annotation","unity","wayland","x11","xfce"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bk138.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null},"funding":{"issuehunt":"bk138/gromit-mpx","liberapay":"bk138","patreon":"bk138","custom":"https://www.paypal.com/donate?hosted_button_id=N7GSSPRPUSTPU"}},"created_at":"2013-08-12T21:47:24.000Z","updated_at":"2025-05-04T21:22:42.000Z","dependencies_parsed_at":"2023-10-20T18:28:06.758Z","dependency_job_id":"5381e49b-a892-4dde-858f-2b51161f0a4f","html_url":"https://github.com/bk138/gromit-mpx","commit_stats":{"total_commits":458,"total_committers":26,"mean_commits":"17.615384615384617","dds":0.5262008733624455,"last_synced_commit":"8da79062a7e1ce7eae06da2daa631e4b5e60bdf4"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bk138%2Fgromit-mpx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bk138%2Fgromit-mpx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bk138%2Fgromit-mpx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bk138%2Fgromit-mpx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bk138","download_url":"https://codeload.github.com/bk138/gromit-mpx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198514,"owners_count":22030965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotation","annotation-tool","cinnamon","drawing","enlightenment","epic-pen-alternative","gnome","kde","lxde","mate","multi-pointer","on-screen","rox","screen-annotation","unity","wayland","x11","xfce"],"created_at":"2024-07-31T03:00:50.750Z","updated_at":"2025-05-14T18:05:05.780Z","avatar_url":"https://github.com/bk138.png","language":"C","funding_links":["https://issuehunt.io/r/bk138/gromit-mpx","https://liberapay.com/bk138","https://patreon.com/bk138","https://www.paypal.com/donate?hosted_button_id=N7GSSPRPUSTPU","https://liberapay.com/bk138/donate","https://www.patreon.com/bk138","https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=N7GSSPRPUSTPU\u0026source=url"],"categories":["C"],"sub_categories":[],"readme":"# Gromit-MPX\n\n[![CI](https://github.com/bk138/gromit-mpx/actions/workflows/ci.yml/badge.svg)](https://github.com/bk138/gromit-mpx/actions/workflows/ci.yml)\n[![Help making this possible](https://img.shields.io/badge/liberapay-donate-yellow.png)](https://liberapay.com/bk138/donate)\n[![Become a patron](https://img.shields.io/badge/patreon-donate-yellow.svg)](https://www.patreon.com/bk138)\n[![Donate](https://img.shields.io/badge/paypal-donate-yellow.png)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick\u0026hosted_button_id=N7GSSPRPUSTPU\u0026source=url)\n[![Gitter](https://badges.gitter.im/gromit-mpx/community.svg)](https://gitter.im/gromit-mpx/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n\n[\u003cimg src=\"https://flathub.org/assets/badges/flathub-badge-i-en.png\" width=\"190px\" /\u003e](https://flathub.org/apps/details/net.christianbeier.Gromit-MPX)\n\nGromit-MPX is an on-screen annotation tool that works with any Unix\ndesktop environment under X11 as well as Wayland.\n\nIts main use is for making presentations of some application.\nNormally, you would have to move the mouse pointer around the point of\ninterest until hopefully everybody noticed it.  With Gromit-MPX, you\ncan draw everywhere onto the screen, highlighting some button or area.\n\n\u003cimg src=\"https://github.com/bk138/gromit-mpx/blob/master/data/on-gnome-wayland.png\" width=\"75%\" /\u003e\n\nKey features include:\n\n  * **Desktop-independent**. Gromit-MPX works with GNOME, KDE, XFCE, ...\n\tunder X11 (every desktop environment) as well as with a Wayland session\n    using XWayland (most desktop environments).\n  * **Hotkey-based**. The fundamental philosophy is that Gromit-MPX does not\n    get into your way of doing things by sticking some UI widget on your\n\tdesktop, potentially obscuring more important contents. It *does*\n\tprovide a UI, but only in form of a tray icon.\n  * **Configurable**. While Gromit-MPX comes with a default config, you are\n\tfree to change key bindings as well as drawing tool configuration.\n  * **Multi-Pointer**. Under X11, it enables graphical annotations with\n\tseveral pointers at once or a dedicated annotation device setup where\n\tyou can use a second pair of input devices to annotate while\n\tsimultaneously continuing to work normally with the first pair.\n  * **Fast**. Where available, Gromit-MPX makes use of Compositing. This\n\tshould be the case on any contemporary desktop environment making use\n\tof the XCOMPOSITE extension under X11 and with every Wayland-based session.\n\nThe name stands for (*GR*aphics *O*ver *MI*scellaneous *T*hings -\n*M*ulti-*P*ointer-E*X*tension). It is a multi-pointer port of the original\n[Gromit annotation tool](http://www.home.unix-ag.org/simon/gromit) by [Simon\nBudig](mailto:simon@budig.de).\n\nIf you already used Gromit-MPX, you probably want to read [NEWS](NEWS.md).\nThe roadmap for future developments can be found [here](https://github.com/bk138/gromit-mpx/milestones?state=open).\n\n## How to use it\n\nYou can operate Gromit-MPX using its tray icon (if your desktop environment\nprovides a sys tray), but since you typically want to use the program you\nare demonstrating and highlighting something is a short interruption of\nyour workflow, Gromit-MPX can be toggled on and off on the fly via a hotkey:\n\nPer default, it grabs the `F9` and `F8` keys, so that no other application\ncan use them and they are available to Gromit-MPX only.  The available\ncommands are:\n\n    F9:        toggle painting\n    SHIFT-F9:  clear screen\n    CTRL-F9:   toggle visibility\n    ALT-F9:    quit Gromit-MPX\n    F8:       undo last stroke\n    SHIFT-F8: redo last undone stroke\n\nYou can specify the keys to grab as hotkeys via:\n\n    gromit-mpx --key \u003ckeysym\u003e --undo-key \u003ckeysym\u003e\n\nNote that you can only specify single keysyms, not key combos. Specifying\nan empty string or `none` for the keysym will prevent Gromit-MPX from\ngrabbing a key.\n\nYou can specify the opacity simply via:\n\n    gromit-mpx -o \u003copacity as real value in [0,1]\u003e\n\nAs opacity is not a tool but a canvas property, it is not configured via\n`gromit-mpx.cfg` but remembered over restarts.\n\nAlternatively you can invoke Gromit-MPX with various arguments to\ncontrol an already running Gromit-MPX .\n\nUsage:\n\n    gromit-mpx --quit\n        will cause the main Gromit-Mpx-MPX process to quit (or \"-q\")\n    gromit-mpx --toggle \u003cdevice-number\u003e\n        will toggle the grabbing of all cursors (or \"-t\"). Optionally,\n        it toggles for the given internal device number (not XInput ID)\n        only.\n    gromit-mpx --visibility\n        will toggle the visibility of the window (or \"-v\")\n    gromit-mpx --clear\n        will clear the screen (or \"-c\")\n    gromit-mpx --undo\n        will undo the last drawing stroke (or \"-z\")\n    gromit-mpx --redo\n        will redo the last undone drawing stroke (or \"-y\")\n    gromit-mpx --line \u003cstartX\u003e \u003cstartY\u003e \u003cendX\u003e \u003cendY\u003e \u003ccolor\u003e \u003cthickness\u003e\n        will draw a straight line with characteristics specified by the arguments (or \"-l\")\n        eg: gromit-mpx -l 200 200 400 400 '#C4A7E7' 6\t\n\nIf activated Gromit-MPX prevents you from using other programs with the\nmouse. You can press the button and paint on the screen. Key presses\n(except the `F9`-Key, see above) will still reach the currently active\nwindow but it may be difficult to change the window-focus without mouse...\nThe next `gromit-mpx --toggle` will deactivate Gromit-MPX and you can\nuse your programs as usual - only the painted regions will be obscured.\n\nGromit-MPX is pressure sensitive, if you are using properly configured\nXInput-Devices you can draw lines with varying width.  It is\npossible to erase something with the other end of the (Wacom) pen.\n\nUndo/redo commands are cumulative. For example, sending two undo commands\nwill undo the last two strokes. The maximum undo/redo depth is 4 strokes.\n\n### Setting up multi-pointer\n\nAs its name implies, Gromit-MPX relies on Multi-Pointer-X functionality\nprovided by the XInput2 extension.\n\nYou can create a simple MPX setup via the `xinput` utility:\n\n    xinput --create-master two # create a second input focus (master)\n    xinput --list # see your master and slave devices and ids\n    xinput --reattach \u003cslave-id\u003e \u003cmaster-id-of-'two'\u003e # reattach slave\n\nIf you attach a keyboard slave device to the newly created second master,\nits hotkey will activate annotation mode for the associated pointer only.\nThis way, can use a second pair of input devices to annotate while\ncontinuing to work normally with the first pair. If you don't have a\nsecond keyboard at hand, you can also toggle a specific pointer via\n`--toggle \u003cdevice-number\u003e`, where device-number is Gromit-MPX's internal\ndevice number, not the XInput ID.\n\nAlternatively, you can also use the graphical tool [input-device-\nmanager](https://github.com/bk138/input-device-manager) to arrange your\nMPX setup.\n\n### Configuration\n\nGromit-MPX is configurable via the file `gromit-mpx.cfg` in the\ndirectory defined by `$XDG_CONFIG_HOME` (usually `~/.config` or\n`~/.var/app/net.christianbeier.Gromit-MPX/config/` if you installed\nthe Flatpak). Here you can specify which Device/Button/Modifier\ncombination invokes which tool. See the copy of `gromit-mpx.cfg`\ndistributed with this program for an example. An overview on the syntax:\n\n    # Comments can be either # Shell-Style or\n    /* C-Style. */\n\nThe `PEN`-tool is for freehand drawing.\n\n![PEN tool](data/tool-pen.webp)\n\nThe following entry defines the tool `red Pen`, a pen with size 7 and color red.\nYou can specify an RGB color in X-Style: e.g. `#FF0033`, specify an\nRGBA color like so: `rgba(0, 0, 255, 0.6)` or use color names from\n[`rgb.txt`](https://en.wikipedia.org/wiki/X11_color_names).\n\n    \"red Pen\" = PEN (size=7 color=\"red\");\n\nThe following Entries copy an existing configuration (in this case\n`red Pen`) and modify the color.\n\n    \"blue Pen\" = \"red Pen\" (color=\"blue\");\n    \"yellow Pen\" = \"red Pen\" (color=\"yellow\");\n\nIf you want another minimum size instead of the default 1, add `minsize`\nlike this:\n\n\t\"red Marker\" = \"red Pen\" (minsize=14);\n\nYou can set a maximum size as well:\n\n\t\"red Marker\" = \"red Pen\" (maxsize=20);\n\nBoth `minsize` and `maxsize` can be combined to define a tool that's\nnot allowed to change size:\n\n\t\"red fixed Marker\" = \"red Pen\" (minsize=10 maxsize=10);\n\nYou can also draw lines that start and/or end in an arrow head. For\nthis you have to specify `arrowsize` and optionally `arrowtype`.\n`arrowsize` is a factor relative to the width of the line. For\nreasonable arrowheads start with 1.\n`arrowtype` can take `start`, `end` or `double` and defaults to `end`\nwhen `arrowsize` is specified and no `arrowtype` given. \n\n    \"blue Pen\" = \"blue Arrow\" (arrowsize=2);\n\nAn `ERASER` is a tool that erases the drawings on screen.\nThe color parameter is not important.\n\n    \"Eraser\" = ERASER (size = 75);\n\nA `RECOLOR`-Tool changes the color of the drawing without changing\nthe shape. Try it out to see the effect.\n\n    \"green Marker\" = RECOLOR (color = \"Limegreen\");\n\nA `LINE`-tool draws straight lines.\n\n![LINE tool](data/tool-line.webp)\n\n    \"green Line\" = LINE (color = \"green\");\n\nA `RECT`-tool draws rectangles.\n\n![RECT tool](data/tool-rect.webp)\n\n    \"red Rectangle\" = RECT (color = \"red\");\n\nA `SMOOTH`-tool that behaves like `PEN` except that it produces smoothed curves.\nThe degree of smoothing can be specified using `simplify=N`. `N` can\nbe imagined as approximate pixel range around the resulting line \nwithin which intermediate points are \"simplified away\". Closed paths\ncan be drawn using the `snap=N` option where `N` indicates the maximum \ndistance between start and end point within which these \"snap\" together. \n\n![SMOOTH tool](data/tool-smooth.webp)\n\n    \"smoothed line\" = SMOOTH (color = \"red\" simplify=10 snap=30);\n\nA `ORTHOGONAL`-tool that behaves like `SMOOTH` except that it produces\nstraight line segments that automatically snap to perfectly horizontal\nand vertical direction when their direction deviated by a maximum of\n`maxangle` degrees. Transitions between straight segments are drawn as\narcs with a certain `radius`, if these segments exceed a length of\n`minlen`.\n\n![ORTHOGONAL tool](data/tool-orthogonal.webp)\n\n    \"ortho line\" = ORTHOGONAL (color=\"red\" size=5 simplify=15 radius=20 minlen=50 snap=40);\n\nIf you define a tool with the same name as an input-device\n(see the output of `xinput --list`) this input-device uses this tool:\n\n\t\"ELAN Touchscreen Pen (0)\" = \"red Pen\";\n\t\"ELAN Touchscreen Eraser (0)\" = \"Eraser\";\n\nAdditionally you can limit the Scope to specific combinations of\nMousebuttons (1,2,3,4,5 or Button1,...,Button5)\nand Modifiers (`SHIFT`, `CONTROL`, `ALT`, `META`, while `ALT==META`).\n\n    \"Core Pointer\" = \"red Pen\";\n    \"Core Pointer\"[SHIFT] = \"blue Pen\";\n    \"Core Pointer\"[CONTROL] = \"yellow Pen\";\n    \"Core Pointer\"[2] = \"green Marker\";\n    \"Core Pointer\"[Button3] = \"Eraser\";\n\nIf you want to limit drawing to a specific input device, define a\ntool with the same name as an input device like above and disable\ndrawing for all others by assigning a zero-width tool like this:\n\n\t\"no Pen\" = PEN (size=0);\n\t\"default\" = \"no Pen\";\n\n\nThe decision which tool to use follows a simple policy:\n\n1. Buttons are more important than Modifiers\n2. High number Buttons are more important than lower ones\n3. Modifiers: `SHIFT` \u003e `CONTROL` \u003e `ALT`/`META`.\n4. Gromit-MPX tries partial matches:\n      If you define `\"Core Pointer\"[]` and `\"Core Pointer\"[SHIFT, CONTROL]`\n      and only `SHIFT` actually is pressed, Gromit-MPX will use the second\n      definition if there is no `\"Core Pointer\"[SHIFT]` definition.\n      The same logic holds for the buttons.\n5. Slave device config takes precedence over master device config, which\n   in turn takes precedence over the fallback default config.\n   \nFor versions \u003e 1.3, you can also change the [hotkeys from the config](data/gromit-mpx.cfg#L5)\nfile by setting the respective `HOTKEY` and/or `UNDOKEY` values.\n\n### Autostart\n\nIf you want to have Gromit-MPX autostarted for your desktop session, the\nsafest way to do so is via the XDG autostart facility:\n\nSimply create a file `~/.config/autostart/gromit-mpx.desktop` with the\nfollowing contents:\n\n```\n[Desktop Entry]\nType=Application\nExec=gromit-mpx\n```\n\nIf you have the Flatpak installed, the last line needs to start with\n`Exec=flatpak run net.christianbeier.Gromit-MPX`. You can freely add\ncommand line arguments to the 'Exec' stanza, configuring the autostarted\ninstance to your needs.\n\n## Building it\n\nGromit-MPX uses CMake as its build system. Thus, it's the usual:\n\n    mkdir build\n    cd build\n    cmake ..\n    make\n    make install\n\nfrom the root of the source tree.\n\n### Release Checklist\n\n* [ ] Update NEWS.\n* [ ] Increment version in CMakeLists.txt\n* [ ] Update Copyright year in About dialog.\n* [ ] Update authors in About dialog and AUTHORS file.\n* [ ] Update AppStream.\n* [ ] Update ChangeLog.\n* [ ] Fill out GitHub release.\n* [ ] Make Flathub release.\n* [ ] Announce on social.\n\n## Potential Problems\n\n* XFCE per default grabs Ctrl-F1 to Ctrl-F12 (switch to workspace 1-12)\n  and Alt-F9 (minimize window) which renders Gromit-MPX's default hotkey\n  mapping unusable. Gromit-MPX detects XFCE and changes the default hotkeys\n  to Home and End. Those can can still be overridden by the user. In case\n  you're using XFCE 4.14 or newer, chances are that all 'special' keys are\n  grabbed by XFCE itself, which means you'll have to modify XFCE's keybindings\n  (Settings-\u003eWindow Manager-\u003eKeyboard) manually in order to 'make room' for\n  Gromit-MPX's ones.\n\n* When there is no [compositing manager](https://en.wikipedia.org/wiki/Compositing_window_manager)\n  such as Mutter or KWin running, Gromit-MPX falls back to a legacy drawing mode. This may\n  drastically slow down your X-Server, especially when you draw very\n  thin lines. It makes heavy use of the shape extension, which is\n  quite expensive if you paint a complex pattern on screen. Especially\n  terminal-programs tend to scroll incredibly slow if something is\n  painted over their window.\n\n* If Gromit-MPX under Wayland complains about \"cannot open display\", make\n  sure you have XWayland runnning or its autostart configured. Gromit-MPX\n  needs XWayland when running in a Wayland session.\n\n* In case you encounter any other kind of problem, please check if it's in\n  the [list of known bugs](https://github.com/bk138/gromit-mpx/issues?q=is%3Aissue+is%3Aopen+label%3Abug).\n  You can help by reporting a new one or adding info to an existing one.\n\n## Similar Tools\n\nIn the Unix-world, similar but different tools are *Ardesia*, *Pylote*\nand *Draw On You Screen*.\n\nSimilar tools for MS-Windows include *DemoHelper* (GPLv2 also), or\nproprietary tools like *ZoomIt*, *ScreenMarker* or *EpicPen*.\n\n## License\n\nLike the original Gromit, this program is distributed under the Gnu\nGeneral Public License.  See the file `COPYING` for details.  Thanks\nto Simon for the groundwork done!\n\n---[Christian Beier](mailto:gromit-mpx@christianbeier.net)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbk138%2Fgromit-mpx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbk138%2Fgromit-mpx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbk138%2Fgromit-mpx/lists"}