frontengine 1.0.31__tar.gz → 1.0.32__tar.gz

{frontengine-1.0.31 → frontengine-1.0.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.31
+Version: 1.0.32
 Summary: FrontEngine is use-define frontview or only use like screen saver
 Author-email: JE-Chen <jechenmailman@gmail.com>
 Project-URL: Homepage, https://github.com/Intergration-Automation-Testing/FrontEngine

frontengine-1.0.32/frontengine/show/presentation/annotation_overlay.py

@@ -0,0 +1,153 @@
+"""
+螢幕塗鴉層：在畫面上用筆或螢光筆畫線、清除、復原。畫圖時需要接收滑鼠，
+所以它不是點擊穿透的；關閉塗鴉即恢復原本的操作。
+
+A screen annotation layer: draw over the screen with a pen or highlighter,
+undo, and clear. It has to take the mouse while you draw, so unlike the other
+overlays it is not click-through — turn it off and the screen is yours again.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from PySide6.QtCore import QPoint, Qt
+from PySide6.QtGui import QColor, QPainter, QPen
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.show.window_helpers import apply_overlay_window_flags
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+TOOL_PEN = "pen"
+TOOL_HIGHLIGHTER = "highlighter"
+TOOL_ERASER = "eraser"
+TOOLS = (TOOL_PEN, TOOL_HIGHLIGHTER, TOOL_ERASER)
+
+PEN_COLORS = (
+    ("Red", "#ff3b30"), ("Yellow", "#ffcc00"), ("Green", "#34c759"),
+    ("Blue", "#0a84ff"), ("Black", "#000000"), ("White", "#ffffff"),
+)
+DEFAULT_PEN_COLOR = "#ff3b30"
+MIN_WIDTH = 1
+MAX_WIDTH = 40
+
+
+def clamp_width(value, fallback: int = 4) -> int:
+    """把筆寬夾在可用範圍。"""
+    try:
+        return max(MIN_WIDTH, min(MAX_WIDTH, int(value)))
+    except (TypeError, ValueError):
+        return fallback
+
+
+def stroke_style(tool: str, color: str, width: int) -> Tuple[QColor, int]:
+    """
+    依工具決定實際的顏色與線寬：螢光筆是半透明的粗線，橡皮擦畫得更粗。
+    Per-tool colour and width: a highlighter is a wide translucent stroke, an
+    eraser is wider still.
+    """
+    pen_color = QColor(color)
+    if not pen_color.isValid():
+        pen_color = QColor(DEFAULT_PEN_COLOR)
+    stroke_width = clamp_width(width)
+    if tool == TOOL_HIGHLIGHTER:
+        pen_color.setAlpha(90)
+        stroke_width = clamp_width(stroke_width * 4)
+    elif tool == TOOL_ERASER:
+        stroke_width = clamp_width(stroke_width * 5)
+    return (pen_color, stroke_width)
+
+
+class AnnotationOverlay(BaseWidget):
+    """
+    塗鴉層：滑鼠拖曳畫線，支援筆／螢光筆／橡皮擦、復原與全部清除。
+    每一筆記成 (工具, 顏色, 線寬, 點清單)，因此復原與重繪都很單純。
+    """
+
+    def __init__(self, color: str = DEFAULT_PEN_COLOR, width: int = 4, tool: str = TOOL_PEN) -> None:
+        front_engine_logger.info(f"[AnnotationOverlay] Init | tool={tool}, color={color}, width={width}")
+        super().__init__()
+        self.opacity = 1.0
+        self.tool = tool if tool in TOOLS else TOOL_PEN
+        self.pen_color = color
+        self.pen_width = clamp_width(width)
+        self.strokes: List[dict] = []
+        self._current: Optional[dict] = None
+        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
+
+    def set_annotation_window_flag(self) -> None:
+        """塗鴉需要接收滑鼠，所以不使用點擊穿透。"""
+        apply_overlay_window_flags(self, show_on_bottom=False, allow_input=True)
+
+    def set_tool(self, tool: str) -> None:
+        if tool in TOOLS:
+            self.tool = tool
+
+    def set_pen(self, color: Optional[str] = None, width: Optional[int] = None) -> None:
+        if color is not None:
+            self.pen_color = color
+        if width is not None:
+            self.pen_width = clamp_width(width)
+
+    def clear(self) -> None:
+        """清掉所有筆畫 / Wipe every stroke."""
+        self.strokes = []
+        self._current = None
+        self.update()
+
+    def undo(self) -> bool:
+        """收回最後一筆；沒有筆畫可收時回傳 False。"""
+        if not self.strokes:
+            return False
+        self.strokes.pop()
+        self.update()
+        return True
+
+    # --- drawing ---------------------------------------------------------
+    def begin_stroke(self, point: QPoint) -> None:
+        self._current = {
+            "tool": self.tool, "color": self.pen_color, "width": self.pen_width, "points": [point],
+        }
+        self.strokes.append(self._current)
+
+    def extend_stroke(self, point: QPoint) -> None:
+        if self._current is not None:
+            self._current["points"].append(point)
+            self.update()
+
+    def end_stroke(self) -> None:
+        # 只有一個點的筆畫畫不出線，直接丟掉
+        # A single-point stroke draws nothing; drop it.
+        if self._current is not None and len(self._current["points"]) < 2:
+            self.strokes.remove(self._current)
+            self.update()
+        self._current = None
+
+    def mousePressEvent(self, event) -> None:
+        if event.button() == Qt.MouseButton.LeftButton:
+            self.begin_stroke(event.position().toPoint())
+        super().mousePressEvent(event)
+
+    def mouseMoveEvent(self, event) -> None:
+        self.extend_stroke(event.position().toPoint())
+        super().mouseMoveEvent(event)
+
+    def mouseReleaseEvent(self, event) -> None:
+        self.end_stroke()
+        super().mouseReleaseEvent(event)
+
+    def draw_content(self, painter: QPainter) -> None:
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+        for stroke in self.strokes:
+            points = stroke["points"]
+            if len(points) < 2:
+                continue
+            color, width = stroke_style(stroke["tool"], stroke["color"], stroke["width"])
+            if stroke["tool"] == TOOL_ERASER:
+                painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_Clear)
+            else:
+                painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_SourceOver)
+            painter.setPen(QPen(color, width, Qt.PenStyle.SolidLine,
+                                Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin))
+            for start, end in zip(points, points[1:]):
+                painter.drawLine(start, end)
+        painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_SourceOver)

frontengine-1.0.32/frontengine/show/presentation/cursor_effects.py

@@ -0,0 +1,166 @@
+"""
+游標強調層：在游標周圍畫一圈亮環、點擊時擴散漣漪，或把游標以外的區域壓暗
+（聚光燈）。教學、簡報與錄影時讓觀眾看得見滑鼠在哪。點擊穿透，不影響操作。
+
+Cursor emphasis: a ring around the pointer, a ripple when you click, or a
+spotlight that dims everything except a circle around the cursor — so an
+audience can follow the mouse during a demo. Click-through throughout.
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from PySide6.QtCore import QPoint, QTimer, Qt
+from PySide6.QtGui import QColor, QCursor, QPainter, QRadialGradient
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+DEFAULT_RING_COLOR = "#ffcc00"
+DEFAULT_RING_RADIUS = 28
+DEFAULT_SPOTLIGHT_RADIUS = 160
+RIPPLE_STEPS = 12
+_MIN_RADIUS = 8
+_MAX_RADIUS = 600
+
+
+def clamp_radius(value, fallback: int = DEFAULT_RING_RADIUS) -> int:
+    """把半徑夾在看得見又不至於蓋滿螢幕的範圍。"""
+    try:
+        return max(_MIN_RADIUS, min(_MAX_RADIUS, int(value)))
+    except (TypeError, ValueError):
+        return fallback
+
+
+def ripple_radius(step: int, base_radius: int, steps: int = RIPPLE_STEPS) -> int:
+    """漣漪第 step 幀的半徑：從基準半徑往外擴散一倍。"""
+    total = max(1, int(steps))
+    progress = min(max(int(step), 0), total) / total
+    return int(clamp_radius(base_radius) * (1.0 + progress))
+
+
+def ripple_alpha(step: int, steps: int = RIPPLE_STEPS) -> int:
+    """漣漪第 step 幀的透明度：越擴散越淡，最後消失。"""
+    total = max(1, int(steps))
+    progress = min(max(int(step), 0), total) / total
+    return max(0, int(200 * (1.0 - progress)))
+
+
+class CursorEffectWidget(BaseWidget):
+    """
+    游標效果層：亮環、點擊漣漪、聚光燈可各自開關，全部跟著游標移動。
+    位置與點擊事件由外部注入（正式路徑接系統游標與全域滑鼠監聽），方便測試。
+    """
+
+    REFRESH_MS = 16
+
+    def __init__(self, ring: bool = True, ripple: bool = True, spotlight: bool = False,
+                 color: str = DEFAULT_RING_COLOR, radius: int = DEFAULT_RING_RADIUS,
+                 spotlight_radius: int = DEFAULT_SPOTLIGHT_RADIUS, dim: int = 55) -> None:
+        front_engine_logger.info(
+            f"[CursorEffectWidget] Init | ring={ring}, ripple={ripple}, spotlight={spotlight}")
+        super().__init__()
+        self.opacity = 1.0
+        self.show_ring = bool(ring)
+        self.show_ripple = bool(ripple)
+        self.show_spotlight = bool(spotlight)
+        self.color = QColor(color) if QColor(color).isValid() else QColor(DEFAULT_RING_COLOR)
+        self.radius = clamp_radius(radius)
+        self.spotlight_radius = clamp_radius(spotlight_radius, DEFAULT_SPOTLIGHT_RADIUS)
+        self.dim = max(0, min(90, int(dim)))
+        self.cursor_point = QPoint(0, 0)
+        self.ripples: List[dict] = []
+        self._cursor_provider = QCursor.pos
+        self._timer = QTimer(self)
+        self._timer.timeout.connect(self.tick)
+
+    def set_cursor_provider(self, provider) -> None:
+        """注入游標位置來源（測試用）。"""
+        self._cursor_provider = provider
+
+    def set_effects(self, ring: Optional[bool] = None, ripple: Optional[bool] = None,
+                    spotlight: Optional[bool] = None) -> None:
+        """開關個別效果。"""
+        if ring is not None:
+            self.show_ring = bool(ring)
+        if ripple is not None:
+            self.show_ripple = bool(ripple)
+        if spotlight is not None:
+            self.show_spotlight = bool(spotlight)
+        self.update()
+
+    def set_style(self, color: Optional[str] = None, radius: Optional[int] = None,
+                  spotlight_radius: Optional[int] = None, dim: Optional[int] = None) -> None:
+        """調整顏色、半徑與壓暗程度。"""
+        if color is not None:
+            candidate = QColor(color)
+            if candidate.isValid():
+                self.color = candidate
+        if radius is not None:
+            self.radius = clamp_radius(radius)
+        if spotlight_radius is not None:
+            self.spotlight_radius = clamp_radius(spotlight_radius, DEFAULT_SPOTLIGHT_RADIUS)
+        if dim is not None:
+            self.dim = max(0, min(90, int(dim)))
+        self.update()
+
+    def start_following(self, interval_ms: int = REFRESH_MS) -> None:
+        """開始跟隨游標。"""
+        self.tick()
+        self._timer.start(max(8, int(interval_ms)))
+
+    def add_ripple(self, point: Optional[QPoint] = None) -> None:
+        """在指定位置（預設為目前游標）加一圈點擊漣漪。"""
+        self.ripples.append({"point": QPoint(point or self.cursor_point), "step": 0})
+        self.update()
+
+    def tick(self) -> None:
+        """更新游標位置並推進漣漪動畫。"""
+        try:
+            position = self._cursor_provider()
+        except Exception:  # pragma: no cover - defensive around injected providers
+            return
+        self.cursor_point = QPoint(int(position.x()) - self.x(), int(position.y()) - self.y())
+        for ripple in list(self.ripples):
+            ripple["step"] += 1
+            if ripple["step"] > RIPPLE_STEPS:
+                self.ripples.remove(ripple)
+        self.update()
+
+    def draw_content(self, painter: QPainter) -> None:
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+        if self.show_spotlight:
+            self._draw_spotlight(painter)
+        if self.show_ring:
+            ring_color = QColor(self.color)
+            ring_color.setAlpha(120)
+            painter.setBrush(ring_color)
+            painter.setPen(Qt.PenStyle.NoPen)
+            painter.drawEllipse(self.cursor_point, self.radius, self.radius)
+        if self.show_ripple:
+            for ripple in self.ripples:
+                color = QColor(self.color)
+                color.setAlpha(ripple_alpha(ripple["step"]))
+                painter.setBrush(Qt.BrushStyle.NoBrush)
+                painter.setPen(color)
+                radius = ripple_radius(ripple["step"], self.radius)
+                painter.drawEllipse(ripple["point"], radius, radius)
+
+    def _draw_spotlight(self, painter: QPainter) -> None:
+        """把游標以外壓暗，中心保持透明，邊緣柔和過渡。"""
+        shade = QColor(0, 0, 0, int(255 * self.dim / 100.0))
+        gradient = QRadialGradient(self.cursor_point, self.spotlight_radius)
+        gradient.setColorAt(0.0, QColor(0, 0, 0, 0))
+        gradient.setColorAt(0.75, QColor(0, 0, 0, 0))
+        gradient.setColorAt(1.0, shade)
+        painter.fillRect(self.rect(), shade)
+        painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_Source)
+        painter.setBrush(gradient)
+        painter.setPen(Qt.PenStyle.NoPen)
+        painter.drawEllipse(self.cursor_point, self.spotlight_radius, self.spotlight_radius)
+        painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_SourceOver)
+
+    def closeEvent(self, event) -> None:
+        if self._timer.isActive():
+            self._timer.stop()
+        super().closeEvent(event)

