frontengine 1.0.28__tar.gz → 1.0.30__tar.gz

{frontengine-1.0.28 → frontengine-1.0.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.28
+Version: 1.0.30
 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.30/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.28 → frontengine-1.0.30}/frontengine/show/pet/desktop_pet.py

@@ -403,14 +403,28 @@ class PetTagGame:
         return self._roles(positions, prey)
 
     def _roles(self, positions: dict, prey) -> dict:
-        """依目前的鬼與獵物組出每個人的角色與要走向的 x。"""
-        it_x, _it_y = positions[self.it]
-        roles = {self.it: (TAG_CHASE, positions[prey][0] if prey is not None else it_x)}
-        for participant, (x, _y) in positions.items():
+        """
+        依目前的鬼與獵物組出每個人的 (角色, 目標 x, 目標 y)。逃跑方向取兩點連線的反向，
+        讓地板模式（只用 x）與飄移／追游標模式（用整個點）都有合理目標。
+        Build each participant's (role, target_x, target_y). Runners head along
+        the line away from "it", which suits floor pets (x only) and wander or
+        chase pets (the whole point) alike.
+        """
+        it_x, it_y = positions[self.it]
+        prey_position = positions[prey] if prey is not None else (it_x, it_y)
+        roles = {self.it: (TAG_CHASE, float(prey_position[0]), float(prey_position[1]))}
+        for participant, (x, y) in positions.items():
             if participant == self.it:
                 continue
-            away = self.flee_distance if x >= it_x else -self.flee_distance
-            roles[participant] = (TAG_FLEE, x + away)
+            dx, dy = x - it_x, y - it_y
+            length = (dx * dx + dy * dy) ** 0.5
+            if length < 1e-9:  # standing on each other: just pick a direction
+                dx, dy, length = 1.0, 0.0, 1.0
+            roles[participant] = (
+                TAG_FLEE,
+                x + self.flee_distance * dx / length,
+                y + self.flee_distance * dy / length,
+            )
         return roles
 
 
@@ -666,6 +680,10 @@ class PetMotion:
         self.ground_feet = 0.0
         # 追向某個 x（用於朝同伴走過去玩耍）/ Horizontal target to walk toward (play).
         self.follow_target_x: Optional[float] = None
+        # 引導目標 (x, y)：三種行為模式都會朝它移動（鬼抓人用），優先於各自的預設動線。
+        # Guidance point (x, y) honoured by every behaviour (used by the tag
+        # game); it takes precedence over each mode's own default movement.
+        self.guidance: Optional[Tuple[float, float]] = None
 
     @property
     def facing_left(self) -> bool:
@@ -713,6 +731,43 @@ class PetMotion:
     def set_target(self, x: float, y: float) -> None:
         self.target = (float(x), float(y))
 
+    def set_guidance(self, x: float, y: Optional[float] = None) -> None:
+        """
+        設定引導目標；地板模式走向該 x，飄移／追游標模式則朝該點移動。
+        Set the guidance point: floor pets walk toward its x, wander and chase
+        pets steer toward the point itself.
+        """
+        centre_y = self.y + self.height / 2.0
+        self.guidance = (float(x), centre_y if y is None else float(y))
+        if self.behaviour == BEHAVIOUR_FLOOR:
+            self.follow_target_x = self.guidance[0]
+
+    def clear_guidance(self) -> None:
+        """取消引導，回到該模式原本的動線 / Drop the guidance and resume normal movement."""
+        self.guidance = None
+        self.follow_target_x = None
+
+    STEER_BLEND = 0.4
+
+    def _steer_toward(self, point: Tuple[float, float]) -> None:
+        """把速度往目標點轉一些（保持速率），轉彎自然而不是瞬間轉向。"""
+        target_x, target_y = point
+        dx = target_x - (self.x + self.width / 2.0)
+        dy = target_y - (self.y + self.height / 2.0)
+        distance = (dx * dx + dy * dy) ** 0.5
+        if distance < 1e-9:
+            return
+        desired_x = self.speed * dx / distance
+        desired_y = self.speed * dy / distance
+        blended_x = self.vx + self.STEER_BLEND * (desired_x - self.vx)
+        blended_y = self.vy + self.STEER_BLEND * (desired_y - self.vy)
+        magnitude = (blended_x * blended_x + blended_y * blended_y) ** 0.5
+        if magnitude < 1e-9:
+            self.vx, self.vy = desired_x, desired_y
+            return
+        self.vx = self.speed * blended_x / magnitude
+        self.vy = self.speed * blended_y / magnitude
+
     def throw(self, vx: float, vy: float) -> None:
         """拖曳放開後以動量丟出（只在重力模式有意義）。"""
         self.vx = float(vx)
