From 07ba086dcdcc0443bd85bb9c4a894e2eaabff069 Mon Sep 17 00:00:00 2001 From: houmaster Date: Mon, 4 Jan 2021 10:35:27 +0100 Subject: [PATCH] Updated readme --- README.md | 73 ++++++++++++++--- keymapper.conf | 211 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 271 insertions(+), 13 deletions(-) create mode 100644 keymapper.conf diff --git a/README.md b/README.md index 310a398b..82327ad7 100644 --- a/README.md +++ b/README.md @@ -105,9 +105,15 @@ Virtual1{A} >> B For convenience aliases for keys can be defined: ```bash +Win = Meta Boss = Virtual1 ``` +Example configuration +--------------------- + +The [authors personal configuration](keymapper.conf) may serve as an inspiration (which itself took some inspiration from [DreymaR's Big Bag Of Keyboard Tricks](https://forum.colemak.com/topic/2315-dreymars-big-bag-of-keyboard-tricks-main-topic/)). + Functional principle -------------------- @@ -119,32 +125,73 @@ For advanced application it is good to know how the mapping is applied: * As long as the key sequence can not match any input expression, its first stroke is removed and forwarded as output. * Keys which already matched but are still physically pressed participate in expression matching as an optional prefix to the key sequence. -Building --------- - -Only a C++17 conforming compiler is required. A script for the -[CMake](https://cmake.org) build system is provided. - Installation ------------ - -### GNU / Linux / X11 - +### Linux On Linux the program is split into two parts: * ```keymapperd``` is the daemon which needs to be run as root or some other user who is authorized to grab the keyboard and inject keys. -* ```keymapper``` needs to be run as normal user within a X11 session. It loads the configuration and informs the daemon about it and the active context. +* ```keymapper``` loads the configuration and informs the daemon about it and the active context. It needs to be run as normal user within an X11 session. Wayland is not yet supported, but it is possible to build keymapper without context awareness and the X11 dependency. + +**Arch Linux and derivatives:** + +An up to date build can be installed from the [AUR](https://aur.archlinux.org/packages/keymapper-git). + +To try it out, simply create a [configuration](#configuration) file and start it using: +``` +systemctl start keymapperd +keymapper +``` + +To install it permanently, enable the ```keymapperd``` service: +``` +systemctl enable keymapperd +``` -**Arch Linux** users can install it from the [AUR](https://aur.archlinux.org/packages/keymapper-git). +**Other Linux distributions:** + +No packages are provided yet, please follow the instructions for [building manually](#Building). + +To try it out, simply create a [configuration](#configuration) file and start it using: +``` +sudo ./keymapperd & +./keymapper +``` ### Windows +A portable build can be downloaded from the [latest release](https://github.com/houmaster/keymapper/releases/latest) page. -On Windows ```keymapper.exe``` can simply be started without special permissions. +```keymapper.exe``` can simply be started without special permissions. To install it permanently, simply add it to the autostarted applications. There are two modes of operation: * By default a [Low level keyboard hook](https://docs.microsoft.com/en-us/windows/desktop/winmsg/about-hooks) is used, which generally works fine but has a few limitations. Foremost the Windows key cannot be mapped reliably and applications which are running as administrator (like the login screen, task manager, ...) resist any mapping. -* When the command line argument ```-i``` is passed, the [Interception](https://github.com/oblitum/Interception/) library is used. It does not have these limitations, but a special keyboard driver needs to be installed and the ```interception.dll``` needs to be placed in the working directory. +* When the command line argument ```-i``` is passed, the [Interception](https://github.com/oblitum/Interception/) library is used. It does not have these limitations, but a special keyboard driver needs to be [installed](https://github.com/oblitum/Interception/#driver-installation) and the ```interception.dll``` needs to be placed in the working directory. + +Building +-------- + +A C++17 conforming compiler is required. A script for the +[CMake](https://cmake.org) build system is provided. + +### Installing dependencies on Debian Linux and derivatives: +``` +sudo apt install build-essential git cmake libudev-dev libusb-1.0-0-dev libx11-dev +``` + +### Checking out the source: +``` +git clone https://github.com/houmaster/keymapper +cd keymapper +``` + +### Building: +``` +mkdir build +cd build +cmake .. +cmake --build . --config Release +``` License ------- diff --git a/keymapper.conf b/keymapper.conf new file mode 100644 index 00000000..bb209e6a --- /dev/null +++ b/keymapper.conf @@ -0,0 +1,211 @@ + +# define a virtual "boss" key, which can be toggled using the scroll-lock key +# when the boss key is "pressed", the keyboard should be intuitively useable + Boss = Virtual1 + ScrollLock >> Boss + +# define and additional modifier "Ext" (the angular bracket key on a german keyboard) + Ext = IntlBackslash + +# define some more aliases + Alt = AltLeft + AltGr = AltRight + Win = Meta + +# pass the Windows key immediately + Win >> Win + +# map Capslock to Backspace + Control{CapsLock} >> CapsLock + CapsLock >> Backspace + +# the Ext modifier alone should have no effect + !Boss Ext >> + +# map Ext-A/D/F to Alt/Shift/Control + !Boss Ext{A} >> AltLeft + !Boss Ext{D} >> ShiftLeft + !Boss Ext{F} >> ControlLeft + +# map Ext-I/J/K/L to cursor keys... + !Boss Ext{I} >> ArrowUp + !Boss Ext{K} >> ArrowDown + !Boss Ext{J} >> ArrowLeft + !Boss Ext{L} >> ArrowRight + !Boss Ext{U} >> cursor_home + !Boss Ext{O} >> cursor_end + !Boss Ext{Y} >> PageUp + !Boss Ext{H} >> PageDown + + !Boss Ext{Semicolon} >> Backspace + !Boss Ext{Q} >> navigate_escape + !Boss Ext{Space} >> Space + !Boss Ext{M} >> Enter + + !Boss Ext{X} >> Control{X} + !Boss Ext{C} >> Control{C} + !Boss Ext{V} >> edit_paste + !Boss Ext{E} >> Control{F} + !Boss (Ext Shift){Z} >> edit_redo + !Boss Ext{Z} >> Control{Y} + + !Boss Ext{Comma} >> navigate_back + !Boss Ext{Period} >> navigate_fore + !Boss Ext{T} >> open_file + !Boss Ext{G} >> go_to_definition + !Boss Ext{BracketRight} >> AudioVolumeUp + !Boss Ext{BracketLeft} >> AudioVolumeDown + !Boss Ext{R} >> Delete + !Boss Ext{B} >> build + +# map Ext-number keys to function keys + !Boss Ext{1} >> F1 + !Boss Ext{2} >> edit_rename + !Boss Ext{3} >> F3 + !Boss Ext{4} >> F4 + !Boss Ext{5} >> F5 + !Boss Ext{6} >> F6 + !Boss Ext{7} >> F7 + !Boss Ext{8} >> F8 + !Boss Ext{9} >> F9 + !Boss Ext{0} >> F10 + !Boss Ext{Minus} >> F11 + !Boss Ext{Equal} >> F12 + +# Ext-W and the navigation keys should step in/out/over during debugging + !Boss Ext{W{L}} >> debug_step_into + !Boss Ext{W{J}} >> debug_step_out + !Boss Ext{W{K}} >> debug_step_over + !Boss Ext{W{Any}} >> + +# the Ext modifier together with other keys should have no effect + !Boss Ext{Any} >> + +# add some Windows key commands + !Boss Win{Q} >> close_window + !Boss Win{A} >> lower_window + !Boss Win{Tab} >> next_tab + !Boss (Win ShiftLeft){Tab} >> prev_tab + !Boss Win{C} >> open_console + +# pass Windows-P unmapped (for Windows output configuration) + !Boss Win{P} >> P + +# colemak layout mapping (on german layout) + !Boss AltGr{I} >> !AltGr{BracketLeft} # ü + !Boss AltGr{A} >> !AltGr{Quote} # ä + !Boss AltGr{Semicolon} >> !AltGr{Semicolon} # ö + !Boss AltGr{D} >> !AltGr{Minus} # ß + + !Boss E >> F + !Boss R >> P + !Boss T >> G + !Boss Y >> J + !Boss U >> L + !Boss I >> U + !Boss O >> Z + !Boss Z >> Y + !Boss Shift{P} >> Period + !Boss P >> Shift{Comma} + !Boss S >> R + !Boss D >> S + !Boss F >> T + !Boss G >> D + !Boss J >> N + !Boss K >> E + !Boss L >> I + !Boss Semicolon >> O + !Boss N >> K + + !Boss Shift{Quote} >> Shift{2} + !Boss Quote >> Shift{Backslash} + !Boss Shift{Period} >> IntlBackslash + !Boss Shift{Comma} >> !Shift IntlBackslash + !Boss Shift{BracketLeft} >> !Shift AltGr{7} + !Boss BracketLeft >> AltGr{8} + !Boss Shift{BracketRight} >> !Shift AltGr{0} + !Boss BracketRight >> AltGr{9} + !Boss Shift{Backquote} >> Equal + !Boss Backquote >> AltGr{BracketRight} + !Boss Shift{2} >> !Shift AltGr{Q} + !Boss Shift{3} >> !Shift Backslash + !Boss Shift{6} >> !Shift Backquote Space + !Boss Shift{7} >> 6 + !Boss Shift{8} >> BracketRight + !Boss Shift{9} >> 8 + !Boss Shift{0} >> 9 + !Boss Minus >> Slash + !Boss Shift{Equal} >> !Shift BracketRight + !Boss Equal >> Shift{0} + !Boss Shift{Backslash} >> !Shift AltGr{IntlBackslash} + !Boss Backslash >> AltGr{Minus} + !Boss Shift{Slash} >> Minus + !Boss Slash >> Shift{7} + +# default mappings for abstract commands + close_window >> !Win Alt{F4} + lower_window >> !Win (Alt Shift){PageDown} + navigate_escape >> Escape + cursor_home >> !Control Home + cursor_end >> !Control End + open_file >> Control{O} + navigate_back >> Alt{ArrowLeft} + navigate_fore >> Alt{ArrowRight} + next_tab >> !Win Control{PageUp} + prev_tab >> !Win Control{PageDown} + edit_paste >> Control{V} + edit_redo >> !Shift Control{Z} + build >> Control{B} + open_console >> Win{C} + debug_step_over >> F10 + debug_step_into >> F11 + debug_step_out >> Shift{F11} + edit_rename >> F2 + +# application specific mappings for abstract commands +[Window system="Linux" title="File Manager"] + cursor_home >> Backspace + cursor_end >> Enter + open_console >> !Win (ShiftLeft ControlLeft){C} + +[Window system="Linux" class="tilix"] + close_window >> !Win (Shift Control){W} + edit_paste >> (Shift Control){V} + open_console >> !Win (Control Alt){A} + +[Window title="Mozilla Firefox"] + open_file >> Control{K} + navigate_escape >> Escape Control{F} Escape + go_to_definition >> Shift{Backslash} + +[Window title="Chromium"] + open_file >> Control{L} + navigate_escape >> Control{L} F6 + +[Window title="Qt Creator"] + open_file >> Control{K} + go_to_definition >> F2 + edit_redo >> (Control Shift){Y} + edit_rename >> (Control Shift){R} + +[Window title="Visual Studio"] + go_to_definition >> F12 + navigate_back >> Control{Slash} + navigate_fore >> (Control Shift){Slash} + build >> (Control Shift){B} + +[Window system="Linux" title="Code - OSS"] + go_to_definition >> F12 + navigate_back >> (Control Alt){Slash} + navigate_fore >> (Control Shift){Slash} + build >> (Control Shift){B} + +[Window title="Visual Studio Code"] + go_to_definition >> F12 + navigate_back >> Alt{ArrowLeft} + navigate_fore >> Alt{ArrowRight} + build >> (Control Shift){B} + +[Window title="Geany"] + go_to_definition >> (Control Shift){T} +