1# Desktop integration
2
3## Running commands
4
5`spawn` binds, `startup` and `terminal` run a program directly, **without a shell**. The line is split on spaces: the first word is the program (from `PATH` or a full path), the rest are its arguments. `;` separates several commands, which all start at once.
6
7```text
8bind.ctrl+cmd+space = spawn fuzzel
9startup = waybar; mako; wl-paste --watch cliphist store
10```
11
12Pipes, `&&`, redirections, `$VARIABLES`, `~` and quotes are passed as plain text. For those, write a script in your `PATH` and run it:
13
14```sh
15#!/bin/sh
16# ~/.local/bin/screenshot-main
17nefercap screenshot -output DP-1 -file "$HOME/Pictures/$(date +%F-%T).png"
18```
19
20```text
21bind.cmd+shift+p = spawn screenshot-main
22```
23
24Programs started by NeferWL get `WAYLAND_DISPLAY`, `DISPLAY` and `NEFERWL_STATE`. `startup` changes apply at the next session.
25
26## Clipboard
27
28The clipboard, primary selection (middle-click paste) and clipboard managers work. A [cliphist](https://github.com/sentriz/cliphist) history:
29
30```text
31startup = wl-paste --watch cliphist store
32bind.cmd+v = spawn cliphist-pick
33```
34
35```sh
36#!/bin/sh
37# ~/.local/bin/cliphist-pick
38cliphist list | fuzzel --dmenu | cliphist decode | wl-copy
39```
40
41Drag and drop works between clients: the surface under the pointer gets the offer, the drop and the chosen action (copy, move or ask, from the modifiers the clients read), and the drag icon follows the cursor. Escape, a refused drop, a dying source or the session lock cancel the drag.
42
43## Input methods
44
45[fcitx5](https://fcitx-im.org) and IBus work through `zwp_input_method_v2`. Start one at session start:
46
47```text
48startup = fcitx5 -d
49```
50
51Candidate popups are not drawn yet.
52
53## X11 apps
54
55X11 apps such as Steam run through [xwayland-satellite](https://github.com/Supreeeme/xwayland-satellite) 0.7+, found in `PATH`. NeferWL starts it when the first X11 app connects; do not start it yourself.
56
57```text
58xwayland = off   # no X11 support
59```
60
61## Session locking
62
63NeferWL supports `ext-session-lock-v1` with an external locker such as swaylock or hyprlock. The locker checks the password; NeferWL hides the desktop and blocks input.
64
65### While locked
66
67- Only the locker gets input. Binds, clipboard requests and new captures are refused.
68- Outputs show black and the locker's surfaces only.
69- Running captures stop.
70- `Ctrl+Alt+Backspace` is disabled. VT switching still works.
71- A locker that uses a screenshot as background (hyprlock `screenshot`, swaylock-effects `--screenshots`) must be in the [capture allowlist](capture.md#the-allowlist).
72
73The locker is told `locked` only once every output shows a protected frame or is off.
74
75### If the locker dies
76
77The session stays locked and black. Start a new locker to take over. There is no emergency unlock key and no timeout.
78
79A locker that exits right after unlocking must do a Wayland roundtrip first, or its exit counts as a crash and the session stays locked.
80
81### Limits
82
83- NeferWL does not authenticate: no PAM, no stored credentials.
84- Any process running as your user can start its own locker and unlock.
85- Clipboard data and window contents a client received before the lock stay with that client.
86- The [state file](desktop.md#state-for-scripts) is not cleared while locked.
87
88## Screen capture
89
90nefercap, `grim` and screen sharing through `xdg-desktop-portal-gnome` work out of the box. Other tools must be added to the allowlist. See [Screen capture](capture.md).
91
92## Idle and screen off
93
94[swayidle](https://github.com/swaywm/swayidle) and [wlopm](https://git.sr.ht/~leon_plickat/wlopm) turn the screens off after a delay:
95
96```text
97startup = swayidle -w timeout 300 wlopm-off resume wlopm-on
98```
99
100```sh
101#!/bin/sh
102# ~/.local/bin/wlopm-off (wlopm-on is the same with --on)
103exec wlopm --off '*'
104```
105
106Video players, games and browsers keep the screens on while they ask to, through Wayland or D-Bus (`org.freedesktop.ScreenSaver`).
107
108## Power keys
109
110NeferWL stops logind from acting on the power, suspend, hibernate and reboot keys. They do nothing unless you bind them:
111
112```text
113bind.XF86PowerOff = spawn systemctl suspend
114bind.XF86Suspend = spawn systemctl hibernate
115```
116
117| Key | Bind name |
118|---|---|
119| Power | `XF86PowerOff` |
120| Sleep | `XF86Sleep` |
121| Suspend | `XF86Suspend` |
122| Reboot | `code:408` |
123
124The lid switch is still handled by logind.
125
126## Bars
127
128Waybar 0.13+ (`ext/workspaces`) and ironbar show and switch workspaces. Taskbars can list, focus and close windows.
129
130Workspace IDs are `name:<name>` for named workspaces, stable across launches. Numbered workspaces get a random prefix per launch, so do not save settings keyed on them.
131
132## State for scripts
133
134NeferWL writes its state as JSON to `$XDG_RUNTIME_DIR/neferwl/<wayland socket>.json`, also given to started programs as `$NEFERWL_STATE`. It lists outputs, workspaces, the focused window, and every window with its app ID, PID, workspace, column and row.
135
136The `workspaces` list holds every workspace with its `visible` flag, its columns and the windows in them, each with `x`, `y`, `width` and `height` in logical pixels of its output. The file is written at most once per second.
137
138```sh
139neferwl state                        # the whole state
140neferwl state output-of "$PID"       # the output showing that process's window
141neferwl state | jq '[.windows[] | select(.hidden)] | length'   # windows in hidden stashes
142neferwl state | jq '.workspaces[] | select(.visible) | .columns[] | .width'   # column widths on screen
143```