One keyboard and mouse for a Mac and a Windows PC over the local network, in either direction.
"""Keyboard and mouse capture on Wayland, through the InputCapture portal and libei: the twin of
capture_x11.py, with the same Hooks, Trigger and names, so the bridge and the sender drive it.
Wayland lets no app see input meant for another, so capture is the desktop's. Beamer puts pointer
barriers on the outside edges of this machine's zones (the edge, its thirds, or a corner's two
walls) and the compositor, when the pointer pushes through one, captures every keyboard and
pointer and sends their events to Beamer over libei until Beamer lets go (Release). Nothing else
can start a capture, so input leaves this machine only across an edge: the shortcut (heard through
GlobalShortcuts) pushes the pointer through a barrier with relative RemoteDesktop motion, and
Beamer sees no other key at all while input is here.
A push into a barrier is not yet a crossing. The barrier holds the pointer, as Windows holds it at
the edge of the desktop, and the movement that follows feeds the sender's own zone models, so the
resistance, the corners and the thirds behave as on the other machines. The pointer can slide
along the barrier while held; the desktop shows it still, so where it is lives in desktop_portal
and the pointer is let go there. Any movement back into the screen, a key, a button, or a pause
in the push lets go of it; the key or button that did is lost, since nothing can play it back
here. Once the zone gives, input is away until the sender brings it home, and the pointer is let
go where the sender lands it (it says so through desktop_portal before or just after it reports
input home, so the let-go waits a moment for it).
While input is away, a key the sender hands back (the stays-here list) is lost for the same
reason, and the full-screen hold and the drag guard have nothing to read (desktop_portal).
Every way home is the desktop's: Release, the session closing when its D-Bus connection does
(a stop, an error, the process dying), and a watchdog that ends that connection when the capture
thread stops answering while the desktop holds input for it.
InputCapture v2 (GNOME 51, Plasma 6.7) remembers the user's answer with a restore token, kept in
the state directory; v1 asks at every start."""
import logging
import math
import os
import linux_desktop
import select
import threading
import time
from typing import Callable, Dict, List, Optional, Tuple
from capture_win import ( # noqa: F401 (re-exported for the bridge, which reads them from here)
BUTTON_TITLES,
MODIFIER_NAMES,
REDIRECT,
RETURN,
TOGGLE,
WHEEL_DELTA,
WM_MOUSEHWHEEL,
WM_MOUSEWHEEL,
Trigger,
button_of,
mouse_event,
wheel_notches,
)
from capture_x11 import ( # noqa: F401 (the same evdev names and titles as X11)
_BUTTONS,
CHORD_MASK,
KEYCODE_OFFSET,
NOT_TRIGGER_VKS,
UNRECORDABLE_TRIGGER_VKS,
VK_TITLES,
VK_TO_NAME,
_wheel_data,
character,
hook_vk,
input_title,
)
from core import keytable
from core import return_edge as crossing
import desktop_portal
import inject_portal
import portal
LOGGER = logging.getLogger(__name__)
INTERFACE = "org.freedesktop.portal.InputCapture"
CAP_KEYBOARD, CAP_POINTER = 1, 2
TICK_SECONDS = 0.05
STALL_SECONDS = 2.0
# A push that stops for this long is a pointer resting at the edge, which is let go.
IDLE_SECONDS = 0.3
# How long a let-go waits for the sender to say where the pointer lands.
LANDING_SECONDS = 0.15
# How long the portal has to answer a request no user sees (zones, barriers).
REQUEST_SECONDS = 10.0
# After the desktop disables the session, the barriers are set again no sooner than this.
DISABLED_SECONDS = 1.0
# An Activated signal with no activation_id (the portal spec allows it): libei's sequences are not
# checked, and Release names none.
NO_ID = -1
# A push that met two barriers at once is put on the nearest within this many pixels of the pointer.
WALL_PX = 64
# While input is away with nothing captured, the sender is asked to bring it home this often.
HOME_AGAIN_SECONDS = 0.5
# ei events that arrive before the portal's Activated signal says which barrier, held until it does.
EARLY_MAX = 64
EARLY_SECONDS = 1.0
# A shortcut push must trigger capture before this deadline expires.
PUSH_SECONDS = 1.5
PUSH_INSET_PX = 4
PUSH_STEPS = 6
PUSH_STEP_PX = 24
# libei's scroll is in the desktop's pixels; mutter and weston send 10 for one wheel click.
PIXELS_PER_NOTCH = 10.0
# evdev's button codes, as X numbers them for capture_x11's table.
EVDEV_BUTTONS = {0x110: 1, 0x111: 3, 0x112: 2, 0x113: 8, 0x114: 9}
# The core modifier bits a held key sets, for when the desktop does not say (libei sends a
# receiver its modifiers only if the compositor chooses to).
HELD_MODS = {42: 1, 54: 1, 29: 4, 97: 4, 56: 8, 125: 64, 126: 64}
# Wall outward directions.
_NORMAL = {"left": (-1, 0), "right": (1, 0), "top": (0, -1), "bottom": (0, 1)}
# The app's own sentences for what Wayland takes away; the bridge shows them as they are.
NO_PORTAL = ("This desktop does not let apps capture the keyboard and mouse (it has no InputCapture "
"portal), so this machine cannot drive another one. It can still be driven if the "
"desktop allows remote control.")
REFUSED = ("The desktop did not allow Beamer to capture the keyboard and mouse. Choose Ask again and allow the "
"requested keyboard and pointer access in the desktop prompt.")
ENDED = "The desktop stopped letting Beamer capture the keyboard and mouse: {detail}"
SESSION_CLOSED = ENDED.format(detail="the session was closed")
MISSING_CAPABILITIES = "InputCapture did not grant both keyboard and pointer capabilities, so this machine cannot send input."
class CaptureUnavailable(RuntimeError):
"""Capture cannot happen here; `sentence` says so in the app's words."""
def __init__(self, sentence: str) -> None:
super().__init__(sentence)
self.sentence = sentence
# -- barriers, pure -------------------------------------------------------
def _outer(monitors: List[crossing.Rect], monitor: crossing.Rect, edge: str) -> List[Tuple[int, int]]:
"""The stretches of `monitor`'s `edge`, as [start, end) along it, that no other display lies
beyond: a barrier must sit on the outside of the union of the zones."""
if edge in ("left", "right"):
line = monitor.x if edge == "left" else monitor.x + monitor.width
start, end = monitor.y, monitor.y + monitor.height
beyond = [(m.y, m.y + m.height) for m in monitors
if (m.x + m.width == line if edge == "left" else m.x == line)]
else:
line = monitor.y if edge == "top" else monitor.y + monitor.height
start, end = monitor.x, monitor.x + monitor.width
beyond = [(m.x, m.x + m.width) for m in monitors
if (m.y + m.height == line if edge == "top" else m.y == line)]
stretches = [(start, end)]
for low, high in beyond:
cut = []
for a, b in stretches:
if high <= a or low >= b:
cut.append((a, b))
continue
if a < low:
cut.append((a, low))
if high < b:
cut.append((high, b))
stretches = cut
return stretches
def _line(monitor: crossing.Rect, edge: str) -> int:
return {"left": monitor.x, "right": monitor.x + monitor.width,
"top": monitor.y, "bottom": monitor.y + monitor.height}[edge]
def _segment(monitor: crossing.Rect, edge: str, a: int, b: int) -> Tuple[int, int, int, int]:
line = _line(monitor, edge)
if edge in ("left", "right"):
return (line, a, line, b - 1)
return (a, line, b - 1, line)
def _clip(stretches, low: int, high: int) -> List[Tuple[int, int]]:
return [(max(a, low), min(b, high)) for a, b in stretches if min(b, high) > max(a, low)]
def _geometry(rect: crossing.Rect) -> tuple:
return rect.x, rect.y, rect.width, rect.height
def _thirds(monitor: crossing.Rect, edge: str) -> List[Tuple[int, int]]:
"""Each third of `monitor` along `edge`, as [start, end), split where return_edge.part_of
splits a fraction of the display."""
start, length = (monitor.y, monitor.height) if edge in ("left", "right") else (monitor.x, monitor.width)
cuts = [start + math.ceil(i * length / 3) for i in range(3)] + [start + length]
return [(cuts[i], cuts[i + 1]) for i in range(3)]
def barriers(models: list, monitors: List[crossing.Rect], whole_edges=False, display_map=None,
warn_unmatched: Optional[Callable[[str], None]] = None) -> List[Tuple[str, Tuple[int, int, int, int]]]:
"""(wall, position) for every barrier the sender's zone models need on these displays, in the
portal's coordinates, each once: a whole edge, the chosen thirds of it, or a corner's two walls
of CORNER_PX + 1 pixels. A notch stretch (SpanEdge) is the Mac's and has none here."""
found: List[Tuple[str, Tuple[int, int, int, int]]] = []
def add(wall, position):
if (wall, position) not in found:
found.append((wall, position))
for model in models:
selected = monitors
if model.display is not None:
display = display_map.get(model.display) if isinstance(display_map, dict) else None
matches = [monitor for monitor in monitors if display is not None and
_geometry(monitor) == _geometry(display)]
if len(matches) == 1:
selected = matches
else:
if warn_unmatched is not None:
warn_unmatched(model.display)
continue
if isinstance(model, crossing.SpanEdge):
continue
for monitor in selected:
if whole_edges:
walls = (model.vertical, model.horizontal) if isinstance(model, crossing.CornerPush) else (model.edge,)
for wall in walls:
start, length = (monitor.y, monitor.height) if wall in ("left", "right") else (monitor.x, monitor.width)
# KDE's portal rejects partial edges, including exposed pieces beside a staggered screen.
if _outer(monitors, monitor, wall) == [(start, start + length)]:
add(wall, _segment(monitor, wall, start, start + length))
continue
if isinstance(model, crossing.CornerPush):
for wall in (model.vertical, model.horizontal):
along_far = wall in ("left", "right")
other = model.horizontal if wall in ("top", "bottom") else model.vertical
if along_far: # a side wall runs along y, from the corner's top or bottom
low = monitor.y if other == "top" else monitor.y + monitor.height - 1 - crossing.CORNER_PX
else:
low = monitor.x if other == "left" else monitor.x + monitor.width - 1 - crossing.CORNER_PX
for a, b in _clip(_outer(monitors, monitor, wall), low, low + crossing.CORNER_PX + 1):
add(wall, _segment(monitor, wall, a, b))
continue
stretches = _outer(monitors, monitor, model.edge)
if isinstance(model, crossing.PartEdge):
thirds = _thirds(monitor, model.edge)
chosen = [thirds[crossing.PARTS.index(part)] for part in crossing.PARTS if part in model.parts]
stretches = [piece for low, high in chosen for piece in _clip(stretches, low, high)]
for a, b in stretches:
add(model.edge, _segment(monitor, model.edge, a, b))
return found
def model_key(models: list) -> tuple:
"""What about the models places barriers, so they are set again only when it changes."""
return tuple((type(m).__name__, m.edge, tuple(sorted(getattr(m, "parts", ()))), getattr(m, "corner", None),
getattr(m, "display", None))
for m in models)
class Press:
"""The pointer held at a barrier while input is still here: where it is, sliding along the
wall, and whether the movement is still a push."""
def __init__(self, wall: str, point: Tuple[int, int], displays: List[crossing.Rect], clock=time.monotonic) -> None:
self.wall = wall
self._displays = displays
self.point = desktop_portal.clamp_to(displays, *point)
self._clock = clock
self._last_push = clock()
self._exact = [float(self.point[0]), float(self.point[1])]
def feed(self, dx: float, dy: float) -> bool:
"""True while the movement pushes outward or slides along the wall; False once it comes
back into the screen, with `point` where it then is."""
nx, ny = _NORMAL[self.wall]
outward = dx * nx + dy * ny
if outward < 0:
self._move(dx, dy)
return False
# Only the part along the wall moves the pointer; the barrier holds the rest.
self._move(dx * (1 - abs(nx)), dy * (1 - abs(ny)))
if outward > 0:
self._last_push = self._clock()
return True
def _move(self, dx: float, dy: float) -> None:
self._exact[0] += dx
self._exact[1] += dy
self.point = desktop_portal.clamp_to(self._displays, *self._exact)
# Travel past the display is not kept: the pointer cannot be there.
for axis in (0, 1):
if self.point[axis] != round(self._exact[axis]):
self._exact[axis] = float(self.point[axis])
def idle(self) -> bool:
return self._clock() - self._last_push > IDLE_SECONDS
# -- the session ----------------------------------------------------------
class _Session:
"""The InputCapture session and its libei receiver, on the capture thread only."""
def __init__(self, bus_factory, ei_factory, tokens, stopping) -> None:
self.portal = portal.Portal(bus_factory(), stopping)
self._ei_factory = ei_factory
self._tokens = tokens
self.handle = None
self.ei = None
self.zone_set = None
self.enabled = False
def check(self) -> None:
preflight = getattr(self._ei_factory, "preflight", None)
if preflight is not None:
preflight()
self.version = self.portal.version(INTERFACE)
def open(self) -> None:
"""Make and start the session; the user may be asked, for as long as they take."""
LOGGER.info("Requesting InputCapture session (portal version %d)", self.version)
try:
if self.version >= 2:
try:
results = portal.plain(self.portal.call(INTERFACE, "CreateSession2", "a{sv}",
({"session_handle_token": ("s", self.portal.token())},)))
except portal.PortalError as exc:
raise CaptureUnavailable(f"{NO_PORTAL} ({exc})") from exc
self.handle = results[0]["session_handle"]
options = {"capabilities": ("u", CAP_KEYBOARD | CAP_POINTER), "persist_mode": ("u", 2)}
token = self._tokens.read()
if token:
options["restore_token"] = ("s", token)
started = self.portal.request(INTERFACE, "Start", "osa{sv}", lambda handle_token: (
self.handle, "", dict(options, handle_token=("s", handle_token))))
if started.get("capabilities", 0) & (CAP_KEYBOARD | CAP_POINTER) != CAP_KEYBOARD | CAP_POINTER:
self._tokens.write("")
raise CaptureUnavailable(MISSING_CAPABILITIES)
if started.get("restore_token"):
self._tokens.write(started["restore_token"])
else:
try:
results = self.portal.request(INTERFACE, "CreateSession", "sa{sv}", lambda handle_token: ("", {
"handle_token": ("s", handle_token),
"session_handle_token": ("s", self.portal.token()),
"capabilities": ("u", CAP_KEYBOARD | CAP_POINTER),
}))
except portal.PortalError as exc:
raise CaptureUnavailable(f"{NO_PORTAL} ({exc})") from exc
self.handle = results["session_handle"]
if results.get("capabilities", 0) & (CAP_KEYBOARD | CAP_POINTER) != CAP_KEYBOARD | CAP_POINTER:
self._tokens.write("")
raise CaptureUnavailable(MISSING_CAPABILITIES)
except portal.Refused:
self._tokens.write("")
raise CaptureUnavailable(REFUSED) from None
fd = self.portal.call(INTERFACE, "ConnectToEIS", "oa{sv}", (self.handle, {}))[0]
try:
self.ei = self._ei_factory(fd)
except Exception:
os.close(fd)
raise
def zones(self) -> List[crossing.Rect]:
results = self.portal.request(INTERFACE, "GetZones", "oa{sv}", lambda token: (self.handle, {"handle_token": ("s", token)}),
timeout=REQUEST_SECONDS)
self.zone_set = results.get("zone_set")
return [crossing.Rect(x, y, width, height) for width, height, x, y in results.get("zones", [])]
def set_barriers(self, positions: List[Tuple[int, int, int, int]]) -> List[int]:
"""Barrier i + 1 for each position; the ids the desktop refused. An enabled session is
disabled first and enabled again after, when there are any: GNOME refuses every barrier
and a second Enable on an enabled session, and an explicit Disable sends no Disabled signal.
A session the desktop already disabled is not sent another Disable, which GNOME refuses."""
if self.enabled:
self.enabled = False
try:
self.portal.call(INTERFACE, "Disable", "oa{sv}", (self.handle, {}))
except portal.PortalError as exc:
LOGGER.warning("Could not disable the capture session before setting its barriers (%s)", exc)
listed = [{"barrier_id": ("u", index + 1), "position": ("(iiii)", tuple(position))}
for index, position in enumerate(positions)]
results = self.portal.request(INTERFACE, "SetPointerBarriers", "oa{sv}aa{sv}u", lambda token: (
self.handle, {"handle_token": ("s", token)}, listed, self.zone_set or 0), timeout=REQUEST_SECONDS)
if positions:
self.enable()
return list(results.get("failed_barriers", []))
def enable(self) -> None:
self.portal.call(INTERFACE, "Enable", "oa{sv}", (self.handle, {}))
self.enabled = True
def release(self, activation_id: int, point: Tuple[int, int]) -> None:
options = {"cursor_position": ("(dd)", (float(point[0]), float(point[1])))}
if activation_id != NO_ID:
options["activation_id"] = ("u", int(activation_id))
self.portal.call(INTERFACE, "Release", "oa{sv}", (self.handle, options))
def close(self) -> None:
try:
if self.ei is not None:
self.ei.close()
finally:
self.ei = None
self.portal.close()
class Hooks:
"""The capture thread and the session it owns, with capture_x11.Hooks' callbacks:
`on_key(name, down, vk, us)`, `on_mouse(message, x, y, mouse_data)` and `on_motion(dx, dy)`,
`vk` the evdev code. `grab_while(predicate)` says when input is away; `barriers_from(models)`
gives the sender's zone models, empty while the edges are held. `on_home` is called on the
capture thread when the desktop ends a capture while input is away (so it comes home), and
`on_failure(exc)` when capture stops on its own after it started."""
def __init__(self, on_key, on_mouse, on_motion, connect: Optional[Callable[[], object]] = None,
ei: Optional[Callable[[int], object]] = None, tokens=None, clock=time.monotonic) -> None:
self._on_key = on_key
self._on_mouse = on_mouse
self._on_motion = on_motion
self._connect = connect or portal.JeepneyBus
self._ei_factory = ei or _ei_receiver
self._tokens = tokens or portal.TokenStore("input-capture")
self._clock = clock
self._push_lock = threading.Lock()
self._whole_edges = linux_desktop.desktop() == "kde"
self._unmatched_displays_logged = set()
self._thread: Optional[threading.Thread] = None
self._ready = threading.Event()
self._stopping = threading.Event()
self._failure: Optional[BaseException] = None
self._predicate: Optional[Callable[[], bool]] = None
self._models: Callable[[], list] = lambda: []
self.on_home: Optional[Callable[[], None]] = None
self.on_failure: Optional[Callable[[BaseException], None]] = None
self.on_permission: Optional[Callable[[str, str, bool], None]] = None
self._session: Optional[_Session] = None
self._beat = clock()
self._reset()
def _reset(self) -> None:
self._pending_push = None
self._activation: Optional[int] = None
self._press: Optional[Press] = None
self._away = False
self._last_wall: Optional[str] = None
self._home_since: Optional[float] = None
self._early: List[tuple] = []
self._early_at = 0.0
self._walls: Dict[int, str] = {}
self._placed: List[Tuple[str, Tuple[int, int, int, int]]] = []
self._selected: List[Tuple[str, Tuple[int, int, int, int]]] = []
self._rejected = set()
self._reject_unannounced = False
self._sequences: Dict[object, int] = {} # libei device: the sequence it emulates under
self._disabled_at: Optional[float] = None
self._removed_at: Optional[float] = None
self._expect_disabled = False # Beamer's own SetPointerBarriers on an enabled session, whose Disabled is to come
self._devices = set() # ids of the captured devices the desktop has added and not removed
self._leaving = set() # of those, the ones a disable Beamer knows of is about to remove
self._sent_home_at: Optional[float] = None
self._key = None
self._zones: List[crossing.Rect] = []
self._keymap = None
self._mods = (0, 0, 0, 0)
self._names_down: Dict[Tuple[int, int], str] = {}
self._carry = [0.0, 0.0]
self._scroll_carry = [0.0, 0.0]
self._frame: List[tuple] = []
def grab_while(self, predicate: Callable[[], bool]) -> None:
"""Hold input for as long as `predicate` is true, once the desktop has captured it. Asked on
the capture thread after every batch, so cheap and never blocking."""
self._predicate = predicate
def barriers_from(self, models: Callable[[], list]) -> None:
self._models = models
def push_through(self, models, on_captured, on_failed, timeout=PUSH_SECONDS) -> bool:
"""Push the local pointer through one of the target peer's placed barriers."""
with self._push_lock:
if self._session is None or self._activation is not None or self._pending_push is not None:
return False
display_map = desktop_portal.display_map()
selected = barriers(models, self._zones, display_map=display_map,
warn_unmatched=self._warn_unmatched_display)
if not selected:
LOGGER.info("Shortcut push: no placed barrier leads to that machine")
return False
wall, (x1, y1, x2, y2) = selected[0]
if wall == "right":
start = (x1 - PUSH_INSET_PX, (y1 + y2) // 2)
elif wall == "left":
start = (x1 + PUSH_INSET_PX, (y1 + y2) // 2)
elif wall == "bottom":
start = ((x1 + x2) // 2, y1 - PUSH_INSET_PX)
else:
start = ((x1 + x2) // 2, y1 + PUSH_INSET_PX)
with self._push_lock:
if self._session is None or self._activation is not None or self._pending_push is not None:
return False
pending = (self._clock() + timeout, wall, on_captured, on_failed)
self._pending_push = pending
# Checked when the session runs it, which can be after the deadline though _tick has not
# yet cleared the push.
def wanted() -> bool:
with self._push_lock:
return self._pending_push is pending and self._clock() <= pending[0]
nx, ny = _NORMAL[wall]
moves = [(nx * PUSH_STEP_PX, ny * PUSH_STEP_PX) for _ in range(PUSH_STEPS)]
LOGGER.info("Shortcut push through the %s barrier from %s", wall, start)
inject_portal.push(*start, moves, wanted)
return True
@property
def grabbed(self) -> bool:
return self._activation is not None
@property
def holding(self) -> bool:
"""Whether the desktop has captured input for Beamer now: only then can it go away."""
return self._activation is not None
def start(self) -> None:
if self._thread is not None and self._thread.is_alive():
if self._stopping.is_set():
raise RuntimeError("The last capture thread has not stopped yet")
return
self._ready.clear()
self._stopping.clear()
self._failure = None
self._thread = threading.Thread(target=self._run, name="Beamer-hooks", daemon=True)
self._thread.start()
if not self._ready.wait(timeout=5.0):
raise RuntimeError("The input capture did not start within five seconds")
if self._failure is not None:
raise self._failure
def request_again(self) -> None:
thread = self._thread
if thread is not None and thread.is_alive():
thread.join(timeout=2.0)
if thread.is_alive():
raise RuntimeError("The last capture session has not stopped yet")
self.start()
def _report_permission(self, status: str, detail: str = "", retryable: bool = False) -> None:
if self.on_permission is not None:
try:
self.on_permission(status, detail, retryable)
except Exception:
LOGGER.exception("Could not report InputCapture permission state")
def stop(self) -> None:
self._stopping.set()
thread = self._thread
if thread is None:
return
thread.join(timeout=2.0)
if thread.is_alive():
LOGGER.error("The capture thread did not stop within two seconds; ending its connection")
self._abort()
thread.join(timeout=1.0)
if not thread.is_alive():
self._thread = None
def _abort(self) -> None:
session = self._session
if session is not None:
abort = getattr(session.portal.bus, "abort", None)
if abort is not None:
abort()
# -- the thread ----------------------------------------------------------
def _run(self) -> None:
session = None
try:
session = self._session = _Session(self._connect, self._ei_factory, self._tokens, self._stopping.is_set)
session.check()
self._beat = self._clock()
threading.Thread(target=self._watch, name="Beamer-hooks-watch", daemon=True).start()
self._ready.set()
session.open()
self._set_zones(session.zones())
self._report_permission("ready")
while not self._stopping.is_set():
self._beat = self._clock()
self._wait(session)
self._beat = self._clock()
for path, interface, member, body in session.portal.signals():
if interface == INTERFACE and body and body[0] == session.handle:
self._signal(member, body[1] if len(body) > 1 else {})
elif interface == portal.SESSION and member == "Closed" and path == session.handle:
raise CaptureUnavailable(SESSION_CLOSED)
events = session.ei.events()
for event in events:
self._beat = self._clock()
try:
self._ei_event(event)
except CaptureUnavailable:
raise
except Exception:
LOGGER.exception("An input event could not be read; carrying on")
self._tick()
except Exception as exc:
if not self._stopping.is_set():
LOGGER.exception("Keyboard and mouse capture stopped")
refused = getattr(exc, "sentence", None) in (REFUSED, MISSING_CAPABILITIES)
status = "refused" if refused else "unavailable"
self._report_permission(status, getattr(exc, "sentence", str(exc)),
refused or getattr(exc, "sentence", None) == SESSION_CLOSED)
started = self._ready.is_set()
self._failure = exc if not started else None
self._ready.set()
if started and not self._stopping.is_set() and self.on_failure is not None:
try:
self.on_failure(exc)
except Exception:
LOGGER.exception("Could not report that capture stopped")
finally:
self._end(session)
self._stopping.set()
def _end(self, session) -> None:
"""The way home on every exit: let go of a capture, then end the connection, which closes
the session even if the Release could not be sent."""
try:
if session is not None and self._activation is not None:
session.release(self._activation, desktop_portal.cursor_position())
except Exception:
LOGGER.exception("Could not let go of the captured input; closing the session lets go of it")
finally:
self._activation = None
self._names_down.clear()
desktop_portal.set_captured(False)
if session is not None:
try:
session.close()
except Exception:
LOGGER.exception("The capture session did not close cleanly")
self._session = None
self._reset()
def _wait(self, session) -> None:
if session.portal.pending():
return
try:
select.select([session.portal.fileno(), session.ei.fileno()], [], [], TICK_SECONDS)
except (OSError, ValueError) as exc:
raise CaptureUnavailable(ENDED.format(detail=exc)) from exc
def _watch(self) -> None:
"""The safety net under a capture thread stuck while the desktop holds input for it:
nothing else can let go, so its connection is ended and the portal closes the session."""
while not self._stopping.wait(STALL_SECONDS / 8):
if self._activation is not None and self._clock() - self._beat > STALL_SECONDS:
LOGGER.error("The capture thread has not answered for %s s while the keyboard and mouse are captured; "
"ending its connection to free them", STALL_SECONDS)
self._abort()
return
# -- portal signals --------------------------------------------------------
def _signal(self, member: str, options: dict) -> None:
if member == "Activated":
self._activated(options)
elif member in ("Deactivated", "Disabled"):
point = options.get("cursor_position")
was_away = self._away
self._activation = None
self._press = None
self._away = False
self._frame = []
desktop_portal.set_captured(False)
if point is not None:
desktop_portal.note_position(*point)
if member == "Disabled":
self._removed_at = None
self._session.enabled = False
self._disabled_at = self._clock()
if self._expect_disabled:
# KWin sends this for its own disable inside every SetPointerBarriers, after the
# Enable that follows; it keeps the barriers, so setting them again would loop.
self._expect_disabled = False
else:
self._key = None # set the barriers and enable again, after DISABLED_SECONDS
self._leaving = set(self._devices)
# Asked of the sender too: a tray switch may have sent input away a moment ago.
if was_away or self._away_wanted():
LOGGER.info("The desktop ended the capture while input was away; bringing it home")
self._home()
elif member == "ZonesChanged":
# Mutter and KWin disable the session on a monitor change; mutter says only this.
self._removed_at = None
self._session.enabled = False
self._leaving = set(self._devices)
self._set_zones(self._session.zones())
def _activated(self, options: dict) -> None:
self._reject_unannounced = False
activation = options.get("activation_id", NO_ID)
point = options.get("cursor_position") or desktop_portal.cursor_position()
barrier = options.get("barrier_id")
# 0 is a push that met two barriers at once (a corner's two walls); the pointer says which.
wall = self._walls.get(barrier) if barrier else self._wall_at(point)
self._last_wall = wall
self._activation = activation
self._frame = []
desktop_portal.set_captured(True)
if wall is None:
LOGGER.info("Captured at a barrier Beamer does not know; letting go")
self._let_go(desktop_portal.clamp_to(self._zones, *point))
return
if self._whole_edges and not self._selected_at(wall, point):
self._reject_unannounced = activation == NO_ID
rejected = {activation} if activation != NO_ID else set(self._sequences.values())
self._rejected.update(rejected)
self._early = [(event, sequence) for event, sequence in self._early if sequence not in rejected]
self._let_go(desktop_portal.clamp_to(self._zones, *point))
return
self._press = Press(wall, point, self._zones, self._clock)
desktop_portal.note_position(*self._press.point)
with self._push_lock:
pending = self._pending_push
if pending is not None and pending[0] >= self._clock() and pending[1] == wall:
self._pending_push = None
else:
pending = None
if pending is not None:
try:
pending[2]()
except Exception:
LOGGER.exception("The shortcut push capture callback failed; letting input go")
self._let_go(self._press.point)
return
early, self._early = self._early, []
for event, sequence in early:
if self._current(sequence):
self._ei_event(event)
def _selected_at(self, wall, point) -> bool:
vertical = wall in ("left", "right")
x, y = point
candidates = [position for index, (edge, position) in enumerate(self._placed)
if edge == wall and index + 1 in self._walls]
if not candidates:
return False
actual = min(candidates, key=lambda p: max(p[0] - x, 0, x - p[2]) + max(p[1] - y, 0, y - p[3]))
line = actual[0] if vertical else actual[1]
along = y if vertical else x
return any(edge == wall and (p[0] if vertical else p[1]) == line
and (p[1] if vertical else p[0]) <= along <= (p[3] if vertical else p[2])
for edge, p in self._selected)
def _wall_at(self, point) -> Optional[str]:
"""The wall of the placed barrier nearest the pointer, within WALL_PX: the desktop reports
the pointer on the screen's side of a barrier, or past it by the push."""
x, y = point
best = None
for index, (wall, (x1, y1, x2, y2)) in enumerate(self._placed):
if index + 1 not in self._walls:
continue
distance = max(x1 - x, 0, x - x2) + max(y1 - y, 0, y - y2)
# KWin omits barrier_id and may report a fast push far beyond the barrier line.
along_edge = y1 <= y <= y2 if wall in ("left", "right") else x1 <= x <= x2
if (distance <= WALL_PX or self._whole_edges and along_edge) and (best is None or distance < best[0]):
best = (distance, wall)
return best[1] if best else None
def _let_go_unannounced(self) -> None:
"""The desktop started sending input for a capture it never announced (no Activated):
after EARLY_SECONDS it is let go under its libei sequence, which is its activation id."""
if not self._early or self._clock() - self._early_at <= EARLY_SECONDS:
return
sequence = self._early[-1][1]
self._early = []
LOGGER.warning("The desktop captured input without saying so; letting go")
self._activation = sequence
self._let_go(desktop_portal.cursor_position())
def _current(self, sequence: Optional[int]) -> bool:
"""Whether input emulated under `sequence` belongs to the capture now held: libei's start
sequence is the portal's activation id."""
return self._activation == NO_ID or sequence is None or sequence == self._activation
def _home(self) -> None:
if self.on_home is not None:
self.on_home()
def _consume_shake_home(self) -> bool:
# The hooks are handed the sender's bound callbacks rather than the sender, so its one-shot
# "this way home was a shake" flag is reached through on_motion's owner.
sender = getattr(self._on_motion, "__self__", None)
consume = getattr(sender, "_consume_shake_home", None)
return bool(consume()) if callable(consume) else False
def _shake_release_point(self, point: Tuple[int, int]) -> Tuple[int, int]:
wall = self._last_wall
candidates = [rect for edge, rect in self._placed if edge == wall]
if not candidates:
return point
x, y = point
def distance(rect):
x1, y1, x2, y2 = rect
return max(x1 - x, 0, x - x2) + max(y1 - y, 0, y - y2)
x1, y1, x2, y2 = min(candidates, key=distance)
if wall == "left":
x = x1 + 24
elif wall == "right":
x = x2 - 24
elif wall == "top":
y = y1 + 24
elif wall == "bottom":
y = y2 - 24
return x, y
def _let_go(self, point: Tuple[int, int]) -> None:
"""Release at `point`. Input counts as held until the Release has gone, and a Release that
fails ends the session, whose closing lets go of input whatever else has failed."""
activation = self._activation
self._press = None
self._away = False
self._home_since = None
self._frame = []
desktop_portal.note_position(*point)
try:
if activation is not None and self._session is not None:
self._session.release(activation, point)
except Exception as exc:
raise CaptureUnavailable(ENDED.format(detail=f"letting go failed: {exc}")) from exc
finally:
self._activation = None
self._names_down.clear()
desktop_portal.set_captured(False)
# The sender may have landed the pointer while the Release was on its way.
landed = desktop_portal.position()
if landed is not None and landed != desktop_portal.clamp_to(self._zones, *point):
desktop_portal.set_cursor_position(*landed)
# -- the tick --------------------------------------------------------------
def _away_wanted(self) -> bool:
predicate = self._predicate
if predicate is None:
return False
try:
return bool(predicate())
except Exception:
LOGGER.exception("Could not tell whether input is away; bringing it home")
return False
def _tick(self) -> None:
with self._push_lock:
pending = self._pending_push
if pending is not None and self._clock() > pending[0]:
self._pending_push = None
else:
pending = None
if pending is not None:
LOGGER.info("Shortcut push: the desktop did not capture at the %s barrier in time", pending[1])
try:
pending[3]()
except Exception:
LOGGER.exception("The shortcut push failure callback failed")
session = self._session
if self._removed_at is not None and self._clock() - self._removed_at >= DISABLED_SECONDS:
self._removed_at = None
if not self._devices and session is not None and session.enabled:
LOGGER.info("The desktop removed all capture devices; enabling the session again")
self._signal("Deactivated", {})
session.enabled = False
self._disabled_at = self._clock()
if self._activation is None:
# Input away with nothing captured (a switch that passed input_held() just before a
# let-go): no key can reach the peer, so it comes home.
if self._away_wanted():
now = self._clock()
if self._sent_home_at is None or now - self._sent_home_at >= HOME_AGAIN_SECONDS:
if self._sent_home_at is None:
LOGGER.info("Input went away with nothing captured; bringing it home")
self._sent_home_at = now
self._home()
else:
self._sent_home_at = None
self._let_go_unannounced()
if self._disabled_at is None or self._clock() - self._disabled_at >= DISABLED_SECONDS:
self._place_barriers(session)
return
if self._press is not None:
if self._away_wanted():
self._press = None
self._away = True
elif self._press.idle() or not self._models():
self._let_go(self._press.point)
return
if self._away_wanted():
self._home_since = None
return
if self._consume_shake_home():
self._let_go(self._shake_release_point(desktop_portal.cursor_position()))
return
now = self._clock()
if self._home_since is None:
self._home_since = now
return
if now - self._home_since >= LANDING_SECONDS:
self._let_go(desktop_portal.cursor_position())
def _set_zones(self, zones: List[crossing.Rect]) -> None:
self._zones = zones
desktop_portal.set_zones(zones)
self._key = None
def _place_barriers(self, session) -> None:
try:
models = list(self._models())
except Exception:
LOGGER.exception("Could not read the zones; no barriers until the next change")
models = []
display_map = desktop_portal.display_map()
key = (model_key(models), tuple(self._zones),
tuple(sorted((name, _geometry(rect)) for name, rect in display_map.items())))
if key == self._key:
if models and not session.enabled:
session.enable()
return
self._key = key
self._expect_disabled = session.enabled
if session.enabled:
self._leaving = set(self._devices)
self._selected = barriers(models, self._zones, display_map=display_map,
warn_unmatched=self._warn_unmatched_display)
placed = self._placed = barriers(models, self._zones, whole_edges=self._whole_edges, display_map=display_map,
warn_unmatched=self._warn_unmatched_display)
failed = session.set_barriers([position for _wall, position in placed])
self._walls = {index + 1: wall for index, (wall, _position) in enumerate(placed) if index + 1 not in failed}
if failed:
LOGGER.warning("The desktop refused %d of %d edge barriers", len(failed), len(placed))
# Once per session: without it the log cannot tell a capture waiting on the desktop's
# dialog from one that is ready and simply not crossed yet (14-10-2026, Fedora).
if session.enabled and not getattr(session, "announced", False):
session.announced = True
LOGGER.info("Input capture is ready: %d of %d edge barriers placed", len(placed) - len(failed), len(placed))
def _warn_unmatched_display(self, display: str) -> None:
if display in self._unmatched_displays_logged:
return
self._unmatched_displays_logged.add(display)
LOGGER.warning("Could not match display %r to one portal zone by geometry; skipping its barriers", display)
# -- ei events -------------------------------------------------------------
def _ei_event(self, event: tuple) -> None:
kind = event[0]
if kind == "device_added":
device = event[1]
self._removed_at = None
self._devices.add(id(device))
self._leaving.discard(id(device))
if hasattr(device, "keymap") and 4 in getattr(device, "caps", ()): # libei.CAP_KEYBOARD
self._read_keymap(device)
return
if kind == "disconnect":
raise CaptureUnavailable(ENDED.format(detail="its input connection closed"))
if kind == "device_removed":
self._devices.discard(id(event[1]))
if id(event[1]) in self._leaving:
self._leaving.discard(id(event[1]))
elif not self._devices and self._session is not None and self._session.enabled:
# Input methods replace devices too; only sustained loss of every device implies cancel.
if self._removed_at is None:
self._removed_at = self._clock()
return
if kind == "device_paused":
device = event[1]
for device_id, code in tuple(self._names_down):
if device_id == id(device):
self._key_event(code, False, device)
return
if kind == "modifiers":
self._mods = tuple(event[2:6])
return
if kind == "start":
self._sequences[event[1]] = event[2]
if self._reject_unannounced:
self._rejected.add(event[2])
return
if kind == "stop":
# What arrives between a let-go and the desktop ending the capture belongs to nobody.
ended = self._sequences.pop(event[1], None)
if ended not in self._sequences.values():
self._rejected.discard(ended)
if not self._sequences:
self._early = []
return
if kind not in ("motion", "button", "key", "scroll", "scroll_discrete", "frame"):
return
sequence = self._sequences.get(event[1]) if len(event) > 1 else None
if sequence in self._rejected:
return
if self._activation is None:
# Ahead of the Activated signal that says which barrier.
if sequence is not None and len(self._early) < EARLY_MAX:
if not self._early:
self._early_at = self._clock()
self._early.append((event, sequence))
return
if not self._current(sequence):
if sequence > self._activation and len(self._early) < EARLY_MAX:
# The next capture's, ahead of its Activated signal.
if not self._early:
self._early_at = self._clock()
self._early.append((event, sequence))
return # else an earlier capture's
if self._press is not None and self._away_wanted():
# Sent away from another thread since the last look (the tray, a driven machine).
self._press = None
self._away = True
if self._press is not None:
self._pressing(event)
return
if kind == "frame":
self._end_frame()
else:
self._frame.append(event)
def _read_keymap(self, device) -> None:
try:
text = device.keymap()
if text:
import xkb_x11
if self._keymap is not None:
self._keymap.close()
self._keymap = xkb_x11.Keymap.from_text(text)
except Exception:
LOGGER.exception("Could not read the captured keyboard's layout; keys with no fixed name are dropped")
def _pressing(self, event: tuple) -> None:
kind = event[0]
if kind in ("key", "button"):
if event[3]:
LOGGER.info("A key or button at the edge lets go of the pointer; it does not reach an app")
self._let_go(self._press.point)
return
if kind != "motion":
return
press = self._press
if not press.feed(event[2], event[3]):
self._let_go(press.point)
return
desktop_portal.note_position(*press.point)
self._motion(event[2], event[3])
if self._away_wanted():
self._press = None
self._away = True
def _end_frame(self) -> None:
events, self._frame = self._frame, []
discrete = any(event[0] == "scroll_discrete" for event in events)
for event in events:
kind = event[0]
if kind == "motion":
self._motion(event[2], event[3])
elif kind == "key":
self._key_event(event[2], event[3], event[1])
elif kind == "button":
self._button(event[2], event[3])
elif kind == "scroll_discrete":
self._wheel(event[2] / 120.0 * WHEEL_DELTA, event[3] / 120.0 * WHEEL_DELTA)
elif kind == "scroll" and not discrete:
self._wheel(event[2] / PIXELS_PER_NOTCH * WHEEL_DELTA, event[3] / PIXELS_PER_NOTCH * WHEEL_DELTA)
def _motion(self, dx: float, dy: float) -> None:
carry = self._carry
carry[0] += dx
carry[1] += dy
whole_x, whole_y = int(carry[0]), int(carry[1])
carry[0] -= whole_x
carry[1] -= whole_y
if whole_x or whole_y:
self._on_motion(whole_x, whole_y)
def _wheel(self, units_x: float, units_y: float) -> None:
"""libei scrolls positive down and right; Windows' wheel is positive up, its horizontal
wheel positive right."""
carry = self._scroll_carry
carry[0] += units_x
carry[1] -= units_y
for index, message in ((1, WM_MOUSEWHEEL), (0, WM_MOUSEHWHEEL)):
whole = int(carry[index])
carry[index] -= whole
if whole:
self._on_mouse(message, 0, 0, _wheel_data(whole))
def _button(self, code: int, down: bool) -> None:
fixed = _BUTTONS.get(EVDEV_BUTTONS.get(code))
if fixed is None:
return
press, release, data = fixed
# An answer of False, the button kept here, cannot be played back on Wayland.
self._on_mouse(press if down else release, 0, 0, data)
def _key_event(self, code: int, down: bool, device) -> None:
key = (id(device), code)
name = self._names_down.get(key) if down else self._names_down.pop(key, None)
if name is None:
name = VK_TO_NAME.get(code)
if name is None and self._keymap is not None:
depressed, latched, locked, group = self._mods
mods = self._keymap.core_mods(depressed | latched | locked)
for held in self._names_down:
held_code = held[1] if isinstance(held, tuple) else held
mods |= HELD_MODS.get(held_code, 0)
name = character(code + KEYCODE_OFFSET, mods, group, self._keymap)
if name is None:
return
if down:
self._names_down[key] = name
self._on_key(name, down, code, keytable.EVDEV_US.get(code))
def _ei_receiver(fd: int):
import libei
return libei.Context(fd, sender=False)
def _libei_present() -> None:
import libei
libei._load()
# Checked before the session is asked for, so the desktop never asks for something Beamer cannot use.
_ei_receiver.preflight = _libei_present