frontengine 1.0.29__tar.gz → 1.0.31__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.29
+Version: 1.0.31
 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.31/frontengine/show/base_widget.py

@@ -0,0 +1,125 @@
+from abc import abstractmethod
+from typing import Optional
+
+from PySide6.QtCore import Qt, QTimer
+from PySide6.QtGui import QColor, QPainter
+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
+
+
+class BaseWidget(QWidget):
+    """
+    BaseWidget: 提供共用 UI 屬性與事件處理的基底類別
+    BaseWidget: Base class providing shared UI attributes and event handling
+    """
+
+    def __init__(self, draw_location_x: int = 0, draw_location_y: int = 0):
+        super().__init__()
+        self.draw_location_x: int = draw_location_x
+        self.draw_location_y: int = draw_location_y
+        self.opacity: float = 0.2
+        # 鎖定＝點擊穿透；解鎖後可用拖曳擺位（見 window_helpers.set_overlay_locked）
+        # Locked means click-through; unlocked overlays can be dragged into place.
+        self.overlay_locked: bool = True
+        self.overlay_lockable: bool = True
+        self.overlay_show_on_bottom: bool = False
+        # 綠幕背景色：設了就以不透明色填滿背景，方便 OBS 去背
+        # Chroma key colour: fills the background opaquely so OBS can key it out.
+        self.background_color: Optional[QColor] = None
+        self._drag_origin = None
+        self._geometry_restored = False
+
+        self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
+        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
+        load_overlay_icon(self)
+
+    def set_ui_window_flag(self, show_on_bottom: bool = False) -> None:
+        front_engine_logger.info(f"{self.__class__.__name__} set_ui_window_flag | show_on_bottom: {show_on_bottom}")
+        apply_overlay_window_flags(self, show_on_bottom=show_on_bottom)
+
+    def set_ui_variable(self, opacity: float = 0.2) -> None:
+        front_engine_logger.info(f"{self.__class__.__name__} set_ui_variable | opacity: {opacity}")
+        self.opacity = opacity
+
+    def set_background_color(self, color) -> None:
+        """
+        設定綠幕背景色（傳 None 取消）。背景以不透明色填滿，內容再依原本的
+        不透明度疊上去，這樣 OBS 的 Chroma Key 才能乾淨去背。
+        Set the chroma key background colour (None clears it). The background is
+        filled opaquely and the content drawn over it at the usual opacity, so
+        OBS's chroma key filter can remove it cleanly.
+        """
+        if color is None:
+            self.background_color = None
+        else:
+            candidate = QColor(color)
+            self.background_color = candidate if candidate.isValid() else None
+        self.setAttribute(
+            Qt.WidgetAttribute.WA_TranslucentBackground, self.background_color is None)
+        self.update()
+
+    # --- drag to position (only while unlocked) --------------------------
+    def mousePressEvent(self, event) -> None:
+        if not self.overlay_locked and event.button() == Qt.MouseButton.LeftButton:
+            self._drag_origin = event.globalPosition().toPoint() - self.frameGeometry().topLeft()
+        super().mousePressEvent(event)
+
+    def mouseMoveEvent(self, event) -> None:
+        if not self.overlay_locked and self._drag_origin is not None:
+            self.move(event.globalPosition().toPoint() - self._drag_origin)
+        super().mouseMoveEvent(event)
+
+    def mouseReleaseEvent(self, event) -> None:
+        if self._drag_origin is not None:
+            self._drag_origin = None
+            self.remember_geometry()
+        super().mouseReleaseEvent(event)
+
+    def remember_geometry(self) -> None:
+        """記住目前位置與大小，之後同類覆蓋層會開在同一處。"""
+        geometry = self.geometry()
+        front_engine_logger.info(
+            f"{self.__class__.__name__} remember_geometry | {geometry.x()},{geometry.y()} "
+            f"{geometry.width()}x{geometry.height()}"
+        )
+        save_overlay_geometry(
+            self.__class__.__name__, geometry.x(), geometry.y(), geometry.width(), geometry.height())
+
+    def showEvent(self, event) -> None:
+        super().showEvent(event)
+        if not self._geometry_restored:
+            self._geometry_restored = True
+            # 顯示流程結束後再套用，避免和 showFullScreen 打架
+            # Applied after the show completes so it does not fight showFullScreen.
+            QTimer.singleShot(0, self.restore_saved_geometry)
+
+    def restore_saved_geometry(self) -> None:
+        """若這類覆蓋層有記住的位置就套用（使用者拖曳過才會有）。"""
+        saved = get_overlay_geometry(self.__class__.__name__)
+        if not saved:
+            return
+        try:
+            if self.isFullScreen():
+                self.showNormal()
+            self.setGeometry(*saved)
+        except RuntimeError:  # pragma: no cover - widget closed mid-callback
+            return
+
+    def paintEvent(self, event) -> None:
+        front_engine_logger.debug(f"{self.__class__.__name__} paintEvent | event: {event}")
+        painter = QPainter(self)
+        if self.background_color is not None:
+            painter.fillRect(self.rect(), self.background_color)
+        painter.save()
+        painter.setOpacity(self.opacity)
+        try:
+            self.draw_content(painter)
+        finally:
+            painter.restore()
+
+    @abstractmethod
+    def draw_content(self, painter: QPainter) -> None:
+        """Subclass hook that renders the widget content onto the shared painter."""

