Module vkclient 

Virtual-keyboard client for typing into a nested app compositor’s socket. zwp_virtual_keyboard_v1 client for typing Unicode text into a nested compositor’s socket.

pixelflux is normally the compositor, but in a nested deployment (a labwc/kwin session running as a client of pixelflux) the apps live on that inner compositor’s socket, and keys injected into pixelflux’s own seat resolve against pixelflux’s keymap — an overlay the inner compositor never sees. So text is typed here as a client of whichever compositor the apps live under — by Computer-Use actions and by selkies over the type_text_wayland ABI — reusing the seat’s [KeymapPolicy] over a US base: base-reachable characters press their ordinary keycodes, everything else is overlay-bound onto the main block’s character keys ([OVERLAY_KEYCODES]). The client is PERSISTENT per socket: the connection, virtual-keyboard device, and its uploaded keymap live across calls, so a flush re-uploads (and settles) only when the accumulated keymap actually changed, and key events ride the protocol’s ordering in one batch with a single closing round-trip. Any failure drops the cached connection and one reconnect is attempted before the error propagates, so a restarted app compositor heals on the next call. Blocking, off the compositor thread, with every round-trip deadline-bounded so a wedged compositor cannot hang the caller forever.

Structs

Globals 🔒

Typer 🔒

Constants

EVDEV_OFFSET 🔒

wl_keyboard / zwp_virtual_keyboard key events carry evdev codes (xkb - 8).

KEYMAP_FORMAT_XKB_V1 🔒

OVERLAY_KEYCODES 🔒

Overlay keycodes: the main block’s character keys, 1 to /. A client may take a keycode for the physical key it names before, or instead of, the keysym the keymap gives it: Chromium drops a key whose code names no key it knows, and runs its browser, media, and launcher keys as commands, so a character bound to a spare vendor keycode is lost, or navigates the page. The character keys are the ones every layout remaps, and this keymap is the virtual keyboard’s own, so rebinding them leaves the user’s keyboard be. Under the X11 255 ceiling for XWayland apps.

OVERLAY_SLOTS 🔒

Statics

KEYMAP_GENERATION 🔒

Bumped whenever the shared policy’s keymap changes; each cached typer re-uploads (and settles) only when it is behind this.

Functions

connect_typer 🔒

flush_keysyms 🔒

shared_policy 🔒

The keymap policy over that base, shared across calls: rebuilding it costs a keymap compile per typed batch, and its accumulated overlay assignments are device-independent, so repeat batches reuse their slots. Locked — callers run off-thread and Computer-Use may type concurrently with selkies.

type_keysyms_to

Like type_text_to, but taps the given keysyms verbatim: the caller owns which keysym spells which character; this owns delivery (base-reachable keysyms press their ordinary keycodes, the rest overlay-bind).

type_text_to

Type text in order through the persistent client for socket_path. Codepoints with no keysym are skipped. Blocking; call off the compositor’s calloop thread.

typers 🔒

universal_keysym 🔒

Universal keysym for a character: Latin-1 keysyms are their codepoint and everything above rides the Unicode plane — the two encodings every compositor and toolkit translate algorithmically. Editing controls map to their keys; other controls have no keysym. Fixed grammar only: which keysym spells a char in any richer sense is selkies’ policy, delivered via type_keysyms_to.

upload_keymap 🔒

us_base_text 🔒

The US base keymap text, compiled once per process: selkies types per text commit, and xkbcommon compilation is the expensive part of a call.