One keyboard and mouse for a Mac and a Windows PC over the local network, in either direction.
"""Translation of macOS trackpad gestures into wire messages.
Two numberings share the values 29-32 and must not be confused:
At the CGEvent tap (bridge.py), measured on macOS 26.6.2:
29 Gesture -- everything two-finger, discriminated by field 110
30 DockControl -- a three/four-finger system swipe or thumb-and-three
pinch, the events Mission Control, Spaces, Show
desktop and Launchpad are driven by
At the AppKit level (kvm_bridge_app.py's overlay panel), the NSEventType
raw values:
29 NSEventTypeGesture (reserved; not translated)
30 NSEventTypeMagnify (pinch-to-zoom)
31 NSEventTypeSwipe (two-finger swipe between pages)
32 NSEventTypeSmartMagnify (reserved; not translated)
`DockSwipeClassifier` handles the tap's DockControl events and emits one
`gesture` message per completed movement. `GestureTranslator` handles the tap's
raw zoom fields and the overlay's NSEvents, turning a pinch into zoom steps and
a page swipe into back or forward, each a CHORD shaped for its receiver:
Ctrl+wheel and Alt+Arrow for a PC, Command with = - [ ] for a Mac, with no
change on the receiving side. Type-29 CGEvents whose HID subtype is zoom (8)
are read directly from their private fields in the tap; overlay NSEvents still
use their public magnification accessor.
Everything here is defensive: an unreadable field is logged once and treated
as "no gesture" rather than raised, so a bug or a changed private field on a
future macOS can never take down keyboard/mouse capture. Translation tests need
neither AppKit nor Quartz.
"""
import logging
from core import protocol
GESTURE_TYPE = 29
MAGNIFY_TYPE = 30
DOCK_CONTROL_TYPE = 30
SWIPE_TYPE = 31
SMART_MAGNIFY_TYPE = 32
GESTURE_EVENT_TYPES = frozenset({GESTURE_TYPE, MAGNIFY_TYPE, SWIPE_TYPE, SMART_MAGNIFY_TYPE})
# Private CGEvent fields on a DockControl event (numbers from iss, verified by
# probe on macOS 26.6.2): 110 IOHID type, 123 motion axis, 132 phase,
# 124 cumulative signed progress, 129/130 velocity on the ended event.
DOCK_FIELD_HID_TYPE = 110
DOCK_FIELD_MOTION = 123
DOCK_FIELD_PHASE = 132
DOCK_FIELD_PROGRESS = 124
DOCK_FIELD_VELOCITY_X = 129
DOCK_FIELD_VELOCITY_Y = 130
# Private CGEvent fields for type-29 gesture events. WebKit names field 113
# kCGEventGestureZoomValue and 132 kCGEventGesturePhase; Mac Mouse Fix reads
# these on type-29 events with field 110 set to the IOHID zoom subtype (8):
# https://www.mail-archive.com/webkit-changes%40lists.webkit.org/msg113473.html
# https://github.com/noah-nuebling/mac-mouse-fix/discussions/366
GESTURE_FIELD_HID_TYPE = 110
GESTURE_FIELD_MAGNIFICATION = 113
GESTURE_FIELD_PHASE = 132
GESTURE_ZOOM_HID_TYPE = 8
CG_GESTURE_PHASE_ENDED = 4
CG_GESTURE_PHASE_CANCELLED = 8
DOCK_SWIPE_HID_TYPE = 23
MOTION_HORIZONTAL = 1
MOTION_VERTICAL = 2
MOTION_PINCH = 3
DOCK_PHASE_ENDED = 4
# A full swipe ends between |0.3| and |0.9|; below this it was a twitch. A
# discrete flick can end with progress still near zero, in which case the
# ended event's velocity carries the direction instead, as iss found.
SWIPE_PROGRESS_THRESHOLD = 0.15
# (name when the sign is negative, name when positive), per motion axis.
# Measured on macOS 26.6.2. iss records the horizontal sign flipping in
# macOS 26 and again in 27, so the table is keyed by major version and an
# unknown version takes the newest entry. The 27 row is iss's report, not a
# measurement here.
_SIGN_TABLES = {
26: {
MOTION_VERTICAL: (protocol.GESTURE_SWIPE_UP, protocol.GESTURE_SWIPE_DOWN),
MOTION_HORIZONTAL: (protocol.GESTURE_SWIPE_RIGHT, protocol.GESTURE_SWIPE_LEFT),
MOTION_PINCH: (protocol.GESTURE_SPREAD, protocol.GESTURE_PINCH),
},
27: {
MOTION_VERTICAL: (protocol.GESTURE_SWIPE_UP, protocol.GESTURE_SWIPE_DOWN),
MOTION_HORIZONTAL: (protocol.GESTURE_SWIPE_LEFT, protocol.GESTURE_SWIPE_RIGHT),
MOTION_PINCH: (protocol.GESTURE_SPREAD, protocol.GESTURE_PINCH),
},
}
def sign_table_for(macos_major):
known = sorted(_SIGN_TABLES)
if macos_major in _SIGN_TABLES:
return _SIGN_TABLES[macos_major]
return _SIGN_TABLES[known[-1]]
class DockSwipeClassifier:
"""Turns the ended event of a DockControl gesture into one gesture
message. Stateless on purpose: began/changed events carry nothing the
ended one does not, and a swipe that straddles the moment redirecting
turns on is not worth tracking."""
def __init__(self, macos_major=26, logger=None):
self.logger = logger or logging.getLogger("Beamer")
self.signs = sign_table_for(macos_major)
self._warned = False
def translate(self, fields):
try:
if int(fields.hid) != DOCK_SWIPE_HID_TYPE:
return []
if int(fields.phase) != DOCK_PHASE_ENDED:
return []
names = self.signs.get(int(fields.motion))
if names is None:
return []
value = float(fields.progress)
if abs(value) < SWIPE_PROGRESS_THRESHOLD:
value = float(fields.velocity)
if value == 0.0:
return []
return [protocol.gesture_msg(names[0] if value < 0 else names[1])]
except Exception:
if not self._warned:
self._warned = True
self.logger.debug("failed to read a DockControl event; ignoring", exc_info=True)
return []
# NSEventPhase bits (AppKit.h). Read defensively via getattr(..., 0): a
# converted event is not guaranteed to expose `.phase` meaningfully (or at
# all) on every macOS version.
NS_EVENT_PHASE_ENDED = 8
NS_EVENT_PHASE_CANCELLED = 16
_PHASE_RESET_MASK = NS_EVENT_PHASE_ENDED | NS_EVENT_PHASE_CANCELLED
# Accumulated `.magnification` needed before one zoom step fires. Positive
# magnification (fingers spreading) zooms in: on a PC a positive wheel delta,
# matching the usual "Ctrl+scroll up zooms in" convention in browsers and other
# zoomable apps, and on a Mac Command-=.
MAGNIFY_STEP = 0.05
# Never on the wire: a zoom step or a page swipe whose chord is chosen when it is sent to a machine,
# since the machine input is on can change between capture and sending.
CHORD = "gesture_chord"
def chord_for(action, receiver):
"""The messages that make `action` ("zoom_in", "zoom_out", "back", "forward") on `receiver`. The
wire's key names are the receiver's own words, so a Mac's "cmd" is Command and Windows' "ctrl"
is Control. `receiver` is "mac" for a Mac and anything else for a PC."""
if action not in ("zoom_in", "zoom_out", "back", "forward"):
raise ValueError(f"unknown gesture action: {action!r}")
if action in ("zoom_in", "zoom_out"):
direction = 1 if action == "zoom_in" else -1
if receiver == "mac":
return _chord("cmd", "=" if direction > 0 else "-")
return [
{"type": protocol.MSG_KEYDOWN, "data": {"key": "ctrl"}},
protocol.scroll_msg(dy=direction, dx=0, mode="line"),
{"type": protocol.MSG_KEYUP, "data": {"key": "ctrl"}},
]
if receiver == "mac":
return _chord("cmd", "[" if action == "back" else "]")
return _chord("alt", "left" if action == "back" else "right")
class GestureTranslator:
"""A zoom step or a page swipe comes out as one CHORD message, for `chord_for` to shape once
the machine it goes to is known."""
def __init__(self, logger=None):
self.logger = logger or logging.getLogger("Beamer")
self._magnify_accum = 0.0
self._warned_types = set()
def wants(self, event_type):
return event_type in GESTURE_EVENT_TYPES
def translate(self, event_type, ns_event):
"""Return a (possibly empty) list of wire-message dicts for one
gesture event. Never raises: any failure reading `ns_event` is
logged once per event type and treated as no gesture."""
try:
if event_type == MAGNIFY_TYPE:
return self._translate_magnify(ns_event)
if event_type == SWIPE_TYPE:
return self._translate_swipe(ns_event)
# Gesture (29) and SmartMagnify (32) are translated separately
# only when the raw CGEvent fields identify a zoom.
return []
except Exception:
self._warn_once(event_type)
return []
def translate_cg_gesture(self, fields):
"""Translate the raw private fields of a type-29 CGEvent zoom."""
try:
if int(fields.get(GESTURE_FIELD_HID_TYPE, -1)) != GESTURE_ZOOM_HID_TYPE:
return []
return self._translate_magnification(
float(fields[GESTURE_FIELD_MAGNIFICATION]),
int(fields[GESTURE_FIELD_PHASE]),
int(fields[GESTURE_FIELD_PHASE]) in (
CG_GESTURE_PHASE_ENDED,
CG_GESTURE_PHASE_CANCELLED,
),
)
except Exception:
self._warn_once(GESTURE_TYPE)
return []
def _warn_once(self, event_type):
if event_type in self._warned_types:
return
self._warned_types.add(event_type)
self.logger.debug(
"failed to read gesture event type %r; ignoring", event_type, exc_info=True
)
def _translate_magnify(self, ns_event):
phase = int(getattr(ns_event, "phase", 0) or 0)
return self._translate_magnification(
float(ns_event.magnification),
phase,
bool(phase & _PHASE_RESET_MASK),
)
def _translate_magnification(self, magnification, phase, reset):
self._magnify_accum += magnification
messages = []
while abs(self._magnify_accum) >= MAGNIFY_STEP:
direction = 1 if self._magnify_accum > 0 else -1
messages.extend(self._zoom_step_messages(direction))
self._magnify_accum -= direction * MAGNIFY_STEP
if reset:
self._magnify_accum = 0.0
return messages
def _zoom_step_messages(self, direction):
return self._shaped("zoom_in" if direction > 0 else "zoom_out")
def _translate_swipe(self, ns_event):
delta_x = float(ns_event.deltaX)
if delta_x == 0:
return []
return self._shaped("back" if delta_x > 0 else "forward")
def _shaped(self, action):
return [{"type": CHORD, "data": {"action": action}}]
def _chord(modifier, key):
# A character key names where it sits on a US keyboard, so a receiving Mac whose layout has
# no such key still presses a key under the modifier rather than typing the character.
data = {"key": key, "us": key} if len(key) == 1 else {"key": key}
return [
{"type": protocol.MSG_KEYDOWN, "data": {"key": modifier}},
{"type": protocol.MSG_KEYDOWN, "data": dict(data)},
{"type": protocol.MSG_KEYUP, "data": dict(data)},
{"type": protocol.MSG_KEYUP, "data": {"key": modifier}},
]