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 is not supported yet.
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```