frontengine 1.0.73__tar.gz → 1.0.74__tar.gz

{frontengine-1.0.73 → frontengine-1.0.74}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frontengine
-Version: 1.0.73
+Version: 1.0.74
 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.74/frontengine/show/reference/reference_board.py

@@ -0,0 +1,155 @@
+"""
+參考圖板：一塊畫布上放好幾張圖，各自可以搬動，整塊可以縮放平移。
+
+和「圖片覆蓋層」的差別是數量與擺法：覆蓋層是把一張圖固定在某個位置當背景，圖板
+是把一疊參考資料攤開來排在手邊——畫圖的、做設計的、對著規格寫程式的都在做這件事。
+
+視圖行為（無邊框、置頂、透明、滾輪縮放、拖曳平移）沿用場景功能的
+`ExtendGraphicView`，這裡只負責「放什麼進去、一開始怎麼排」。
+
+A reference board: several images on one canvas, each movable, the whole thing
+zoomable and pannable.
+
+It differs from the image overlay in number and arrangement: the overlay fixes one
+picture in place as a backdrop, while a board spreads a pile of references out
+within reach - what illustrators, designers and anyone coding against a
+specification actually do.
+
+The view behaviour - frameless, on top, transparent, wheel zoom, drag to pan -
+comes from the scene feature's `ExtendGraphicView`; this only decides what goes on
+it and how it is laid out to begin with.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Sequence, Tuple
+
+from PySide6.QtCore import Qt
+from PySide6.QtGui import QPixmap
+from PySide6.QtWidgets import QGraphicsPixmapItem, QGraphicsScene
+
+from frontengine.show.scene.extend_graphic_view import ExtendGraphicView
+from frontengine.utils.logging.loggin_instance import front_engine_logger
+
+BOARD_EXTENSIONS = (".png", ".jpg", ".jpeg", ".webp", ".bmp", ".gif")
+DEFAULT_COLUMNS = 3
+DEFAULT_ITEM_SIZE = 320
+ITEM_GAP = 24
+
+
+def columns_for(count: int, preferred: int = DEFAULT_COLUMNS) -> int:
+    """
+    幾張圖排幾欄。張數比預設欄數少時就照張數排，免得三張圖被排成一欄兩列、
+    右邊空一大塊。
+    How many columns for this many images. Fewer images than the preferred column
+    count simply use their own number, so three pictures are not laid out as a
+    row of two with a gap beside them.
+    """
+    count = max(0, int(count))
+    if count == 0:
+        return 0
+    return max(1, min(int(preferred), count))
+
+
+def grid_positions(count: int, item_size: int = DEFAULT_ITEM_SIZE,
+                   columns: int = DEFAULT_COLUMNS,
+                   gap: int = ITEM_GAP) -> List[Tuple[int, int]]:
+    """
+    一開始把圖排成網格的座標。純算術，所以排版不必開視窗就能驗。
+
+    先排好再讓使用者自己搬：全部疊在原點的話，開起來看到的是一張圖，其他幾張都
+    藏在下面，使用者會以為只載入了一張。
+    The initial grid coordinates. Pure arithmetic, so the layout can be checked
+    without a window.
+
+    They are arranged before the user rearranges them: stacked at the origin, the
+    board would open showing one picture with the rest hidden underneath, and it
+    would look as though only one had loaded.
+    """
+    count = max(0, int(count))
+    if count == 0:
+        return []
+    column_count = columns_for(count, columns)
+    step = max(1, int(item_size)) + max(0, int(gap))
+    return [((index % column_count) * step, (index // column_count) * step)
+            for index in range(count)]
+
+
+def readable_images(paths: Sequence[str]) -> List[str]:
+    """
+    留下副檔名認得、而且真的讀得進來的圖。
+
+    壞掉或不是圖片的檔案要在這裡就擋下來：讓 QPixmap 靜靜產生一張空圖的話，圖板
+    上會出現一塊看不見的空白，使用者只會覺得「有一張圖不見了」。
+    Keep the files whose suffix is known and that actually load.
+
+    A broken or non-image file is dropped here: letting QPixmap quietly produce a
+    null pixmap puts an invisible blank on the board, and all the user sees is
+    that one of their pictures is missing.
+    """
+    kept = []
+    for path in paths or ():
+        try:
+            candidate = Path(str(path))
+            if candidate.suffix.lower() not in BOARD_EXTENSIONS:
+                continue
+            if not candidate.is_file():
+                continue
+        except OSError:  # pragma: no cover - filesystem boundary
+            continue
+        if QPixmap(str(candidate)).isNull():
+            front_engine_logger.info(f"[ReferenceBoard] skipped unreadable image: {candidate}")
+            continue
+        kept.append(str(candidate))
+    return kept
+
+
+class ReferenceBoardWidget(ExtendGraphicView):
+    """好幾張參考圖放在同一塊畫布上，各自可以搬動。"""
+
+    def __init__(self, item_size: int = DEFAULT_ITEM_SIZE, columns: int = DEFAULT_COLUMNS):
+        front_engine_logger.info("[ReferenceBoardWidget] Init")
+        self.board_scene = QGraphicsScene()
+        super().__init__(self.board_scene)
+        self.item_size = max(64, int(item_size))
+        self.columns = max(1, int(columns))
+        self.items: List[QGraphicsPixmapItem] = []
+
+    def add_images(self, paths: Sequence[str]) -> int:
+        """把圖加進圖板並排好，回傳實際加進去的張數。"""
+        usable = readable_images(paths)
+        positions = grid_positions(len(usable), self.item_size, self.columns)
+        for path, (x, y) in zip(usable, positions):
+            pixmap = QPixmap(path).scaled(
+                self.item_size, self.item_size,
+                Qt.AspectRatioMode.KeepAspectRatio,
+                Qt.TransformationMode.SmoothTransformation)
+            item = QGraphicsPixmapItem(pixmap)
+            # 每張圖各自可以搬：圖板的用途就是把它們排成自己看得順的位置。
+            # Each picture moves on its own: arranging them is the whole point.
+            item.setFlag(QGraphicsPixmapItem.GraphicsItemFlag.ItemIsMovable, True)
+            item.setFlag(QGraphicsPixmapItem.GraphicsItemFlag.ItemIsSelectable, True)
+            item.setPos(x, y)
+            self.board_scene.addItem(item)
+            self.items.append(item)
+        front_engine_logger.info(f"[ReferenceBoardWidget] added {len(usable)} of {len(paths or ())}")
+        return len(usable)
+
+    def remove_selected(self) -> int:
+        """把選起來的圖從圖板上拿掉，回傳拿掉幾張。"""
+        removed = 0
+        for item in list(self.items):
+            if item.isSelected():
+                self.board_scene.removeItem(item)
+                self.items.remove(item)
+                removed += 1
+        return removed
+
+    def keyPressEvent(self, event) -> None:
+        if event.key() == Qt.Key.Key_Escape:
+            self.close()
+            return
+        if event.key() in (Qt.Key.Key_Delete, Qt.Key.Key_Backspace):
+            self.remove_selected()
+            return
+        super().keyPressEvent(event)

{frontengine-1.0.73 → frontengine-1.0.74}/frontengine/ui/main_ui.py

@@ -402,6 +402,10 @@ class FrontEngineMainUI(QMainWindow):
                           "pinned_widget_list"):
             self.control_center_ui.register_overlay_source(
                 lambda attribute=attribute: getattr(self.tools_setting_ui, attribute, []))
+        # 參考圖板也要進控制中心，否則「全部關閉」關不掉它
+        # The reference boards belong here too, or "close all" cannot reach them
+        self.control_center_ui.register_overlay_source(
+            lambda: getattr(self.image_setting_ui, "board_widget_list", []))
 
     # 螢幕保護能顯示哪些分頁：來源名稱 -> (頁面屬性, 啟動方法, 覆蓋層清單屬性)
     # What the screensaver can show: source -> (page attribute, start method,

{frontengine-1.0.73 → frontengine-1.0.74}/frontengine/ui/page/image/image_setting_ui.py

@@ -6,6 +6,7 @@ from PySide6.QtWidgets import (
 )
 
 from frontengine.show.image.paint_image import ImageWidget
+from frontengine.show.reference.reference_board import ReferenceBoardWidget
 from frontengine.ui.dialog.choose_file_dialog import choose_image
 from frontengine.ui.page.layout_kit import SettingPage
 from frontengine.ui.page.utils import (
@@ -97,6 +98,21 @@ class ImageSettingUI(SettingPage):
         self.slideshow_interval_combobox.addItems(["3", "5", "10", "15", "30", "60"])
         self.slideshow_interval_combobox.setCurrentText("5")
         self.slideshow_shuffle_checkbox = tr(QCheckBox(), "slideshow_shuffle", "Shuffle")
+        # 參考圖板：好幾張圖攤在同一塊畫布上，各自可以搬動
+        # Reference board: several pictures on one canvas, each movable
+        self.board_widget_list: list = []
+        self.board_choose_button = tr(QPushButton(), "image_board_choose",
+                                      "Open reference board...")
+        self.board_choose_button.clicked.connect(self.open_reference_board)
+        self.board_close_button = tr(QPushButton(), "image_board_close", "Close boards")
+        self.board_close_button.clicked.connect(self.close_reference_boards)
+        self.board_hint_label = tr(
+            QLabel(), "image_board_hint",
+            "Pick several pictures at once. Drag each one to arrange it, drag the "
+            "background to pan, scroll to zoom, Delete removes the selected one and "
+            "Escape closes the board.")
+        self.board_hint_label.setWordWrap(True)
+
         self.slideshow_recursive_checkbox = tr(QCheckBox(), "slideshow_recursive",
             "Include subfolders")
 
@@ -117,6 +133,10 @@ class ImageSettingUI(SettingPage):
         slideshow.add_row(self.slideshow_interval_label, self.slideshow_interval_combobox)
         slideshow.add_inline(self.slideshow_shuffle_checkbox, self.slideshow_recursive_checkbox)
 
+        board = self.add_section("image_board_label", "Reference board")
+        board.add_inline(self.board_choose_button, self.board_close_button)
+        board.add_widget(self.board_hint_label)
+
         where = self.add_section("section_where", "Where")
         where.add_row(self.target_monitor_label, self.target_monitor_combobox)
         where.add_inline(self.show_on_all_screen_checkbox, self.show_on_bottom_checkbox,
@@ -125,6 +145,38 @@ class ImageSettingUI(SettingPage):
         self.finish_body()
         self.set_footer(primary=self.start_button, status=self.ready_label)
 
+    def open_reference_board(self):
+        """
+        挑幾張圖開一塊參考圖板。一張都沒挑就不要開空白畫布——那看起來像壞掉。
+        Open a board from several chosen pictures. Nothing chosen opens nothing:
+        an empty canvas reads as a fault.
+        """
+        paths, _ = QFileDialog.getOpenFileNames(
+            self,
+            language_wrapper.language_word_dict.get("image_board_choose", "Open reference board..."),
+            "",
+            "Images (*.png *.jpg *.jpeg *.webp *.bmp *.gif)")
+        if not paths:
+            return None
+        board = ReferenceBoardWidget()
+        if board.add_images(paths) == 0:
+            # 全部讀不進來就不要留一塊空畫布在畫面上。
+            # With nothing readable, do not leave an empty canvas on screen.
+            board.close()
+            return None
+        board.showMaximized()
+        self.board_widget_list.append(board)
+        return board
+
+    def close_reference_boards(self) -> None:
+        """關掉開過的參考圖板。"""
+        for board in list(self.board_widget_list):
+            try:
+                board.close()
+            except RuntimeError:  # pragma: no cover - 底層物件已消失
+                pass
+        self.board_widget_list.clear()
+
     def set_show_all_screen(self) -> None:
         front_engine_logger.info("[ImageSettingUI] set_show_all_screen")
         self.show_all_screen = self.show_on_all_screen_checkbox.isChecked()

{frontengine-1.0.73 → frontengine-1.0.74}/frontengine/utils/multi_language/english.py

@@ -171,6 +171,10 @@ english_word_dict = {
     "web_setting_open_enable_input": "Enable input",
     # Scene UI
     "tab_scene_text": "Scene",
+    "image_board_label": "REFERENCE BOARD",
+    "image_board_choose": "Open reference board...",
+    "image_board_close": "Close boards",
+    "image_board_hint": "Pick several pictures at once. Drag each one to arrange it, drag the background to pan, scroll to zoom, Delete removes the selected one and Escape closes the board.",
     "scene_start": "Start scene",
     "scene_table_view_type": "Type",
     "scene_file_path": "File path",

{frontengine-1.0.73 → frontengine-1.0.74}/frontengine/utils/multi_language/france.py

@@ -171,6 +171,10 @@ french_word_dict = {
     "web_setting_open_enable_input": "Activer l'entrée",
     # Scene UI
     "tab_scene_text": "Scène",
+    "image_board_label": "PLANCHE DE RÉFÉRENCE",
+    "image_board_choose": "Ouvrir une planche...",
+    "image_board_close": "Fermer les planches",
+    "image_board_hint": "Choisissez plusieurs images à la fois. Faites glisser chacune pour l'arranger, le fond pour vous déplacer, la molette pour zoomer ; Suppr retire l'image sélectionnée et Échap ferme la planche.",
     "scene_start": "Commencer la scène",
     "scene_table_view_type": "Type",
     "scene_file_path": "Chemin du fichier",

{frontengine-1.0.73 → frontengine-1.0.74}/frontengine/utils/multi_language/germany.py

@@ -171,6 +171,10 @@ germany_word_dict = {
     "web_setting_open_enable_input": "Eingabe aktivieren",
     # Szenen-UI
     "tab_scene_text": "Szene",
+    "image_board_label": "REFERENZTAFEL",
+    "image_board_choose": "Referenztafel öffnen...",
+    "image_board_close": "Tafeln schließen",
+    "image_board_hint": "Mehrere Bilder auf einmal wählen. Einzelne ziehen zum Anordnen, den Hintergrund ziehen zum Verschieben, Mausrad zum Zoomen, Entf entfernt das gewählte Bild, Escape schließt die Tafel.",
     "scene_start": "Szene starten",
     "scene_table_view_type": "Typ",
     "scene_file_path": "Dateipfad",

{frontengine-1.0.73 → frontengine-1.0.74}/frontengine/utils/multi_language/italy.py

@@ -171,6 +171,10 @@ italian_word_dict = {
     "web_setting_open_enable_input": "Abilita input",
     # Scene UI
     "tab_scene_text": "Scena",
+    "image_board_label": "TAVOLA DI RIFERIMENTO",
+    "image_board_choose": "Apri tavola di riferimento...",
+    "image_board_close": "Chiudi le tavole",
+    "image_board_hint": "Scegli più immagini insieme. Trascina ciascuna per disporla, trascina lo sfondo per spostarti, rotellina per lo zoom, Canc toglie quella selezionata ed Esc chiude la tavola.",
     "scene_start": "Inizia la scena",
     "scene_table_view_type": "Tipo",
     "scene_file_path": "Percorso del file",

{frontengine-1.0.73 → frontengine-1.0.74}/frontengine/utils/multi_language/russian.py

@@ -171,6 +171,10 @@ russian_word_dict = {
     "web_setting_open_enable_input": "Включить ввод",
     # Scene UI
     "tab_scene_text": "Сцена",
+    "image_board_label": "ДОСКА РЕФЕРЕНСОВ",
+    "image_board_choose": "Открыть доску референсов...",
+    "image_board_close": "Закрыть доски",
+    "image_board_hint": "Выберите сразу несколько изображений. Перетаскивайте каждое, чтобы расставить, фон - чтобы сдвинуть вид, колесо - масштаб; Delete убирает выбранное, Escape закрывает доску.",
     "scene_start": "Начать сцену",
     "scene_table_view_type": "Тип",
     "scene_file_path": "Путь файла",

{frontengine-1.0.73 → frontengine-1.0.74}/frontengine/utils/multi_language/simplified_chinese.py

@@ -171,6 +171,10 @@ simplified_chinese_word_dict = {
     "web_setting_open_enable_input": "启用输入",
     # Scene UI
     "tab_scene_text": "场景",
+    "image_board_label": "参考图板",
+    "image_board_choose": "打开参考图板⋯",
+    "image_board_close": "关闭图板",
+    "image_board_hint": "一次挑多张图。拖动单张可以排位置，拖背景可以平移，滚轮缩放，Delete 移除选中的那张，Escape 关闭图板。",
     "scene_start": "开始场景",
     "scene_table_view_type": "类型",
     "scene_file_path": "文件路径",

{frontengine-1.0.73 → frontengine-1.0.74}/frontengine/utils/multi_language/traditional_chinese.py

@@ -171,6 +171,10 @@ traditional_chinese_word_dict = {
     "web_setting_open_enable_input": "啟用輸入",
     # Scene UI
     "tab_scene_text": "場景",
+    "image_board_label": "參考圖板",
+    "image_board_choose": "開啟參考圖板⋯",
+    "image_board_close": "關閉圖板",
+    "image_board_hint": "一次挑多張圖。拖曳單張可以排位置，拖背景可以平移，滾輪縮放，Delete 移除選取的那張，Escape 關閉圖板。",
     "scene_start": "開始場景",
     "scene_table_view_type": "類型",
     "scene_file_path": "檔案路徑",

{frontengine-1.0.73 → frontengine-1.0.74}/frontengine.egg-info/PKG-INFO

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

@@ -45,6 +45,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/reference/__init__.py
+frontengine/show/reference/reference_board.py
 frontengine/show/replica/__init__.py
 frontengine/show/replica/replica_widget.py
 frontengine/show/scene/__init__.py

{frontengine-1.0.73 → frontengine-1.0.74}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "frontengine"
-version = "1.0.73"
+version = "1.0.74"
 authors = [
     { name = "JE-Chen", email = "jechenmailman@gmail.com" },
 ]