xremap 0.15.4

Dynamic key remap for X and Wayland
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

## Press/release key

The press/release key can be used to match when keys are pressed, released or repeated.
It's only available in `modmap`, and can as the only feature in `modmap` emit actions.

[In more detail](#in-more-detail)

### Example: Action on key press

This configuration will show a notification each time `KEY_A` is pressed. It will also
preserve the normal behavior of `KEY_A`.

```yml
modmap:
  - remap:
      A:
        press: { launch: ["notify-send", "KEY_A pressed"] }
```

### Example: Shift lock

When using `Capslock` it's possible to type uppercase letters, but numbers and symbols will keep their
ordinary behavior. ShiftLock is a technique to lock the keyboard so it's possible type uppercase letters
and symbols. It's a way to avoid holding shift.

```yml
modmap:
  - mode: LeftShiftLocked
    remap:
      LeftShift:
        skip_key_event: true
        press:
          - { release: LeftShift }
          - { set_mode: default }

  - remap:
      LeftShift:
        skip_key_event: true
        press:
          - { press: LeftShift }
          - { set_mode: LeftShiftLocked }
```

Note: It will still lock shift if it's interrupted. The normal way to use shift is to interrupt it.
So the normal behavior is not preserved with this example.

### Example: Emit key combo on key press

When `Capslock` is pressed will the key combo `ctrl-v` be emitted and it will be held until `Capslock`
is released. This is different from remapping in `keymap` with `Capslock: c-v`, where the key combo is released right
away.

```yml
modmap:
  - remap:
      Capslock:
        press: [{ press: LeftCtrl }, { press: V }]
        release: [{ release: V }, { release: LeftCtrl }]
        skip_key_event: true
```

### Example: Disable key repeat

This configuration makes the press/release explicit and then disables the normal action. The effect
is that the key doesn't do anything on repeat.

```yml
modmap:
  - remap:
      A:
        press: { press: A }
        release: { release: A }
        skip_key_event: true
```

Note: This doesn't necessarily disable the repeat behavior, because the kernel inserts key repeat
automatically for the latest pressed key.

## In more detail

`press`, `release` and `repeat` can all take the same values and default is no actions.

```yml
modmap:
  - remap:
      Capslock:
        skip_key_event: true # Default is false.
        press: KEY_A # Single key
        release: Ctrl-V # Key combo
        repeat: [KEY_B, KEY_C] # Several keys or key combos.
        # repeat: [] # Default is no actions.
        # repeat: null # Another way to say no actions.
        # repeat: [{ sleep: 10 }] # Single action
        # repeat: [{ press: D }, { release: D }] # Several actions.
```

### Actions

The same [actions as in keymap](#in-more-detail) are supported.

The trigger key is emitted after the actions, except if it's disabled with `skip_key_event`.

Key events emitted from `modmap` will normally go through `keymap` and can be remapped there. That's still true
for the trigger key. It's however not true for actions
that are emitted from press/release keys. They go around the `keymap` even if they contain key events like
`[KEY_A, { press: B }, { release: B }]`.

The `set_mode`, `escape_next_key` and `mark_set` take effect before the trigger key is remapped in `keymap`.