scroll: one verb, two axes, and the sign carries the direction
A session could move a cursor and press it, but not scroll. The protocol already had the request -- zwlr_virtual_pointer_v1.axis(time, axis, value) -- it had simply never been implemented, in the driver or the broker. hhstream session pointer scroll <id> --axis vertical --amount 3 Positive is down (vertical) or right (horizontal): the protocol's direction, not a choice of ours, which is why direction travels in the sign and there is deliberately no up/down vocabulary layered over it. The output is whatever the last warp aimed at, exactly like a button, so scrolling somewhere else is a warp first -- and the lease is what keeps the whole gesture atomic. Bounded at 100 wheel clicks per request on both sides, because a decimal-point slip should be a refusal rather than a session scrolled somewhere unrecoverable. The resume point is re-stamped, not moved: the cursor did not go anywhere, so the coordinates are re-affirmed and only the stamp advances. Recorded in the contract as an amendment to the frozen op set, because adding an op to a frozen interface should be visible rather than implied. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
d0efba0877
commit
6b395305e0
17 files changed
+642
-2
No files matched your search
@@ -193,6 +193,10 @@ class WaylandSink:
|
||||
self._pointer(output).button(_now_ms(), code, state)
|
||||
self._flush()
|
||||
|
||||
def axis(self, output: str, axis: int, value: float) -> None:
|
||||
self._pointer(output).axis(_now_ms(), axis, value)
|
||||
self._flush()
|
||||
|
||||
def frame(self, output: str) -> None:
|
||||
self._pointer(output).frame()
|
||||
self._flush()
|
||||
|
||||
@@ -27,7 +27,30 @@ CODES: dict[str, int] = {
|
||||
#: ``wl_pointer.button_state``. Named on the wire so a log line reads.
|
||||
STATES: dict[str, int] = {"up": 0, "down": 1}
|
||||
|
||||
#: ``wl_pointer_axis`` values. Named "vertical"/"horizontal" rather than
|
||||
#: up/down/left/right, because the sign is what carries the direction: the
|
||||
#: protocol's positive vertical scroll is *down*, and a caller asking for
|
||||
#: "down" while a negative value means down is how a scroll ends up backwards.
|
||||
AXES: dict[str, int] = {"vertical": 0, "horizontal": 1}
|
||||
|
||||
#: The largest scroll a single request may carry, in wheel clicks. Bounded so a
|
||||
#: decimal-point slip (3 -> 30000) is a refusal rather than a session scrolled
|
||||
#: into next week, where the only clue is that the page will not move back.
|
||||
MAX_AXIS_VALUE = 100.0
|
||||
|
||||
NAMES = tuple(CODES)
|
||||
AXIS_NAMES = tuple(AXES)
|
||||
|
||||
|
||||
def axis_for(name: str) -> int:
|
||||
"""The protocol axis for a name, or :class:`ValueError` naming the set."""
|
||||
|
||||
try:
|
||||
return AXES[name]
|
||||
except KeyError:
|
||||
raise ValueError(
|
||||
f"unknown axis {name!r} (known: {', '.join(AXIS_NAMES)})"
|
||||
) from None
|
||||
|
||||
|
||||
def code_for(name: str) -> int:
|
||||
|
||||
@@ -39,6 +39,13 @@ class PointerSink(Protocol):
|
||||
def button(self, output: str, code: int, state: int) -> None:
|
||||
"""An evdev button code and a ``wl_pointer.button_state``."""
|
||||
|
||||
def axis(self, output: str, axis: int, value: float) -> None:
|
||||
"""Scroll by ``value`` wheel clicks along ``axis`` (a ``wl_pointer_axis``).
|
||||
|
||||
Positive vertical is *down* and positive horizontal is *right*, which is
|
||||
the protocol's direction and not a choice of ours.
|
||||
"""
|
||||
|
||||
def frame(self, output: str) -> None:
|
||||
"""Commit the queued events. Nothing is delivered until this."""
|
||||
|
||||
@@ -107,6 +114,37 @@ class Dispatcher:
|
||||
self._pressed.pop(name, None)
|
||||
return {"ok": True}
|
||||
|
||||
def _op_axis(self, request: dict) -> dict[str, Any]:
|
||||
"""Scroll the aimed output.
|
||||
|
||||
The output is implicit, like ``button``: there is one cursor, and a
|
||||
scroll belongs to whatever it is currently over. A caller that wants to
|
||||
scroll somewhere else warps first, which is also what makes the gesture
|
||||
serialisable by the lease.
|
||||
"""
|
||||
|
||||
name = request.get("axis", "vertical")
|
||||
if not isinstance(name, str):
|
||||
raise Rejected("'axis' must be a string")
|
||||
try:
|
||||
code = buttons.axis_for(name)
|
||||
except ValueError as exc:
|
||||
raise Rejected(str(exc)) from None
|
||||
|
||||
value = request.get("value", 1.0)
|
||||
if isinstance(value, bool) or not isinstance(value, (int, float)):
|
||||
raise Rejected("'value' must be a number of wheel clicks")
|
||||
value = float(value)
|
||||
if value != value or value in (float("inf"), float("-inf")):
|
||||
raise Rejected("'value' must be finite")
|
||||
if abs(value) > buttons.MAX_AXIS_VALUE:
|
||||
raise Rejected(
|
||||
f"'value' {value} exceeds the {buttons.MAX_AXIS_VALUE:g} wheel-click limit"
|
||||
)
|
||||
|
||||
self._sink.axis(self._aimed(), code, value)
|
||||
return {"ok": True}
|
||||
|
||||
def _op_frame(self, request: dict) -> dict[str, Any]:
|
||||
self._sink.frame(self._aimed())
|
||||
return {"ok": True}
|
||||
@@ -131,6 +169,7 @@ class Dispatcher:
|
||||
_ops = {
|
||||
"warp": _op_warp,
|
||||
"button": _op_button,
|
||||
"axis": _op_axis,
|
||||
"frame": _op_frame,
|
||||
"pressed": _op_pressed,
|
||||
"release_all": _op_release_all,
|
||||
|
||||
@@ -302,6 +302,14 @@ def _build_namespace(parser: argparse.ArgumentParser) -> None:
|
||||
#: and this list only buys a typo an exit 2 instead of an exit 10.
|
||||
BUTTONS = ("left", "right", "middle", "side", "extra", "forward", "back", "task")
|
||||
|
||||
#: Axis names the driver knows (``hhstream_pointer.buttons.AXES``), mirrored for
|
||||
#: the same reason and with the same caveat: the driver remains the authority.
|
||||
#: Direction is the sign of the amount, so there is deliberately no "down" or
|
||||
#: "up" here -- the protocol fixes positive as down (vertical) and right
|
||||
#: (horizontal), and a second vocabulary over it is how a scroll ends up
|
||||
#: backwards.
|
||||
AXES = ("vertical", "horizontal")
|
||||
|
||||
|
||||
def _build_pointer(verbs: Any, common: argparse.ArgumentParser) -> None:
|
||||
"""``session pointer <verb>`` — the one cursor, under a lease (PLAN §6).
|
||||
@@ -409,6 +417,29 @@ def _build_pointer(verbs: Any, common: argparse.ArgumentParser) -> None:
|
||||
"--button", default="left", choices=BUTTONS, metavar="B", help=_button_help()
|
||||
)
|
||||
|
||||
scroll = with_lease(add_gesture(
|
||||
"scroll",
|
||||
_cmd_pointer_scroll,
|
||||
help="scroll the session's screen where the cursor is",
|
||||
description=(
|
||||
"Scroll the session's screen. --amount is signed wheel clicks: "
|
||||
"positive scrolls down (vertical) or right (horizontal), which is "
|
||||
"the protocol's direction rather than a choice of ours. The cursor "
|
||||
"does not move, so the resume point keeps its coordinates -- but it "
|
||||
"is re-stamped, because a scroll is the session acting and a later "
|
||||
"resume should know when it last did."
|
||||
),
|
||||
))
|
||||
scroll.add_argument("id", help="session id")
|
||||
scroll.add_argument(
|
||||
"--axis", default="vertical", choices=AXES, metavar="A",
|
||||
help="vertical (default) or horizontal",
|
||||
)
|
||||
scroll.add_argument(
|
||||
"--amount", type=float, default=3.0, metavar="N",
|
||||
help="wheel clicks, signed; positive is down/right (default: 3)",
|
||||
)
|
||||
|
||||
for name, state in (("down", "down"), ("up", "up")):
|
||||
sub = with_lease(add_gesture(
|
||||
name,
|
||||
@@ -951,6 +982,29 @@ def _cmd_pointer_click(args: argparse.Namespace) -> int:
|
||||
return _finish_gesture(args, reply, render, args.id)
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_pointer_scroll(args: argparse.Namespace) -> int:
|
||||
lease_id = _lease_of(args, args.id)
|
||||
if not lease_id:
|
||||
return _no_lease(args, args.id)
|
||||
reply = _request(
|
||||
args,
|
||||
"pointer.scroll",
|
||||
id=args.id,
|
||||
lease_id=lease_id,
|
||||
axis=args.axis,
|
||||
amount=args.amount,
|
||||
)
|
||||
|
||||
def render(r: dict[str, Any]) -> str:
|
||||
return (
|
||||
f"{r.get('id')}: scrolled {r.get('axis')} by {r.get('amount')} "
|
||||
f"at {fmt.render_bookmark(r.get('bookmark'))}"
|
||||
)
|
||||
|
||||
return _finish_gesture(args, reply, render, args.id)
|
||||
|
||||
|
||||
@_guard
|
||||
def _cmd_pointer_button(args: argparse.Namespace) -> int:
|
||||
lease_id = _lease_of(args, args.id)
|
||||
|
||||
@@ -83,6 +83,17 @@ class PointerDriver:
|
||||
def button(self, button: str, state: str) -> None:
|
||||
self.request({"op": "button", "button": button, "state": state})
|
||||
|
||||
def axis(self, axis_name: str, value: float) -> None:
|
||||
"""Scroll the aimed output by ``value`` wheel clicks along ``axis_name``.
|
||||
|
||||
Positive vertical is down, positive horizontal is right (the protocol's
|
||||
direction). The output is whatever the last ``warp`` aimed at, so a
|
||||
scroll into another session is a warp first -- which is also what the
|
||||
lease serialises.
|
||||
"""
|
||||
|
||||
self.request({"op": "axis", "axis": axis_name, "value": float(value)})
|
||||
|
||||
def frame(self) -> None:
|
||||
"""Commit what was queued. Nothing the driver was sent is delivered
|
||||
to the compositor until this, so every gesture ends with one."""
|
||||
|
||||
@@ -116,6 +116,12 @@ DEFAULT_CONTAINER_SLOTS = 4
|
||||
#: and "click 10000 times" is not a gesture.
|
||||
MAX_CLICK_COUNT = 3
|
||||
|
||||
#: The largest scroll one request may carry, in wheel clicks. The driver
|
||||
#: enforces the same ceiling with its own copy (they are separate processes and
|
||||
#: neither imports the other); this one exists so the broker refuses early with a
|
||||
#: message naming the caller's value rather than relaying the driver's.
|
||||
MAX_SCROLL_AMOUNT = 100.0
|
||||
|
||||
SIGNALS_BY_NAME = {
|
||||
"TERM": signal.SIGTERM,
|
||||
"SIGTERM": signal.SIGTERM,
|
||||
@@ -1658,6 +1664,44 @@ class SessionManager:
|
||||
"bookmark": self._restore_point(session, output),
|
||||
}
|
||||
|
||||
async def pointer_scroll(
|
||||
self, session_id: str, lease_id: str, axis: Any = "vertical", amount: Any = 3
|
||||
) -> dict[str, Any]:
|
||||
"""Scroll the session's screen.
|
||||
|
||||
Same shape as a click -- the lease is checked first, then the driver is
|
||||
told, then the resume point is re-stamped -- with one difference that is
|
||||
worth being precise about: **the cursor does not move**. The
|
||||
coordinates are therefore re-affirmed rather than changed. The stamp
|
||||
advances, because a scroll is the session acting and a later resume
|
||||
should know when it last did -- but not one pixel of the position
|
||||
changes, and a bookmark that claimed otherwise would be fiction.
|
||||
"""
|
||||
|
||||
session, output = await self._refresh(session_id, lease_id)
|
||||
name = _axis_name(axis if axis is not None else "vertical")
|
||||
clicks = _checked_amount(amount)
|
||||
await self._drive("axis", name, clicks)
|
||||
await self._drive("frame")
|
||||
# A bookmark from a container this session no longer has is not a
|
||||
# position in this one, so a missing or stale one falls back to the
|
||||
# centre that the acquire would have aimed at.
|
||||
known = self._restore_point(session, output) or {}
|
||||
mark = self._mark(
|
||||
session,
|
||||
lease_id,
|
||||
output,
|
||||
float(known.get("x", 0.5)),
|
||||
float(known.get("y", 0.5)),
|
||||
)
|
||||
self.audit.emit("pointer_scroll", session=session.id, axis=name, amount=clicks)
|
||||
return {
|
||||
"id": session.id,
|
||||
"axis": name,
|
||||
"amount": clicks,
|
||||
"bookmark": mark,
|
||||
}
|
||||
|
||||
async def pointer_release(self, session_id: str, lease_id: str) -> dict[str, Any]:
|
||||
"""Give the cursor back, leaving nothing pressed and a bookmark behind."""
|
||||
|
||||
@@ -2079,6 +2123,35 @@ def _button_name(value: Any) -> str:
|
||||
return value
|
||||
|
||||
|
||||
def _axis_name(value: Any) -> str:
|
||||
if not isinstance(value, str) or not value:
|
||||
raise ManagerError("invalid_argument", f"axis must be a name, got {value!r}")
|
||||
return value
|
||||
|
||||
|
||||
def _checked_amount(value: Any) -> float:
|
||||
"""A scroll amount in wheel clicks, signed.
|
||||
|
||||
Signed rather than split into `--up`/`--down`: the protocol carries direction
|
||||
in the sign (positive vertical is down), and a second vocabulary on top of it
|
||||
is how a scroll ends up backwards. Zero is refused because it is never
|
||||
intended -- it is a caller that forgot to pass an amount.
|
||||
"""
|
||||
|
||||
if isinstance(value, bool) or not isinstance(value, (int, float)):
|
||||
raise ManagerError(
|
||||
"invalid_argument", f"amount must be a number of wheel clicks, got {value!r}"
|
||||
)
|
||||
amount = float(value)
|
||||
if amount == 0 or abs(amount) > MAX_SCROLL_AMOUNT:
|
||||
raise ManagerError(
|
||||
"invalid_argument",
|
||||
f"amount must be non-zero and at most {MAX_SCROLL_AMOUNT:g} wheel clicks, "
|
||||
f"got {amount}",
|
||||
)
|
||||
return amount
|
||||
|
||||
|
||||
def _checked_count(value: Any) -> int:
|
||||
if isinstance(value, bool) or not isinstance(value, int):
|
||||
raise ManagerError("invalid_argument", f"count must be an integer, got {value!r}")
|
||||
|
||||
@@ -148,6 +148,7 @@ VERBS = (
|
||||
"pointer.move",
|
||||
"pointer.button",
|
||||
"pointer.click",
|
||||
"pointer.scroll",
|
||||
"pointer.release",
|
||||
"pointer.state",
|
||||
)
|
||||
@@ -171,6 +172,7 @@ MUTATING_VERBS = frozenset(
|
||||
"pointer.move",
|
||||
"pointer.button",
|
||||
"pointer.click",
|
||||
"pointer.scroll",
|
||||
"pointer.release",
|
||||
}
|
||||
)
|
||||
|
||||
@@ -70,6 +70,7 @@ class ControlServer:
|
||||
"pointer.move": self._op_pointer_move,
|
||||
"pointer.button": self._op_pointer_button,
|
||||
"pointer.click": self._op_pointer_click,
|
||||
"pointer.scroll": self._op_pointer_scroll,
|
||||
"pointer.release": self._op_pointer_release,
|
||||
"pointer.state": self._op_pointer_state,
|
||||
}
|
||||
@@ -356,6 +357,18 @@ class ControlServer:
|
||||
)
|
||||
)
|
||||
|
||||
async def _op_pointer_scroll(
|
||||
self, request: dict[str, Any], caller: dict[str, Any]
|
||||
) -> dict[str, Any]:
|
||||
return protocol.ok(
|
||||
**await self.manager.pointer_scroll(
|
||||
request.get("id"),
|
||||
request.get("lease_id"),
|
||||
request.get("axis", "vertical"),
|
||||
request.get("amount", 3),
|
||||
)
|
||||
)
|
||||
|
||||
async def _op_pointer_release(
|
||||
self, request: dict[str, Any], caller: dict[str, Any]
|
||||
) -> dict[str, Any]:
|
||||
|
||||
Reference in new issue
Block a user