frontengine 1.0.65__tar.gz → 1.0.66__tar.gz

{frontengine-1.0.65 → frontengine-1.0.66}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.65
+Version: 1.0.66
 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.66/frontengine/show/replica/replica_widget.py

@@ -0,0 +1,118 @@
+"""
+視窗複本覆蓋層：一個小視窗，裡面是另一個視窗的即時畫面。
+
+和其他覆蓋層不同，這一個**不能點擊穿透**：使用者要能把它拖到順手的位置、拉大縮小、
+關掉。所以它是一個可以拖曳的無邊框視窗，而不是一層蓋在畫面上的東西。
+
+A window replica overlay: a small window showing another window, live.
+
+Unlike the other overlays this one must **not** pass clicks through: the user has
+to be able to drag it somewhere convenient, resize it and close it. So it is a
+draggable frameless window rather than a sheet laid over the screen.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from PySide6.QtCore import QPoint, Qt
+from PySide6.QtGui import QColor, QPainter
+from PySide6.QtWidgets import QWidget
+
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+from frontengine.utils.window_replica.dwm_thumbnail import (
+    DEFAULT_REPLICA_WIDTH, MIN_REPLICA_SIZE, DwmThumbnail, available, fit_within,
+)
+
+
+class WindowReplicaWidget(QWidget):
+    """顯示另一個視窗即時畫面的小視窗。"""
+
+    def __init__(self, source_handle: int, title: str = "",
+                 opacity_percent: int = 100, parent: Optional[QWidget] = None) -> None:
+        front_engine_logger.info(f"[WindowReplicaWidget] Init | source={source_handle}")
+        super().__init__(parent)
+        self.setAttribute(Qt.WidgetAttribute.WA_DeleteOnClose)
+        self.setWindowFlags(
+            Qt.WindowType.FramelessWindowHint
+            | Qt.WindowType.WindowStaysOnTopHint
+            | Qt.WindowType.Tool)
+        self.setWindowTitle(title or "FrontEngine")
+        self.setMinimumSize(MIN_REPLICA_SIZE, MIN_REPLICA_SIZE)
+
+        self.source_handle = int(source_handle)
+        self.source_title = title
+        self.opacity_percent = max(1, min(100, int(opacity_percent)))
+        self.thumbnail = DwmThumbnail()
+        self._drag_origin: Optional[QPoint] = None
+
+        self.resize(DEFAULT_REPLICA_WIDTH, int(DEFAULT_REPLICA_WIDTH * 9 / 16))
+
+    def start(self) -> bool:
+        """
+        接上來源視窗並依它的長寬比調整大小。接不上就回 False，呼叫端不要把一個
+        空視窗留在畫面上。
+        Attach to the source and take its aspect ratio. False when it could not
+        attach, so the caller does not leave an empty window on screen.
+        """
+        if not available():
+            front_engine_logger.info("[WindowReplicaWidget] not supported on this platform")
+            return False
+        # 縮圖要接在「這個視窗的 handle」上，所以必須先讓它有 handle。
+        # The thumbnail attaches to this window's handle, so it needs one first.
+        self.show()
+        if not self.thumbnail.register(int(self.winId()), self.source_handle):
+            return False
+        source_size = self.thumbnail.source_size()
+        width, height = fit_within(source_size, (DEFAULT_REPLICA_WIDTH,
+                                                 int(DEFAULT_REPLICA_WIDTH * 9 / 16)))
+        self.resize(width, height)
+        self._refresh()
+        return True
+
+    def _refresh(self) -> None:
+        self.thumbnail.update(self.width(), self.height(),
+                              opacity=int(self.opacity_percent * 255 / 100))
+
+    def set_opacity_percent(self, percent: int) -> None:
+        self.opacity_percent = max(1, min(100, int(percent)))
+        self._refresh()
+
+    def resizeEvent(self, event) -> None:
+        super().resizeEvent(event)
+        self._refresh()
+
+    def paintEvent(self, event) -> None:
+        # DWM 把縮圖合成上來之前，先鋪一層不透明底色。少了這一步，來源還沒畫上來的
+        # 那一瞬間會透出後面的東西，看起來像破圖。
+        # An opaque backing before DWM composites the thumbnail. Without it the
+        # moment before the source arrives shows whatever is behind, which reads
+        # as a rendering fault.
+        painter = QPainter(self)
+        painter.fillRect(self.rect(), QColor(0, 0, 0))
+
+    def mousePressEvent(self, event) -> None:
+        if event.button() == Qt.MouseButton.LeftButton:
+            self._drag_origin = event.globalPosition().toPoint() - self.frameGeometry().topLeft()
+            event.accept()
+
+    def mouseMoveEvent(self, event) -> None:
+        if self._drag_origin is not None and event.buttons() & Qt.MouseButton.LeftButton:
+            self.move(event.globalPosition().toPoint() - self._drag_origin)
+            event.accept()
+
+    def mouseReleaseEvent(self, event) -> None:
+        self._drag_origin = None
+        event.accept()
+
+    def mouseDoubleClickEvent(self, event) -> None:
+        """雙擊關掉——沒有標題列，總得有一個看得懂的出口。"""
+        self.close()
+        event.accept()
+
+    def closeEvent(self, event) -> None:
+        # 縮圖是系統資源，視窗沒了也不會自己消失。從標題列以外的任何路徑關閉時
+        # closeEvent 是唯一會被呼叫到的地方，所以收尾放這裡。
+        # The thumbnail is a system resource and does not go away with the
+        # window. closeEvent is the one place every close path reaches.
+        self.thumbnail.unregister()
+        super().closeEvent(event)

frontengine-1.0.66/frontengine/ui/dialog/window_replica_dialog.py

@@ -0,0 +1,124 @@
+"""
+挑一個視窗，開一個顯示它即時畫面的小視窗。
+
+和「釘選視窗」的差別在於原視窗動不動：釘選會把它搬到最上層，複本讓它留在原地。
+Pick a window and open a small one showing it live. The difference from pinning
+is whether the original moves: pinning brings it to the top, a replica leaves it
+where it is.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import (
+    QAbstractItemView, QDialog, QDialogButtonBox, QGridLayout, QLabel, QListWidget,
+    QListWidgetItem, QPushButton, QSlider, QWidget,
+)
+
+from frontengine.show.replica.replica_widget import WindowReplicaWidget
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+from frontengine.utils.multi_language.language_wrapper import language_wrapper
+from frontengine.utils.multi_language.retranslate import retranslator, tr
+from frontengine.utils.window_pin import window_pin
+from frontengine.utils.window_replica.dwm_thumbnail import available
+
+
+def _t(key: str, fallback: str) -> str:
+    return language_wrapper.language_word_dict.get(key, fallback)
+
+
+class WindowReplicaDialog(QDialog):
+    """列出目前的視窗，讓使用者挑一個做成即時複本。"""
+
+    def __init__(self, parent: Optional[QWidget] = None, lister=None,
+                 replica_factory=WindowReplicaWidget) -> None:
+        front_engine_logger.info("[WindowReplicaDialog] Init")
+        super().__init__(parent)
+        self.setWindowTitle(_t("window_replica_title", "Replicate a window"))
+        self._lister = lister or window_pin.list_windows
+        self._replica_factory = replica_factory
+        self.replica_widget_list: List[WindowReplicaWidget] = []
+
+        self.window_list = QListWidget()
+        self.window_list.setSelectionMode(QAbstractItemView.SelectionMode.SingleSelection)
+        self.refresh_button = tr(QPushButton(), "window_replica_refresh", "Refresh")
+        self.refresh_button.clicked.connect(self.reload_windows)
+        self.show_button = tr(QPushButton(), "window_replica_show", "Show replica")
+        self.show_button.clicked.connect(self.start_replica)
+
+        self.opacity_label = tr(QLabel(), "window_replica_opacity", "Opacity")
+        self.opacity_slider = QSlider(Qt.Orientation.Horizontal)
+        self.opacity_slider.setRange(10, 100)
+        self.opacity_slider.setValue(100)
+
+        hint_key, hint_fallback = (
+            ("window_replica_hint",
+             "A second window showing the chosen one live; the original stays where it "
+             "is. Drag the replica to move it, double-click it to close it. Windows only.")
+            if available() else
+            ("window_replica_unsupported", "Window replicas are Windows only."))
+        self.hint_label = QLabel(_t(hint_key, hint_fallback))
+        retranslator.bind(self.hint_label, hint_key, hint_fallback)
+        self.hint_label.setWordWrap(True)
+
+        self.button_box = QDialogButtonBox(QDialogButtonBox.StandardButton.Close)
+        self.button_box.rejected.connect(self.reject)
+
+        layout = QGridLayout(self)
+        layout.addWidget(self.window_list, 0, 0, 1, 2)
+        layout.addWidget(self.refresh_button, 1, 0)
+        layout.addWidget(self.show_button, 1, 1)
+        layout.addWidget(self.opacity_label, 2, 0)
+        layout.addWidget(self.opacity_slider, 2, 1)
+        layout.addWidget(self.hint_label, 3, 0, 1, 2)
+        layout.addWidget(self.button_box, 4, 0, 1, 2)
+
+        self.show_button.setEnabled(available())
+        self.reload_windows()
+
+    def reload_windows(self) -> List[Tuple[int, str]]:
+        """重新抓一次視窗清單。"""
+        self.window_list.clear()
+        windows = self._lister() or []
+        for handle, title in windows:
+            item = QListWidgetItem(title)
+            item.setData(Qt.ItemDataRole.UserRole, int(handle))
+            self.window_list.addItem(item)
+        return windows
+
+    def selected(self) -> Optional[Tuple[int, str]]:
+        """目前選到的 (handle, 標題)；沒選就是 None。"""
+        item = self.window_list.currentItem()
+        if item is None:
+            return None
+        return int(item.data(Qt.ItemDataRole.UserRole)), item.text()
+
+    def start_replica(self) -> Optional[WindowReplicaWidget]:
+        """
+        對選到的視窗開一個複本。接不上就把它收掉再回 None——留一個永遠黑著的
+        小視窗在畫面上，比什麼都不做更糟。
+        Open a replica of the selected window. If it cannot attach, the widget is
+        closed and this returns None: leaving a permanently black window on
+        screen is worse than doing nothing.
+        """
+        chosen = self.selected()
+        if chosen is None:
+            return None
+        handle, title = chosen
+        replica = self._replica_factory(handle, title, self.opacity_slider.value(), None)
+        if not replica.start():
+            front_engine_logger.info(f"[WindowReplicaDialog] could not replicate {title!r}")
+            replica.close()
+            return None
+        self.replica_widget_list.append(replica)
+        return replica
+
+    def close_all(self) -> None:
+        """關掉這個對話框開過的所有複本。"""
+        for replica in list(self.replica_widget_list):
+            try:
+                replica.close()
+            except RuntimeError:  # pragma: no cover - 底層物件已消失
+                pass
+        self.replica_widget_list.clear()

