frontengine 1.0.33__tar.gz → 1.0.35__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.33
+Version: 1.0.35
 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
@@ -85,6 +85,50 @@ Audio features are Windows-only and degrade to "no pulse" elsewhere.
 
 ---
 
+## Focus
+
+Two overlays for when the screen is competing with your work, both on the
+**Focus** tab:
+
+- **Dim background windows** — everything except the window you are working in
+  is shaded, at an adjustable strength. Off Windows, where the active window
+  cannot be identified without a native binding, it shades the whole screen.
+- **Cover a distraction** — mask a strip of the screen: the taskbar, a
+  notification corner, an edge, or all of it.
+
+Both pass clicks through, so what they cover still works — it just stops pulling
+your eye.
+
+---
+
+## Wallpaper
+
+Play a folder of images and animations *beneath* every window, from the
+**Wallpaper** tab:
+
+- **A playlist per monitor** — each screen points at its own folder, changes on
+  its own timer, and can be shuffled or read recursively.
+- **React to audio** — the wallpaper can pulse with your speakers' output level,
+  using the same meter-only reading as the pet (no audio is captured).
+
+---
+
+## Community content
+
+- **Steam Workshop** — subscribed items are picked up from Steam's own
+  `steamapps/workshop/content` folder: presets are imported and pet packs are
+  listed with their paths, from **Presets → Import Workshop content**.
+  Publishing to the Workshop needs the Steamworks SDK and is not built in.
+- **Plugins** — a `plugins/` folder can add its own tabs, either through a
+  `FRONTENGINE_TABS` mapping or a `register(registry)` hook.
+
+  > A plugin is Python and runs with the same privileges as FrontEngine — it
+  > cannot be sandboxed. Loading is **off by default** (Settings → Load plugins),
+  > every load is logged, and one broken plugin is skipped rather than stopping
+  > the app. Only install plugins you trust.
+
+---
+
 ## Install
 
 - **System Requirements**

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

@@ -61,6 +61,50 @@ Audio features are Windows-only and degrade to "no pulse" elsewhere.
 
 ---
 
+## Focus
+
+Two overlays for when the screen is competing with your work, both on the
+**Focus** tab:
+
+- **Dim background windows** — everything except the window you are working in
+  is shaded, at an adjustable strength. Off Windows, where the active window
+  cannot be identified without a native binding, it shades the whole screen.
+- **Cover a distraction** — mask a strip of the screen: the taskbar, a
+  notification corner, an edge, or all of it.
+
+Both pass clicks through, so what they cover still works — it just stops pulling
+your eye.
+
+---
+
+## Wallpaper
+
+Play a folder of images and animations *beneath* every window, from the
+**Wallpaper** tab:
+
+- **A playlist per monitor** — each screen points at its own folder, changes on
+  its own timer, and can be shuffled or read recursively.
+- **React to audio** — the wallpaper can pulse with your speakers' output level,
+  using the same meter-only reading as the pet (no audio is captured).
+
+---
+
+## Community content
+
+- **Steam Workshop** — subscribed items are picked up from Steam's own
+  `steamapps/workshop/content` folder: presets are imported and pet packs are
+  listed with their paths, from **Presets → Import Workshop content**.
+  Publishing to the Workshop needs the Steamworks SDK and is not built in.
+- **Plugins** — a `plugins/` folder can add its own tabs, either through a
+  `FRONTENGINE_TABS` mapping or a `register(registry)` hook.
+
+  > A plugin is Python and runs with the same privileges as FrontEngine — it
+  > cannot be sandboxed. Loading is **off by default** (Settings → Load plugins),
+  > every load is logged, and one broken plugin is skipped rather than stopping
+  > the app. Only install plugins you trust.
+
+---
+
 ## Install
 
 - **System Requirements**

{frontengine-1.0.33 → frontengine-1.0.35}/frontengine/show/base_widget.py

