frontengine 1.0.35__tar.gz → 1.0.36__tar.gz

{frontengine-1.0.35 → frontengine-1.0.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.35
+Version: 1.0.36
 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
@@ -113,6 +113,59 @@ Play a folder of images and animations *beneath* every window, from the
 
 ---
 
+## Widgets
+
+Four desktop widgets on the **Widgets** tab:
+
+- **Audio spectrum** — bars or a ring, log-spaced bands, smoothed with a
+  fast-attack/slow-decay follower and peak markers that drift down.
+  > Unlike the pet and the wallpaper, which read only the output *meter*, a
+  > spectrum needs the actual samples to compute frequencies — so this one
+  > **captures the system output stream**. The samples are analysed in memory,
+  > never written to disk or sent anywhere, and capture stops the moment you
+  > stop the spectrum. Windows only.
+- **Now playing** — the current track from Windows' media controls when the
+  optional `winsdk` bindings are installed; otherwise the name of the app that
+  is actually making sound.
+- **System monitor** — CPU, memory and disk as small sparklines. An average
+  hides a stall; a line does not.
+- **Sticky notes** — editable cards that float above every window and keep
+  their text, colour and position between sessions.
+
+---
+
+## Tools
+
+Measuring and capture tools on the **Tools** tab:
+
+- **Colour picker / pixel ruler / protractor** — click to sample or measure;
+  the result is copied straight to the clipboard as `#rrggbb`, `rgb(...)`,
+  `hsl(...)` or a CSS custom property.
+- **Region capture** — drag out an area; it lands on the clipboard and can be
+  saved to a file.
+- **Pin a window** — keep another program's window on top, or fade it, while
+  you work against it. Only stacking and opacity are touched, never window
+  content. Windows only.
+- **Camera** — your webcam in a circle, rounded box or rectangle, shown
+  locally and never recorded.
+
+---
+
+## Rules
+
+Things that decide for themselves, from the **Settings** menu:
+
+- **Smart pause** — stand the overlays down while a fullscreen app is running,
+  while the machine is on battery, or while a named app has focus.
+- **App profiles** — apply a saved preset when you switch to a given app.
+- **Reminders** — every N minutes, or once a day at a set time, shown as a
+  toast that closes itself.
+
+The control center also carries a **quality tier** (high / balanced / saver)
+that caps every overlay's refresh rate and drops its render resolution.
+
+---
+
 ## Community content
 
 - **Steam Workshop** — subscribed items are picked up from Steam's own

{frontengine-1.0.35 → frontengine-1.0.36}/README.md

@@ -89,6 +89,59 @@ Play a folder of images and animations *beneath* every window, from the
 
 ---
 
+## Widgets
+
+Four desktop widgets on the **Widgets** tab:
+
+- **Audio spectrum** — bars or a ring, log-spaced bands, smoothed with a
+  fast-attack/slow-decay follower and peak markers that drift down.
+  > Unlike the pet and the wallpaper, which read only the output *meter*, a
+  > spectrum needs the actual samples to compute frequencies — so this one
+  > **captures the system output stream**. The samples are analysed in memory,
+  > never written to disk or sent anywhere, and capture stops the moment you
+  > stop the spectrum. Windows only.
+- **Now playing** — the current track from Windows' media controls when the
+  optional `winsdk` bindings are installed; otherwise the name of the app that
+  is actually making sound.
+- **System monitor** — CPU, memory and disk as small sparklines. An average
+  hides a stall; a line does not.
+- **Sticky notes** — editable cards that float above every window and keep
+  their text, colour and position between sessions.
+
+---
+
+## Tools
+
+Measuring and capture tools on the **Tools** tab:
+
+- **Colour picker / pixel ruler / protractor** — click to sample or measure;
+  the result is copied straight to the clipboard as `#rrggbb`, `rgb(...)`,
+  `hsl(...)` or a CSS custom property.
+- **Region capture** — drag out an area; it lands on the clipboard and can be
+  saved to a file.
+- **Pin a window** — keep another program's window on top, or fade it, while
+  you work against it. Only stacking and opacity are touched, never window
+  content. Windows only.
+- **Camera** — your webcam in a circle, rounded box or rectangle, shown
+  locally and never recorded.
+
+---
+
+## Rules
+
+Things that decide for themselves, from the **Settings** menu:
+
+- **Smart pause** — stand the overlays down while a fullscreen app is running,
+  while the machine is on battery, or while a named app has focus.
+- **App profiles** — apply a saved preset when you switch to a given app.
+- **Reminders** — every N minutes, or once a day at a set time, shown as a
+  toast that closes itself.
+
+The control center also carries a **quality tier** (high / balanced / saver)
+that caps every overlay's refresh rate and drops its render resolution.
+
+---
+
 ## Community content
 
 - **Steam Workshop** — subscribed items are picked up from Steam's own

frontengine-1.0.36/frontengine/show/camera/camera_widget.py

@@ -0,0 +1,182 @@
+"""
+攝影機覆蓋層：把本機攝影機的畫面放在桌面上（直播用的圓形頭像框那種）。
+畫面只在本機顯示，不錄影、不上傳；關掉覆蓋層就停止擷取。
+
+A camera overlay: put the local webcam on the desktop - the round talking-head
+frame streamers use. The picture is shown locally only; nothing is recorded or
+uploaded, and closing the overlay stops the camera.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from PySide6.QtCore import QRect, Qt
+from PySide6.QtGui import QColor, QPainter, QPainterPath, QPen, QPixmap
+from PySide6.QtMultimedia import QCamera, QMediaCaptureSession, QMediaDevices, QVideoSink
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+SHAPE_RECTANGLE = "rectangle"
+SHAPE_CIRCLE = "circle"
+SHAPE_ROUNDED = "rounded"
+SHAPES = (SHAPE_RECTANGLE, SHAPE_CIRCLE, SHAPE_ROUNDED)
+
+DEFAULT_BORDER = 4
+_CORNER_RADIUS = 18
+
+
+def normalize_shape(shape) -> str:
+    """把外框形狀正規化；不認得的一律當方形。"""
+    name = str(shape or "").strip().lower()
+    return name if name in SHAPES else SHAPE_RECTANGLE
+
+
+def list_cameras() -> List[Tuple[str, str]]:
+    """
+    可用的攝影機 [(id, 顯示名稱)]；沒有裝置或查詢失敗回傳空清單。
+    Available cameras as (id, description); [] when there are none.
+    """
+    try:
+        return [(bytes(device.id()).decode("utf-8", "replace"), device.description())
+                for device in QMediaDevices.videoInputs()]
+    except Exception as error:  # pragma: no cover - depends on the platform backend
+        front_engine_logger.warning(f"[CameraWidget] listing cameras failed: {error!r}")
+        return []
+
+
+def shape_path(shape: str, rect: QRect) -> QPainterPath:
+    """外框形狀對應的裁切路徑。"""
+    path = QPainterPath()
+    name = normalize_shape(shape)
+    if name == SHAPE_CIRCLE:
+        size = min(rect.width(), rect.height())
+        square = QRect(rect.x() + (rect.width() - size) // 2,
+                       rect.y() + (rect.height() - size) // 2, size, size)
+        path.addEllipse(square)
+    elif name == SHAPE_ROUNDED:
+        path.addRoundedRect(rect, _CORNER_RADIUS, _CORNER_RADIUS)
+    else:
+        path.addRect(rect)
+    return path
+
+
+class CameraWidget(BaseWidget):
+    """
+    攝影機畫面覆蓋層。影像來源可注入（測試直接餵 QPixmap），因此不需要真的
+    攝影機也能驗證裁切與繪製。
+    """
+
+    def __init__(self, shape: str = SHAPE_CIRCLE, border: int = DEFAULT_BORDER,
+                 mirrored: bool = True) -> None:
+        front_engine_logger.info(f"[CameraWidget] Init | shape={shape}")
+        super().__init__()
+        self.opacity = 1.0
+        self.shape = normalize_shape(shape)
+        self.border = max(0, int(border))
+        self.mirrored = bool(mirrored)
+        self.border_color = QColor("#ffffff")
+        self.frame: Optional[QPixmap] = None
+        self._camera: Optional[QCamera] = None
+        self._session: Optional[QMediaCaptureSession] = None
+        self._sink: Optional[QVideoSink] = None
+        self.resize(240, 240)
+
+    def set_shape(self, shape: str) -> None:
+        self.shape = normalize_shape(shape)
+        self.update()
+
+    def set_border(self, border: int) -> None:
+        self.border = max(0, int(border))
+        self.update()
+
+    def set_mirrored(self, mirrored: bool) -> None:
+        """自拍鏡像：看自己的時候左右相反比較自然。"""
+        self.mirrored = bool(mirrored)
+        self.update()
+
+    def set_frame(self, pixmap: Optional[QPixmap]) -> None:
+        """直接給一張畫面（正式由攝影機推送，測試直接餵）。"""
+        self.frame = pixmap if pixmap is not None and not pixmap.isNull() else None
+        self.update()
+
+    def start(self, camera_id: Optional[str] = None) -> bool:
+        """
+        打開攝影機開始顯示；沒有裝置或啟動失敗回傳 False。
+        Open the camera. False when there is no device or it refuses to start.
+        """
+        devices = QMediaDevices.videoInputs()
+        if not devices:
+            front_engine_logger.warning("[CameraWidget] no camera available")
+            return False
+        chosen = devices[0]
+        if camera_id:
+            for device in devices:
+                if bytes(device.id()).decode("utf-8", "replace") == camera_id:
+                    chosen = device
+                    break
+        try:
+            self.stop()
+            self._camera = QCamera(chosen)
+            self._sink = QVideoSink(self)
+            self._sink.videoFrameChanged.connect(self._on_frame)
+            self._session = QMediaCaptureSession()
+            self._session.setCamera(self._camera)
+            self._session.setVideoSink(self._sink)
+            self._camera.start()
+        except Exception as error:  # pragma: no cover - depends on the backend
+            front_engine_logger.warning(f"[CameraWidget] start failed: {error!r}")
+            self.stop()
+            return False
+        front_engine_logger.info(f"[CameraWidget] started | {chosen.description()}")
+        return True
+
+    def stop(self) -> None:
+        """關閉攝影機（覆蓋層關掉時一定會走到這裡）。"""
+        if self._camera is not None:
+            try:
+                self._camera.stop()
+            except RuntimeError:  # pragma: no cover - already torn down
+                pass
+        self._camera = None
+        self._session = None
+        self._sink = None
+
+    def _on_frame(self, video_frame) -> None:  # pragma: no cover - needs a real camera
+        image = video_frame.toImage() if video_frame is not None else None
+        if image is None or image.isNull():
+            return
+        self.set_frame(QPixmap.fromImage(image))
+
+    def draw_content(self, painter: QPainter) -> None:
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing, True)
+        path = shape_path(self.shape, self.rect())
+        painter.save()
+        painter.setClipPath(path)
+        if self.frame is not None:
+            scaled = self.frame.scaled(
+                self.size(), Qt.AspectRatioMode.KeepAspectRatioByExpanding,
+                Qt.TransformationMode.SmoothTransformation)
+            if self.mirrored:
+                scaled = scaled.transformed(_mirror_transform())
+            painter.drawPixmap(
+                QRect((self.width() - scaled.width()) // 2,
+                      (self.height() - scaled.height()) // 2,
+                      scaled.width(), scaled.height()), scaled)
+        else:
+            painter.fillRect(self.rect(), QColor(0, 0, 0, 160))
+        painter.restore()
+        if self.border > 0:
+            painter.setPen(QPen(self.border_color, self.border))
+            painter.drawPath(path)
+
+    def closeEvent(self, event) -> None:
+        self.stop()
+        super().closeEvent(event)
+
+
+def _mirror_transform():
+    """左右翻轉用的變換矩陣。"""
+    from PySide6.QtGui import QTransform
+
+    return QTransform().scale(-1, 1)

frontengine-1.0.36/frontengine/show/capture/region_capture.py

@@ -0,0 +1,180 @@
+"""
+區域截圖：拖出一塊範圍，放開後把那塊畫面抓下來，可以存檔或複製到剪貼簿，
+也可以直接交給塗鴉層繼續標註。
+
+Region capture: drag out an area, and on release grab it - to a file, to the
+clipboard, or straight into the annotation layer to mark up.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable, Optional
+
+from PySide6.QtCore import QPoint, QRect, Qt
+from PySide6.QtGui import QColor, QGuiApplication, QPainter, QPen, QPixmap
+
+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
+
+MIN_CAPTURE_SIZE = 4
+_DIM_COLOR = QColor(0, 0, 0, 110)
+_EDGE_COLOR = "#4dd0e1"
+
+
+def normalize_rect(start: QPoint, end: QPoint) -> QRect:
+    """
+    把兩個角落整理成正的矩形（不管往哪個方向拖）。
+    Two corners to a positive rectangle, whichever way the drag went.
+    """
+    left, right = sorted((int(start.x()), int(end.x())))
+    top, bottom = sorted((int(start.y()), int(end.y())))
+    return QRect(left, top, right - left, bottom - top)
+
+
+def is_usable(rect: QRect) -> bool:
+    """太小的框（多半是誤點）不算一次截圖。"""
+    return rect.width() >= MIN_CAPTURE_SIZE and rect.height() >= MIN_CAPTURE_SIZE
+
+
+def safe_capture_path(folder: str, name: str) -> Optional[Path]:
+    """
+    組出儲存路徑並擋掉路徑穿越：檔名只取最後一段，且結果必須仍在資料夾底下。
+    Build the save path and refuse path traversal: only the final component of
+    the name is used, and the result must still sit inside the folder.
+    """
+    try:
+        base = Path(folder).resolve()
+        candidate = (base / Path(str(name)).name).resolve()
+    except (OSError, ValueError):
+        return None
+    if base != candidate.parent:
+        front_engine_logger.warning(f"[RegionCapture] refusing path outside {base}: {name!r}")
+        return None
+    return candidate
+
+
+class RegionCaptureWidget(BaseWidget):
+    """
+    全螢幕的截圖框選層：按住拖曳畫出範圍，放開就擷取。擷取函式與完成後的
+    處理都可注入，所以整個流程不需要真的螢幕也測得到。
+    """
+
+    def __init__(self, on_captured: Optional[Callable[[QPixmap, QRect], None]] = None) -> None:
+        front_engine_logger.info("[RegionCaptureWidget] Init")
+        super().__init__()
+        self.opacity = 1.0
+        self.overlay_lockable = False
+        self.origin: Optional[QPoint] = None
+        self.current: Optional[QPoint] = None
+        self.captured: Optional[QPixmap] = None
+        self._on_captured = on_captured
+        self._grabber = self._default_grabber
+        apply_overlay_window_flags(self, show_on_bottom=False, allow_input=True)
+        self.setCursor(Qt.CursorShape.CrossCursor)
+
+    @staticmethod
+    def _default_grabber(rect: QRect):  # pragma: no cover - needs a real screen
+        screen = QGuiApplication.primaryScreen()
+        if screen is None:
+            return None
+        return screen.grabWindow(0, rect.x(), rect.y(), rect.width(), rect.height())
+
+    def set_grabber(self, grabber) -> None:
+        self._grabber = grabber or self._default_grabber
+
+    def selection(self) -> Optional[QRect]:
+        """目前框出來的範圍；還沒開始拖就是 None。"""
+        if self.origin is None or self.current is None:
+            return None
+        return normalize_rect(self.origin, self.current)
+
+    # --- interaction -----------------------------------------------------
+    def begin(self, point: QPoint) -> None:
+        self.origin = QPoint(point)
+        self.current = QPoint(point)
+        self.update()
+
+    def extend(self, point: QPoint) -> None:
+        if self.origin is not None:
+            self.current = QPoint(point)
+            self.update()
+
+    def finish(self, point: QPoint) -> Optional[QPixmap]:
+        """
+        放開滑鼠：框太小就當作取消，否則擷取那塊畫面並回傳。
+        Releasing the mouse: too small counts as a cancel, otherwise grab that
+        part of the screen and hand it back.
+        """
+        self.extend(point)
+        rect = self.selection()
+        self.origin = self.current = None
+        if rect is None or not is_usable(rect):
+            self.update()
+            return None
+        try:
+            pixmap = self._grabber(rect)
+        except Exception as error:  # pragma: no cover - screen grab boundary
+            front_engine_logger.warning(f"[RegionCaptureWidget] grab failed: {error!r}")
+            pixmap = None
+        if pixmap is None or pixmap.isNull():
+            self.update()
+            return None
+        self.captured = pixmap
+        if self._on_captured is not None:
+            self._on_captured(pixmap, rect)
+        self.update()
+        return pixmap
+
+    def mousePressEvent(self, event) -> None:
+        if event.button() == Qt.MouseButton.LeftButton:
+            self.begin(event.position().toPoint())
+        super().mousePressEvent(event)
+
+    def mouseMoveEvent(self, event) -> None:
+        self.extend(event.position().toPoint())
+        super().mouseMoveEvent(event)
+
+    def mouseReleaseEvent(self, event) -> None:
+        if event.button() == Qt.MouseButton.LeftButton:
+            self.finish(event.position().toPoint())
+            self.close()
+        super().mouseReleaseEvent(event)
+
+    # --- outputs ---------------------------------------------------------
+    def copy_to_clipboard(self) -> bool:
+        """把剛擷取的畫面放進剪貼簿。"""
+        if self.captured is None or self.captured.isNull():
+            return False
+        clipboard = QGuiApplication.clipboard()
+        if clipboard is None:  # pragma: no cover - no clipboard at all
+            return False
+        clipboard.setPixmap(self.captured)
+        return True
+
+    def save_to(self, folder: str, name: str) -> Optional[str]:
+        """存成檔案並回傳實際路徑；沒有畫面或路徑不合法時回傳 None。"""
+        if self.captured is None or self.captured.isNull():
+            return None
+        path = safe_capture_path(folder, name)
+        if path is None:
+            return None
+        if not self.captured.save(str(path)):
+            front_engine_logger.warning(f"[RegionCaptureWidget] save failed: {path}")
+            return None
+        front_engine_logger.info(f"[RegionCaptureWidget] saved | {path}")
+        return str(path)
+
+    # --- painting --------------------------------------------------------
+    def draw_content(self, painter: QPainter) -> None:
+        rect = self.selection()
+        painter.fillRect(self.rect(), _DIM_COLOR)
+        if rect is None or rect.isEmpty():
+            return
+        # 框內回復原本亮度，框線標出範圍
+        # Clear the selection back to full brightness and outline it.
+        painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_Clear)
+        painter.fillRect(rect, Qt.GlobalColor.transparent)
+        painter.setCompositionMode(QPainter.CompositionMode.CompositionMode_SourceOver)
+        painter.setPen(QPen(QColor(_EDGE_COLOR), 2))
+        painter.drawRect(rect)