{frontengine-1.0.65 → frontengine-1.0.66}/frontengine/ui/main_ui.py

@@ -888,6 +888,10 @@ class FrontEngineMainUI(QMainWindow):
             self.widgets_setting_ui.stop_spectrum()
         if getattr(self, "tools_setting_ui", None) is not None:
             self.tools_setting_ui.release_pinned_windows()
+            # 複本註冊的是 DWM 縮圖，那是系統資源：視窗沒了也不會自己消失。
+            # A replica holds a DWM thumbnail, a system resource that does not
+            # go away just because the process is closing.
+            self.tools_setting_ui.close_replicas()
             self.tools_setting_ui.stop_camera()
             self.tools_setting_ui.stop_virtual_camera()
 

{frontengine-1.0.65 → frontengine-1.0.66}/frontengine/ui/page/tools/tools_setting_ui.py

@@ -25,6 +25,7 @@ from frontengine.ui.dialog.screen_text_dialog import (
     ScreenTextDialog, ask_for_consent, has_consent,
 )
 from frontengine.ui.dialog.window_pin_dialog import WindowPinDialog
+from frontengine.ui.dialog.window_replica_dialog import WindowReplicaDialog
 from frontengine.user_setting.user_setting_file import user_setting_dict, write_user_setting
 from frontengine.ui.page.utils import coerce_int
 from frontengine.ui.page.layout_kit import SettingPage
