Skip to content

Commit 912aae1

Browse files
paperbennipaperbenni
committed
2 parents 91272d9 + 970fca8 commit 912aae1

7 files changed

Lines changed: 315 additions & 34 deletions

File tree

‎.vitepress/config.mts‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ export default defineConfig({
3131
{ text: 'Home', link: '/' },
3232
{ text: 'Download', link: '/download' },
3333
{ text: 'Documentation', link: '/docs/' },
34+
{ text: 'Tips', link: '/tips/vim' },
3435
{ text: 'Development', link: '/development/development' },
3536
{ text: 'FAQ', link: '/faq' },
3637
{ text: 'Support', link: '/support' },
@@ -68,6 +69,15 @@ export default defineConfig({
6869
]
6970
}
7071
],
72+
'/tips/': [
73+
{
74+
text: 'General Linux Tips',
75+
items: [
76+
{ text: 'Vim hotkeys', link: '/tips/vim' },
77+
{ text: 'Game Begin Guide', link: '/tips/gamebegin' },
78+
]
79+
}
80+
],
7181
'/docs/': [
7282
{
7383
text: 'Getting Started',
@@ -81,7 +91,6 @@ export default defineConfig({
8191
text: "Beginner's Guide",
8292
items: [
8393
{ text: 'Installation Guide', link: '/docs/beginner/installguide' },
84-
{ text: 'Vim hotkeys', link: '/docs/beginner/vim' },
8594
]
8695
},
8796
{
@@ -126,6 +135,7 @@ export default defineConfig({
126135
text: 'Window Management',
127136
items: [
128137
{ text: 'Hotkeys', link: '/docs/hotkeys' },
138+
{ text: 'Modes', link: '/docs/modes' },
129139
{ text: 'Overlays', link: '/docs/overlays' },
130140
{ text: 'Layouts', link: '/docs/layouts' },
131141
{ text: 'Floating Windows', link: '/docs/floating' },
@@ -144,7 +154,6 @@ export default defineConfig({
144154
text: 'Gaming',
145155
items: [
146156
{ text: 'Gaming', link: '/docs/gaming/gaming' },
147-
{ text: 'Game Begin', link: '/docs/gaming/gamebegin' }
148157
]
149158
}
150159
],

‎docs/instantwmctl.md‎

Lines changed: 32 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,14 @@
66

77
```bash
88
instantwmctl [command]
9+
10+
# Get JSON output for machine-readable results
11+
instantwmctl --json [command]
12+
instantwmctl -j [command]
913
```
1014

15+
The `--json` flag can be used with most commands to get machine-readable JSON output instead of human-readable text. Place the flag **before** the subcommand.
16+
1117
## General Commands
1218

1319
| Command | Description |
@@ -34,6 +40,7 @@ instantwmctl [command]
3440
|---------|-------------|
3541
| `instantwmctl tag` | Switch to tag 2 (default) |
3642
| `instantwmctl tag <number>` | Switch to tag number (1-8) |
43+
| `instantwmctl tag view <number>` | Explicitly switch to tag number |
3744
| `instantwmctl tag name <name>` | Rename current tag |
3845
| `instantwmctl tag reset` | Reset all tag names to defaults |
3946

@@ -42,18 +49,18 @@ instantwmctl [command]
4249
| Command | Description |
4350
|---------|-------------|
4451
| `instantwmctl layout` | Switch to tile layout |
45-
| `instantwmctl layout <number>` | Switch to layout by index |
46-
47-
Layout indices:
48-
- 0 = Tile
49-
- 1 = Grid
50-
- 2 = Floating
51-
- 3 = Monocle
52-
- 4 = Vert
53-
- 5 = Deck
54-
- 6 = Overview
55-
- 7 = Bstack
56-
- 8 = Horiz
52+
| `instantwmctl layout <name>` | Switch to layout by name |
53+
54+
Layout names:
55+
- tile = Tile
56+
- grid = Grid
57+
- floating = Floating
58+
- monocle = Monocle
59+
- vert = Vert
60+
- deck = Deck
61+
- overview = Overview
62+
- bstack = Bstack
63+
- horiz = Horiz
5764

5865
## Monitor Management
5966

@@ -62,7 +69,9 @@ Layout indices:
6269
| `instantwmctl monitor list` | List all monitors |
6370
| `instantwmctl monitor switch <index>` | Switch to monitor by index |
6471
| `instantwmctl monitor next` | Switch to next monitor |
72+
| `instantwmctl monitor next <count>` | Switch to monitor N steps ahead |
6573
| `instantwmctl monitor prev` | Switch to previous monitor |
74+
| `instantwmctl monitor prev <count>` | Switch to monitor N steps back |
6675
| `instantwmctl monitor set -r 1920x1080 -f 144` | Configure monitor |
6776
| `instantwmctl monitor set --enable` | Enable monitor |
6877
| `instantwmctl monitor set --disable` | Disable monitor |
@@ -72,15 +81,16 @@ Monitor set options:
7281
- `-f, --rate` - Refresh rate in Hz
7382
- `-p, --pos` - Position (e.g., "1920,0")
7483
- `-s, --scale` - Scale factor
84+
- `-t, --transform` - Display transform (Normal, 90, 180, 270, Flipped, flipped-90, flipped-180, flipped-270)
7585

7686
## Window Movement
7787

7888
| Command | Description |
7989
|---------|-------------|
80-
| `instantwmctl tagmon` | Move window to next monitor |
81-
| `instantwmctl tagmon -1` | Move window to previous monitor |
82-
| `instantwmctl followmon` | Move window to next monitor and follow |
83-
| `instantwmctl followmon -1` | Move window to previous monitor and follow |
90+
| `instantwmctl tag-mon next` | Move window to next monitor |
91+
| `instantwmctl tag-mon prev` | Move window to previous monitor |
92+
| `instantwmctl follow-mon next` | Move window to next monitor and follow |
93+
| `instantwmctl follow-mon prev` | Move window to previous monitor and follow |
8494

8595
## Toggle Features
8696

@@ -89,7 +99,6 @@ Monitor set options:
8999
| `instantwmctl toggle animated` | Toggle window animations |
90100
| `instantwmctl toggle focus-follows-mouse` | Toggle focus follows mouse |
91101
| `instantwmctl toggle focus-follows-float-mouse` | Toggle focus follows mouse for floating windows |
92-
| `instantwmctl toggle alt-tab` | Toggle alt-tab mode |
93102
| `instantwmctl toggle alt-tag` | Toggle alt-tag mode |
94103
| `instantwmctl toggle hide-tags` | Toggle hide tags |
95104

@@ -103,10 +112,8 @@ Toggle actions can take additional arguments:
103112
| Command | Description |
104113
|---------|-------------|
105114
| `instantwmctl border <width>` | Set border width in pixels |
106-
| `instantwmctl prefix` | Enable prefix mode |
107-
| `instantwmctl prefix 0` | Disable prefix mode |
108-
| `instantwmctl special-next` | Enable special next mode for cycling |
109-
| `instantwmctl special-next 0` | Disable special next mode |
115+
| `instantwmctl special-next float` | Enable special next mode for cycling |
116+
| `instantwmctl special-next none` | Disable special next mode |
110117

111118
## Keyboard Layout
112119

@@ -142,6 +149,7 @@ Layouts can include variants: `de(nodeadkeys)`, `us(intl)`, etc.
142149
| Command | Description |
143150
|---------|-------------|
144151
| `instantwmctl mouse list` | List input device configuration |
152+
| `instantwmctl mouse devices` | List all detected input devices |
145153
| `instantwmctl mouse list "type:touchpad"` | List touchpad configuration |
146154
| `instantwmctl mouse pointer-accel "type:touchpad" 0.5` | Set pointer acceleration |
147155
| `instantwmctl mouse accel-profile "type:touchpad" flat` | Set acceleration profile |
@@ -151,6 +159,8 @@ Layouts can include variants: `de(nodeadkeys)`, `us(intl)`, etc.
151159

152160
Valid identifiers: `type:touchpad`, `type:pointer`, `type:keyboard`, or `*` for all devices.
153161

162+
Note: `instantwmctl input` is an alias for `instantwmctl mouse`.
163+
154164
## Modes
155165

156166
| Command | Description |
@@ -193,7 +203,7 @@ instantwmctl tag 3
193203
instantwmctl toggle animated
194204

195205
# Change layout to grid
196-
instantwmctl layout 1
206+
instantwmctl layout grid
197207

198208
# Enable tap-to-click on touchpad
199209
instantwmctl mouse tap "type:touchpad" enabled

‎docs/modes.md‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Modes
2+
3+
Modes in instantWM work similarly to Sway/i3 modes, allowing you to define sets of keybindings that are only active in certain contexts. This is useful for defining specialized keybindings for tasks like resizing windows, navigating scratchpads, or running specific commands.
4+
5+
## Basic Usage
6+
7+
Define modes in your [`config.toml`](wmsettings#configuration-file-location):
8+
9+
```toml
10+
[modes.resize]
11+
description = "Resize"
12+
keybinds = [
13+
{ modifiers = [], key = "Escape", action = { set_mode = "default" } },
14+
{ modifiers = [], key = "Return", action = { set_mode = "default" } },
15+
{ modifiers = ["Shift"], key = "h", action = { set_mfact = -0.05 } },
16+
{ modifiers = ["Shift"], key = "j", action = "focus_down" },
17+
{ modifiers = ["Shift"], key = "k", action = "focus_up" },
18+
{ modifiers = ["Shift"], key = "l", action = { set_mfact = 0.05 } },
19+
]
20+
21+
[modes.move]
22+
description = "Move"
23+
keybinds = [
24+
{ modifiers = [], key = "Escape", action = { set_mode = "default" } },
25+
{ modifiers = [], key = "Return", action = { set_mode = "default" } },
26+
{ modifiers = ["Shift"], key = "h", action = "move_client_left" },
27+
{ modifiers = ["Shift"], key = "j", action = "move_client_right" },
28+
{ modifiers = ["Shift"], key = "k", action = "focus_up" },
29+
{ modifiers = ["Shift"], key = "l", action = "focus_down" },
30+
]
31+
```
32+
33+
Then bind a key to enter a mode:
34+
35+
```toml
36+
[[keybinds]]
37+
modifiers = ["Super"]
38+
key = "r"
39+
action = { set_mode = "resize" }
40+
```
41+
42+
## Switching Modes
43+
44+
Use the `set_mode` action to enter a mode:
45+
46+
```toml
47+
action = { set_mode = "mode_name" }
48+
```
49+
50+
To exit a mode and return to the default mode:
51+
52+
```toml
53+
action = { set_mode = "default" }
54+
```
55+
56+
The current mode is displayed in the status bar. If a description is set for the mode, it will be shown instead of the mode name.
57+
58+
## Mode Descriptions
59+
60+
You can add an optional description to each mode that will be displayed in the status bar instead of the mode name:
61+
62+
```toml
63+
[modes.resize]
64+
description = "Resize windows"
65+
66+
[[modes.resize.keybinds]]
67+
key = "h"
68+
action = { set_mfact = -0.05 }
69+
```
70+
71+
In this example, when the resize mode is active, the status bar will show "mode: Resize windows" instead of "mode: resize".
72+
73+
## Mode Keybinds
74+
75+
Each mode can have its own keybinds using the same format as regular keybinds:
76+
77+
```toml
78+
[modes.my_mode]
79+
description = "My Custom Mode"
80+
81+
[[modes.my_mode.keybinds]]
82+
modifiers = ["Super"]
83+
key = "h"
84+
action = "focus_left"
85+
```
86+
87+
## Use Cases
88+
89+
### Resize Mode
90+
91+
A common pattern is to have a resize mode for adjusting window sizes:
92+
93+
```toml
94+
[modes.resize]
95+
description = "Resize"
96+
97+
[[modes.resize.keybinds]]
98+
modifiers = []
99+
key = "h"
100+
action = { set_mfact = -0.05 }
101+
102+
[[modes.resize.keybinds]]
103+
modifiers = []
104+
key = "j"
105+
action = { set_mfact = 0.05 }
106+
107+
[[modes.resize.keybinds]]
108+
modifiers = []
109+
key = "k"
110+
action = "inc_nmaster"
111+
112+
[[modes.resize.keybinds]]
113+
modifiers = []
114+
key = "l"
115+
action = "dec_nmaster"
116+
117+
[[modes.resize.keybinds]]
118+
modifiers = []
119+
key = "Return"
120+
action = { set_mode = "default" }
121+
122+
[[modes.resize.keybinds]]
123+
modifiers = []
124+
key = "Escape"
125+
action = { set_mode = "default" }
126+
```
127+
128+
Bind it with:
129+
130+
```toml
131+
[[keybinds]]
132+
modifiers = ["Super"]
133+
key = "r"
134+
action = { set_mode = "resize" }
135+
```
136+
137+
### Move Mode
138+
139+
Similarly, a move mode for moving windows between tags:
140+
141+
```toml
142+
[modes.move]
143+
description = "Move"
144+
145+
[[modes.move.keybinds]]
146+
modifiers = []
147+
key = "1"
148+
action = { spawn = ["instantwmctl", "action", "tag_all"] }
149+
150+
[[modes.move.keybinds]]
151+
modifiers = []
152+
key = "Return"
153+
action = { set_mode = "default" }
154+
155+
[[modes.move.keybinds]]
156+
modifiers = []
157+
key = "Escape"
158+
action = { set_mode = "default" }
159+
```
160+
161+
## Command Line Control
162+
163+
You can also control modes using `instantwmctl`:
164+
165+
```bash
166+
# List all configured modes
167+
instantwmctl mode list
168+
169+
# Set a mode (use "default" to exit)
170+
instantwmctl mode set resize
171+
172+
# Toggle a mode (enter if not active, exit if already active)
173+
instantwmctl mode toggle resize
174+
```
175+
176+
The `mode list` command shows all configured modes with an asterisk (*) next to the currently active mode.
177+
178+
## Built-in Modes
179+
180+
instantWM has built-in handling for move and resize modes that are triggered automatically when dragging windows with the mouse. These are separate from the user-defined modes configured via TOML.

0 commit comments

Comments
 (0)