@@ -945,6 +1000,8 @@ class PetMotion:
     def _step_wander(self, left, top, right, bottom) -> Tuple[int, int]:
         if abs(self.vy) < 1e-9:
             self.vy = float(self.speed)
+        if self.guidance is not None:
+            self._steer_toward(self.guidance)
         self.x += self.vx
         self.y += self.vy
         if self.x <= left:
@@ -963,14 +1020,19 @@ class PetMotion:
 
     # --- chase cursor ---
     def _step_chase(self, left, top, right, bottom) -> Tuple[int, int]:
-        if self.target is None:
+        # 被引導時（鬼抓人）以引導目標為準，而不是游標
+        # While guided (tag game) the guidance point wins over the cursor.
+        chase_target = self.guidance if self.guidance is not None else self.target
+        if chase_target is None:
             return int(self.x), int(self.y)
-        target_x, target_y = self.target
+        target_x, target_y = chase_target
         dx = target_x - (self.x + self.width / 2)
         dy = target_y - (self.y + self.height / 2)
         distance = (dx * dx + dy * dy) ** 0.5
         if distance <= self.CHASE_STOP_DISTANCE:
-            self.asleep = True
+            # 追到游標會睡著；玩鬼抓人時只是站在對方身上，不睡。
+            # Catching the cursor means a nap; catching a playmate does not.
+            self.asleep = self.guidance is None
             return int(self.x), int(self.y)
         self.asleep = False
         step = float(self.speed) * self.CHASE_SPEED_FACTOR
@@ -1099,8 +1161,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)
@@ -1111,17 +1174,17 @@ class DesktopPetWidget(BaseWidget):
 
     def apply_tag_role(self, role) -> None:
         """
-        套用鬼抓人角色 (角色, 目標 x)；None 代表沒在玩，恢復平常的同伴互動。
+        套用鬼抓人角色 (角色, 目標 x, 目標 y)；None 代表沒在玩，恢復平常的同伴互動。
         Apply a tag role; None means the game is off and normal peer play resumes.
         """
         if role is None:
             if self._tag_role is not None:
                 self._tag_role = None
-                self.motion.clear_follow()
+                self.motion.clear_guidance()
             return
-        self._tag_role, target_x = role
+        self._tag_role, target_x, target_y = role
         self.motion.wake()
-        self.motion.set_follow(target_x)
+        self.motion.set_guidance(target_x, target_y)
 
     def on_tagged(self) -> None:
         """換自己當鬼時喊一句 / Shout when the tag lands on this pet."""