@@ -8,6 +8,7 @@ from PySide6.QtWidgets import QWidget
 from frontengine.show.window_helpers import apply_overlay_window_flags, load_overlay_icon
 from frontengine.user_setting.user_setting_file import get_overlay_geometry, save_overlay_geometry
 from frontengine.utils.logging.loggin_instance import front_engine_logger
+from frontengine.utils.power_mode.power_mode import DEFAULT_TIER, normalize_tier, tier_render_scale
 
 
 class BaseWidget(QWidget):
@@ -29,6 +30,9 @@ class BaseWidget(QWidget):
         # 綠幕背景色：設了就以不透明色填滿背景，方便 OBS 去背
         # Chroma key colour: fills the background opaquely so OBS can key it out.
         self.background_color: Optional[QColor] = None
+        # 畫質檔位：影響更新頻率上限與算圖縮放（見 utils/power_mode）
+        # Quality tier: caps the refresh rate and scales rendering (see utils/power_mode).
+        self.quality_tier: str = DEFAULT_TIER
         self._drag_origin = None
         self._geometry_restored = False
 
@@ -44,6 +48,27 @@ class BaseWidget(QWidget):
         front_engine_logger.info(f"{self.__class__.__name__} set_ui_variable | opacity: {opacity}")
         self.opacity = opacity
 