{frontengine-1.0.29 → frontengine-1.0.31}/frontengine/show/pet/desktop_pet.py

@@ -1,7 +1,9 @@
+import json
 import random as _random_module
 import sys
 from datetime import datetime, timedelta
 from pathlib import Path
+from urllib.parse import urlparse
 from typing import Optional, Tuple
 
 from PySide6.QtCore import Qt, QRect, QTimer, QUrl, Signal
@@ -83,6 +85,10 @@ def scan_pet_pack(folder: str) -> dict:
     return result
 
 
+# 可以請寵物幫忙開啟的網址協定 / URL schemes the pet will open for you
+_WEB_SCHEMES = frozenset({"http", "https"})
+
+
 # 拖進寵物的檔案分類 / What a file dropped onto the pet means
 DROP_SPRITE = "sprite"  # 圖片或動作包 -> 換一套外觀
 DROP_FOOD = "food"      # 其他檔案 -> 當成食物餵給寵物
@@ -142,6 +148,55 @@ def classify_food(path) -> str:
     return FOOD_SNACK
 
 
+# 動作包設定檔：放在動作包資料夾裡，用來描述這隻寵物的個性與參數
+# Pack manifest: sits inside a pet pack folder describing that pet's traits.
+PACK_MANIFEST_NAME = "pet.json"
+_MANIFEST_NUMBERS = ("size", "speed")
+_MANIFEST_FLAGS = ("climb", "talk", "sit_on_windows")
+
+
+def read_pet_manifest(folder) -> dict:
+    """
+    讀取動作包裡的 pet.json（可選）。只取認得的欄位，型別不符就略過，
+    讀不到或格式錯誤一律回傳空 dict，讓動作包永遠不會弄壞寵物。
+
+    Read a pack's optional pet.json. Only known, well-typed fields are kept and
+    anything unreadable yields {}, so a pack can never break the pet.
+    """
+    manifest: dict = {}
+    try:
+        path = Path(folder) / PACK_MANIFEST_NAME
+        if not path.is_file():
+            return manifest
+        with path.open("r", encoding="utf-8") as handle:
+            raw = json.load(handle)
+    except (OSError, ValueError, TypeError):
+        return manifest
+    if not isinstance(raw, dict):
+        return manifest
+    for key in _MANIFEST_NUMBERS:
+        try:
+            if key in raw:
+                manifest[key] = max(1, int(raw[key]))
+        except (TypeError, ValueError):
+            continue
+    for key in _MANIFEST_FLAGS:
+        if isinstance(raw.get(key), bool):
+            manifest[key] = raw[key]
+    if isinstance(raw.get("name"), str):
+        manifest["name"] = raw["name"]
+    if isinstance(raw.get("sound"), str):
+        manifest["sound"] = raw["sound"]
+    lines = raw.get("lines")
+    if isinstance(lines, dict):
+        manifest["lines"] = {
+            str(pool): [str(line) for line in values if str(line).strip()]
+            for pool, values in lines.items()
+            if isinstance(values, list) and values
+        }
+    return manifest
+
+
 def derive_visual_state(dragging: bool, airborne: bool, surface: str, motion_state: str) -> str:
     """依目前情形推導應顯示的視覺狀態 / Derive which sprite state to show."""
     if dragging:
@@ -1101,9 +1156,21 @@ class DesktopPetWidget(BaseWidget):
         self._hunger = PetHunger(user_setting_dict.get("pet_hunger", 70))
         self._hunger_warned = False
         self._messages = self._load_messages()
+        # 動作包自帶的設定（可含台詞、速度、體型、音效）
+        # Traits shipped inside the pack (lines, speed, size, sound).
+        self.manifest = read_pet_manifest(self.image_path) if self.image_path.is_dir() else {}
+        self._apply_manifest()
         self._volume = max(0.0, min(1.0, float(volume)))
         self._sound: Optional[QSoundEffect] = None
-        self._init_sound(sound_path)
+        self._init_sound(self.manifest.get("sound_path", sound_path))
+        # 語音朗讀（可選，缺少 QtTextToSpeech 時自動停用）
+        # Optional spoken lines; disabled automatically without QtTextToSpeech.
+        self._speech = None
+        self._speak = False
+        # AI 對話（可選，需環境變數金鑰；預設關閉）
+        # Optional AI chat; needs an env-var key and is off by default.
+        self._chat_service = None
+        self._pending_chat_reply: Optional[str] = None
         self._sit_on_windows = bool(sit_on_windows)
         self._platform_tick = 0
         # 音訊視覺化：依可注入的音量 provider 脈動 / Audio-reactive pulse
@@ -1152,6 +1219,11 @@ class DesktopPetWidget(BaseWidget):
             language_wrapper.language_word_dict.get("pet_set_reminder", "Set reminder..."), self)
         self.reminder_action.triggered.connect(self._prompt_reminder)
         self.menu.addAction(self.reminder_action)
+        self.chat_action = QAction(
+            language_wrapper.language_word_dict.get("pet_chat_menu", "Talk to me..."), self)
+        self.chat_action.triggered.connect(self._prompt_chat)
+        self.chat_action.setVisible(False)  # shown only when a chat service is attached
+        self.menu.addAction(self.chat_action)
         self.close_action = QAction(language_wrapper.language_word_dict.get("control_center_close_all", "Close"), self)
         self.close_action.triggered.connect(self.close)
         self.menu.addAction(self.close_action)
@@ -1161,8 +1233,9 @@ class DesktopPetWidget(BaseWidget):
     PLAY_CHANCE = 0.25
 
     def set_pet_window_flag(self) -> None:
-        """寵物需接收滑鼠以便拖曳，故 allow_input=True 並置頂。"""
+        """寵物需接收滑鼠以便拖曳，故 allow_input=True 並置頂，也不參與全域鎖定。"""
         apply_overlay_window_flags(self, show_on_bottom=False, allow_input=True)
