Skip to content

Commit

Permalink
Updated readme
Browse files Browse the repository at this point in the history
  • Loading branch information
houmaster committed Jan 4, 2021
1 parent 971796e commit 07ba086
Show file tree
Hide file tree
Showing 2 changed files with 271 additions and 13 deletions.
73 changes: 60 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
--------------------

Expand All @@ -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
-------
Expand Down
211 changes: 211 additions & 0 deletions keymapper.conf
View file
Original file line number Diff line number Diff line change
@@ -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}

0 comments on commit 07ba086

Please sign in to comment.