+    def set_quality_tier(self, tier: str) -> None:
+        """
+        設定畫質檔位。基底類別只記下來並通知子類別，實際怎麼省由子類別決定
+        （例如放慢自己的計時器、用較低解析度算圖）。
+        Set the quality tier. The base class records it and tells the subclass;
+        what to actually give up - timer rate, render resolution - is the
+        subclass's call.
+        """
+        self.quality_tier = normalize_tier(tier)
+        front_engine_logger.info(
+            f"{self.__class__.__name__} set_quality_tier | tier: {self.quality_tier}")
+        self.apply_quality_tier()
+        self.update()
+
+    def apply_quality_tier(self) -> None:
+        """子類別覆寫這裡，把新的檔位套到自己的計時器／算圖上。"""
+
+    def render_scale(self) -> float:
+        """目前檔位的算圖縮放，1.0 表示原生解析度。"""
+        return tier_render_scale(self.quality_tier)
+
     def set_background_color(self, color) -> None:
         """
         設定綠幕背景色（傳 None 取消）。背景以不透明色填滿，內容再依原本的

frontengine-1.0.35/frontengine/show/focus_shield/focus_shield_widget.py

@@ -0,0 +1,137 @@
+"""
+專注用的兩種遮罩：
+  - DimBackgroundWidget：把作用中視窗以外的地方壓暗，視線自然留在手上的工作
+  - DistractionMaskWidget：蓋住指定的螢幕區域（工作列、通知角落）
+兩者都是點擊穿透的，所以被遮住的地方仍然可以正常點擊。
+
+Two focus masks: one dims everything except the active window so your eye stays
+on the work, the other covers a chosen strip of the screen (the taskbar, a
+notification corner). Both pass clicks through, so what is covered still works.
+"""
+from __future__ import annotations
+
+import sys
+from typing import List, Optional, Tuple
+
+from PySide6.QtCore import QRect, QTimer
+from PySide6.QtGui import QColor, QPainter
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.utils.focus_shield.focus_shield import (
+    REGION_BOTTOM, clamp_percent, mask_rect, surrounding_rects,
+)
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+DEFAULT_DIM = 45
+
+
+def active_window_rect() -> Optional[Tuple[int, int, int, int]]:
+    """
+    回傳目前作用中視窗的 (x, y, w, h)；取不到或非 Windows 回傳 None
+    （其他平台會退化成「整片壓暗」，仍然可用）。
+    The active window's rectangle, or None off Windows — where the dimmer simply
+    shades the whole screen instead.
+    """
+    if sys.platform != "win32":
+        return None
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        user32 = ctypes.windll.user32
+        hwnd = user32.GetForegroundWindow()
+        if not hwnd:
+            return None
+        rect = wintypes.RECT()
+        if not user32.GetWindowRect(hwnd, ctypes.byref(rect)):
+            return None
+        return (rect.left, rect.top, rect.right - rect.left, rect.bottom - rect.top)
+    except Exception as error:  # pragma: no cover - Win32 boundary
+        front_engine_logger.debug(f"[focus_shield] active window unavailable: {error!r}")
+        return None
+
+
+class DimBackgroundWidget(BaseWidget):
+    """
+    背景變暗：只有作用中視窗保持原樣，其餘壓暗；視窗換了會自動跟上。
+    """
+
+    REFRESH_MS = 250
+
+    def __init__(self, dim: int = DEFAULT_DIM) -> None:
+        front_engine_logger.info(f"[DimBackgroundWidget] Init | dim={dim}")
+        super().__init__()
+        self.opacity = 1.0
+        self.dim = clamp_percent(dim, DEFAULT_DIM)
+        self.shaded: List[Tuple[int, int, int, int]] = []
+        self._window_provider = active_window_rect
+        self._timer = QTimer(self)
+        self._timer.timeout.connect(self.refresh)
+
+    def set_window_provider(self, provider) -> None:
+        """注入作用中視窗來源（測試用）。"""
+        self._window_provider = provider
+
+    def set_dim(self, dim: int) -> None:
+        self.dim = clamp_percent(dim, DEFAULT_DIM)
+        self.update()
+
+    def start_following(self, interval_ms: int = REFRESH_MS) -> None:
+        self.refresh()
+        self._timer.start(max(50, int(interval_ms)))
+
+    def screen_rect(self) -> Tuple[int, int, int, int]:
+        geometry = self.geometry()
+        return (geometry.x(), geometry.y(), geometry.width(), geometry.height())
+
+    def refresh(self) -> None:
+        """重新計算要壓暗的區塊。"""
+        try:
+            active = self._window_provider()
+        except Exception:  # pragma: no cover - defensive around providers
+            active = None
+        rects = surrounding_rects(self.screen_rect(), active)
+        origin_x, origin_y = self.x(), self.y()
+        # 換算成本視窗的座標系 / Convert to this widget's own coordinates
+        self.shaded = [(x - origin_x, y - origin_y, w, h) for x, y, w, h in rects]
+        self.update()
+
+    def draw_content(self, painter: QPainter) -> None:
+        shade = QColor(0, 0, 0, int(255 * self.dim / 100.0))
+        for x, y, width, height in self.shaded:
+            painter.fillRect(QRect(x, y, width, height), shade)
+
+    def closeEvent(self, event) -> None:
+        if self._timer.isActive():
+            self._timer.stop()
+        super().closeEvent(event)
+
+
+class DistractionMaskWidget(BaseWidget):
+    """
+    干擾遮罩：把螢幕的某個區域（預設底部，正好蓋住工作列）以不透明色蓋掉。
+    """
+
+    def __init__(self, region: str = REGION_BOTTOM, percent: int = 6,
+                 color: str = "#101010") -> None:
+        front_engine_logger.info(
+            f"[DistractionMaskWidget] Init | region={region}, percent={percent}")
+        super().__init__()
+        self.opacity = 1.0
+        self.region = region
+        self.percent = clamp_percent(percent)
+        self.mask_color = QColor(color) if QColor(color).isValid() else QColor("#101010")
+
+    def geometry_for(self, screen_rect: Tuple[int, int, int, int]) -> QRect:
+        """算出這個遮罩該放在哪裡、多大。"""
+        x, y, width, height = mask_rect(screen_rect, self.region, self.percent)
+        return QRect(x, y, width, height)
+
+    def set_region(self, region: Optional[str] = None, percent: Optional[int] = None) -> None:
+        if region is not None:
+            self.region = region
+        if percent is not None:
+            self.percent = clamp_percent(percent)
+
+    def draw_content(self, painter: QPainter) -> None:
+        painter.fillRect(self.rect(), self.mask_color)

{frontengine-1.0.33 → frontengine-1.0.35}/frontengine/show/pet/desktop_pet.py

@@ -1,6 +1,5 @@
 import json
 import random as _random_module
-import sys
 from datetime import datetime, timedelta
 from pathlib import Path
 from urllib.parse import urlparse

frontengine-1.0.35/frontengine/show/toast/toast_widget.py

@@ -0,0 +1,120 @@
+"""
+提示卡：在畫面上方短暫顯示一行字（提醒到期、規則觸發等），時間到自己關掉。
+點擊穿透，不會擋到底下的操作。
+
+A toast: a line of text shown briefly near the top of the screen - a reminder
+coming due, a rule firing - that closes itself. Click-through, so it never gets
+in the way of what is underneath.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from PySide6.QtCore import Qt, QTimer
+from PySide6.QtGui import QColor, QFont, QFontMetrics, QGuiApplication, QPainter
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+DEFAULT_DURATION_MS = 5000
+MIN_DURATION_MS = 500
+_PADDING = 18
+_CORNER_RADIUS = 10
+
+
+def clamp_duration(value, fallback: int = DEFAULT_DURATION_MS) -> int:
+    """顯示時間至少半秒，避免設成 0 讓提示閃一下就不見。"""
+    try:
+        return max(MIN_DURATION_MS, int(value))
+    except (TypeError, ValueError):
+        return fallback
+
+
+class ToastWidget(BaseWidget):
+    """
+    一張自動消失的提示卡。文字寬度決定卡片寬度，位置預設貼在主螢幕上方置中。
+    An auto-dismissing toast. The card is sized to its text and sits centred
+    near the top of the primary screen by default.
+    """
+
+    def __init__(self, message: str = "", duration_ms: int = DEFAULT_DURATION_MS,
+                 font_size: int = 18) -> None:
+        front_engine_logger.info(f"[ToastWidget] Init | message={message!r}")
+        super().__init__()
+        self.message: str = str(message)
+        self.duration_ms: int = clamp_duration(duration_ms)
+        self.text_color = QColor("#ffffff")
+        self.card_color = QColor(20, 20, 20, 230)
+        self.opacity = 1.0
+        # 提示卡不該被拖曳擺位，也不接受點擊
+        # A toast is never dragged into place and never takes clicks.
+        self.overlay_lockable = False
+        self._font = QFont()
+        self._font.setPointSize(max(8, int(font_size)))
+        self._close_timer = QTimer(self)
+        self._close_timer.setSingleShot(True)
+        self._close_timer.timeout.connect(self.close)
+        self.set_ui_window_flag(show_on_bottom=False)
+        self.resize_to_message()
+
+    def set_message(self, message: str) -> None:
+        """換一則訊息並重新計算卡片大小。"""
+        self.message = str(message)
+        self.resize_to_message()
+        self.update()
+
+    def card_size(self) -> tuple:
+        """依文字算出卡片的寬高（含內距）。"""
+        metrics = QFontMetrics(self._font)
+        width = metrics.horizontalAdvance(self.message) + _PADDING * 2
+        height = metrics.height() + _PADDING
+        return (max(80, width), max(36, height))
+
+    def resize_to_message(self) -> None:
+        width, height = self.card_size()
+        self.resize(width, height)
+        self.move_to_top_centre()
+
+    def move_to_top_centre(self, screen=None) -> None:
+        """擺到螢幕上方置中（離頂端一小段距離，避開全螢幕程式的標題列）。"""
+        target = screen or QGuiApplication.primaryScreen()
+        if target is None:  # pragma: no cover - no screen at all
+            return
+        available = target.availableGeometry()
+        self.move(
+            available.x() + (available.width() - self.width()) // 2,
+            available.y() + max(24, available.height() // 12),
+        )
+
+    def show_toast(self, screen=None) -> None:
+        """顯示並在時間到時自動關閉。"""
+        self.resize_to_message()
+        self.move_to_top_centre(screen)
+        self.show()
+        self._close_timer.start(self.duration_ms)
+
+    def draw_content(self, painter: QPainter) -> None:
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing, True)
+        painter.setPen(Qt.PenStyle.NoPen)
+        painter.setBrush(self.card_color)
+        painter.drawRoundedRect(self.rect(), _CORNER_RADIUS, _CORNER_RADIUS)
+        painter.setFont(self._font)
+        painter.setPen(self.text_color)
+        painter.drawText(self.rect(), Qt.AlignmentFlag.AlignCenter, self.message)
+
+
+def show_toast(message: str, duration_ms: int = DEFAULT_DURATION_MS,
+               screen=None) -> Optional[ToastWidget]:
+    """
+    顯示一則提示卡並回傳它（訊息為空就不顯示，回傳 None）。呼叫端不必自己
+    管生命週期：時間到會自己 close，而 BaseWidget 帶著 WA_DeleteOnClose。
+    Show a toast and hand it back (None for an empty message). Callers do not
+    have to manage its life: it closes itself, and BaseWidget carries
+    WA_DeleteOnClose.
+    """
+    text = str(message or "").strip()
+    if not text:
+        return None
+    toast = ToastWidget(text, duration_ms)
+    toast.show_toast(screen)
+    return toast

