{"id":18668640,"url":"https://github.com/kstenschke/xmchord","last_synced_at":"2025-04-12T00:24:00.429Z","repository":{"id":60116883,"uuid":"183263371","full_name":"kstenschke/xmchord","owner":"kstenschke","description":"Linux desktop automation shortcuts via mouse/trackball+keyboard chording","archived":false,"fork":false,"pushed_at":"2022-10-07T06:16:41.000Z","size":2279,"stargazers_count":28,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T20:11:55.984Z","etag":null,"topics":["chording","driver","expert","expert-mouse","kensington","launcher","linux","mouse","mouse-buttons","observer","productivity","shortcut-actions","trackball","x-windows","x11"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kstenschke.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-24T16:06:01.000Z","updated_at":"2024-10-29T18:20:21.000Z","dependencies_parsed_at":"2022-09-25T22:43:22.165Z","dependency_job_id":null,"html_url":"https://github.com/kstenschke/xmchord","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstenschke%2Fxmchord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstenschke%2Fxmchord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstenschke%2Fxmchord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kstenschke%2Fxmchord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kstenschke","download_url":"https://codeload.github.com/kstenschke/xmchord/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248498613,"owners_count":21114157,"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":["chording","driver","expert","expert-mouse","kensington","launcher","linux","mouse","mouse-buttons","observer","productivity","shortcut-actions","trackball","x-windows","x11"],"created_at":"2024-11-07T08:44:25.811Z","updated_at":"2025-04-12T00:24:00.391Z","avatar_url":"https://github.com/kstenschke.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"xmchord\n=======\n\n[![Platform](https://img.shields.io/badge/platform-linux-blue)](#)\n[![License](https://img.shields.io/badge/License-new%20BSD-blue)](https://github.com/kstenschke/xmchord/blob/master/LICENSE)\n[![Written in C++](https://img.shields.io/badge/written%20in-C++-blue)](#) \n\n[![Build Status](https://travis-ci.com/kstenschke/xmchord.svg?branch=master)](https://travis-ci.com/kstenschke/xmchord)\n[![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/kstenschke/xmchord.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/kstenschke/xmchord/context:cpp)\n[![CodeFactor](https://www.codefactor.io/repository/github/kstenschke/xmchord/badge)](https://www.codefactor.io/repository/github/kstenschke/xmchord)\n\n\nxmchord is a productivity tool for Linux desktops, that binds custom\nactions to `chording*` events of mouse buttons and key presses: this way, \nmouse buttons become additional modifier keys. \n\n**`*Chording:`** Chording generally means pushing several keys or buttons\nsimultaneously to achieve a result.\n\nxmchord comes with a comprehensive set of shortcut **actions to automate and speed-up\n user activities** that are common on the Linux desktop.\n\n\n## Table of contents\n\n* [What does it do?](#what-does-it-do)\n* [Usage and arguments](#usage-and-arguments)\n * [Command: `help`](#command-help)\n * [Command: `debug`](#command-debug)\n * [Command: `actions`](#command-actions)\n * [Argument: `--keyboard`](#argument---keyboard)\n * [Command: `listDevices`](#command-listdevices)\n * [Command: `printPreferences`](#command-printpreferences)\n * [Command: `reset`](#command-reset)\n * [Command: `version`](#command-version)\n* [Included shortcut actions](#included-shortcut-actions)\n * [Third party dependencies](#third-party-dependencies)\n * [Global actions](#global-actions-not-application-specific)\n + [Application launchers](#application-launchers)\n + [Various global actions](#various-global-actions)\n * [Application specific actions](#application-specific-actions)\n * [Chrome, Chromium and Firefox Web-Browser](#chrome-chromium-and-firefox-web-browser)\n + [Advanced browser action: Toggle URL sub string](#advanced-browser-action-toggle-url-sub-string)\n * [Claws Mail](#claws-mail)\n * [Gnome Terminal](#gnome-terminal)\n + [Terminal command snippets](#terminal-command-snippets)\n * [Gnome Screenshot](#gnome-screenshot)\n * [Mattermost Desktop Client](#mattermost-desktop-client)\n * [Thunderbird](#thunderbird)\n + [Advanced global-actions](#advanced-global-actions) \n * [Open generic URL](#open-generic-url)\n * [Archived/inactive actions](#archivedinactive-actions)\n* [Build from source](#build-from-source)\n* [Code Convention](#code-convention)\n* [Contributing](#contributing)\n* [Bug Reporting and Feature Requests](#bug-reporting-and-feature-requests)\n* [Changelog](#changelog)\n* [Third Party References](#third-party-references)\n * [Build tools and Continuous Integration](#build-tools-and-continuous-integration)\n* [Author and License](#author-and-license)\n* [Addendum I: Linux trackball configuration snippets](#addendum-i-linux-trackball-configuration-snippets)\n* [Addendum II: Action shell scripting tricks](#addendum-ii-action-shell-scripting-tricks)\n * [1. User-specific actions](#1-user-specific-actions)\n * [2. Launching applications and switching windows](#2-launching-applications-and-switching-windows)\n * [3. Triggering window actions](#3-triggering-window-actions)\n * [4. Application specific shortcut actions](#4-application-specific-shortcut-actions)\n\n## What does it do?\n\nxmchord listens for events of mouse buttons pressed together with keyboard keys.\nWhen observing a chording event, xmchord generates an identifier code for the\ngiven combination (and order) of button/key presses. \nIf there is a shell script file named by the current event code within \nxmchord's `actions` directory, it is executed.\n\n\n## Usage and arguments\n\nUsage is: `sudo xmchord` \n\nTo ensure read-access to Linux device events, xmchord must be run with root\nprivileges (e.g. via`sudo`).\nAction shell scripts that perform user specific tasks, therefor must take care \nof [running on that user's behalf](#1-user-specific-actions).\n\n\n### Command: `help`\n\nRunning `xmchord help` or `xmchord h`, displays a list and explanation of\navailable commands.\n\n\n### Command: `debug`\n\nRunning `xmchord debug` or `xmchord d`, activates tracing of event codes.\nWhile in debug mode, action shell script files can be added without having to\nstop and restart xmchord.\n\nIn regular mode, xmchord reduces processing time by indexing which actions are\navailable during startup.\n\n\n### Command: `actions`\n\nRunning `xmchord actions` or `xmchord a`, lists all recognized action shell\nscripts, including their inlined description comments (which must be prefixed \nwith `#:`).\n\n\n### Argument: `--keyboard`\n\nxmchord by default installs its keyboard watcher upon the 1st keyboard device\nfound (e.g. on laptops the built-in one). This optional argument allows setting\na specific keyboard device to be used.\nxmchord stores this device preference, so once it is set, xmchord continues\nusing that device when restarted later. \n \nRunning `xmchord -k=/path/to/my/keyboard` or \n`xmchord --keyboard=/path/to/my/keyboard` selects the device at the given path\nas the keyboard watcher's target. \n**Tip:** xmchord's device detection is looking for a matching substring, \ntherefore the device-identifier can also be given w/o a path, e.g:\n`xmchord -k=Logitech`.\n\n\n### Command: `listDevices`\n\nRunning `xmchord listDevices` or `xmchord l` lists paths of available devices.\n\n\n### Command: `printPreferences`\n\nRunning `xmchord printPreferences` or `xmchord p` outputs xmchord's preferences\nif given, or a respective info if not.\n\n\n### Command: `reset`\n\nRunning `xmchord reset` or `xmchord r` unsets xmchord's keyboard device \npreference.\n\n\n### Command: `version`\n\nRunning `xmchord version` or `xmchord v`, tests whether xmchord is available\nand displays it's version number.\n\n\n## Included shortcut actions\n\nSee files under `bin/actions`\n\nThe included shortcut actions are scripted for use with a \n[**Kensington Expert Mouse trackball**](https://www.kensington.com/p/products/control/trackballs/expert-mouse-wired-trackball), \ntested on Linux Mint Cinnamon, but should be compatible or easily\nadjustable for other devices and Linux distributions and desktop environments.\n\n\n### Third party dependencies\n\nThe following third party dependencies must be installed for\nall included actions to work:\n\n| Application | Description |\n|-----------------------------------------------------------------|-----------------------------------------------------------------------------------|\n| [aosd-cat of libaosd](https://github.com/atheme-legacy/libaosd) | Display TEXT, or standard input, on top of display |\n| [feh](https://feh.finalrewind.org/) | Image viewer aimed mostly at console users to simply display images w/o fancy GUI |\n| [sed](https://manpages.debian.org/buster/sed/sed.1.en.html) | Stream editor for filtering and transforming text |\n| [wmctrl](http://tripie.sweb.cz/utils/wmctrl/) | Command line tool to interact with an EWMH/NetWM compatible X Window Manager |\n| [xdotool](https://www.semicomplete.com/projects/xdotool/) | Fake keyboard/mouse input, window management, and more |\n| [xsrel](https://linux.die.net/man/1/xsel) | Manipulate the X selection (Clipboard) |\n| [xclip](https://github.com/astrand/xclip) | Interface to X selections (\"the clipboard\") from the command line. |\n\n\n**Install dependencies that are not included in Linux Mint distribution by default:** \n\n````bash\nsudo apt install aosd-cat feh xclip xdotool xsel -y\n````\n\n\n### Global actions (not application specific)\n\n**Symbols are:**\n\n◤ ◥ = Top buttons left / right \n◣ ◢ = Bottom buttons left / right\n\n\n#### Application launchers\n\nThese actions launch applications, or bring re-focus their window, if already\nrunning (like the behavior on Mac OS). \n\n| **Shortcut** | **Description** |\n|--------------------------------|---------------------------------------------------------------------|\n| ◤ + G | Summon default email client (like mail key on keyboard) |\n| ◤ + M | Bring Mattermost desktop client to front, launch if not yet running |\n| ◤ + O | Bring Orange-player to front, launch if not yet running |\n| ◤ + W | Summon default web browser (like browser key on keyboard) |\n| ◣ + C | Launch or bring Chromium to front |\n| ◣ + D | Launch or bring DataGrip to front |\n| ◣ + F | Launch or bring Firefox to front |\n| ◣ + K | Launch or bring Kitematic to front |\n| ◣ + M | Launch or bring Claws Mail to front |\n| ◣ + Y | Bring CherryTree to front, launch if not yet running |\n| ◣ + Esc | Launch or bring System Monitor to front |\n\n\n#### Various global actions\n\n| **Shortcut** | **Description** |\n|--------------------------------|--------------------------------------------------------------------------------|\n| ◤ + ← | Go to workspace left of current (Hit SUPER+SHIFT+Left) |\n| ◤ + → | Go to workspace left of current (Hit SUPER+SHIFT+Right) |\n| ◤ + ◣ | Jump to next workspace |\n| Right Shift + ◤ + ◣ | Jump to previous workspace |\n| ◣ + ◢ | Touch bottom-right hot-corner (E.g. expose windows) |\n| ◣ + I | Display public and private IP and wifi MAC address, copy public IP address |\n| ◣ + L | Toggle keyboard backlight |\n| ◣ + R | Toggle active window roll-up state |\n| ◣ + S | Toggle active window \"roll-sideways\" state |\n| ◣ + T | Toggle active window always-on-top state |\n| ◣ + U | Type current UNIX timestamp |\n| ◣ + V | Toggle active window always-on-visible-workspace state |\n| ◣ + W | Hit CTRL+W (close window) |\n| ◣ + Ä | Type large A-umlaut (helpful e.g. on swiss keyboards) |\n| ◣ + Ö | Type large O-umlaut (helpful e.g. on swiss keyboards) |\n| ◣ + Ü | Type large U-umlaut (helpful e.g. on swiss keyboards) |\n| ◣ + 0 | Move active window to workspace 0 |\n| ◣ + 1 | Move active window to workspace 1 |\n| ◣ + 2 | Move active window to workspace 2 |\n| ◣ + 3 | Move active window to workspace 3 |\n| ◣ + 4 | Move active window to workspace 4 |\n| ◣ + 8 | Move caret eight times to the right (helpful e.g. to crop git hashes quickly) |\n| ◣ + ← | Focus previous tab |\n| ◣ + → | Focus next tab |\n| ◣ + ↑ | Scroll to top (same as home key) |\n| ◣ + ↓ | Scroll to bottom (same as end key) |\n| ◣ + Numpad \"-\" | Toggle play/pause audio |\n| ◣ + Numpad 7 | Tile active window to top-left 50% of screen |\n| ◣ + Numpad 8 | Tile active window to top 50% of screen |\n| ◣ + Numpad 9 | Tile active window to top-right 50% of screen |\n| ◣ + Numpad 6 | Tile active window to right 50% of screen |\n| ◣ + Numpad 3 | Tile active window to bottom-right 50% of screen |\n| ◣ + Numpad 2 | Tile active window to bottom 50% of screen |\n| ◣ + Numpad 1 | Tile active window to bottom-left 50% of screen |\n| ◣ + Numpad 4 | Tile active window to left 50% of screen |\n| ◣ + Numpad 5 | Maximize active window |\n| ◣ + ' | Output name of application of focused window (to terminal) |\n| ◣ + $ | Convert selected text to all upper/lower case |\n| ◣ + ENTER | Click left mouse button three times (select line) |\n| \u0026nbsp; \u0026nbsp; ◢ + A | Select all (same as CTRL+A) |\n| \u0026nbsp; \u0026nbsp; ◢ + C | Copy (same as CTRL+C) |\n| \u0026nbsp; \u0026nbsp; ◢ + F | Find (same as CTRL+F) |\n| \u0026nbsp; \u0026nbsp; ◢ + V | Paste (same as CTRL+V) |\n| \u0026nbsp; \u0026nbsp; ◢ + X | Cut (same as CTRL+X) |\n| \u0026nbsp; \u0026nbsp; ◢ + Y | Redo (same as CTRL+Y) |\n| \u0026nbsp; \u0026nbsp; ◢ + Z | Undo (same as CTRL+Z) |\n| \u0026nbsp; \u0026nbsp; ◢ + Numpad 4 | Move active window to screen left of current |\n| \u0026nbsp; \u0026nbsp; ◢ + Numpad 6 | Move active window to screen right of current |\n| \u0026nbsp; \u0026nbsp; ◢ + Numpad Plus | Zoom in (same as CTRL+Plus) |\n| \u0026nbsp; \u0026nbsp; ◢ + Numpad Minus | Zoom out (same as CTRL+Minus) |\n| \u0026nbsp; \u0026nbsp; ◢ + ↑ | Increase audio volume |\n| \u0026nbsp; \u0026nbsp; ◢ + ↓ | Decrease audio volume |\n\n\n### Application specific actions\n\nFor these actions to be triggered, a window of the respective application must\nbe focussed when the shortcut is fired.\n\n\n#### Chrome, Chromium and Firefox Web-Browser\n\n| **Shortcut** | **Description** |\n|------------------------------|----------------------------------------------|\n| ◤ + D | Show downloads |\n| ◤ + R | Reload |\n| ◤ + L \u0026nbsp; or \u0026nbsp; ◤ + U | Focus URL field |\n| ◣ + ← | Focus previous tab (browser and DevTools) |\n| ◣ + → | Focus next tab (browser and DevTools) |\n| Right-CTRL + ◣ + ← | Focus previous tab, than reload it |\n| Right-CTRL + ◣ + → | Focus next tab, than reload it |\n| ◣ + , | Decrement numeric ending of current URL by 1 |\n| ◣ + . | Increment numeric ending of current URL by 1 |\n| ◣ + Backspace | Remove trailing segment from current URL |\n| ◣ + C | Copy trailing segment of current URL |\n| ◣ + D | Duplicate active tab |\n| ◣ + H | Toggle HTML \"view-source\" of current URL |\n| ◣ + N | Move active tab to new window |\n| ◣ + RETURN | Browse for selected text in new tab |\n| \u0026nbsp; \u0026nbsp; ◢ + ← | Go URL backwards |\n| \u0026nbsp; \u0026nbsp; ◢ + → | Go URL forward |\n| \u0026nbsp; \u0026nbsp; ◢ + F4 | Close active tab |\n\n\n##### Advanced browser action: Toggle URL sub string\n\n| **Shortcut** | **Description** |\n|--------------------------------|-----------------------------|\n| ◣ + \\[-\\] | Toggle URL sub string |\n\nWhen running this action while the current browser URL contains one of two\nsub strings, it is been replaced by the other and the browser reloaded.\n\nThe following environment variables must be set in your `/etc/environment`:\n\n`sudo nano /etc/environment`\n\n````sh\nPATH=\"/usr/local/sbin:...\"\n\nXMCHORD_URL_SUBSTR_1='http://localhost'\nXMCHORD_URL_SUBSTR_2='https://yoururl.com'\n````\n\nFor changes to take effect after editing `/etc/environment` reload it and\nrestart xmchord.\n\n\n#### Claws Mail\n\n| **Shortcut** | **Description** |\n|---------------------|----------------------------------------------------------------|\n| ◣ + F | Open \"Search Folder\" popup |\n| ◣ + H | Toggle \"Hide read messages\", precondition: \"thread view\" must be deactivated |\n\n\n#### Gnome Terminal\n\n| **Shortcut** | **Description** |\n|--------------|----------------------------------------------------------------|\n| ◤ | Close active tab |\n| ◣ + F | Open `Find` popup |\n| ◣ + Numpad / | Insert 40 empty lines (helpful to separate sections of output) |\n| ◣ + ← | Focus previous tab |\n| ◣ + → | Focus next tab |\n| ◣ + ↑ | Scroll to top |\n| ◣ + ↓ | Scroll to bottom |\n\n#### Terminal command snippets\n\n| **Shortcut** | **Description** |\n|----------------------------|---------------------------------------------------------------------------------------------------------|\n| ◣ + C | Type and execute command to `cd` into a favorite local path |\n| ◣ + D | Type `scp` command to recursively download remote directory |\n| ◣ + L | Shortcut to wipe a cache directory: Type and execute command to clean a preferred path by executing `rm -rf` upon it. |\n| ◣ + S | Type and execute command to connect to preferred SSH host and `cd` into preferred path |\n| ◣ + SPACE | Type `yes` and hit ENTER |\n| ◣ + U | Type `scp` command to recursively upload local directory to remote |\n| ◣ + X | Type `exit` and hit ENTER |\n\nFor the `cd`, `rm -rf`, `scp` and `ssh` shortcut snippets, the following environment variables \nmust be set in your `/etc/environment`:\n\n`sudo nano /etc/environment`\n\n````sh\nPATH=\"/usr/local/sbin:...\"\n\nXMCHORD_CD_FAVORITE=/home/john/Projects/myProject\n\nXMCHORD_RM_FAVORITE=/home/john/Projects/myProject/var/cache\n\nXMCHORD_SCP_REMOTE=johndoe@yourhost:/var/www\nXMCHORD_SCP_LOCAL=/home/john/yourhost_var_www\n\nXMCHORD_SSH_REMOTE=johndoe@yourhost\nXMCHORD_SSH_REMOTE_NEEDS_CONFIRMATION=1\nXMCHORD_SSH_REMOTE_PATH_INITIAL=/var/www\n````\n\nFor changes to take effect, restart xmchord after editing your \n`/etc/environment`.\n\n\n#### Gnome Screenshot\n\nThese actions automate the steps for transferring screenshots made with \nGnome Screenshot into other applications. \nFor them to work, the mouse must be hovering Gnome Screenshot's \n`copy to clipboard` button when fired. \n\n| **Shortcut** | **Description** |\n|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ◣ + AltGr | Click and hit [Esc] = Copy to clipboard and close Gnome Screenhot popup at once |\n| ◣ + G | Click, hit [Esc], focus Gimp (if running) and paste image from clipboard as new image |\n| \u0026nbsp; \u0026nbsp; ◢ + V | **View as \"sticky note:\"** Click, hit [Esc], store clipboard to temporary image file and open image file in feh Image Viewer, Set feh window always-on-top and always-on-visible-workspace. |\n\n\n#### Mattermost Desktop Client\n\n| **Shortcut** | **Description** |\n|--------------|--------------------------------|\n| ◣ + M | Open \"direct messages\" popup |\n| ◣ + U | Upload files |\n| ◣ + W | Type \":wave:\" |\n| ◣ + . | Next unread channel |\n| ◣ + 1 | Type \":+1:\" (= thumbs-up icon) |\n\n\n#### Thunderbird\n\n| **Shortcut** | **Description** |\n|--------------|-------------------------------|\n| ◣ + B | Open address book |\n| ◣ + F | Open \"Search Messages\" popup |\n\n\n## Advanced global actions\n\nThese actions differ from the basic global actions, in that they require some manual configuration,\nas described here.\n\n\n### Open generic URL\n\nThis action adds text from a currently given text-selection to a preset URL, \nand loads the resulting URL in the web browser (chromium by default).\n\n| **Shortcut** | **Description** |\n|--------------|----------------------------------------------------------------------|\n| ◣ + O | Open generic URL in browser. Precondition: a text selection is given |\n\nThe following environment variable must be set in your `/etc/environment`:\n\n`sudo nano /etc/environment`\n\n````sh\nPATH=\"/usr/local/sbin:...\"\n\nXMCHORD_GENERIC_URL='https://www.your-domain.com/?id=SELECTED_TEXT'\n````\n\nWhen running this action, ``SELECTED_TEXT`` will be replaced by your text \nselection.\n\nFor changes to take effect after editing `/etc/environment` reload it and\nrestart xmchord.\n\nTo use a different browser, edit script: ``0220022-24.sh``\n\n\n### Archived/inactive actions\n\nSome additional actions that aren't active by default can be found within\nthe ``actions/inactive`` directory.\n\n\n## Build from source\n\n``cmake CMakeLists.txt; make``\n\n\n## Code Convention\n\nThe source code of xmchord follows the Google C++ Style Guide, see: \nhttps://google.github.io/styleguide/cppguide.html \nThe source code of action shell script files follows the Google Shell Style\nGuide, see https://google.github.io/styleguide/shell.xml\n\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n\n## Bug Reporting and Feature Requests\n\nIf you find a bug or have an enhancement request, please file an issue on the\ngithub repository.\n\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md)\n\n\n## Third Party References\n\n[Expert Mouse® Trackball](https://www.kensington.com/p/products/electronic-control-solutions/trackball-products/expert-mouse-wireless-trackball/) \nis a registered trademark of Kensington Computer Products Group, a division of \nACCO Brands\n\nThe example action for window arrangement uses splitDesk.sh, \nbased on the \n[original script](https://gist.github.com/culyun/a7347a58168a75ba8c06f1ddd67cf06d) \nby Steve Simpson.\n\n\n### Build tools and Continuous Integration\n\nThe following third party tools are used for building xmchord with automatic\ncontrol over code quality and standards: \n\n| Tool or Service | Description | License |\n| ----------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| [Clang](https://clang.llvm.org) | A C language family frontend for LLVM | [Apache License](https://www.apache.org/licenses/) | \n| [Cmake](https://cmake.org) | Family of tools designed to build, test and package software | [New BSD License](https://en.wikipedia.org/wiki/New_BSD_License) | \n| [Cppcheck](http://cppcheck.sourceforge.net/) | Static analysis tool for C/C++ code | [GNU General Public License version 3](https://www.gnu.org/licenses/gpl-3.0.html) | \n| [cpplint](https://github.com/cpplint/cpplint) | Static code checker for C++ | [BSD-3 Clause](https://opensource.org/licenses/BSD-3-Clause) | \n| [GCC](https://gcc.gnu.org) | GCC, the GNU Compiler Collection | [GNU General Public License version 3](https://gcc.gnu.org/onlinedocs/libstdc++/manual/appendix_gpl.html) | \n| [lgtm automated code review](https://lgtm.com/) | Code analysis platform for finding zero-days and preventing critical vulnerabilities | [lgtm Terms of Service](https://lgtm.com/tos) | \n| [ShellCheck](https://github.com/koalaman/shellcheck) | ShellCheck, a static analysis tool for shell scripts | [GNU General Public License version 3](https://gcc.gnu.org/onlinedocs/libstdc++/manual/appendix_gpl.html) | \n| [Tavis CI](https://travis-ci.org/) | Test and Deploy Your Code with Confidence | [Travis CI Contact \u0026 Legal Inquiries](https://www.ideracorp.com/legal/TravisCI) | \n\nThanks a lot!\n\n\n## Author and License\n\nWritten by Kay Stenschke.\nxmchord is licensed under the [New BSD License](http://opensource.org/licenses/BSD-3-Clause)\n\n\n\u003e Copyright (c), Kay Stenschke\n\u003e All rights reserved.\n\u003e\n\u003e Redistribution and use in source and binary forms, with or without modification,\n\u003e are permitted provided that the following conditions are met:\n\u003e\n\u003e 1. Redistributions of source code must retain the above copyright notice, this\n\u003e list of conditions and the following disclaimer.\n\u003e\n\u003e 2. Redistributions in binary form must reproduce the above copyright notice,\n\u003e this list of conditions and the following disclaimer in the documentation\n\u003e and/or other materials provided with the distribution.\n\u003e\n\u003e 3. Neither the name of the copyright holder nor the names of its contributors\n\u003e may be used to endorse or promote products derived from this software without\n\u003e specific prior written permission.\n\u003e\n\u003e THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND\n\u003e ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED\n\u003e WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\n\u003e DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR\n\u003e ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\n\u003e (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;\n\u003e LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON\n\u003e ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n\u003e (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS\n\u003e SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n\n## Addendum I: Linux trackball configuration snippets\n\n**Output list of devices:** ``xinput --list`` \n**Output mouse buttons mapping:** ``xinput get-button-map \u003cdevice-ID\u003e`` \n**Trace mouse button IDs:** ``xev`` \n\n**Set speed and acceleration, buttons mapping and wheel emulation:**\n\n```bash\n#!/bin/bash\n\nfor id in `xinput --list|grep 'Kensington Expert Wireless TB Mouse'|perl -ne 'while (m/id=(\\d+)/g){print \"$1\\n\";}'`; do\n # set speed + accelleration\n xinput set-ptr-feedback $id 0 34 12\n\n # set top/left button to be middle-click\n xinput set-button-map $id 3 2 1 4 5 6 7 8 9 10 11 12 # left-handed: bottom-right is left-click\n\n # emulate mouse wheel on bottom/left (right-click) button + move\n xinput set-prop \"pointer:Kensington Expert Wireless TB Mouse\" \"libinput Scroll Method Enabled\" 0, 0, 1\n\t\n # on Kensington Expert Mouse, buttons are: \n # 0 = no button needed\n # 2 = top/left\n # 8 = top/right\n # 1 = bottom/left\n # 8 1 = bottom buttons together\n # 8 2 = bottom right + top/left together\n\n # set bottom button to fire scroll-mode\n xinput set-prop \"pointer:Kensington Expert Wireless TB Mouse\" \"libinput Button Scrolling Button\" 1\n \n # map bottom-left button held to scroll\n xinput set-prop $id \"Evdev Wheel Emulation Timeout\" 300\ndone \n```\n\n\n## Addendum II: Action shell scripting tricks\n\n### 1. User-specific actions\n\n**Problem:** xmchord runs as root, but some actions need to be run for a\nspecific logged-in user.\n\nE.g. Cinnamon's D-Bus methods require being launched by a specific user.\nThe following script switches from root to original user, before triggering the\ndesired method:\n\n```bash\n#!/bin/bash\nme=$SUDO_USER\nsudo -u $me dbus-send --dest=org.Cinnamon --print-reply /org/Cinnamon org.Cinnamon.switchWorkspaceRight\n```\n\n\n### 2. Launching applications and switching windows\n\nShell scripts can detect whether an application is running already and using\ne.g. [wmctrl](http://tripie.sweb.cz/utils/wmctrl/), bring a respective window\nonto the active workspace, or launch the application (similar to the behavior\non Mac OS).\n\n```bash\n#!/bin/bash\nif pidof -s evolution \u003e /dev/null; then\n wmctrl -a Evolution\nelse\n me=$SUDO_USER\n sudo -u $me nohup evolution \u003e /dev/null \u0026\nfi\n```\n\n\n### 3. Triggering window actions\n\nUsing e.g. [wmctrl](http://tripie.sweb.cz/utils/wmctrl/), shell scripts can\nswitch the active window's roll-up and always-on-top state:\n\n```bash\n#!/bin/bash\nwmctrl -b toggle,shaded -r :ACTIVE:\n```\n\n\n```bash\n#!/bin/bash\nwmctrl -r :ACTIVE: -b toggle,above\n```\n\n\n### 4. Application specific shortcut actions\n\nUsing e.g. [xdotool](https://www.semicomplete.com/projects/xdotool/), shell\nscripts can detect the currently focused window's application, and vary\nthe triggered function accordingly. Xdotool also allows to trigger\nkey-combinations for various shortcuts:\n\n```bash\n#!/bin/bash\nfocusApplication=\\\n`cat /proc/$(xdotool getwindowpid $(xdotool getwindowfocus))/comm`\n\nif [[ \"$focusApplication\" =~ \"gnome-terminal-\" ]]; then\n xdotool key Control_L+Page_Up\nelse\n xdotool key shift+ctrl+Tab\nfi\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkstenschke%2Fxmchord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkstenschke%2Fxmchord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkstenschke%2Fxmchord/lists"}