@@ -85,6 +86,7 @@ class ToolsSettingUI(SettingPage):
         # raises RuntimeError on touch and "copy last" was a silent no-op.
         self.last_capture: Optional[QPixmap] = None
         self.pin_dialog: Optional[WindowPinDialog] = None
+        self.replica_dialog: Optional[WindowReplicaDialog] = None
 
         self._build_measure_row()
         self._build_capture_row()
@@ -95,6 +97,11 @@ class ToolsSettingUI(SettingPage):
         self.pin_button = tr(QPushButton(), "tools_pin_window", "Pin a window...")
         self.pin_button.clicked.connect(self.open_pin_dialog)
 
+        # 視窗複本：原視窗留在原地，另外開一個小視窗顯示它的即時畫面
+        # Window replica: the original stays put, a small window shows it live
+        self.replica_button = tr(QPushButton(), "tools_replicate_window", "Replicate a window...")
+        self.replica_button.clicked.connect(self.open_replica_dialog)
+
         # 視窗版面：記下每個視窗的位置，之後一鍵擺回去
         # Window layouts: remember where the windows are and put them back later.
         self.layout_label = tr(QLabel(), "tools_layout_label", "Window layout")
@@ -154,7 +161,7 @@ class ToolsSettingUI(SettingPage):
         windows.add_row("tools_name", self.layout_name_edit, "Name")
         windows.add_inline(self.layout_save_button)
         windows.add_row("tools_saved", self.layout_combobox, "Saved")
