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
63Use an external locker such as swaylock or hyprlock. See [Session locking](session-lock.md).
64
65## Screen capture
66
67nefercap, `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).
68
69## Idle and screen off
70
71[swayidle](https://github.com/swaywm/swayidle) and [wlopm](https://git.sr.ht/~leon_plickat/wlopm) turn the screens off after a delay:
72
73```text
74startup = swayidle -w timeout 300 wlopm-off resume wlopm-on
75```
76
77```sh
78#!/bin/sh
79# ~/.local/bin/wlopm-off (wlopm-on is the same with --on)
80exec wlopm --off '*'
81```
82
83Video players, games and browsers keep the screens on while they ask to, through Wayland or D-Bus (`org.freedesktop.ScreenSaver`).
84
85## Power keys
86
87NeferWL stops logind from acting on the power, suspend, hibernate and reboot keys. They do nothing unless you bind them:
88
89```text
90bind.XF86PowerOff = spawn systemctl suspend
91bind.XF86Suspend = spawn systemctl hibernate
92```
93
94| Key | Bind name |
95|---|---|
96| Power | `XF86PowerOff` |
97| Sleep | `XF86Sleep` |
98| Suspend | `XF86Suspend` |
99| Reboot | `code:408` |
100
101The lid switch is still handled by logind.
102
103## Bars
104
105Waybar 0.13+ (`ext/workspaces`) and ironbar show and switch workspaces. Taskbars can list, focus and close windows.
106
107Workspace 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.
108
109## State for scripts
110
111NeferWL 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.
112
113```sh
114neferwl state                        # the whole state
115neferwl state output-of "$PID"       # the output showing that process's window
116neferwl state | jq '[.windows[] | select(.hidden)] | length'   # windows in hidden stashes
117```