+        self.overlay_lockable = False
 
     def center(self) -> Tuple[int, int]:
         return (self.x() + self.width() // 2, self.y() + self.height() // 2)
@@ -1357,6 +1430,58 @@ class DesktopPetWidget(BaseWidget):
         if self._timeline_start is None:
             self._timeline_start = self._now_provider()
 
+    def _apply_manifest(self) -> None:
+        """套用動作包設定：台詞併入句庫，速度／體型／音效覆寫預設值。"""
+        if not self.manifest:
+            return
+        front_engine_logger.info(f"[DesktopPetWidget] pack manifest | {self.manifest}")
+        for pool, lines in (self.manifest.get("lines") or {}).items():
+            self._messages[pool] = list(lines)
+        if "speed" in self.manifest:
+            self.motion.speed = max(1, int(self.manifest["speed"]))
+        if "size" in self.manifest:
+            self._base_size = max(16, int(self.manifest["size"]))
+            self._apply_growth_size()
+        if "climb" in self.manifest:
+            self.motion.climb = bool(self.manifest["climb"])
+        if "talk" in self.manifest:
+            self._talk = bool(self.manifest["talk"])
+        sound = self.manifest.get("sound")
+        if sound:
+            candidate = self.image_path / sound
+            if candidate.is_file():
+                self.manifest["sound_path"] = str(candidate)
+
+    def set_speech_enabled(self, enabled: bool) -> bool:
+        """
+        開關語音朗讀；系統缺少 QtTextToSpeech 時回傳 False 並維持關閉。
+        Toggle spoken lines, returning False when QtTextToSpeech is unavailable.
+        """
+        if not enabled:
+            self._speak = False
+            return False
+        if self._speech is None:
+            try:
+                from PySide6.QtTextToSpeech import QTextToSpeech
+
+                self._speech = QTextToSpeech(self)
+            except Exception as error:  # pragma: no cover - optional Qt module
+                front_engine_logger.warning(f"[DesktopPetWidget] speech unavailable: {error!r}")
+                self._speech = None
+                self._speak = False
+                return False
+        self._speak = True
+        return True
+
+    def _speak_text(self, text: str) -> None:
+        """把台詞念出來（未啟用或失敗時安靜略過）。"""
+        if not self._speak or self._speech is None or not text:
+            return
+        try:
+            self._speech.say(text)
+        except Exception as error:  # pragma: no cover - speech backend guard
+            front_engine_logger.warning(f"[DesktopPetWidget] speech failed: {error!r}")
+
     def _load_messages(self) -> dict:
         d = language_wrapper.language_word_dict
 
@@ -1381,6 +1506,11 @@ class DesktopPetWidget(BaseWidget):
             "away": lines("pet_chatter_away", "Still there?|I'll nap till you're back~|Zzz..."),
             "levelup": lines("pet_chatter_levelup", "Level up!|I'm growing!|We're getting closer!"),
             "costume": lines("pet_chatter_costume", "New look!|How do I look?|Nice fit!"),
+            "fetch": lines("pet_chatter_fetch", "Fetch!|On it!|Opening that for you!"),
+            "focus_start": lines("pet_chatter_focus_start", "Focus time!|Let's concentrate!|I'll wait here."),
+            "focus_break": lines("pet_chatter_focus_break", "Break time!|Stretch a little!|Rest your eyes."),
+            "focus_back": lines("pet_chatter_focus_back", "Back to it!|Round two!|Let's keep going."),
+            "focus_done": lines("pet_chatter_focus_done", "Long break earned!|Great run!|Take a proper rest."),
             "tag": lines("pet_chatter_tag", "You're it!|Caught you!|My turn to chase!"),
             "any": lines("pet_chatter_any", "Hi there!|(^_^)|Keep going!"),
         }
@@ -1488,6 +1618,53 @@ class DesktopPetWidget(BaseWidget):
             return
         self.add_reminder(text.strip(), minutes)
 
