pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk/gui/visual/qt_dialog_chrome.py

@@ -0,0 +1,337 @@
+"""Reusable frameless chrome for every PyCForge dialog.
+
+The titlebar exposes a deliberately empty toolbar host. Future dialog-specific
+icon actions can be added there without replacing the drag surface or window
+controls.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import QEvent, QObject, QPoint, QRect, QSize, Qt, QTimer
+from PySide6.QtWidgets import (
+    QDialog,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QSizePolicy,
+    QVBoxLayout,
+    QWidget,
+    QAbstractButton,
+)
+
+from .qt_icons import load_pycforge_icon
+from .qt_branding import BrandElidedLabel
+from .qt_window_chrome import _ResizeHandle, _WindowControlButton
+
+
+class DialogTitleBar(QFrame):
+    """Accessible drag surface with an extensible icon-toolbar slot."""
+
+    def __init__(self, controller: "DialogWindowChrome") -> None:
+        super().__init__(controller.dialog)
+        self.controller = controller
+        self.setObjectName("DialogTitleBar")
+        self.setProperty("dialogChrome", True)
+        self.setMinimumHeight(38)
+        self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Fixed)
+        self.setAccessibleName("Dialog title and controls")
+        self.setAccessibleDescription("Drag to move the dialog." + (
+            " Double-click to maximize or restore." if controller.maximizable else ""
+        ))
+
+        layout = QHBoxLayout(self)
+        layout.setDirection(QHBoxLayout.Direction.LeftToRight)
+        layout.setContentsMargins(10, 3, 0, 3)
+        layout.setSpacing(7)
+        self.brand = QLabel()
+        self.brand.setObjectName("DialogTitleBrand")
+        self.brand.setPixmap(controller.dialog.windowIcon().pixmap(
+            QSize(22, 22), self.devicePixelRatioF()))
+        self.brand.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents, True)
+        layout.addWidget(self.brand)
+
+        self.title = BrandElidedLabel(controller.dialog.windowTitle(), mode=Qt.TextElideMode.ElideRight)
+        self.title.setObjectName("DialogTitleText")
+        self.title.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents, True)
+        self.title.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)
+        layout.addWidget(self.title, 1)
+
+        self.toolbar_host = QWidget()
+        self.toolbar_host.setObjectName("DialogTitleToolbar")
+        self.toolbar_host.setAccessibleName("Dialog titlebar tools")
+        self.toolbar_layout = QHBoxLayout(self.toolbar_host)
+        self.toolbar_layout.setContentsMargins(0, 0, 4, 0)
+        self.toolbar_layout.setSpacing(2)
+        layout.addWidget(self.toolbar_host)
+
+        self.maximize_button = None
+        if controller.maximizable:
+            self.maximize_button = _WindowControlButton(
+                "maximize",
+                "Maximize dialog",
+                "Maximize this PyCForge dialog",
+                controller.toggle_maximized,
+                self,
+            )
+            layout.addWidget(self.maximize_button)
+        self.close_button = _WindowControlButton(
+            "close",
+            "Close dialog",
+            "Close this PyCForge dialog",
+            controller.dialog.reject,
+            self,
+        )
+        layout.addWidget(self.close_button)
+
+    def add_toolbar_widget(self, widget: QWidget) -> None:
+        """Place action buttons left and passive title information in its host."""
+
+        if isinstance(widget, QAbstractButton):
+            self.add_left_toolbar_widget(widget)
+        else:
+            self.toolbar_layout.addWidget(widget)
+
+    def add_left_toolbar_widget(self, widget: QWidget) -> None:
+        """Place a dialog-specific action before the title and brand mark."""
+        self.layout().insertWidget(0, widget)
+
+    def sync_title(self) -> None:
+        title = self.controller.dialog.windowTitle()
+        self.title.set_full_text(title)
+        self.title.setToolTip(title)
+        self.title.setAccessibleDescription(title)
+
+    def sync_window_state(self) -> None:
+        if self.maximize_button is None:
+            return
+        if self.controller.dialog.isMaximized():
+            self.maximize_button.set_kind(
+                "restore", "Restore dialog", "Restore this PyCForge dialog"
+            )
+        else:
+            self.maximize_button.set_kind(
+                "maximize", "Maximize dialog", "Maximize this PyCForge dialog"
+            )
+
+    def mouseDoubleClickEvent(self, event) -> None:  # noqa: N802 - Qt API
+        if event.button() == Qt.MouseButton.LeftButton and self.controller.maximizable:
+            self.controller.toggle_maximized()
+            event.accept()
+            return
+        super().mouseDoubleClickEvent(event)
+
+    def mousePressEvent(self, event) -> None:  # noqa: N802 - Qt API
+        if event.button() == Qt.MouseButton.LeftButton:
+            self.controller.begin_move(self, event.globalPosition().toPoint())
+            event.accept()
+            return
+        super().mousePressEvent(event)
+
+    def mouseMoveEvent(self, event) -> None:  # noqa: N802 - Qt API
+        if self.controller.continue_move(event.globalPosition().toPoint()):
+            event.accept()
+            return
+        super().mouseMoveEvent(event)
+
+    def mouseReleaseEvent(self, event) -> None:  # noqa: N802 - Qt API
+        if self.controller.finish_move():
+            event.accept()
+            return
+        super().mouseReleaseEvent(event)
+
+
+class DialogWindowChrome(QObject):
+    """Own frameless dialog movement, resizing, and title synchronization."""
+
+    def __init__(self, dialog: QDialog, layout: QVBoxLayout, *, resizable: bool,
+                 maximizable: bool = False) -> None:
+        super().__init__(dialog)
+        self.dialog = dialog
+        # ``_ResizeHandle`` is shared with the main-window chrome and expects
+        # its controller to expose the controlled top-level as ``window``.
+        self.window = dialog
+        self.resizable = bool(resizable)
+        if maximizable and not self.resizable:
+            raise ValueError("A maximizable dialog must also be resizable")
+        self.maximizable = bool(maximizable)
+        self._manual_move: tuple[QPoint, QPoint] | None = None
+        self._manual_surface: QWidget | None = None
+        self._initial_focus_target: QWidget | None = None
+        self._focus_timer = QTimer(self)
+        self._focus_timer.setSingleShot(True)
+        self._focus_timer.timeout.connect(self._restore_initial_focus)
+        dialog.setWindowFlag(Qt.WindowType.FramelessWindowHint, True)
+        dialog.setWindowFlag(Qt.WindowType.WindowMaximizeButtonHint, self.maximizable)
+        dialog.setWindowFlag(Qt.WindowType.WindowMinimizeButtonHint, False)
+        dialog.setWindowFlag(Qt.WindowType.NoDropShadowWindowHint, False)
+        dialog.setAttribute(Qt.WidgetAttribute.WA_StyledBackground, True)
+        if dialog.windowIcon().isNull():
+            dialog.setWindowIcon(load_pycforge_icon("brand-mark"))
+        try:
+            dialog.setSizeGripEnabled(False)
+        except AttributeError:
+            pass
+        self.title_bar = DialogTitleBar(self)
+        layout.insertWidget(0, self.title_bar)
+        dialog.installEventFilter(self)
+        self.resize_handles = self._build_resize_handles() if self.resizable else ()
+        self._sync_handles()
+
+    def eventFilter(self, watched, event) -> bool:  # noqa: N802 - Qt API
+        if watched is not getattr(self, "dialog", None):
+            return False
+        event_type = event.type()
+        if event_type == QEvent.Type.WindowTitleChange:
+            self.title_bar.sync_title()
+        elif event_type in {QEvent.Type.Hide, QEvent.Type.WindowDeactivate}:
+            for button in (self.title_bar.close_button, self.title_bar.maximize_button):
+                if button is not None:
+                    button.clear_pointer_state()
+        elif event_type in {
+            QEvent.Type.Resize,
+            QEvent.Type.Show,
+            QEvent.Type.WindowStateChange,
+        }:
+            self.title_bar.sync_window_state()
+            self._sync_handles()
+            if event_type == QEvent.Type.Show:
+                if not self.resizable:
+                    # Constructors finish their screen-aware layout before Show.
+                    # Compact prompts have neither resize handles nor an OS
+                    # resize path; content-rich dialogs opt in independently.
+                    self.dialog.setFixedSize(self.dialog.size())
+                # A frameless title control is inserted before the dialog body
+                # in the focus chain.  Windows can therefore restore focus to
+                # that control and leave its hover-equivalent underline lit.
+                # Defer until Qt completes activation, then restore the
+                # dialog-owned content target only when chrome owns focus.
+                self._focus_timer.start(0)
+        return False
+
+    def set_initial_focus_target(self, target: QWidget) -> None:
+        """Keep first/reopened focus in dialog content, not titlebar chrome."""
+
+        if not isinstance(target, QWidget):
+            raise TypeError("initial dialog focus target must be a QWidget")
+        if target.window() is not self.dialog:
+            raise ValueError("initial dialog focus target must belong to the dialog")
+        if target.focusPolicy() == Qt.FocusPolicy.NoFocus:
+            raise ValueError("initial dialog focus target must accept focus")
+        self._initial_focus_target = target
+        target.setFocus(Qt.FocusReason.ActiveWindowFocusReason)
+
+    def _restore_initial_focus(self) -> None:
+        target = self._initial_focus_target
+        if target is None or not self.dialog.isVisible():
+            return
+        focused = self.dialog.focusWidget()
+        controls = {
+            self.title_bar.maximize_button,
+            self.title_bar.close_button,
+        }
+        if focused is None or focused in controls:
+            target.setFocus(Qt.FocusReason.ActiveWindowFocusReason)
+
+    def toggle_maximized(self) -> None:
+        if not self.maximizable:
+            return
+        self.dialog.showNormal() if self.dialog.isMaximized() else self.dialog.showMaximized()
+        self.title_bar.sync_window_state()
+        self._sync_handles()
+
+    def begin_move(self, surface: QWidget, global_position: QPoint) -> None:
+        handle = self.dialog.windowHandle()
+        if handle is not None:
+            try:
+                if handle.startSystemMove():
+                    return
+            except (AttributeError, RuntimeError):
+                pass
+        self._manual_move = (global_position, self.dialog.frameGeometry().topLeft())
+        self._manual_surface = surface
+        surface.grabMouse()
+
+    def continue_move(self, global_position: QPoint) -> bool:
+        if self._manual_move is None:
+            return False
+        start, origin = self._manual_move
+        self.dialog.move(origin + global_position - start)
+        return True
+
+    def finish_move(self) -> bool:
+        if self._manual_move is None:
+            return False
+        surface = self._manual_surface
+        self._manual_move = None
+        self._manual_surface = None
+        if surface is not None:
+            surface.releaseMouse()
+        return True
+
+    def start_system_resize(self, edges: Qt.Edge) -> bool:
+        if not self.resizable or self.dialog.isMaximized():
+            return False
+        handle = self.dialog.windowHandle()
+        if handle is None:
+            return False
+        try:
+            return bool(handle.startSystemResize(edges))
+        except (AttributeError, RuntimeError):
+            return False
+
+    def _build_resize_handles(self) -> tuple[_ResizeHandle, ...]:
+        left, right = Qt.Edge.LeftEdge, Qt.Edge.RightEdge
+        top, bottom = Qt.Edge.TopEdge, Qt.Edge.BottomEdge
+        specs = (
+            ("left edge", left, Qt.CursorShape.SizeHorCursor),
+            ("right edge", right, Qt.CursorShape.SizeHorCursor),
+            ("top edge", top, Qt.CursorShape.SizeVerCursor),
+            ("bottom edge", bottom, Qt.CursorShape.SizeVerCursor),
+            ("top-left corner", top | left, Qt.CursorShape.SizeFDiagCursor),
+            ("top-right corner", top | right, Qt.CursorShape.SizeBDiagCursor),
+            ("bottom-left corner", bottom | left, Qt.CursorShape.SizeBDiagCursor),
+            ("bottom-right corner", bottom | right, Qt.CursorShape.SizeFDiagCursor),
+        )
+        return tuple(_ResizeHandle(self, *spec) for spec in specs)
+
+    def _sync_handles(self) -> None:
+        if not self.resize_handles:
+            return
+        if self.dialog.isMaximized() or self.dialog.isMinimized():
+            for handle in self.resize_handles:
+                handle.hide()
+            return
+        width, height, border, corner = self.dialog.width(), self.dialog.height(), 5, 10
+        geometries = (
+            QRect(0, corner, border, max(0, height - 2 * corner)),
+            QRect(width - border, corner, border, max(0, height - 2 * corner)),
+            QRect(corner, 0, max(0, width - 2 * corner), border),
+            QRect(corner, height - border, max(0, width - 2 * corner), border),
+            QRect(0, 0, corner, corner),
+            QRect(width - corner, 0, corner, corner),
+            QRect(0, height - corner, corner, corner),
+            QRect(width - corner, height - corner, corner, corner),
+        )
+        for handle, geometry in zip(self.resize_handles, geometries, strict=True):
+            handle.setGeometry(geometry)
+            handle.show()
+            handle.raise_()
+
+
+def install_dialog_chrome(
+    dialog: QDialog,
+    layout: QVBoxLayout,
+    *,
+    resizable: bool = True,
+    maximizable: bool = False,
+) -> DialogWindowChrome:
+    """Install PyCForge chrome and retain it for the dialog lifetime."""
+
+    if not isinstance(dialog, QDialog) or not isinstance(layout, QVBoxLayout):
+        raise TypeError("dialog chrome requires a QDialog and QVBoxLayout")
+    chrome = DialogWindowChrome(dialog, layout, resizable=resizable, maximizable=maximizable)
+    dialog._dialog_window_chrome = chrome
+    return chrome
+
+
+__all__ = ["DialogTitleBar", "DialogWindowChrome", "install_dialog_chrome"]

pycforge_sdk/gui/visual/qt_file_icons.py

@@ -0,0 +1,130 @@
+"""Recognizable file badges drawn in the workspace's steel-blue palette."""
+from functools import lru_cache
+
+from PySide6.QtCore import QFileInfo, QPointF, QRectF, Qt
+from PySide6.QtGui import QAbstractFileIconProvider, QColor, QIcon, QPainter, QPainterPath, QPen, QPixmap
+
+from .qt_icons import load_pycforge_icon
+from .visual_tokens import PYCFORGE_COLORS as COLORS
+
+
+@lru_cache(maxsize=4)
+def file_type_icon(suffix: str) -> QIcon:
+    """White folded page with a blue grid, eye or C, at native icon sizes."""
+    if suffix not in {'py', 'pcfproj', 'pcfplugin', 'c'}:
+        raise ValueError('unsupported file badge')
+    icon = QIcon()
+    for size in (16, 20, 24, 32, 48, 64, 96, 128):
+        pixmap = QPixmap(size, size)
+        pixmap.fill(Qt.GlobalColor.transparent)
+        painter = QPainter(pixmap)
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+        painter.scale(size / 24, size / 24)
+        page = QPainterPath()
+        page.moveTo(4, 1.5)
+        page.lineTo(14, 1.5)
+        page.lineTo(20, 7.5)
+        page.lineTo(20, 22.5)
+        page.lineTo(4, 22.5)
+        page.closeSubpath()
+        painter.setPen(QPen(QColor(COLORS.text_soft), 0.7))
+        painter.setBrush(QColor('#FFFFFF'))
+        painter.drawPath(page)
+        fold = QPainterPath()
+        fold.moveTo(14, 1.5)
+        fold.lineTo(14, 7.5)
+        fold.lineTo(20, 7.5)
+        painter.setBrush(QColor(COLORS.text))
+        painter.drawPath(fold)
+
+        # The deeper steel blue remains distinct against the white page even
+        # at the smallest tree-row size. It is an existing theme token.
+        blue = QColor(COLORS.selection_active)
+        painter.setPen(QPen(blue, 1.8, Qt.PenStyle.SolidLine,
+                            Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin))
+        painter.setBrush(Qt.BrushStyle.NoBrush)
+        if suffix == 'py':
+            painter.setPen(Qt.PenStyle.NoPen)
+            painter.setBrush(blue)
+            for x in (7.2, 12.7):
+                for y in (10.2, 15.7):
+                    painter.drawRoundedRect(QRectF(x, y, 4.1, 4.1), 0.65, 0.65)
+        elif suffix == 'pcfplugin':
+            painter.drawLine(QPointF(8, 12), QPointF(16, 18))
+            painter.drawLine(QPointF(8, 18), QPointF(16, 12))
+            painter.setBrush(blue)
+            for x, y in ((8, 12), (16, 12), (8, 18), (16, 18)):
+                painter.drawEllipse(QPointF(x, y), 1.7, 1.7)
+        elif suffix == 'pcfproj':
+            eye = QPainterPath()
+            eye.moveTo(6.2, 15)
+            eye.cubicTo(9.3, 10.2, 14.7, 10.2, 17.8, 15)
+            eye.cubicTo(14.7, 19.8, 9.3, 19.8, 6.2, 15)
+            painter.drawPath(eye)
+            painter.setPen(Qt.PenStyle.NoPen)
+            painter.setBrush(blue)
+            painter.drawEllipse(QPointF(12, 15), 1.8, 1.8)
+        else:
+            letter = QPainterPath()
+            letter.moveTo(16, 11.2)
+            letter.cubicTo(8.2, 7.4, 6.2, 20.7, 16, 18.4)
+            painter.setPen(QPen(blue, 2.4, Qt.PenStyle.SolidLine,
+                                Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin))
+            painter.drawPath(letter)
+        painter.end()
+        for mode in (QIcon.Mode.Normal, QIcon.Mode.Active, QIcon.Mode.Selected):
+            icon.addPixmap(pixmap, mode)
+    return icon
+
+
+class PyCForgeFileIconProvider(QAbstractFileIconProvider):
+    """Use theme artwork and distinct Python, project and C file badges."""
+
+    _CONTAINER_TYPES = frozenset(
+        {
+            QAbstractFileIconProvider.IconType.Computer,
+            QAbstractFileIconProvider.IconType.Desktop,
+            QAbstractFileIconProvider.IconType.Network,
+            QAbstractFileIconProvider.IconType.Drive,
+            QAbstractFileIconProvider.IconType.Folder,
+        }
+    )
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._folder_icon = load_pycforge_icon("open")
+        self._source_icon = load_pycforge_icon("module")
+        self._file_icons = {suffix: file_type_icon(suffix)
+                            for suffix in ('py', 'pcfproj', 'pcfplugin', 'c')}
+
+    def icon(
+        self,
+        value: QFileInfo | QAbstractFileIconProvider.IconType,
+    ) -> QIcon:
+        if isinstance(value, QFileInfo):
+            if value.isDir():
+                return self._folder_icon
+            if value.fileName() == 'project.json':
+                return self._file_icons['pcfproj']
+            return self._file_icons.get(value.suffix().casefold(), self._source_icon)
+        if value in self._CONTAINER_TYPES:
+            return self._folder_icon
+        return self._source_icon
+
+    def type(self, info: QFileInfo) -> str:
+        if info.isDir():
+            return "Folder"
+        suffix = info.suffix().casefold()
+        if suffix == "py":
+            return "Python source"
+        if suffix == "c":
+            return "C source"
+        if suffix == "pcfproj":
+            return "PyCForge project"
+        if suffix == "pcfplugin":
+            return "PyCForge conversion import"
+        if info.fileName() == "project.json":
+            return "PyCForge SDK project"
+        return "Source file"
+
+

