2 |
3 | pkgname=map2
4 | pkgver=1.0.6
5 | pkgrel=1
6 | pkgdesc="A scripting language that allows complex key remapping on Linux, written in Rust"
7 | arch=('x86_64' 'i686')
8 | license=('MIT')
9 | depends=()
10 | makedepends=(rustup)
11 |
12 | build() {
13 | cd ..
14 | cargo build --release --locked --all-features --target-dir=target
15 | }
16 |
17 | check() {
18 | cd ..
19 | cargo test --release --locked --target-dir=target
20 | }
21 |
22 | package() {
23 | cd ..
24 | install -Dm 755 target/release/${pkgname} -t "${pkgdir}/usr/bin"
25 |
26 | install -Dm644 docs/man/map2.1 "$pkgdir/usr/share/man/man1/map2.1"
27 | }
28 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
map2
3 | Linux input remapping
Remap your keyboard, mouse, controller and more!
4 |
5 | [](https://github.com/shiro/map2)
6 | [](https://github.com/shiro/map2/blob/master/LICENSE)
7 | [](https://discord.gg/brKgH43XQN)
8 | [](https://github.com/shiro/map2/actions/workflows/CI.yml)
9 | [](https://ko-fi.com/C0C3RTCCI)
10 |
11 |
12 | Want to remap your input devices like keyboards, mice, controllers and more?
13 | There's nothing you can't remap with **map2**!
14 |
15 | - 🖱️ **Remap keys, mouse events, controllers, pedals, and more!**
16 | - 🔧 **Highly configurable**, using Python
17 | - 🚀 **Blazingly fast**, written in Rust
18 | - 📦 **Tiny install size** (around 5Mb), almost no dependencies
19 | - ❤️ **Open source**, made with love
20 |
21 | Visit our [official documentation](https://shiro.github.io/map2/en/basics/introduction)
22 | for the full feature list and API.
23 |
24 | ---
25 |
26 |
27 |
If you like open source, consider supporting
28 |
29 |
30 |
31 |
8 |
26 |
44 |
{title}
18 |
21 |
22 |
23 |
26 |
27 |
28 |
52 |
--------------------------------------------------------------------------------
/docs/src/components/RightSidebar/Example.solid.tsx:
--------------------------------------------------------------------------------
1 | import "solid-js";
2 | import {createSignal} from "solid-js";
3 |
4 | const Example = () => {
5 | const [count, setCount] = createSignal(0);
6 |
7 | return (
8 |
9 |
10 | {count()}
11 |
12 |
13 | );
14 | };
15 |
16 | export default Example;
17 |
--------------------------------------------------------------------------------
/docs/src/components/RightSidebar/RightSidebar.astro:
--------------------------------------------------------------------------------
1 | ---
2 | import type { MarkdownHeading } from 'astro'
3 | import TableOfContents from './TableOfContents'
4 | import MoreMenu from './MoreMenu.astro'
5 |
6 | type Props = {
7 | headings: MarkdownHeading[]
8 | editUrl: string
9 | }
10 |
11 | const { headings, editUrl } = Astro.props
12 | ---
13 |
14 |
20 |
21 |
35 |
--------------------------------------------------------------------------------
/docs/src/components/RightSidebar/TableOfContents.tsx:
--------------------------------------------------------------------------------
1 | import type { MarkdownHeading } from "astro";
2 | import type { FunctionalComponent } from "preact";
3 | import { unescape } from "html-escaper";
4 | import { useState, useEffect, useRef } from "preact/hooks";
5 |
6 | type ItemOffsets = {
7 | id: string
8 | topOffset: number
9 | };
10 |
11 | const TableOfContents: FunctionalComponent<{ headings: MarkdownHeading[] }> = ({
12 | headings = []
13 | }) => {
14 | const toc = useRef();
15 | const onThisPageID = "on-this-page-heading";
16 | const itemOffsets = useRef([]);
17 | const [currentID, setCurrentID] = useState("overview");
18 | useEffect(() => {
19 | const getItemOffsets = () => {
20 | const titles = document.querySelectorAll('article :is(h1, h2, h3, h4)')
21 | itemOffsets.current = Array.from(titles).map((title) => ({
22 | id: title.id,
23 | topOffset: title.getBoundingClientRect().top + window.scrollY
24 | }))
25 | }
26 |
27 | getItemOffsets()
28 | window.addEventListener('resize', getItemOffsets)
29 |
30 | return () => {
31 | window.removeEventListener('resize', getItemOffsets)
32 | }
33 | }, [])
34 |
35 | useEffect(() => {
36 | if (!toc.current) return
37 |
38 | const setCurrent: IntersectionObserverCallback = (entries) => {
39 | for (const entry of entries) {
40 | if (entry.isIntersecting) {
41 | const { id } = entry.target
42 | if (id === onThisPageID) continue
43 | setCurrentID(entry.target.id)
44 | break
45 | }
46 | }
47 | }
48 |
49 | const observerOptions: IntersectionObserverInit = {
50 | // Negative top margin accounts for `scroll-margin`.
51 | // Negative bottom margin means heading needs to be towards top of viewport to trigger intersection.
52 | rootMargin: '-100px 0% -66%',
53 | threshold: 1
54 | }
55 |
56 | const headingsObserver = new IntersectionObserver(
57 | setCurrent,
58 | observerOptions
59 | )
60 |
61 | // Observe all the headings in the main page content.
62 | document
63 | .querySelectorAll('article :is(h1,h2,h3)')
64 | .forEach((h) => headingsObserver.observe(h))
65 |
66 | // Stop observing when the component is unmounted.
67 | return () => headingsObserver.disconnect()
68 | }, [toc.current])
69 |
70 | const onLinkClick = (e) => {
71 | setCurrentID(e.target.getAttribute('href').replace('#', ''))
72 | }
73 |
74 | return (
75 | <>
76 |
77 | On this page
78 |
79 |
94 |
95 | )
96 | }
97 |
98 | export default TableOfContents
99 |
--------------------------------------------------------------------------------
/docs/src/components/RightSidebar/ThemeToggleButton.scss:
--------------------------------------------------------------------------------
1 | .theme-toggle {
2 | display: inline-flex;
3 | align-items: center;
4 | gap: 0.25em;
5 | padding: 0.33em 0.67em;
6 | border-radius: 99em;
7 | background-color: var(--theme-code-inline-bg);
8 | }
9 |
10 | .theme-toggle > label:focus-within {
11 | outline: 2px solid transparent;
12 | box-shadow: 0 0 0 0.08em var(--theme-accent), 0 0 0 0.12em white;
13 | }
14 |
15 | .theme-toggle > label {
16 | color: var(--theme-code-inline-text);
17 | position: relative;
18 | display: flex;
19 | align-items: center;
20 | justify-content: center;
21 | opacity: 0.5;
22 | }
23 |
24 | .theme-toggle .checked {
25 | color: var(--theme-accent);
26 | opacity: 1;
27 | }
28 |
29 | input[name='theme-toggle'] {
30 | position: absolute;
31 | opacity: 0;
32 | top: 0;
33 | right: 0;
34 | bottom: 0;
35 | left: 0;
36 | z-index: -1;
37 | }
38 |
--------------------------------------------------------------------------------
/docs/src/components/RightSidebar/ThemeToggleButton.tsx:
--------------------------------------------------------------------------------
1 | import type { FunctionalComponent } from 'preact'
2 | import { useState, useEffect } from 'preact/hooks'
3 | import './ThemeToggleButton.scss'
4 |
5 | const themes = ['light', 'dark']
6 |
7 | const icons = [
8 | ,
21 |
30 | ]
31 |
32 | const ThemeToggle: FunctionalComponent = () => {
33 | const [theme, setTheme] = useState(() => {
34 | if (import.meta.env.SSR) {
35 | return undefined
36 | }
37 | if (typeof localStorage !== undefined && localStorage.getItem('theme')) {
38 | return localStorage.getItem('theme')
39 | }
40 | if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
41 | return "dark";
42 | }
43 | return "light";
44 | })
45 |
46 | useEffect(() => {
47 | const root = document.documentElement
48 | if (theme === 'light') {
49 | root.classList.remove('theme-dark')
50 | } else {
51 | root.classList.add('theme-dark')
52 | }
53 | }, [theme])
54 |
55 | return (
56 |
57 | {themes.map((t, i) => {
58 | const icon = icons[i]
59 | const checked = t === theme
60 | return (
61 |
76 | )
77 | })}
78 |
79 | )
80 | }
81 |
82 | export default ThemeToggle
83 |
--------------------------------------------------------------------------------
/docs/src/components/ValidKeysTable.solid.tsx:
--------------------------------------------------------------------------------
1 | import {Show, For} from "solid-js/web";
2 |
3 | import keyEnumCode from "@project/evdev-rs/src/enums.rs?raw";
4 | import aliasEnumCode from "@project/src/key_defs.rs?raw";
5 |
6 |
7 | const keys = (() => {
8 | const code = keyEnumCode;
9 | const pat = "pub enum EV_KEY {";
10 | const fromIdx = code.indexOf(pat) + pat.length;
11 | const toIdx = code.indexOf("}", fromIdx);
12 |
13 | const snippet = code.slice(fromIdx, toIdx);
14 |
15 | const literals = new Set([
16 | "apostrophe",
17 | "backslash",
18 | "comma",
19 | "dollar",
20 | "dot",
21 | "equal",
22 | "euro",
23 | "grave",
24 | "leftbrace",
25 | "minus",
26 | "rightbrace",
27 | "semicolon",
28 | "slash",
29 | ]);
30 |
31 | return snippet
32 | .split(",")
33 | .map(x => x.trim())
34 | .map(x => x.slice(
35 | x.startsWith("KEY_") ? "KEY_".length : 0,
36 | x.indexOf(" "))
37 | )
38 | .map(x => x.toLowerCase())
39 | .filter(x => x.length > 1)
40 | .filter(x => !literals.has(x));
41 | })();
42 |
43 | const aliases = (() => {
44 | const code = aliasEnumCode;
45 | const pat = "let mut m = HashMap::new();";
46 | const fromIdx = code.indexOf(pat) + pat.length;
47 | const toIdx = code.indexOf("m\n", fromIdx);
48 |
49 | const snippet = code.slice(fromIdx, toIdx);
50 |
51 | return Object.fromEntries(
52 | snippet
53 | .replaceAll("\n", " ")
54 | .split(";")
55 | .map(x => x.trim())
56 | .filter(Boolean)
57 | .map(x => new RegExp(`"(.*)".*KEY_([^.]+)`).exec(x)!.slice(1, 3))
58 | .map(([alias, key]) => [key.toLowerCase(), alias.toLowerCase()])
59 | );
60 | })();
61 |
62 |
63 | const descriptions = {
64 | brl_dot1: "braille dot 1",
65 | brl_dot2: "braille dot 2",
66 | brl_dot3: "braille dot 3",
67 | brl_dot4: "braille dot 4",
68 | brl_dot5: "braille dot 5",
69 | brl_dot6: "braille dot 6",
70 | brl_dot7: "braille dot 7",
71 | brl_dot8: "braille dot 8",
72 | brl_dot9: "braille dot 9",
73 | brl_dot10: "braille dot 10",
74 | btn_left: "left mouse button",
75 | btn_right: "right mouse button",
76 | btn_middle: "middle mouse button",
77 | down: "'down' directional key",
78 | f1: "function 1",
79 | f2: "function 2",
80 | f3: "function 3",
81 | f4: "function 4",
82 | f5: "function 5",
83 | f6: "function 6",
84 | f7: "function 7",
85 | f8: "function 8",
86 | f9: "function 9",
87 | f10: "function 10",
88 | f11: "function 11",
89 | f12: "function 12",
90 | f13: "function 13",
91 | f14: "function 14",
92 | f15: "function 15",
93 | f16: "function 16",
94 | f17: "function 17",
95 | f18: "function 18",
96 | f19: "function 19",
97 | f20: "function 20",
98 | f21: "function 21",
99 | f22: "function 22",
100 | f23: "function 23",
101 | f24: "function 24",
102 | kp0: "keypad 0",
103 | kp1: "keypad 1",
104 | kp2: "keypad 2",
105 | kp3: "keypad 3",
106 | kp4: "keypad 4",
107 | kp5: "keypad 5",
108 | kp6: "keypad 6",
109 | kp7: "keypad 7",
110 | kp8: "keypad 8",
111 | kp9: "keypad 9",
112 | kpasterisk: "keypad '*'",
113 | kpcomma: "keypad ','",
114 | kpdot: "keypad '.'",
115 | kpenter: "keypad 'center'",
116 | kpequal: "keypad '='",
117 | kpjpcomma: "keypad Japanese '、'",
118 | kpleftparen: "keypad '('",
119 | kpminus: "keypad '-'",
120 | kpplus: "keypad '+'",
121 | kpplusminus: "keypad '+/-'",
122 | kprightparen: "keypad ')'",
123 | kpslash: "keypad '/'",
124 | left: "'left' directional key",
125 | leftalt: "left meta",
126 | leftctrl: "left control",
127 | leftmeta: "left meta",
128 | leftshift: "left shift",
129 | numeric_0: "numpad 0",
130 | numeric_1: "numpad 1",
131 | numeric_2: "numpad 2",
132 | numeric_3: "numpad 3",
133 | numeric_4: "numpad 4",
134 | numeric_5: "numpad 5",
135 | numeric_6: "numpad 6",
136 | numeric_7: "numpad 7",
137 | numeric_8: "numpad 8",
138 | numeric_9: "numpad 9",
139 | numeric_a: "numpad 'a'",
140 | numeric_b: "numpad 'b'",
141 | numeric_c: "numpad 'c'",
142 | numeric_d: "numpad 'd'",
143 | numeric_pound: "numpad '£'",
144 | numeric_star: "numpad '*'",
145 | right: "'right' directional key",
146 | rightalt: "right alt",
147 | rightctrl: "right control",
148 | rightmeta: "right meta",
149 | rightshift: "right shift",
150 | up: "'up' directional key",
151 | yen: "JPY (円)",
152 | };
153 |
154 |
155 |
156 | const ValidKeysTable = () => {
157 | return (
158 | <>
159 |
160 |
161 |
162 | | Key names |
163 | Description |
164 |
165 |
166 | {(key) =>
167 |
168 |
169 |
170 | {aliases[key]}
171 |
172 |
173 | {key}
174 | |
175 | {descriptions[key]} |
176 |
177 | }
178 |
179 |
180 |
181 |
182 | );
183 | }
184 |
185 | export default ValidKeysTable;
186 |
--------------------------------------------------------------------------------
/docs/src/consts.ts:
--------------------------------------------------------------------------------
1 | export const SITE = {
2 | title: 'map2 docs',
3 | description: 'Linux key remapping tool map2 - official documentation',
4 | defaultLanguage: 'en-us'
5 | } as const
6 |
7 | export const OPEN_GRAPH = {
8 | image: {
9 | src: 'logo.png',
10 | alt: 'map2 logo - stylized letters "M" and "2"'
11 | },
12 | }
13 |
14 | export const KNOWN_LANGUAGES = {
15 | English: 'en'
16 | } as const
17 | export const KNOWN_LANGUAGE_CODES = Object.values(KNOWN_LANGUAGES)
18 |
19 | export const EDIT_URL = `https://github.com/shiro/map2/docs`;
20 |
21 | export const COMMUNITY_INVITE_URL = `https://discord.gg/brKgH43XQN`;
22 | export const DONATE_URL = `https://ko-fi.com/shiroi_usagi`;
23 |
24 | // See "Algolia" section of the README for more information.
25 | export const ALGOLIA = {
26 | indexName: 'XXXXXXXXXX',
27 | appId: 'XXXXXXXXXX',
28 | apiKey: 'XXXXXXXXXX'
29 | }
30 |
31 | export type Sidebar = Record<
32 | (typeof KNOWN_LANGUAGE_CODES)[number],
33 | Record
34 | >
35 | export const SIDEBAR: Sidebar = {
36 | en: {
37 | "Basics": [
38 | { text: "Introduction", link: "en/basics/introduction" },
39 | { text: "Install", link: "en/basics/install" },
40 | { text: "Getting started", link: "en/basics/getting-started" },
41 | { text: "Keys and key sequences", link: "en/basics/keys-and-key-sequences" },
42 | { text: "Routing", link: "en/basics/routing" },
43 | ],
44 | "Advanced": [
45 | { text: "Secure setup", link: "en/advanced/secure-setup" },
46 | { text: "Autostart", link: "en/advanced/autostart" },
47 | ],
48 | "API": [
49 | { text: "map2", link: "en/api/map2" },
50 | { text: "Reader", link: "en/api/reader" },
51 | { text: "Mapper", link: "en/api/mapper" },
52 | { text: "Text Mapper", link: "en/api/text-mapper" },
53 | { text: "Chord Mapper", link: "en/api/chord-mapper" },
54 | { text: "Writer", link: "en/api/writer" },
55 | { text: "Virtual Writer", link: "en/api/virtual-writer" },
56 | { text: "Window", link: "en/api/window" },
57 | ],
58 | "Examples": [
59 | { text: "Hello world", link: "en/examples/hello-world" },
60 | { text: "Chords", link: "en/examples/chords" },
61 | { text: "Text mapping", link: "en/examples/text-mapping" },
62 | { text: "WASD mouse control", link: "en/examples/wasd-mouse-control" },
63 | { text: "Keyboard to controller", link: "en/examples/keyboard-to-controller" },
64 | ]
65 | }
66 | }
67 |
--------------------------------------------------------------------------------
/docs/src/content/config.ts:
--------------------------------------------------------------------------------
1 | import { defineCollection, z } from 'astro:content'
2 | import { SITE } from '../consts'
3 |
4 | const docs = defineCollection({
5 | schema: z.object({
6 | title: z.string().default(SITE.title),
7 | description: z.string().default(SITE.description),
8 | lang: z.literal('en-us').default(SITE.defaultLanguage),
9 | dir: z.union([z.literal('ltr'), z.literal('rtl')]).default('ltr'),
10 | image: z
11 | .object({
12 | src: z.string(),
13 | alt: z.string()
14 | })
15 | .optional(),
16 | ogLocale: z.string().optional()
17 | })
18 | })
19 |
20 | export const collections = { docs }
21 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/advanced/autostart.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Autostart'
3 | description: 'Autostart map2 scripts on login'
4 | ---
5 |
6 | A common use case for map2 is to run a script automatically after logging in, the way
7 | to do it depends on your Linux distro and system setup.
8 |
9 | We'll use [Systemd](https://wiki.archlinux.org/title/systemd) since most distros ship with
10 | it, but changing the commands to work on other systems should be pretty easy as well.
11 |
12 | ## Setting things up
13 |
14 | The way to prepare things depends on how you are running your map2 scripts, please check the
15 | [Secure setup](/map2/en/advanced/secure-setup) section.
16 |
17 | If you are running your scripts as **superuser** as shown in the [Getting started](/map2/en/basics/getting-started)
18 | section, please first complete any of the ways in [Secure setup](/map2/en/advanced/secure-setup) and continue
19 | with the appropriate section below.
20 |
21 |
22 | ### The lazy way
23 |
24 | Uset this method if you are using:
25 |
26 | - the **_lazy way_** from the [Secure setup](/map2/en/advanced/secure-setup#the-lazy-way) section.
27 |
28 |
29 | Copy the service definition into `~/.config/systemd/user/map2.service`.
30 |
31 | ```
32 | [Unit]
33 | Description=map2 autostart service
34 | PartOf=graphical-session.target
35 |
36 | [Service]
37 | ExecStart=python /path/to/my-map2-script.py
38 | Restart=always
39 | RestartSec=5s
40 |
41 | [Install]
42 | WantedBy=graphical-session.target
43 | ```
44 |
45 | And change `/path/to/my-map2-script.py` to your script path.
46 |
47 |
48 | ### The secure way
49 |
50 |
51 | Uset this method if you are using:
52 |
53 | - the **_secure way_** from the [Secure setup](/map2/en/advanced/secure-setup#the-secure-way) section.
54 |
55 | In the following section, replace `/home/map2/my-map2-script.py` with your script path.
56 |
57 |
58 | Create a shell script file in `/home/map2/autostart.sh`:
59 |
60 | ```bash
61 | #!/bin/bash
62 | # map 2 autostart script
63 | # runs a map2 script by switching to the map2 user
64 |
65 | su map2 -pc 'python /home/map2/my-map2-script.py'
66 | ```
67 |
68 | And run the following commands:
69 |
70 | ```bash
71 | # make the autostart script executable
72 | chmod +x /home/map2/autostart.sh
73 |
74 | # allow everyone to run the autostart script
75 | echo "ALL ALL=(root) NOPASSWD:SETENV: /home/map2/autostart.sh" | sudo tee -a /etc/sudoers
76 | ```
77 |
78 | Copy the following into `~/.config/systemd/user/map2.service`:
79 |
80 | ```
81 | [Unit]
82 | Description=map2 autostart service
83 | PartOf=graphical-session.target
84 |
85 | [Service]
86 | ExecStart=sudo -E /home/map2/autostart.sh
87 | Restart=always
88 | RestartSec=5s
89 |
90 | [Install]
91 | WantedBy=graphical-session.target
92 | ```
93 |
94 |
95 | ## Running the service
96 |
97 |
98 | Now that we created a service, we need to make sure it works and enable it so it starts automatically.
99 |
100 | ```bash
101 | # tell systemd we edited a service
102 | systemctl --user daemon-reload
103 |
104 | # start the service and make sure it runs the script
105 | systemctl --user start map2
106 |
107 | # after ensuring it works, enable it so it runs on every startup
108 | systemctl --user enable map2
109 | ```
110 |
111 | Your script should now run automatically when you login to your desktop environment.
112 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/advanced/secure-setup.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Secure setup'
3 | description: 'Setup map2 in a more secure way'
4 | ---
5 |
6 | As discussed in the [Getting started](map2/en/basics/getting-started) section, running your script with
7 | superuser access is not ideal since it allows the script to steal your data, modify your system or
8 | remove system files. This is especially risky when running code that you haven't written yourself.
9 |
10 |
11 | The initial setup **always** requires superuser access, ask your local system administrator for help if necessary.
12 |
13 |
14 | ## The lazy way
15 |
16 | A quick way to avoid running as superuser is to be a member of the `input` group, however this
17 | also allows other processes to listen in on input events (keyloggers, etc.).
18 | If possible, please use [the secure way](#the-secure-way).
19 | Just to demonstrate, we'll go over the *quick and insecure* approach in this section.
20 |
21 | Add the current user into the `input` group.
22 |
23 | ```bash
24 | # allow the current user to intercept input device events
25 | sudo usermod -aG input `whoami`
26 | ```
27 |
28 | By default, modifying input events always requires superuser access, so we need to change that as
29 | well.
30 | Copy the following into `/etc/udev/rules.d/999-map2.rules`.
31 |
32 | ```
33 | # Allow the 'input' group to manipulate input events
34 | SUBSYSTEM=="misc", KERNEL=="uinput", MODE="0660", GROUP="input"
35 | ```
36 |
37 | With this the current user should be able to run map2 scripts without superuser permissions.
38 |
39 |
40 | ## The secure way
41 |
42 | The more secure (and complicated) approach is to create a new user that has exclusive ownership of the
43 | script files and is allowed to intercept events from input devices.
44 | This way, even if a user account gets compromised, it would not be possible to tamper with script files
45 | or spy on input devices.
46 |
47 |
48 |
49 |
50 | Create a new system user called `map2` and set a secure password for it:
51 |
52 | ```bash
53 | # add a new system user called 'map2', also create a home directory
54 | sudo useradd -rm -s /bin/sh map2
55 | # allow it to intercept input device events
56 | sudo usermod -aG input map2
57 | # set a secure password for the new user
58 | sudo passwd map2
59 | ```
60 |
61 | If you have an existing script, transfer the ownership to the `map2` user and remove all permissions
62 | to the file for other users, so others can't read/modify the script.
63 | We should also move the script to `/home/map2` in order to avoid permission issues.
64 |
65 | ```bash
66 | # transfer all ownership, remove access for other users
67 | sudo chown map2:map2 my-map2-script.py
68 | sudo chmod 700 my-map2-script.py
69 | # move the script to a location owned by the map2 user
70 | sudo mv my-map2-script.py /home/map2
71 | ```
72 |
73 | To also allow the `input` group to modify input events,
74 | copy the following into
75 | `/etc/udev/rules.d/999-map2.rules`.
76 |
77 | ```
78 | # Allow the 'input' group to manipulate input events
79 | SUBSYSTEM=="misc", KERNEL=="uinput", MODE="0660", GROUP="input"
80 | ```
81 |
82 | And apply the configuration changes.
83 |
84 | ```bash
85 | # reload the udev rules since we modified them
86 | sudo udevadm control --reload-rules
87 | sudo udevadm trigger
88 | ```
89 |
90 | After this, superuser access is no longer needed.
91 |
92 | ### Running the script
93 |
94 |
95 | Now any user can run the script without superuser access, as long as they know the password for the
96 | `map2` user. You can even modify the script that way.
97 |
98 | ```bash
99 | su map2 -pc 'python ~/my-map2-script.py'
100 | ```
101 |
102 |
103 | ### Optional extra steps
104 |
105 | It's also possible to allow the `map2` user access to only specific input devices rather than all of them.
106 | This is optional and usually not required unless security is very important.
107 |
108 | Change the contents of `/etc/udev/rules.d/999-map2.rules` to:
109 |
110 | ```
111 | # Allow the 'map2' group to manipulate input events
112 | SUBSYSTEM=="misc", KERNEL=="uinput", MODE="0660", GROUP="map2"
113 |
114 | # Assign specific input devices to the group 'map2'
115 | ATTRS{name}=="Gaming Keyboard", SUBSYSTEM=="input", MODE="0644", GROUP="map2"
116 | ```
117 |
118 | And modify the filter rules to match the devices you want to grant access to. There are lots of
119 | guides describing udev rules, for example the [Arch Wiki](https://wiki.archlinux.org/title/udev)
120 | explains it pretty well.
121 |
122 | Finally reload the configuration and adjust the permissions.
123 |
124 | ```bash
125 | # reload the udev rules since we modified them
126 | sudo udevadm control --reload-rules
127 | sudo udevadm trigger
128 |
129 | # remove the map2 user from the input group
130 | sudo gpasswd -d map2 input
131 | ```
132 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/api/chord-mapper.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Chord mapper'
3 | description: 'Chord mapper | map2 API documentation'
4 | ---
5 |
6 |
7 | Creates a mapping layer that triggers on multiple keys being pressed at once or in very quick
8 | succession.
9 | When activated, it outputs a key sequence or calls a user-function.
10 |
11 | ```python
12 | import map2
13 |
14 | mapper = map2.ChordMapper()
15 |
16 | # trigger when "a" & "b" are pressed together
17 | mapper.map(["a", "b"], "c")
18 |
19 | # mapping to sequences is fine too
20 | mapper.map(["z", "x"], "{backspace} wow!")
21 |
22 | # map to user-function
23 | def greet(): print("hello!")
24 | mapper.map(["w", "q"], greet)
25 | ```
26 |
27 | Supported on:
28 | - ✅ Hyprland
29 | - ✅ X11
30 | - ✅ Gnome (wayland)
31 | - ✅ KDE plasma (wayland)
32 |
33 |
34 | ## Options
35 |
36 | ### model
37 |
38 | ```
39 | string?
40 | ```
41 |
42 | Sets the XKB keyboard model.
43 |
44 | ### layout
45 |
46 | ```
47 | string?
48 | ```
49 |
50 | Sets the XKB keyboard layout.
51 |
52 | ### variant
53 |
54 | ```
55 | string?
56 | ```
57 |
58 | Sets the XKB keyboard variant.
59 |
60 | ### options
61 |
62 | ```
63 | string?
64 | ```
65 |
66 | Sets the XKB keyboard options.
67 |
68 |
69 | ## Methods
70 |
71 | ### map(from, to)
72 |
73 | Maps 2 keys, when pressed together, to a different text sequence or user-function.
74 |
75 | - **from**: [key, key]
76 | - **to**: key_sequence | () -> void
77 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/api/map2.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'map2'
3 | description: 'map2 | map2 API documentation'
4 | ---
5 |
6 |
7 | ```python
8 | import map2
9 |
10 | # speicfy the default XKB keyboard layout
11 | map2.default(layout = "us")
12 |
13 | # everything will use the default layout unless specified otherwise
14 | reader = map2.Reader()
15 | mapper = map2.Mapper()
16 | writer = map2.Writer(capabilities = {"keys": True)
17 |
18 | # define the event flow
19 | map2.link([reader, mapper, writer])
20 | ```
21 |
22 |
23 | A collection of global functions that interact with other objects.
24 |
25 |
26 | Supported on:
27 | - ✅ Hyprland
28 | - ✅ X11
29 | - ✅ Gnome (wayland)
30 | - ✅ KDE plasma (wayland)
31 |
32 |
33 | ## Options
34 |
35 | This object has no options.
36 |
37 |
38 |
39 | ## Methods
40 |
41 | ### default(**options)
42 |
43 | Sets global default values such as keyboard layout.
44 |
45 | - **options.model**: string?
46 | - **options.layout**: string?
47 | - **options.variant**: string?
48 | - **options.options**: string?
49 |
50 | ### link(path)
51 |
52 | Links objects and defines the event flow.
53 |
54 | - **path**: ([Reader](map2/en/api/reader) | [Mapper](map2/en/api/mapper) | [Writer](map2/en/api/writer))[]
55 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/api/mapper.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Mapper'
3 | description: 'Mapper | map2 API documentation'
4 | ---
5 |
6 |
7 | ```python
8 | import map2
9 |
10 | mapper = map2.Mapper()
11 |
12 | # map key to key
13 | mapper.map("a", "b")
14 |
15 | # map key to key sequence
16 | mapper.map("b", "hello world")
17 |
18 | def user_function1(key, state):
19 | # map "c" to "hello world"
20 | if key == "c": return "hello world"
21 | # forward keys except for "z"
22 | if key != "z": return True
23 |
24 | # map key to user function
25 | mapper.map("c", user_function1)
26 |
27 | # catch all non-mapped keys
28 | mapper.map_fallback("d", user_function1)
29 |
30 | # map key to key
31 | mapper.map_key("d", "tab")
32 |
33 | def user_function2(type, value):
34 | print("move event {}: {}".format(type, value))
35 |
36 | # map mouse movements, touchscreen taps, etc.
37 | mapper.map_relative(user_function2)
38 | mapper.map_absolute(user_function2)
39 | ```
40 |
41 |
42 | Creates a mapping layer that can be used to tap into the input event stream,
43 | modify events and call user defined functions.
44 |
45 | Supported on:
46 | - ✅ Hyprland
47 | - ✅ X11
48 | - ✅ Gnome (wayland)
49 | - ✅ KDE plasma (wayland)
50 |
51 | ## Options
52 |
53 |
54 | ### model
55 |
56 | ```
57 | string?
58 | ```
59 |
60 | Sets the XKB keyboard model.
61 |
62 | ### layout
63 |
64 | ```
65 | string?
66 | ```
67 |
68 | Sets the XKB keyboard layout.
69 |
70 | ### variant
71 |
72 | ```
73 | string?
74 | ```
75 |
76 | Sets the XKB keyboard variant.
77 |
78 | ### options
79 |
80 | ```
81 | string?
82 | ```
83 |
84 | Sets the XKB keyboard options.
85 |
86 |
87 |
88 |
89 | ## Methods
90 |
91 | ### map(from, to)
92 |
93 | Maps a key to a key sequence.
94 |
95 | - **from**: key
96 | - **to**: key_sequence
97 |
98 | ### map_key(from, to)
99 |
100 | Maps a key to a key.
101 |
102 | - **from**: key
103 | - **to**: key
104 |
105 | ### map_fallback(handler)
106 |
107 | Maps all keys without explicit mappings to a user function
108 |
109 | - **handler**: (key: key, state: "down" | "up" | "repeat") -> string?
110 |
111 | ### map_relative(handler)
112 |
113 | Maps relative movement input events such as mouse moves to a user function.
114 |
115 | - **handler**: (type: string, value: int) -> string?
116 |
117 | ### map_absolute(handler)
118 |
119 | Maps absolute movement input events such as touchscreen taps to a user function.
120 |
121 | - **handler**: (type: string, value: int) -> string?
122 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/api/reader.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Reader'
3 | description: 'Reader | map2 API documentation'
4 | ---
5 |
6 |
7 | ```python
8 | import map2
9 |
10 | # readers intercept all keyboard inputs and forward them
11 | reader = map2.Reader(patterns=["/dev/input/by-id/my-keyboard"])
12 |
13 | # send keys as if they were read from a physical device
14 | reader.send("{ctrl down}a{ctrl up}")
15 | ```
16 |
17 |
18 |
19 | All devices matching a pattern will be *grabbed*, meaning all events will be intercepted by map2
20 | and not forwarded to the system. If events are not passed to an output device such as [Writer](/map2/en/api/writer),
21 | they will be lost, please avoid locking your only keyboard when testing.
22 |
23 |
24 | Supported on:
25 | - ✅ Hyprland
26 | - ✅ X11
27 | - ✅ Gnome (wayland)
28 | - ✅ KDE plasma (wayland)
29 |
30 |
31 | ## Options
32 |
33 |
34 | ### patterns
35 |
36 | ```
37 | string[]?
38 | ```
39 |
40 | A list of file descriptors to intercept events from.
41 |
42 | The patterns are regular expressions, if you are not familiar with them, consider reading a
43 | [quick tutorial](https://www.regular-expressions.info/quickstart.html).
44 |
45 | Some quick examples:
46 |
47 | - `/dev/input5`: The specific device on `/dev/input5`
48 | - `/dev/input\d+`: All input devices
49 | - `/dev/input/by-id/.*Gaming_Keyboard.*`: All devices who's ID contains `Gaming_Keyboard`
50 |
51 |
52 |
53 | ## Methods
54 |
55 | ### send(input)
56 |
57 | Sends keys as if they were read from a physical device.
58 |
59 | - **input**: key_sequence
60 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/api/text-mapper.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Text mapper'
3 | description: 'Text mapper | map2 API documentation'
4 | ---
5 |
6 |
7 | Creates a text-based mapping layer that triggers on certain key-sequences (hotstrings).
8 | When activated, it erases the trigger sequence by emmiting `backspace` key events and
9 | then emmits the replacement text or calls a user-function.
10 |
11 | ```python
12 | import map2
13 |
14 | # set the output keyboard layout
15 | map2.default(layout = "us")
16 |
17 | mapper = map2.TextMapper()
18 |
19 | # map text to other text
20 | mapper.map("hello", "bye")
21 |
22 | # capitals and special letters are allowed
23 | mapper.map("LaSeRs?", "lAsErS!")
24 |
25 | # map to user-function
26 | def greet(): print("Hello!")
27 | mapper.map("greet", greet)
28 |
29 | # ❌ This won't work, writers can only output keys contained
30 | # in the output keybarod layout.
31 | # Since we specified the 'us' layout above, we can't map to kanji directly.
32 | mapper.map("usagi", "兎")
33 |
34 | # ✅ we can instead use a virtual writer for writing special characters.
35 | # note: not all environments support virtual writers
36 | virtual_writer = map2.VirtualWriter()
37 | def write_special(text):
38 | def fn(): writer_virtual.send(text)
39 | return fn
40 | mapper.map("usagi", write_special("兎"))
41 | ```
42 |
43 |
44 |
45 | Supported on:
46 | - ✅ Hyprland
47 | - ✅ X11
48 | - ✅ Gnome (wayland)
49 | - ✅ KDE plasma (wayland)
50 |
51 | ## Options
52 |
53 |
54 | ### model
55 |
56 | ```
57 | string?
58 | ```
59 |
60 | Sets the XKB keyboard model.
61 |
62 | ### layout
63 |
64 | ```
65 | string?
66 | ```
67 |
68 | Sets the XKB keyboard layout.
69 |
70 | ### variant
71 |
72 | ```
73 | string?
74 | ```
75 |
76 | Sets the XKB keyboard variant.
77 |
78 | ### options
79 |
80 | ```
81 | string?
82 | ```
83 |
84 | Sets the XKB keyboard options.
85 |
86 |
87 |
88 |
89 | ## Methods
90 |
91 | ### map(from, to)
92 |
93 | Maps a text sequence to a different text sequence or user-function.
94 |
95 | - **from**: key_sequence
96 | - **to**: key_sequence | () -> void
97 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/api/virtual-writer.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Virtual Writer'
3 | description: 'VirtualWriter | map2 API documentation'
4 | ---
5 |
6 |
7 | ```python
8 | import map2
9 |
10 | writer = map2.VirtualWriter()
11 |
12 | # send any text
13 | writer.send("hello world")
14 | # including really weird characters
15 | writer.send("∇⋅∇ψ = ρ")
16 | ```
17 |
18 | Creates a virtual output device that is able to type any text. It's different from a regular
19 | [Writer](/map2/en/api/writer) in that it doesn't simulate a physical device, but rather sends text directly to the
20 | desktop environment.
21 |
22 | Supported on:
23 | - ✅ Hyprland
24 | - ❌ X11
25 | - ❌ Gnome (wayland)
26 | - ❌ KDE plasma (wayland)
27 |
28 | ## Options
29 |
30 | This object has no options.
31 |
32 |
33 | ## Methods
34 |
35 | ### send(input)
36 |
37 | Sends an arbitrary text input to the desktop environment.
38 |
39 | - **input**: string
40 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/api/window.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Window'
3 | description: 'Window | map2 API documentation'
4 | ---
5 |
6 |
7 | ```python
8 | import map2
9 |
10 | window = map2.Window()
11 |
12 | def on_window_change(active_window_class):
13 | if active_window_class == "firefox":
14 | print("firefox is in focus")
15 | else:
16 | print("firefox is not in focus")
17 |
18 | # the user function will be called whenever the active window changes
19 | window.on_window_change(on_window_change)
20 | ```
21 |
22 | Listens to window change events from the desktop environemnt and calls the provided
23 | user function with the active window information.
24 |
25 |
26 | Supported on:
27 | - ✅ Hyprland
28 | - ✅ X11
29 | - ❌ Gnome (wayland)
30 | - ❌ KDE plasma (wayland)
31 |
32 |
33 | ## Options
34 |
35 | This object has no options.
36 |
37 |
38 | ## Methods
39 |
40 | ### on_window_change(handler)
41 |
42 | Register a user function that gets called when the active window changes.
43 |
44 | - **handler**: (active_window_class: string?) -> None
45 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/api/writer.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Writer'
3 | description: 'Writer | map2 API documentation'
4 | ---
5 |
6 |
7 | ```python
8 | import map2
9 |
10 | # clone existing device
11 | writer1 = map2.Writer(clone_from = "/dev/input/by-id/example-keyboard")
12 |
13 | # create a new virtual device with specific capabilities
14 | writer2 = map2.Writer(capabilities = {"rel": True, "buttons": True})
15 | ```
16 |
17 |
18 | Creates a virtual device that can emmit output events and behaves just like
19 | a physical devices.
20 |
21 |
22 | Supported on:
23 | - ✅ Hyprland
24 | - ✅ X11
25 | - ✅ Gnome (wayland)
26 | - ✅ KDE plasma (wayland)
27 |
28 |
29 | ## Options
30 |
31 |
32 | ### clone_from
33 |
34 | ```
35 | string?
36 | ```
37 |
38 | Defines which output events the virtual device can emmit based on an existing device.
39 |
40 |
41 | ### capabilities
42 |
43 | ```
44 | {
45 | "rel": bool?,
46 | "abs": bool?,
47 | "buttons": bool?,
48 | "keys": bool?,
49 | }
50 | ```
51 |
52 | Defines which output events the virtual device can emmit.
53 |
54 |
55 | ## Methods
56 |
57 | ### send(input)
58 |
59 | Sends input events as if they were received through an input node.
60 |
61 | - **input**: key_sequence
62 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/basics/getting-started.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Getting started'
3 | description: 'Start using map2 for Linux input remapping, a simple guide'
4 | ---
5 |
6 | A map2 script is simply a python file that uses the map2 package. There are many good python tutorials
7 | out there, for example the [W3Schools python tutorial](https://www.w3schools.com/python).
8 |
9 | ## Running a script
10 |
11 | In most Linux setups, a regular user lacks the permissions to intercept input events for security reasons.
12 | If you have superuser permissions, you can simply run your script as the superuser
13 | (the `-E` flag is important to run in the current environment).
14 |
15 | ```bash
16 | sudo -E python my-map2-script.py
17 | ```
18 |
19 | This is somewhat risky as the script has access to copy your data, modify files and even remove system files.
20 | Use this method only for code you trust or have written yourself!
21 |
22 | For a more secure setup see the [Secure setup](/map2/en/advanced/secure-setup) section.
23 |
24 | ## Input devices
25 |
26 | On Linux, all connected input devices are listed in `/dev/inputX` where `X` is a number.
27 | To get more information about a device (label, ID, etc.), the following command can be used:
28 |
29 | ```bash
30 | udevadm info -q all -a /dev/inputX
31 | ```
32 |
33 | Some devices will also show up in `/dev/input/by-id` and `/dev/input/by-path`. This devices
34 | are just symbolic links to the appropriate `/dev/inputX` device, but with more
35 | descriptive names.
36 |
37 |
38 |
39 | ## My first map2 script
40 |
41 | Now that we know which input device we want to map on, let's write a short python script!
42 |
43 | ```python
44 | import time
45 | import map2
46 |
47 | # readers intercept all keyboard inputs and forward them
48 | reader = map2.Reader(patterns=["/dev/input/by-id/my-keyboard"])
49 |
50 | # mappers change inputs, you can also chain multiple mappers!
51 | mapper = map2.Mapper()
52 |
53 | # writers create new virtual devices we can write into
54 | writer = map2.Writer(clone_from = "/dev/input/by-id/my-keyboard")
55 |
56 | # finally, link nodes to control the event flow
57 | map2.link([reader, mapper, writer])
58 |
59 | mapper.map("a", "hello world")
60 |
61 | # keep running for 7 seconds
62 | time.sleep(7)
63 | ```
64 |
65 | After running the script, pressing the `a` key should emit `hello world` instead!
66 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/basics/install.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Install'
3 | description: 'Install map2 using one of various distribution options'
4 | ---
5 |
6 |
7 | ## Using pip
8 |
9 | It's safe to install the package globally, alternatively it also works in virtual envs.
10 |
11 | ```bash
12 | pip install map2
13 | ```
14 |
15 | ## AUR (Arch user Repository)
16 |
17 | Useful for people running Arch Linux, Manjaro, etc.
18 |
19 | ```bash
20 | pacman -S python-map2
21 | ```
22 |
23 | ## Building from source
24 |
25 | If you want to build the source code yourself, make sure you have `rust` and `cargo` installed
26 | and clone the repository.
27 |
28 | ```bash
29 | # clone the repository
30 | git clone https://github.com/shiro/map2.git
31 | cd map2
32 |
33 | # setup the environemnt
34 | python -m venv .env
35 | source .env/bin/activate
36 | pip install maturin patchelf
37 |
38 | # run build
39 | maturin develop
40 | ```
41 |
42 | ## Next steps
43 |
44 | To get started, check out the [Getting started](/map2/en/basics/getting-started) page for a
45 | basic guide on writing and running map2 scripts.
46 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/basics/introduction.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Introduction'
3 | description: 'map2 documentation introduction'
4 | ---
5 |
6 | **Welcome to map2**
7 |
8 | Want to remap your input devices like keyboards, mice, controllers and more?
9 | There's nothing you can't remap with **map2**!
10 |
11 | - 🖱️ **Remap keys, mouse events, controllers, pedals, and more!**
12 | - 🔧 **Highly configurable**, using Python
13 | - 🚀 **Blazingly fast**, written in Rust
14 | - 📦 **Tiny install size** (around 5Mb), almost no dependencies
15 | - ❤️ **Open source**, made with love
16 |
17 | Let's look at an example:
18 |
19 |
20 | ```python
21 | import map2
22 |
23 | # readers intercept all keyboard inputs and forward them
24 | reader = map2.Reader(patterns=["/dev/input/by-id/my-keyboard"])
25 | # mappers change inputs, you can also chain multiple mappers!
26 | mapper = map2.Mapper()
27 | # writers create new virtual devices we can write into
28 | writer = map2.Writer(clone_from = "/dev/input/by-id/my-keyboard")
29 | # finally, link nodes to control the event flow
30 | map2.link([reader, mapper, writer])
31 |
32 | # map the "a" key to "B"
33 | mapper.map("a", "B")
34 |
35 | # map "CTRL + ALT + u" to "META + SHIFT + w"
36 | mapper.map("^!u", "#+w")
37 |
38 | # key sequences are also supported
39 | mapper.map("s", "hello world!")
40 |
41 | # use the full power of Python using functions
42 | def custom_function(key, state):
43 | print("called custom function")
44 |
45 | # custom conditions and complex sequences
46 | if key == "d":
47 | return "{ctrl down}a{ctrl up}"
48 | return True
49 |
50 | mapper.map("d", custom_function)
51 | ```
52 |
53 | For the next step, check the [Install](/map2/en/basics/install) page and the
54 | [Getting started](/map2/en/basics/getting-started) page.
55 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/basics/keys-and-key-sequences.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Keys and key sequences'
3 | description: 'Learn about map2 keys and key sequences'
4 | ---
5 | import ValidKeysTable from "@root/components/ValidKeysTable.solid";
6 |
7 |
8 | All of map2's functions that deal with mapping keys and emmiting virtual input events accept
9 | a specific syntax for defining such events.
10 |
11 | ## Single keys
12 |
13 | Let's look at an example, the [Mapper::map_key(key, key)](/map2/en/api/mapper) function:
14 |
15 | ```python
16 | import map2
17 |
18 | mapper = map2.Mapper()
19 | mapper.map_key("a", "tab")
20 | ```
21 |
22 | This function maps the "a" key to the "tab" key and expects a `key` type for both sides.
23 | When functions expect a `key`, it means that only a single key with optional modifiers is allowed.
24 |
25 | Passing in additional modifiers is possible by prepending the keys with one or more of the following special
26 | characters:
27 |
28 | - `^`: ctrl
29 | - `!`: alt
30 | - `+`: shift
31 | - `#`: meta
32 |
33 | Let's map `ALT + a` to `CTRL + tab`:
34 |
35 | ```python
36 | import map2
37 |
38 | mapper = map2.Mapper()
39 |
40 | # "ALT + b" to "CTRL + tab"
41 | mapper.map_key("!b", "^tab")
42 |
43 | # if we want to map the "!" key, we need to escape it with "\"
44 | mapper.map_key("\\!", "^tab")
45 |
46 | # note that we used two "\" since it's a python string
47 | ```
48 |
49 | *Note*: Keys are case-sensitive except special keys discussed in the next section.
50 |
51 |
52 | ## Key sequences
53 |
54 | Sometimes functions accept more than one key, in which case we need to use the more explicit syntax.
55 | Let's look at the [Mapper::map(key, key_sequence)](/map2/en/api/mapper) function:
56 |
57 | ```python
58 | mapper.map("!a", "Hello!")
59 | mapper.map("b", "{ctrl down}{tab}{ctrl up}")
60 |
61 | # mixing regular characters with special ones is also allowed
62 | mapper.map("#c", "type this and CTRL+w{ctrl down}w{ctrl up}")
63 | ```
64 |
65 | Notice that the first argument is a `key` type while the second argument is a `key_sequence`.
66 | The special modifier characters are treated as normal characters, instead there are only two
67 | special characters in sequences: `{` and `}`.
68 |
69 | Special keys now need to be surrounded by curly braces, i.e. "tab" becomes `{tab}`, which
70 | will result in tab being pressed and released right after.
71 |
72 | In many cases, we want a key to be held for some time, which can be achieved by specifying a
73 | `state` after the key name, i.e. `{ctrl down}` will press the control key, but not release it.
74 |
75 | Valid states are:
76 | - `down`
77 | - `up`
78 | - `repeat`
79 |
80 |
81 | ## Special key list
82 |
83 | Here's a list of all special key names you can use with `{KEY_NAME}`.
84 |
85 |
86 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/basics/routing.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Routing'
3 | description: 'Routing using map2: define the input event flow'
4 | ---
5 |
6 | Routing in map2 refers to linking nodes such as [Reader](/map2/en/api/reader) and [Writer](/map2/en/api/writer),
7 | defining the input event flow chain.
8 |
9 | Let's look at a basic example:
10 |
11 |
12 | ```python
13 | import map2
14 |
15 | reader_kbd = map2.Reader(patterns=["/dev/input/by-id/example-keyboard"])
16 | reader_mouse = map2.Reader(patterns=["/dev/input/by-id/example-mouse"])
17 |
18 | mapper_kbd = map2.Mapper()
19 | mapper_mouse = map2.Mapper()
20 |
21 | writer_kbd = map2.Writer(clone_from = "/dev/input/by-id/example-keyboard")
22 | writer_mouse = map2.Writer(clone_from = "/dev/input/by-id/example-mouse")
23 |
24 | map2.link([reader_kbd, mapper_kbd, writer_kbd])
25 | map2.link([reader_mouse, mapper_mouse, writer_mouse])
26 | ```
27 |
28 | Here, we define two separate event chains, one for each input device, routing events
29 | from the respective reader, through a mapper and to a writer.
30 |
31 | ## Nodes
32 |
33 | Each object that can be placed in a chain is called a node.
34 |
35 | There exist 3 types of nodes:
36 |
37 | - **input**: needs to be at the beginning of a chain
38 | - **passthrough**: can't be at the beginning or end of a chain
39 | - **output**: needs to be at the end of a chain
40 |
41 | A good example for the 3 types of nodes are [Reader](/map2/en/api/reader),
42 | [Mapper](/map2/en/api/mapper) and [Writer](/map2/en/api/writer) respectively.
43 |
44 |
45 | ### Input nodes
46 |
47 | Input nodes collect input events, either from a physical device or from
48 | other inputs, and pass them on to the next node in the chain.
49 |
50 | Currently every input node can only appear in a **single chain**.
51 | This means the following code is invalid:
52 |
53 | ```python
54 | import map2
55 |
56 | reader = map2.Reader(patterns=["/dev/input/by-id/example-keyboard"])
57 | writer1 = map2.Writer(clone_from = "/dev/input/by-id/example-keyboard1")
58 | writer2 = map2.Writer(clone_from = "/dev/input/by-id/example-keyboard1")
59 |
60 | # error: every reader can only appear in a single chain
61 | map2.link([reader, writer1])
62 | map2.link([reader, writer2])
63 | ```
64 |
65 | ### Passthrough nodes
66 |
67 | Passthrough nodes receive input events from the previous node in the chain,
68 | and pass them on to the next node in the chain, potentially modifying,
69 | removing or creating new input events.
70 |
71 | A passtrhough node can appear in more than one chain at a time, let's look at
72 | an example:
73 |
74 | ```python
75 | import map2
76 |
77 | reader1 = map2.Reader(patterns=["/dev/input/by-id/example-keyboard-1"])
78 | reader2 = map2.Reader(patterns=["/dev/input/by-id/example-keyboard-1"])
79 | mapper = map2.Mapper()
80 | writer1 = map2.Writer(clone_from = "/dev/input/by-id/example-keyboard-1")
81 | writer2 = map2.Writer(clone_from = "/dev/input/by-id/example-keyboard-1")
82 |
83 | map2.link([reader1, mapper, writer1])
84 | map2.link([reader2, mapper, writer2])
85 | ```
86 |
87 | In this example, events from `reader1` flow through `mapper` and into `writer1`, while
88 | events from `reader2` flow through `mapper` into `writer2`.
89 |
90 | An important thing to note is, that the modifier state for each chain is separate, i.e.
91 | emitting `shift down` from `reader1` does not affect the mapping behaviour of
92 | inputs coming from `reader2`.
93 |
94 | It's also possible to chain multiple passthrough nodes.
95 |
96 | ```python
97 | import map2
98 |
99 | reader = map2.Reader(patterns=["/dev/input/by-id/example-keyboard-1"])
100 | mapper1 = map2.Mapper()
101 | mapper2 = map2.Mapper()
102 | mapper3 = map2.Mapper()
103 | writer = map2.Writer(clone_from = "/dev/input/by-id/example-keyboard-1")
104 |
105 | map2.link([reader, mapper1, mapper2, mapper3, writer])
106 | ```
107 |
108 | This can be useful for creating *mapping layers*, where each layer maps independently
109 | on the inputs received from the previous layer.
110 |
111 | ### Output nodes
112 |
113 | Output nodes consume events and usually pass them to a physical device, to the desktop
114 | environment, etc.
115 |
116 | Linking multiple chains to an output node is allowed, let's look at an example:
117 |
118 | ```python
119 | import map2
120 |
121 | reader1 = map2.Reader(patterns=["/dev/input/by-id/example-keyboard-1"])
122 | reader2 = map2.Reader(patterns=["/dev/input/by-id/example-keyboard-1"])
123 | writer = map2.Writer(clone_from = "/dev/input/by-id/example-keyboard-1")
124 |
125 | map2.link([reader1, writer])
126 | map2.link([reader2, writer])
127 | ```
128 |
129 | In this example, a single writer consumes events from multiple chains.
130 |
--------------------------------------------------------------------------------
/docs/src/content/docs/en/examples/chords.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Chords'
3 | description: 'TODO'
4 | ---
5 |
6 | import { Code } from 'astro:components';
7 | import code from "@examples/chords.py?raw";
8 |
9 |
10 |