+    # --- optional AI chat --------------------------------------------------
+    def set_chat_service(self, service) -> None:
+        """
+        接上 AI 對話服務（None 表示關閉）；服務不可用時右鍵選單不會出現該項目。
+        Attach the AI chat service (None disables it); the menu entry only
+        appears when the service is actually usable.
+        """
+        self._chat_service = service
+        usable = service is not None and bool(getattr(service, "available", lambda: False)())
+        self.chat_action.setVisible(usable)
+
+    def _prompt_chat(self) -> None:
+        """問使用者要說什麼，然後在背景等回覆（不卡 UI）。"""
+        from PySide6.QtWidgets import QInputDialog
+
+        if self._chat_service is None:
+            return
+        title = language_wrapper.language_word_dict.get("pet_chat_menu", "Talk to me...")
+        text, ok = QInputDialog.getText(
+            self, title, language_wrapper.language_word_dict.get("pet_chat_prompt", "Say something:"))
+        if not ok or not text.strip():
+            return
+        self.ask_chat(text.strip())
+
+    def ask_chat(self, message: str) -> None:
+        """送出一句話並在收到回覆時說出來；失敗則說一句抱歉。"""
+        if self._chat_service is None:
+            return
+        self.say(language_wrapper.language_word_dict.get("pet_chat_thinking", "Hmm, let me think..."))
+        self._chat_service.ask_async(message, self.handle_chat_reply)
+
+    def handle_chat_reply(self, reply: Optional[str]) -> None:
+        """處理回覆（可能來自背景執行緒）；空回覆時說一句抱歉。"""
+        if reply:
+            self._pending_chat_reply = reply
+        else:
+            self._pending_chat_reply = language_wrapper.language_word_dict.get(
+                "pet_chat_failed", "I couldn't reach my thoughts just now.")
+        # 回覆可能在背景執行緒抵達，透過計時器回到 UI 執行緒再顯示
+        # The reply may arrive off-thread; hop back to the UI thread to show it.
+        QTimer.singleShot(0, self._say_pending_chat_reply)
+
+    def _say_pending_chat_reply(self) -> None:
+        if self._pending_chat_reply:
+            self.say(self._pending_chat_reply)
+            self._pending_chat_reply = None
+
     def _init_sound(self, sound_path: Optional[str]) -> None:
         if not sound_path:
             return
@@ -1611,6 +1788,7 @@ class DesktopPetWidget(BaseWidget):
             text = pick_message(datetime.now().hour, self._chatter_rng, self._messages, mood=mood)
         if text:
             self._bubble.show_message(text, self)
+            self._speak_text(text)
 
     def _on_tick(self) -> None:
         if self._dragging:
@@ -1687,26 +1865,72 @@ class DesktopPetWidget(BaseWidget):
                 return local_path
         return None
 
+    @staticmethod
+    def dropped_link(mime_data) -> Optional[str]:
+        """
+        從拖曳資料取出網址（拖連結到寵物身上請牠幫忙開啟）；沒有則回傳 None。
+        Pull an http(s) link out of a drop so the pet can open it for you.
+        """
+        if mime_data is None:
+            return None
+        candidates = []
+        if mime_data.hasUrls():
+            candidates += [url.toString() for url in mime_data.urls() if not url.isLocalFile()]
+        if mime_data.hasText():
+            candidates.append(mime_data.text())
+        for candidate in candidates:
+            text = str(candidate or "").strip()
+            # 用網址解析判斷通訊協定，比字串開頭比對穩，也不必在程式碼裡寫死協定前綴。
+            # Parse the URL instead of prefix-matching: sturdier, and no scheme
+            # literals baked into the source.
+            try:
+                scheme = urlparse(text).scheme.lower()
+            except ValueError:
+                continue
+            if scheme in _WEB_SCHEMES:
+                return text
+        return None
+
+    def _accepts_drop(self, mime_data) -> bool:
+        return self.dropped_path(mime_data) is not None or self.dropped_link(mime_data) is not None
+
     def dragEnterEvent(self, event) -> None:
-        if self.dropped_path(event.mimeData()) is not None:
+        if self._accepts_drop(event.mimeData()):
             event.acceptProposedAction()
 
     def dragMoveEvent(self, event) -> None:
-        if self.dropped_path(event.mimeData()) is not None:
+        if self._accepts_drop(event.mimeData()):
             event.acceptProposedAction()
 
     def dropEvent(self, event) -> None:
         path = self.dropped_path(event.mimeData())
-        if path is None:
+        link = self.dropped_link(event.mimeData()) if path is None else None
+        if path is None and link is None:
             return