-        windows.add_inline(self.layout_restore_button, self.pin_button)
+        windows.add_inline(self.layout_restore_button, self.pin_button, self.replica_button)
 
         self.add_body_widget(self.hint_label)
         self.finish_body()
@@ -366,6 +373,20 @@ class ToolsSettingUI(SettingPage):
         self.pin_dialog.exec()
         return self.pin_dialog
 
+    def open_replica_dialog(self) -> WindowReplicaDialog:
+        """開視窗複本對話框（關掉主程式時會把開過的複本收乾淨）。"""
+        self.replica_dialog = WindowReplicaDialog(self)
+        self.replica_dialog.exec()
+        return self.replica_dialog
+
+    def close_replicas(self) -> None:
+        """關掉開過的視窗複本（主程式關閉時呼叫）。"""
+        if self.replica_dialog is not None:
+            try:
+                self.replica_dialog.close_all()
+            except RuntimeError:
+                self.replica_dialog = None
+
     def release_pinned_windows(self) -> None:
         """把釘過的別人視窗放開（主程式關閉時呼叫）。"""
         if self.pin_dialog is not None:

{frontengine-1.0.65 → frontengine-1.0.66}/frontengine/utils/multi_language/english.py

@@ -46,6 +46,13 @@ english_word_dict = {
     "tools_shape": "Shape",
     "tools_name": "Name",
     "tools_saved": "Saved",
+    "tools_replicate_window": "Replicate a window...",
+    "window_replica_title": "Replicate a window",
+    "window_replica_refresh": "Refresh",
+    "window_replica_show": "Show replica",
+    "window_replica_opacity": "Opacity",
+    "window_replica_hint": "A second window showing the chosen one live; the original stays where it is. Drag the replica to move it, double-click it to close it. Windows only.",
+    "window_replica_unsupported": "Window replicas are Windows only.",
     "settings_menu_screensaver": "Screensaver...",
     "screensaver_title": "Screensaver",
     "screensaver_enable": "Show something when idle",

{frontengine-1.0.65 → frontengine-1.0.66}/frontengine/utils/multi_language/france.py

@@ -47,6 +47,13 @@ french_word_dict = {
     "tools_shape": "Forme",
     "tools_name": "Nom",
     "tools_saved": "Enregistrés",
+    "tools_replicate_window": "Dupliquer une fenêtre...",
+    "window_replica_title": "Dupliquer une fenêtre",
+    "window_replica_refresh": "Actualiser",
+    "window_replica_show": "Afficher le duplicata",
+    "window_replica_opacity": "Opacité",
+    "window_replica_hint": "Une seconde fenêtre affiche la fenêtre choisie en direct ; l'originale reste à sa place. Faites glisser pour la déplacer, double-cliquez pour la fermer. Windows uniquement.",
+    "window_replica_unsupported": "Les duplicatas de fenêtre sont réservés à Windows.",
     "settings_menu_screensaver": "Économiseur d'écran...",
     "screensaver_title": "Économiseur d'écran",
     "screensaver_enable": "Afficher quelque chose en cas d'inactivité",

{frontengine-1.0.65 → frontengine-1.0.66}/frontengine/utils/multi_language/germany.py

@@ -47,6 +47,13 @@ germany_word_dict = {
     "tools_shape": "Form",
     "tools_name": "Name",
     "tools_saved": "Gespeichert",
+    "tools_replicate_window": "Fenster duplizieren...",
+    "window_replica_title": "Fenster duplizieren",
+    "window_replica_refresh": "Aktualisieren",
+    "window_replica_show": "Duplikat anzeigen",
+    "window_replica_opacity": "Deckkraft",
+    "window_replica_hint": "Ein zweites Fenster zeigt das gewählte live; das Original bleibt, wo es ist. Ziehen zum Verschieben, Doppelklick zum Schließen. Nur Windows.",
+    "window_replica_unsupported": "Fensterduplikate gibt es nur unter Windows.",
     "settings_menu_screensaver": "Bildschirmschoner...",
     "screensaver_title": "Bildschirmschoner",
     "screensaver_enable": "Bei Untätigkeit etwas anzeigen",

{frontengine-1.0.65 → frontengine-1.0.66}/frontengine/utils/multi_language/italy.py

@@ -47,6 +47,13 @@ italian_word_dict = {
     "tools_shape": "Forma",
     "tools_name": "Nome",
     "tools_saved": "Salvati",
+    "tools_replicate_window": "Duplica una finestra...",
+    "window_replica_title": "Duplica una finestra",
+    "window_replica_refresh": "Aggiorna",
+    "window_replica_show": "Mostra il duplicato",
+    "window_replica_opacity": "Opacità",
+    "window_replica_hint": "Una seconda finestra mostra quella scelta in diretta; l'originale resta dov'è. Trascina per spostarla, doppio clic per chiuderla. Solo Windows.",
+    "window_replica_unsupported": "I duplicati di finestra sono solo per Windows.",
     "settings_menu_screensaver": "Salvaschermo...",
     "screensaver_title": "Salvaschermo",
     "screensaver_enable": "Mostra qualcosa quando sei inattivo",

{frontengine-1.0.65 → frontengine-1.0.66}/frontengine/utils/multi_language/russian.py

@@ -47,6 +47,13 @@ russian_word_dict = {
     "tools_shape": "Форма",
     "tools_name": "Имя",
     "tools_saved": "Сохранённые",
+    "tools_replicate_window": "Копия окна...",
+    "window_replica_title": "Копия окна",
+    "window_replica_refresh": "Обновить",
+    "window_replica_show": "Показать копию",
+    "window_replica_opacity": "Непрозрачность",
+    "window_replica_hint": "Второе окно показывает выбранное вживую, оригинал остаётся на месте. Перетащите, чтобы переместить, двойной щелчок закрывает. Только Windows.",
+    "window_replica_unsupported": "Копии окон работают только в Windows.",
     "settings_menu_screensaver": "Заставка...",
     "screensaver_title": "Заставка",
     "screensaver_enable": "Показывать что-нибудь при простое",

{frontengine-1.0.65 → frontengine-1.0.66}/frontengine/utils/multi_language/simplified_chinese.py

@@ -47,6 +47,13 @@ simplified_chinese_word_dict = {
     "tools_shape": "形状",
     "tools_name": "名称",
     "tools_saved": "已保存",
+    "tools_replicate_window": "窗口副本⋯",
+    "window_replica_title": "窗口副本",
+    "window_replica_refresh": "刷新",
+    "window_replica_show": "显示副本",
+    "window_replica_opacity": "透明度",
+    "window_replica_hint": "另外开一个小窗口显示选定窗口的实时画面，原窗口留在原地不动。拖动可以移动它，双击关闭。仅限 Windows。",
+    "window_replica_unsupported": "窗口副本仅限 Windows。",
     "settings_menu_screensaver": "屏幕保护⋯",
     "screensaver_title": "屏幕保护",
     "screensaver_enable": "空闲时显示东西",

{frontengine-1.0.65 → frontengine-1.0.66}/frontengine/utils/multi_language/traditional_chinese.py

@@ -47,6 +47,13 @@ traditional_chinese_word_dict = {
     "tools_shape": "形狀",
     "tools_name": "名稱",
     "tools_saved": "已儲存",
+    "tools_replicate_window": "視窗複本⋯",
+    "window_replica_title": "視窗複本",
+    "window_replica_refresh": "重新整理",
+    "window_replica_show": "顯示複本",
+    "window_replica_opacity": "透明度",
+    "window_replica_hint": "另外開一個小視窗顯示選定視窗的即時畫面，原視窗留在原地不動。拖曳可以搬動它，連點兩下關閉。僅限 Windows。",
+    "window_replica_unsupported": "視窗複本僅限 Windows。",
     "settings_menu_screensaver": "螢幕保護⋯",
     "screensaver_title": "螢幕保護",
     "screensaver_enable": "閒置時顯示東西",

frontengine-1.0.66/frontengine/utils/window_replica/dwm_thumbnail.py

@@ -0,0 +1,189 @@
+"""
+用 DWM 縮圖做出另一個視窗的即時複本。
+
+這和「釘選視窗」是兩件事：釘選是把**原視窗**搬到最上層，原本在哪就不在哪了；
+複本是另外開一個小視窗顯示它的即時畫面，原視窗留在原地不動。想邊工作邊看影片、
+或盯著背景的編譯進度，要的是後者。
+
+畫面由 DWM 直接合成，不需要抓圖也不需要輪詢，所以更新是即時的而且幾乎不耗 CPU。
+Windows 專屬：其他平台一律回報「做不到」，不假裝成功。
+
+A live replica of another window, via DWM thumbnails.
+
+This is not window pinning. Pinning moves the *real* window to the top, so it is
+no longer where it was; a replica is a second small window showing its live
+picture while the original stays put. Watching a video or a build log while
+working is the second thing.
+
+DWM composites the picture itself - no screen grabbing, no polling - so it is
+live and costs almost nothing. Windows only: every other platform reports "not
+possible" rather than pretending.
+"""
+from __future__ import annotations
+
+import sys
+from typing import Optional, Tuple
+
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+# DWM_THUMBNAIL_PROPERTIES 的旗標 / Flags for DWM_THUMBNAIL_PROPERTIES
+DWM_TNP_RECTDESTINATION = 0x00000001
+DWM_TNP_RECTSOURCE = 0x00000002
+DWM_TNP_OPACITY = 0x00000004
+DWM_TNP_VISIBLE = 0x00000008
+DWM_TNP_SOURCECLIENTAREAONLY = 0x00000010
+
+MIN_REPLICA_SIZE = 80
+DEFAULT_REPLICA_WIDTH = 480
+
+
+def available() -> bool:
+    """這個平台能不能做視窗複本。"""
+    return sys.platform == "win32"
+
+
+def fit_within(source: Tuple[int, int], bounds: Tuple[int, int]) -> Tuple[int, int]:
+    """
+    把來源尺寸等比縮到不超過 bounds，並保持長寬比。
+
+    純算術，所以縮放這件事不必開一個真的視窗才能驗證。來源尺寸拿不到時會是 0，
+    這裡直接回傳 bounds 而不是除以零。
+    Scale the source into `bounds` keeping its aspect ratio. Pure arithmetic, so
+    the scaling can be checked without opening a window. A source size can come
+    back as 0, in which case this returns the bounds rather than dividing by it.
+    """
+    source_width, source_height = source
+    max_width, max_height = bounds
+    if source_width <= 0 or source_height <= 0:
+        return max(MIN_REPLICA_SIZE, max_width), max(MIN_REPLICA_SIZE, max_height)
+    scale = min(max_width / source_width, max_height / source_height)
+    width = max(MIN_REPLICA_SIZE, int(source_width * scale))
+    height = max(MIN_REPLICA_SIZE, int(source_height * scale))
+    return width, height
+
+
+class DwmThumbnail:
+    """
+    一個註冊好的 DWM 縮圖。register() 開始、update() 調整、unregister() 收掉。
+
+    縮圖是系統資源，忘了 unregister 的話 DWM 會一直替一個已經看不到的目的地合成
+    畫面。釋放一律由呼叫端明確做，**沒有** __del__ 兜底：直譯器關閉時的解構順序
+    不保證，那時 ctypes 載入的 dwmapi 可能已經不在，靠它反而是靠一個不會發生的
+    保險。實際的三條路徑是覆蓋層的 closeEvent、對話框的 close_all()、以及主程式
+    關閉時的收尾。
+
+    A registered DWM thumbnail. It is a system resource: forgetting to
+    unregister leaves DWM compositing for a destination nobody can see.
+
+    Releasing is always explicit, with **no** __del__ fallback: destruction order
+    at interpreter shutdown is not guaranteed and the ctypes-loaded dwmapi may
+    already be gone, so relying on it means relying on something that may never
+    run. The three real paths are the overlay's closeEvent, the dialog's
+    close_all(), and the application's own shutdown.
+    """
+
+    def __init__(self) -> None:
+        self._handle: Optional[int] = None
+        self._dwmapi = None
+
+    @property
+    def registered(self) -> bool:
+        return self._handle is not None
+
+    def register(self, destination: int, source: int) -> bool:
+        """把 source 視窗的畫面接到 destination 視窗上。"""
+        if not available():
+            return False
+        self.unregister()
+        try:
+            import ctypes
+            from ctypes import wintypes
+
+            dwmapi = ctypes.windll.dwmapi
+            handle = wintypes.HANDLE()
+            result = dwmapi.DwmRegisterThumbnail(
+                wintypes.HWND(destination), wintypes.HWND(source), ctypes.byref(handle))
+            if result != 0 or not handle.value:
+                front_engine_logger.warning(
+                    f"[DwmThumbnail] register failed | hresult={result}")
+                return False
+            self._dwmapi = dwmapi
+            self._handle = handle.value
+            return True
+        except Exception as error:  # pragma: no cover - Win32 boundary
+            front_engine_logger.warning(f"[DwmThumbnail] register error: {error!r}")
+            return False
+
+    def source_size(self) -> Tuple[int, int]:
+        """來源視窗的原始尺寸；問不到就回 (0, 0)。"""
+        if self._handle is None or self._dwmapi is None:
+            return (0, 0)
+        try:
+            import ctypes
+            from ctypes import wintypes
+
+            class SIZE(ctypes.Structure):
+                _fields_ = [("cx", wintypes.LONG), ("cy", wintypes.LONG)]
+
+            size = SIZE()
+            if self._dwmapi.DwmQueryThumbnailSourceSize(
+                    wintypes.HANDLE(self._handle), ctypes.byref(size)) != 0:
+                return (0, 0)
+            return (int(size.cx), int(size.cy))
+        except Exception as error:  # pragma: no cover - Win32 boundary
+            front_engine_logger.warning(f"[DwmThumbnail] source size error: {error!r}")
+            return (0, 0)
+
+    def update(self, width: int, height: int, opacity: int = 255,
+               client_area_only: bool = True) -> bool:
+        """把縮圖鋪滿目的地視窗的這個大小。"""
+        if self._handle is None or self._dwmapi is None:
+            return False
+        try:
+            import ctypes
+            from ctypes import wintypes
+
+            class RECT(ctypes.Structure):
+                _fields_ = [("left", wintypes.LONG), ("top", wintypes.LONG),
+                            ("right", wintypes.LONG), ("bottom", wintypes.LONG)]
+
+            class DWM_THUMBNAIL_PROPERTIES(ctypes.Structure):
+                _fields_ = [
+                    ("dwFlags", wintypes.DWORD),
+                    ("rcDestination", RECT),
+                    ("rcSource", RECT),
+                    ("opacity", ctypes.c_ubyte),
+                    ("fVisible", wintypes.BOOL),
+                    ("fSourceClientAreaOnly", wintypes.BOOL),
+                ]
+
+            properties = DWM_THUMBNAIL_PROPERTIES()
+            properties.dwFlags = (DWM_TNP_RECTDESTINATION | DWM_TNP_OPACITY
+                                  | DWM_TNP_VISIBLE | DWM_TNP_SOURCECLIENTAREAONLY)
+            properties.rcDestination = RECT(0, 0, max(1, int(width)), max(1, int(height)))
+            properties.opacity = max(0, min(255, int(opacity)))
+            properties.fVisible = True
+            # 只取客戶區：不然複本裡會有一圈原視窗的標題列與邊框，看起來像截圖失誤。
+            # Client area only: otherwise the replica carries the source's title
+            # bar and border, which reads as a botched screenshot.
+            properties.fSourceClientAreaOnly = bool(client_area_only)
+            result = self._dwmapi.DwmUpdateThumbnailProperties(
+                wintypes.HANDLE(self._handle), ctypes.byref(properties))
+            return result == 0
+        except Exception as error:  # pragma: no cover - Win32 boundary
+            front_engine_logger.warning(f"[DwmThumbnail] update error: {error!r}")
+            return False
+
+    def unregister(self) -> None:
+        """收掉縮圖。重複呼叫是安全的。"""
+        if self._handle is None or self._dwmapi is None:
+            self._handle = None
+            return
+        try:
+            from ctypes import wintypes
+
+            self._dwmapi.DwmUnregisterThumbnail(wintypes.HANDLE(self._handle))
+        except Exception as error:  # pragma: no cover - Win32 boundary
+            front_engine_logger.warning(f"[DwmThumbnail] unregister error: {error!r}")
+        finally:
+            self._handle = None

{frontengine-1.0.65 → frontengine-1.0.66}/frontengine.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.65
+Version: 1.0.66
 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.65 → frontengine-1.0.66}/frontengine.egg-info/SOURCES.txt

@@ -42,6 +42,8 @@ frontengine/show/presentation/annotation_overlay.py
 frontengine/show/presentation/cursor_effects.py
 frontengine/show/presentation/keystroke_display.py
 frontengine/show/presentation/magnifier.py
+frontengine/show/replica/__init__.py
+frontengine/show/replica/replica_widget.py
 frontengine/show/scene/__init__.py
 frontengine/show/scene/extend_graphic_scene.py
 frontengine/show/scene/extend_graphic_view.py
@@ -85,6 +87,7 @@ frontengine/ui/dialog/signage_dialog.py
 frontengine/ui/dialog/smart_pause_dialog.py
 frontengine/ui/dialog/usage_report_dialog.py
 frontengine/ui/dialog/window_pin_dialog.py
+frontengine/ui/dialog/window_replica_dialog.py
 frontengine/ui/menu/__init__.py
 frontengine/ui/menu/help_menu.py
 frontengine/ui/menu/how_to_menu.py
@@ -254,5 +257,7 @@ frontengine/utils/weather/weather_service.py
 frontengine/utils/window_pin/__init__.py
 frontengine/utils/window_pin/window_layout.py
 frontengine/utils/window_pin/window_pin.py
+frontengine/utils/window_replica/__init__.py
+frontengine/utils/window_replica/dwm_thumbnail.py
 frontengine/utils/workshop/__init__.py
 frontengine/utils/workshop/workshop_content.py