frontengine-1.0.35/frontengine/show/wallpaper/wallpaper_widget.py

@@ -0,0 +1,169 @@
+"""
+桌布覆蓋層：在所有視窗底下播放圖片或動圖，可依系統音量脈動（音訊反應桌布），
+並由播放清單定時換張。音量來源沿用寵物已經在用的系統峰值電表，只讀電表、
+不擷取音訊內容。
+
+A wallpaper layer: plays an image or animation beneath every window, optionally
+pulsing with the system output level, with a playlist swapping it over time.
+The level comes from the same meter the pet uses — a meter reading only, never
+captured audio.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from PySide6.QtCore import QRect, Qt, QTimer
+from PySide6.QtGui import QMovie, QPainter, QPixmap
+
+from frontengine.show.base_widget import BaseWidget
+from frontengine.utils.audio_meter.audio_envelope import AudioEnvelope
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+from frontengine.utils.power_mode.power_mode import tier_interval
+
+_ANIMATED_SUFFIXES = (".gif", ".webp")
+MIN_REACT_SCALE = 1.0
+MAX_REACT_SCALE = 1.25
+
+
+def react_scale(level, strength: int = 100) -> float:
+    """
+    把音量 (0~1) 換成桌布的縮放比例：安靜時 1.0，最大聲時最多放大 25%。
+    strength 是效果強度百分比，0 代表完全不反應。
+    Map an audio level to a wallpaper scale: 1.0 when quiet, up to +25% loud.
+    """
+    try:
+        clamped = max(0.0, min(1.0, float(level)))
+    except (TypeError, ValueError):
+        return MIN_REACT_SCALE
+    try:
+        share = max(0, min(100, int(strength))) / 100.0
+    except (TypeError, ValueError):
+        share = 1.0
+    return MIN_REACT_SCALE + (MAX_REACT_SCALE - MIN_REACT_SCALE) * clamped * share
+
+
+class WallpaperWidget(BaseWidget):
+    """
+    桌布：顯示一張圖或一段動圖，位於所有視窗底下；可選擇隨系統音量脈動。
+    """
+
+    REACT_INTERVAL_MS = 33
+
+    def __init__(self, media_path: str = "", audio_react: bool = False,
+                 react_strength: int = 100) -> None:
+        front_engine_logger.info(
+            f"[WallpaperWidget] Init | path={media_path}, audio_react={audio_react}")
+        super().__init__()
+        self.opacity = 1.0
+        self.media_path: Optional[Path] = None
+        self._movie: Optional[QMovie] = None
+        self._pixmap: Optional[QPixmap] = None
+        self.audio_react = bool(audio_react)
+        self.react_strength = max(0, min(100, int(react_strength)))
+        self.scale = MIN_REACT_SCALE
+        self._level_provider = None
+        self._envelope = AudioEnvelope()
+        self._react_timer = QTimer(self)
+        self._react_timer.timeout.connect(self._update_scale)
+        if media_path:
+            self.set_media(media_path)
+
+    def set_media(self, media_path: str) -> bool:
+        """換一張桌布；載不起來時保留原本的並回傳 False。"""
+        path = Path(media_path)
+        if not path.is_file():
+            front_engine_logger.warning(f"[WallpaperWidget] missing media: {path}")
+            return False
+        if path.suffix.lower() in _ANIMATED_SUFFIXES:
+            movie = QMovie(str(path))
+            if not movie.isValid():
+                return False
+            self._stop_movie()
+            self._movie = movie
+            self._pixmap = None
+            movie.frameChanged.connect(self.update)
+            movie.start()
+        else:
+            pixmap = QPixmap(str(path))
+            if pixmap.isNull():
+                return False
+            self._stop_movie()
+            self._pixmap = pixmap
+            self._movie = None
+        self.media_path = path
+        self.update()
+        return True
+
+    def set_audio_level_provider(self, provider) -> None:
+        """設定音量來源（回傳 0~1 或 None）。"""
+        self._level_provider = provider
+        self._envelope.reset()
+
+    def set_audio_react(self, enabled: bool, strength: Optional[int] = None) -> None:
+        """開關音訊反應並視需要調整強度。"""
+        self.audio_react = bool(enabled)
+        if strength is not None:
+            self.react_strength = max(0, min(100, int(strength)))
+        if self.audio_react:
+            self._react_timer.start(tier_interval(self.REACT_INTERVAL_MS, self.quality_tier))
+        else:
+            self._react_timer.stop()
+            self.scale = MIN_REACT_SCALE
+            self.update()
+
+    def apply_quality_tier(self) -> None:
+        """畫質檔位改變時，跟著調整脈動的更新頻率（算圖縮放在繪製時套用）。"""
+        if self._react_timer.isActive():
+            self._react_timer.start(tier_interval(self.REACT_INTERVAL_MS, self.quality_tier))
+
+    def _update_scale(self) -> None:
+        """取一次音量、平滑後換成縮放比例。"""
+        if not self.audio_react or self._level_provider is None:
+            self.scale = MIN_REACT_SCALE
+            return
+        try:
+            level = self._level_provider()
+        except Exception:  # pragma: no cover - defensive around providers
+            level = None
+        if level is None:
+            self.scale = MIN_REACT_SCALE
+            self._envelope.reset()
+        else:
+            self.scale = react_scale(self._envelope.push(level), self.react_strength)
+        self.update()
+
+    def _stop_movie(self) -> None:
+        if self._movie is not None:
+            self._movie.stop()
+            self._movie = None
+
+    def current_pixmap(self) -> Optional[QPixmap]:
+        if self._movie is not None:
+            return self._movie.currentPixmap()
+        return self._pixmap
+
+    def draw_content(self, painter: QPainter) -> None:
+        pixmap = self.current_pixmap()
+        if pixmap is None or pixmap.isNull():
+            return
+        # 低畫質檔位先把來源縮小再放大回來：算的像素少，看起來只是稍軟。
+        # Lower tiers shrink the source before scaling it back up: fewer pixels
+        # to push, at the cost of a slightly softer picture.
+        scale = self.render_scale()
+        if scale < 1.0:
+            pixmap = pixmap.scaled(
+                max(1, int(pixmap.width() * scale)), max(1, int(pixmap.height() * scale)),
+                Qt.AspectRatioMode.IgnoreAspectRatio, Qt.TransformationMode.FastTransformation)
+        width = int(self.width() * self.scale)
+        height = int(self.height() * self.scale)
+        # 放大時往外溢出，維持置中，畫面才不會出現黑邊
+        # Overflow outward and stay centred so no bars appear while pulsing.
+        painter.drawPixmap(
+            QRect((self.width() - width) // 2, (self.height() - height) // 2, width, height), pixmap)
+
+    def closeEvent(self, event) -> None:
+        if self._react_timer.isActive():
+            self._react_timer.stop()
+        self._stop_movie()
+        super().closeEvent(event)