-        front_engine_logger.info(f"[DesktopPetWidget] dropEvent | path={path}")
+        front_engine_logger.info(f"[DesktopPetWidget] dropEvent | path={path}, link={link}")
         self.motion.wake()
-        if classify_drop(path) == DROP_SPRITE:
+        if link is not None:
+            self.fetch_link(link)
+        elif classify_drop(path) == DROP_SPRITE:
             self.change_sprite(path)
         else:
             self.feed(classify_food(path))
         event.acceptProposedAction()
 
+    def fetch_link(self, url: str) -> None:
+        """把拖進來的連結叼去瀏覽器開啟，並說一句 / Fetch a dropped link in the browser."""
+        from frontengine.utils.browser.browser import open_browser
+
+        front_engine_logger.info(f"[DesktopPetWidget] fetch_link | url={url}")
+        self._gain_affection(1)
+        pool = self._messages.get("fetch") or []
+        if pool:
+            self.say(pool[self._chatter_rng.randrange(len(pool))])
+        try:
+            open_browser(url)
+        except Exception as error:  # pragma: no cover - browser boundary
+            front_engine_logger.warning(f"[DesktopPetWidget] open_browser failed: {error!r}")
+
     def contextMenuEvent(self, event) -> None:
         self.menu.popup(event.globalPos())
 

{frontengine-1.0.29 → frontengine-1.0.31}/frontengine/show/text/draw_text.py

@@ -41,6 +41,11 @@ class TextWidget(BaseWidget):
         self._marquee_timer = QTimer(self)
         self._marquee_timer.timeout.connect(self._tick_marquee)
 
+        # 動態文字來源（時鐘／倒數／系統資訊…）/ Dynamic text source
+        self.text_source = None
+        self._source_timer = QTimer(self)
+        self._source_timer.timeout.connect(self.refresh_text)
+
     def set_font_variable(self, font_size: int = 100) -> None:
         front_engine_logger.info(f"[TextWidget] set_font_variable | font_size={font_size}")
         self.font_size = font_size
@@ -82,6 +87,35 @@ class TextWidget(BaseWidget):
         else:
             self._marquee_timer.stop()
 
+    def set_text_source(self, source) -> None:
+        """
+        接上動態文字來源（TextSource）；靜態來源只取一次文字，不啟動計時器。
+        Attach a dynamic text source; a static one is read once, with no timer.
+        """
+        front_engine_logger.info(f"[TextWidget] set_text_source | kind={getattr(source, 'kind', None)}")
+        self._source_timer.stop()
+        self.text_source = source
+        if source is None:
+            return
+        source.start()
+        self.refresh_text()
+        interval = getattr(source, "refresh_interval_ms", 0)
+        if interval > 0:
+            self._source_timer.start(int(interval))
+
+    def refresh_text(self) -> None:
+        """向來源取一次最新文字並重繪 / Pull the latest text and repaint."""
+        if self.text_source is None:
+            return
+        try:
+            text = self.text_source.text()
+        except Exception as error:  # pragma: no cover - defensive around providers
+            front_engine_logger.warning(f"[TextWidget] text source failed: {error!r}")
+            return
+        if text != self.text:
+            self.text = text
+            self.update()
+
     def _tick_marquee(self) -> None:
         text_width = QFontMetrics(self.draw_font).horizontalAdvance(self.text)
         self.marquee_offset -= self.marquee_speed
@@ -102,6 +136,12 @@ class TextWidget(BaseWidget):
                 self.text,
             )
 
+    def closeEvent(self, event) -> None:
+        for timer in (self._marquee_timer, self._source_timer):
+            if timer.isActive():
+                timer.stop()
+        super().closeEvent(event)
+
     def draw_content(self, painter: QPainter) -> None:
         painter.setFont(self.draw_font)
         if self.outline:

frontengine-1.0.31/frontengine/show/window_helpers.py