pycforge_sdk/gui/visual/qt_icons.py

@@ -0,0 +1,80 @@
+"""High-DPI Qt helpers for packaged multi-resolution PNG icons."""
+
+from __future__ import annotations
+
+from numbers import Real
+
+from PySide6.QtCore import QSize
+from PySide6.QtGui import QColor, QIcon, QPainter, QPixmap
+
+from .icons import pycforge_icon_paths
+
+
+def load_pycforge_icon(name: str) -> QIcon:
+    """Build a QIcon containing every packaged resolution for *name*."""
+
+    icon = QIcon()
+    for size, path in pycforge_icon_paths(name):
+        icon.addFile(
+            str(path),
+            QSize(size, size),
+            QIcon.Mode.Normal,
+            QIcon.State.Off,
+        )
+    if icon.isNull():
+        raise RuntimeError(f"raster icon could not be loaded: {name}")
+    return icon
+
+
+def render_icon_pixmap(
+    name: str,
+    logical_size: int,
+    device_pixel_ratio: Real = 1.0,
+) -> QPixmap:
+    """Render one logical icon at a DPR-aware physical display size."""
+
+    if (
+        isinstance(logical_size, bool)
+        or not isinstance(logical_size, int)
+        or not 1 <= logical_size <= 512
+    ):
+        raise ValueError("logical icon size must be from 1 to 512 pixels")
+    if (
+        isinstance(device_pixel_ratio, bool)
+        or not isinstance(device_pixel_ratio, Real)
+        or not 1.0 <= float(device_pixel_ratio) <= 8.0
+    ):
+        raise ValueError("device pixel ratio must be from 1.0 to 8.0")
+    pixmap = load_pycforge_icon(name).pixmap(
+        QSize(logical_size, logical_size),
+        float(device_pixel_ratio),
+    )
+    if pixmap.isNull():
+        raise RuntimeError(f"raster icon could not be rendered: {name}")
+    return pixmap
+
+
+def render_tinted_icon(
+    name: str,
+    logical_size: int,
+    color: str,
+    device_pixel_ratio: Real = 1.0,
+) -> QIcon:
+    """Render a packaged raster glyph as one solid semantic color."""
+
+    tint = QColor(color)
+    if not tint.isValid():
+        raise ValueError("icon tint must be a valid Qt color")
+    pixmap = render_icon_pixmap(name, logical_size, device_pixel_ratio)
+    painter = QPainter(pixmap)
+    try:
+        painter.setCompositionMode(
+            QPainter.CompositionMode.CompositionMode_SourceIn
+        )
+        painter.fillRect(pixmap.rect(), tint)
+    finally:
+        painter.end()
+    return QIcon(pixmap)
+
+
+__all__ = ["load_pycforge_icon", "render_icon_pixmap", "render_tinted_icon"]