Shell components talk to YAWC over a Unix socket at
$XDG_RUNTIME_DIR/yawc-$WAYLAND_DISPLAY.sock, exported to every client as
YAWC_SOCKET. The protocol is text: one request a line, fields separated by
tabs.
Trying it
printf 'hotkeys\n' | nc -U -q1 "$YAWC_SOCKET"
yawc msg activate-app etyde-files # one request, for scripts
yawc msg 'spawn etyde-applet calculator'From an applet, use the SDK’s client instead (see Background work and the system).
Requests
Windows
| Request | Effect |
|---|---|
subscribe | Start receiving windows blocks whenever the list changes |
activate <id> | Focus a window, restoring it if minimized |
minimize <id>, close <id> | |
activate-app <app_id> | Bring that application’s window forward |
overview-windows <id> <id>… | Open the overview with only these windows, to pick one by sight |
spawn <command> | Run a shell command in the session |
The shell
| Request | Effect |
|---|---|
listen-shell | Receive dock-show, dock-hide, launcher-toggle and the other shell events (the dock applet) |
shell-focus <app_id>⇥on|off | Give the keyboard to a shell window, or hand it back |
regions <app_id>⇥<passthrough 0|1>⇥<slide>[⇥<region>…] | Describe parts of a window (below) |
caret-popup layout|clipboard|off | The caret surface is about to show this: move it to where the person is typing |
Keys, clipboard, screens
| Request | Reply |
|---|---|
hotkeys | A hotkeys block |
set-hotkey <name>⇥<binding> | ok, or error⇥<message> |
inhibit-hotkeys on|off | Lets a client record key combinations (Settings > Keyboard) |
set-clipboard <text> | Puts text on the clipboard. \n, \t and \\ are escapes. |
set-clipboard-file <mime>⇥<path> | Puts a file’s contents on the clipboard under one type (a screenshot) |
outputs | An outputs block |
set-output <name>⇥<property>⇥<value> | Changes enabled, primary, x, y, scale or mode; saved to the config. ok or error⇥<message> |
(⇥ is a tab.)
Replies and events
| Line | Meaning |
|---|---|
windows <n> | Followed by n lines: <id>⇥<app_id>⇥<flags>⇥<title>. Flags: a active, m minimized, - neither. |
hotkeys <n> | Followed by n lines: <name>⇥<binding> |
outputs <n> | Followed by n lines: <name>⇥<flags>⇥<x>⇥<y>⇥<scale>⇥<mode>⇥<modes>. Flags: e enabled, p primary. modes is a comma-separated list. |
dock-show, dock-hide | The dock is sliding in or out |
launcher-toggle, clipboard-toggle | That hotkey was pressed |
overview-on, overview-off | The overview opened or closed |
clipboard⇥<text> | A client copied this text |
clipboard-image⇥<path> | A picture was copied; it is in this PNG file, which the shell takes over |
layout⇥<name> | The keyboard layout was switched (also said once to a new listener) |
keep-above⇥on|off⇥<title> | The hotkey pinned this window on top, or let it go |
Glass regions
Any client may describe regions of its window; YAWC blurs what is behind each one, clipped to its rounded shape, right beneath the window’s surface. Nirvana does this for the dock, the launcher and window sidebars.
A region is x y w h radius corners flags, in window coordinates:
| Field | Meaning |
|---|---|
corners | A bit mask of the corners rounded by radius: 1 top left, 2 top right, 4 bottom right, 8 bottom left |
flags | b: blur what is behind. i: accepts pointer input. |
With passthrough 1 the pointer only hits i regions: the rest of the
window is click-through. slide is how far the dock moves down when hidden.
A note on trust
The socket is the session’s own: whoever can reach it is already a program of
the logged-in user. It is not a sandbox boundary, and spawn runs what it is
given.