@@ -0,0 +1,68 @@
+import os
+from pathlib import Path
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QIcon
+from PySide6.QtWidgets import QWidget
+
+_OVERLAY_BASE_FLAGS = (
+    Qt.WindowType.WindowTransparentForInput
+    | Qt.WindowType.FramelessWindowHint
+    | Qt.WindowType.Tool
+)
+
+
+def apply_overlay_window_flags(
+    widget: QWidget,
+    show_on_bottom: bool = False,
+    allow_input: bool = False,
+) -> None:
+    """
+    Apply the shared "overlay" window flag combination to a widget.
+
+    allow_input=True omits WindowTransparentForInput so the widget can still
+    receive mouse/keyboard (used by the web overlay when the user opts in).
+    """
+    flags = Qt.WindowType.FramelessWindowHint | Qt.WindowType.Tool
+    if not allow_input:
+        flags |= Qt.WindowType.WindowTransparentForInput
+    if show_on_bottom:
+        flags |= Qt.WindowType.WindowStaysOnBottomHint
+    else:
+        flags |= Qt.WindowType.WindowStaysOnTopHint
+    widget.setWindowFlags(flags)
+    # 記住這次的選擇，之後鎖定／解鎖時才能保持同樣的堆疊層級
+    # Remember the choice so lock/unlock keeps the same stacking level.
+    widget.overlay_show_on_bottom = bool(show_on_bottom)
+    widget.overlay_locked = not bool(allow_input)
+
+
+def set_overlay_locked(widget: QWidget, locked: bool) -> bool:
+    """
+    鎖定覆蓋層＝點擊穿透（滑鼠事件直接落到底下的程式）；解鎖＝可以接收滑鼠、
+    用拖曳調整位置。回傳是否真的切換（不可鎖定的覆蓋層如寵物會回傳 False）。
+
+    Locking an overlay makes it click-through so clicks reach whatever is
+    behind it; unlocking lets it take the mouse so it can be dragged into
+    place. Returns False for overlays that opt out of locking (e.g. the pet).
+    """
+    if not getattr(widget, "overlay_lockable", True):
+        return False
+    was_visible = widget.isVisible()
+    apply_overlay_window_flags(
+        widget,
+        show_on_bottom=getattr(widget, "overlay_show_on_bottom", False),
+        allow_input=not locked,
+    )
+    # 變更 window flags 會讓視窗被隱藏，原本看得見的要重新顯示
+    # Changing window flags hides the window, so show it again if it was visible.
+    if was_visible:
+        widget.show()
+    return True
+
+
+def load_overlay_icon(widget: QWidget) -> None:
+    """Set the shared frontengine.ico as the widget's window icon if present."""
+    icon_path = Path(os.getcwd()) / "frontengine.ico"
+    if icon_path.exists() and icon_path.is_file():
+        widget.setWindowIcon(QIcon(str(icon_path)))

{frontengine-1.0.29 → frontengine-1.0.31}/frontengine/ui/dialog/hotkey_settings_dialog.py

@@ -30,6 +30,8 @@ _ACTION_LABELS: Dict[str, Tuple[str, str]] = {
     "mute_all": ("control_center_mute_all", "Mute all"),
     "opacity_up": ("hotkey_opacity_up", "Opacity up"),
     "opacity_down": ("hotkey_opacity_down", "Opacity down"),
+    "dashboard_next": ("web_dashboard_next", "Next page"),
+    "toggle_lock": ("hotkey_toggle_lock", "Lock / unlock overlays"),
 }
 
 

{frontengine-1.0.29 → frontengine-1.0.31}/frontengine/ui/main_ui.py

@@ -321,6 +321,10 @@ class FrontEngineMainUI(QMainWindow):
             self.control_center_ui.step_opacity_all(0.1)
         elif action == "opacity_down":
             self.control_center_ui.step_opacity_all(-0.1)
+        elif action == "dashboard_next":
+            self.web_setting_ui.show_next_dashboard_page()
+        elif action == "toggle_lock":
+            self.control_center_ui.toggle_lock_all()
 
     def _on_fullscreen_changed(self, fullscreen_active: bool) -> None:
         """