frontengine-1.0.32/frontengine/show/presentation/keystroke_display.py

@@ -0,0 +1,161 @@
+"""
+按鍵顯示：把剛按下的按鍵顯示在畫面角落，做教學影片或直播時觀眾才知道你按了什麼。
+PowerToys 至今沒有內建這個功能，而本專案本來就有全域鍵盤監聽（pynput），
+所以只需要一層顯示。按鍵格式化是純函式，可獨立測試。
+
+Keystroke display: show what you just pressed in a screen corner, so viewers of
+a tutorial or stream can follow along. PowerToys still has no built-in version;
+this project already listens for global hotkeys, so only the display is new.
+The formatting is pure and independently testable.
+"""
+from __future__ import annotations
+
+import time
+from typing import List, Tuple
+
+from PySide6.QtCore import QRect, QTimer, Qt
+from PySide6.QtGui import QColor, QFont, QFontMetrics, QPainter
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+DEFAULT_HOLD_SECONDS = 2.0
+MAX_KEYS_SHOWN = 6
+
+# 修飾鍵的顯示名稱 / How modifier keys are shown
+_MODIFIER_NAMES = {
+    "ctrl": "Ctrl", "ctrl_l": "Ctrl", "ctrl_r": "Ctrl",
+    "alt": "Alt", "alt_l": "Alt", "alt_r": "Alt", "alt_gr": "AltGr",
+    "shift": "Shift", "shift_l": "Shift", "shift_r": "Shift",
+    "cmd": "Win", "cmd_l": "Win", "cmd_r": "Win",
+}
+# 特殊鍵的顯示名稱 / Friendlier names for special keys
+_SPECIAL_NAMES = {
+    "space": "Space", "enter": "Enter", "return": "Enter", "tab": "Tab",
+    "backspace": "Backspace", "delete": "Del", "esc": "Esc", "escape": "Esc",
+    "up": "↑", "down": "↓", "left": "←", "right": "→",
+    "page_up": "PgUp", "page_down": "PgDn", "home": "Home", "end": "End",
+}
+
+
+def format_key(name) -> str:
+    """
+    把按鍵名稱轉成畫面上好讀的字（修飾鍵、方向鍵、功能鍵各有寫法）。
+    Turn a key name into something readable on screen.
+    """
+    text = str(name or "").strip().strip("'")
+    if not text:
+        return ""
+    lowered = text.lower()
+    if lowered in _MODIFIER_NAMES:
+        return _MODIFIER_NAMES[lowered]
+    if lowered in _SPECIAL_NAMES:
+        return _SPECIAL_NAMES[lowered]
+    if lowered.startswith("key."):
+        return format_key(text[4:])
+    if len(text) == 1:
+        return text.upper()
+    if lowered.startswith("f") and lowered[1:].isdigit():
+        return text.upper()
+    return text.replace("_", " ").title()
+
+
+def format_combo(keys) -> str:
+    """把同時按著的按鍵組成 `Ctrl + Shift + S` 這種字串（去重、保留順序）。"""
+    parts: List[str] = []
+    for key in keys or ():
+        formatted = format_key(key)
+        if formatted and formatted not in parts:
+            parts.append(formatted)
+    return " + ".join(parts)
+
+
+def visible_keys(entries, now: float, hold_seconds: float = DEFAULT_HOLD_SECONDS,
+                 limit: int = MAX_KEYS_SHOWN) -> List[str]:
+    """
+    從 (文字, 時間) 清單裡挑出還沒過期的按鍵，最多顯示 limit 個（最新在後）。
+    The still-fresh entries from a list of (text, timestamp) pairs.
+    """
+    fresh = [text for text, stamp in entries or () if now - stamp <= max(0.1, float(hold_seconds))]
+    return fresh[-max(1, int(limit)):]
+
+
+class KeystrokeDisplayWidget(BaseWidget):
+    """
+    按鍵顯示層：把最近按下的按鍵排成一列顯示，過幾秒自動淡出。點擊穿透。
+    按鍵來源由外部推入（`push_keys`），因此不需要在這裡自己開監聽器。
+    """
+
+    REFRESH_MS = 100
+    PADDING = 12
+
+    def __init__(self, hold_seconds: float = DEFAULT_HOLD_SECONDS, font_size: int = 28,
+                 color: str = "#ffffff", background: str = "#000000") -> None:
+        front_engine_logger.info(f"[KeystrokeDisplayWidget] Init | hold={hold_seconds}s")
+        super().__init__()
+        self.opacity = 1.0
+        self.hold_seconds = max(0.2, float(hold_seconds))
+        self.text_color = QColor(color) if QColor(color).isValid() else QColor("#ffffff")
+        self.background_color = QColor(background) if QColor(background).isValid() else QColor("#000000")
+        self.font_size = max(8, int(font_size))
+        self.entries: List[Tuple[str, float]] = []
+        self._now = time.monotonic
+        self._timer = QTimer(self)
+        self._timer.timeout.connect(self._expire)
+
+    def set_clock(self, clock) -> None:
+        """注入時間來源（測試用）。"""
+        self._now = clock
+
+    def start(self, interval_ms: int = REFRESH_MS) -> None:
+        """開始定期清掉過期的按鍵。"""
+        self._timer.start(max(30, int(interval_ms)))
+
+    def push_keys(self, keys) -> None:
+        """
+        推入一次按鍵事件（單一鍵或組合鍵）；空的輸入忽略。
+        Record one keypress (single key or combination); blanks are ignored.
+        """
+        text = format_combo(keys if isinstance(keys, (list, tuple, set)) else [keys])
+        if not text:
+            return
+        self.entries.append((text, self._now()))
+        self.entries = self.entries[-(MAX_KEYS_SHOWN * 2):]
+        self.update()
+
+    def current_text(self) -> str:
+        """目前該顯示的字串。"""
+        return "   ".join(visible_keys(self.entries, self._now(), self.hold_seconds))
+
+    def _expire(self) -> None:
+        before = len(visible_keys(self.entries, self._now(), self.hold_seconds))
+        if before != len(self.entries):
+            self.entries = [
+                (text, stamp) for text, stamp in self.entries
+                if self._now() - stamp <= self.hold_seconds
+            ]
+            self.update()
+
+    def draw_content(self, painter: QPainter) -> None:
+        text = self.current_text()
+        if not text:
+            return
+        font = QFont(self.font().family(), self.font_size)
+        painter.setFont(font)
+        metrics = QFontMetrics(font)
+        width = metrics.horizontalAdvance(text) + self.PADDING * 2
+        height = metrics.height() + self.PADDING
+        box = QRect(max(0, (self.width() - width) // 2),
+                    max(0, self.height() - height - self.PADDING), width, height)
+        background = QColor(self.background_color)
+        background.setAlpha(170)
+        painter.setPen(Qt.PenStyle.NoPen)
+        painter.setBrush(background)
+        painter.drawRoundedRect(box, 8, 8)
+        painter.setPen(self.text_color)
+        painter.drawText(box, int(Qt.AlignmentFlag.AlignCenter), text)
+
+    def closeEvent(self, event) -> None:
+        if self._timer.isActive():
+            self._timer.stop()
+        super().closeEvent(event)

frontengine-1.0.32/frontengine/show/presentation/magnifier.py

@@ -0,0 +1,127 @@
+"""
+區域放大鏡：抓取游標周圍的一小塊畫面，放大後顯示在覆蓋層上，
+方便簡報時展示細節（ZoomIt 式）。點擊穿透，抓圖用 Qt 自己的螢幕擷取。
+
+A region magnifier: grab a small area around the cursor and draw it enlarged,
+for showing detail during a demo. Click-through, and the capture uses Qt's own
+screen grab rather than any platform API.
+"""
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+from PySide6.QtCore import QRect, QTimer, Qt
+from PySide6.QtGui import QColor, QCursor, QGuiApplication, QPainter, QPixmap
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+MIN_ZOOM = 1.25
+MAX_ZOOM = 8.0
+DEFAULT_ZOOM = 2.0
+DEFAULT_SIZE = 240
+
+
+def clamp_zoom(value, fallback: float = DEFAULT_ZOOM) -> float:
+    """把放大倍率夾在 1.25x~8x（再高就只剩馬賽克）。"""
+    try:
+        return max(MIN_ZOOM, min(MAX_ZOOM, round(float(value), 2)))
+    except (TypeError, ValueError):
+        return fallback
+
+
+def source_rect(center: Tuple[int, int], size: int, zoom: float,
+                bounds: Tuple[int, int, int, int]) -> QRect:
+    """
+    算出要擷取的螢幕區域：以游標為中心、邊長為顯示尺寸除以倍率，並限制在螢幕內。
+    The screen area to grab: centred on the cursor, sized by the zoom factor,
+    and kept inside the screen.
+    """
+    side = max(8, int(int(size) / max(MIN_ZOOM, float(zoom))))
+    left, top, right, bottom = bounds
+    x = int(center[0]) - side // 2
+    y = int(center[1]) - side // 2
+    x = max(left, min(x, max(left, right - side)))
+    y = max(top, min(y, max(top, bottom - side)))
+    return QRect(x, y, side, side)
+
+
+class MagnifierWidget(BaseWidget):
+    """
+    放大鏡：定期擷取游標周圍畫面並放大顯示。擷取來源可注入，方便測試。
+    """
+
+    REFRESH_MS = 60
+
+    def __init__(self, zoom: float = DEFAULT_ZOOM, size: int = DEFAULT_SIZE) -> None:
+        front_engine_logger.info(f"[MagnifierWidget] Init | zoom={zoom}, size={size}")
+        super().__init__()
+        self.opacity = 1.0
+        self.zoom = clamp_zoom(zoom)
+        self.view_size = max(80, int(size))
+        self.captured: Optional[QPixmap] = None
+        self._cursor_provider = QCursor.pos
+        self._grabber = self._grab_screen
+        self._timer = QTimer(self)
+        self._timer.timeout.connect(self.refresh)
+
+    def set_cursor_provider(self, provider) -> None:
+        self._cursor_provider = provider
+
+    def set_grabber(self, grabber) -> None:
+        """注入擷取函式：接收 QRect，回傳 QPixmap（測試用）。"""
+        self._grabber = grabber
+
+    def set_zoom(self, zoom: Optional[float] = None, size: Optional[int] = None) -> None:
+        if zoom is not None:
+            self.zoom = clamp_zoom(zoom)
+        if size is not None:
+            self.view_size = max(80, int(size))
+            self.resize(self.view_size, self.view_size)
+        self.update()
+
+    def start_following(self, interval_ms: int = REFRESH_MS) -> None:
+        self.refresh()
+        self._timer.start(max(16, int(interval_ms)))
+
+    @staticmethod
+    def _grab_screen(rect: QRect) -> Optional[QPixmap]:
+        """用 Qt 擷取指定螢幕區域；沒有可用螢幕時回傳 None。"""
+        screen = QGuiApplication.primaryScreen()
+        if screen is None:
+            return None
+        return screen.grabWindow(0, rect.x(), rect.y(), rect.width(), rect.height())
+
+    def screen_bounds(self) -> Tuple[int, int, int, int]:
+        screen = self.screen() or QGuiApplication.primaryScreen()
+        if screen is None:
+            return (0, 0, 1920, 1080)
+        geometry = screen.geometry()
+        return (geometry.left(), geometry.top(), geometry.right(), geometry.bottom())
+
+    def refresh(self) -> None:
+        """擷取游標周圍的畫面 / Grab the area around the cursor."""
+        try:
+            position = self._cursor_provider()
+            rect = source_rect((position.x(), position.y()), self.view_size, self.zoom,
+                               self.screen_bounds())
+            self.captured = self._grabber(rect)
+        except Exception as error:  # pragma: no cover - capture boundary
+            front_engine_logger.debug(f"[MagnifierWidget] capture failed: {error!r}")
+            return
+        self.update()
+
+    def draw_content(self, painter: QPainter) -> None:
+        if self.captured is None or self.captured.isNull():
+            return
+        painter.setRenderHint(QPainter.RenderHint.SmoothPixmapTransform)
+        target = QRect(0, 0, self.width(), self.height())
+        painter.drawPixmap(target, self.captured)
+        painter.setPen(QColor(255, 255, 255, 180))
+        painter.setBrush(Qt.BrushStyle.NoBrush)
+        painter.drawRect(target.adjusted(0, 0, -1, -1))
+
+    def closeEvent(self, event) -> None:
+        if self._timer.isActive():
+            self._timer.stop()
+        super().closeEvent(event)