{frontengine-1.0.28 → frontengine-1.0.30}/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.30/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.28 → frontengine-1.0.30}/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.28 → frontengine-1.0.30}/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:
         """

{frontengine-1.0.28 → frontengine-1.0.30}/frontengine/ui/page/control_center/control_center_ui.py

@@ -1,6 +1,7 @@
 from PySide6.QtCore import QTimer, Qt
 from PySide6.QtWidgets import QGridLayout, QWidget, QPushButton, QTextEdit, QScrollArea
 
+from frontengine.show.window_helpers import set_overlay_locked
 from frontengine.ui.color.global_color import error_color, output_color
 from frontengine.ui.page.gif.gif_setting_ui import GIFSettingUI
 from frontengine.ui.page.image.image_setting_ui import ImageSettingUI
@@ -10,6 +11,7 @@ from frontengine.ui.page.sound_player.sound_player_setting_ui import SoundPlayer
 from frontengine.ui.page.text.text_setting_ui import TextSettingUI
 from frontengine.ui.page.video.video_setting_ui import VideoSettingUI
 from frontengine.ui.page.web.web_setting_ui import WEBSettingUI
+from frontengine.user_setting.user_setting_file import clear_overlay_geometry
 from frontengine.utils.logging.loggin_instance import front_engine_logger
 from frontengine.utils.multi_language.language_wrapper import language_wrapper
 from frontengine.utils.redirect_manager.redirect_manager_class import redirect_manager_instance
@@ -74,6 +76,13 @@ class ControlCenterUI(QWidget):
         # 全域不透明度（None 表示尚未使用過）/ Global opacity level (None until first used)
         self._global_opacity = None
         self.mute_all_button = self._create_button("control_center_mute_all", self.toggle_mute_all)
+        # 覆蓋層鎖定（點擊穿透）與綠幕背景 / Overlay lock (click-through) and chroma key
+        self._overlays_locked = True
+        self._chroma_key = False
+        self.lock_all_button = self._create_button("control_center_unlock_all", self.toggle_lock_all)
+        self.chroma_key_button = self._create_button("control_center_chroma_key_on", self.toggle_chroma_key)
+        self.reset_positions_button = self._create_button(
+            "control_center_reset_positions", self.reset_overlay_positions)
         self.clear_all_button = self._create_button("control_center_close_all", self.clear_all)
 
         # Log panel
@@ -96,8 +105,11 @@ class ControlCenterUI(QWidget):
         self.grid_layout.addWidget(self.hide_all_button, 7, 0)
         self.grid_layout.addWidget(self.show_all_button, 8, 0)
         self.grid_layout.addWidget(self.mute_all_button, 9, 0)
-        self.grid_layout.addWidget(self.clear_all_button, 10, 0)
-        self.grid_layout.addWidget(self.log_panel_scroll_area, 0, 1, 11, 1)  # 明確指定 rowSpan=11, colSpan=1
+        self.grid_layout.addWidget(self.lock_all_button, 10, 0)
+        self.grid_layout.addWidget(self.chroma_key_button, 11, 0)
+        self.grid_layout.addWidget(self.reset_positions_button, 12, 0)
+        self.grid_layout.addWidget(self.clear_all_button, 13, 0)
+        self.grid_layout.addWidget(self.log_panel_scroll_area, 0, 1, 14, 1)  # 明確指定 rowSpan, colSpan=1
         self.setLayout(self.grid_layout)
 
         # Redirect
@@ -225,6 +237,59 @@ class ControlCenterUI(QWidget):
         """切換全域靜音狀態 / Toggle the global mute state."""
         self.set_mute_all(not getattr(self, "_muted", False))
 
+    # --- lock / chroma key / positions -----------------------------------
+    CHROMA_KEY_COLOR = "#00ff00"
+
+    def set_lock_all(self, locked: bool) -> None:
+        """
+        鎖定＝所有覆蓋層點擊穿透；解鎖＝可以用滑鼠把覆蓋層拖到想要的位置，
+        放開時位置會被記住。寵物不受影響（它本來就要接收滑鼠）。
+        Locked overlays are click-through; unlocked ones can be dragged into
+        place and remember where they were dropped. The pet is left alone as it
+        needs the mouse either way.
+        """
+        front_engine_logger.info(f"ControlCenterUI set_lock_all | locked={locked}")
+        self._overlays_locked = bool(locked)
+        self._for_each_overlay(lambda widget: set_overlay_locked(widget, self._overlays_locked))
+        self.lock_all_button.setText(
+            language_wrapper.language_word_dict.get(
+                "control_center_unlock_all" if self._overlays_locked else "control_center_lock_all",
+                "Unlock overlays" if self._overlays_locked else "Lock overlays",
+            )
+        )
+
+    def toggle_lock_all(self) -> None:
+        """切換覆蓋層鎖定狀態 / Toggle the overlay lock."""
+        self.set_lock_all(not getattr(self, "_overlays_locked", True))
+
+    def set_chroma_key(self, enabled: bool) -> None:
+        """開關綠幕背景（給 OBS 之類的軟體去背用）。"""
+        front_engine_logger.info(f"ControlCenterUI set_chroma_key | enabled={enabled}")
+        self._chroma_key = bool(enabled)
+        color = self.CHROMA_KEY_COLOR if self._chroma_key else None
+
+        def apply(widget) -> None:
+            setter = getattr(widget, "set_background_color", None)
+            if setter is not None:
+                setter(color)
+
+        self._for_each_overlay(apply)
+        self.chroma_key_button.setText(
+            language_wrapper.language_word_dict.get(
+                "control_center_chroma_key_off" if self._chroma_key else "control_center_chroma_key_on",
+                "Chroma key off" if self._chroma_key else "Chroma key on",
+            )
+        )
+
+    def toggle_chroma_key(self) -> None:
+        """切換綠幕背景 / Toggle the chroma key background."""
+        self.set_chroma_key(not getattr(self, "_chroma_key", False))
+
+    def reset_overlay_positions(self) -> None:
+        """忘掉記住的覆蓋層位置，之後開的覆蓋層回到各自的預設顯示方式。"""
+        front_engine_logger.info("ControlCenterUI reset_overlay_positions")
+        clear_overlay_geometry()
+
     def _sample_overlay_opacity(self) -> float:
         """取一個現有覆蓋層的不透明度作為起始值 / Seed from an existing overlay's opacity."""
         for widget_list in self._all_overlay_widget_lists():