pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk/gui/visual/qt_screen_geometry.py

@@ -0,0 +1,166 @@
+"""Screen-aware top-level window geometry for the PyCForge Qt UI.
+
+Qt reports monitor work areas in device-independent pixels.  Keeping all
+preferred and minimum sizes in that same coordinate system lets Windows own
+display scaling while ensuring restored or default geometry never starts
+outside the usable monitor area.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from PySide6.QtCore import QPoint
+from PySide6.QtWidgets import QApplication, QWidget
+
+
+DEFAULT_SCREEN_MARGIN = 16
+
+
+@dataclass(frozen=True, slots=True)
+class WindowGeometryPlan:
+    """Validated logical-pixel dimensions for one top-level window."""
+
+    width: int
+    height: int
+    minimum_width: int
+    minimum_height: int
+
+
+def plan_window_geometry(
+    available_width: int,
+    available_height: int,
+    *,
+    preferred_width: int,
+    preferred_height: int,
+    minimum_width: int,
+    minimum_height: int,
+    margin: int = DEFAULT_SCREEN_MARGIN,
+) -> WindowGeometryPlan:
+    """Return preferred and minimum dimensions bounded by a monitor work area."""
+
+    values = (
+        available_width,
+        available_height,
+        preferred_width,
+        preferred_height,
+        minimum_width,
+        minimum_height,
+        margin,
+    )
+    if any(isinstance(value, bool) or not isinstance(value, int) for value in values):
+        raise TypeError("window geometry dimensions must be integers")
+    if available_width < 1 or available_height < 1:
+        raise ValueError("available screen dimensions must be positive")
+    if preferred_width < 1 or preferred_height < 1:
+        raise ValueError("preferred window dimensions must be positive")
+    if minimum_width < 1 or minimum_height < 1:
+        raise ValueError("minimum window dimensions must be positive")
+    if margin < 0:
+        raise ValueError("screen margin cannot be negative")
+
+    # On exceptionally small logical desktops, retaining a margin is less
+    # important than keeping the complete window reachable.
+    horizontal_margin = min(margin, max(0, (available_width - 1) // 2))
+    vertical_margin = min(margin, max(0, (available_height - 1) // 2))
+    usable_width = max(1, available_width - (2 * horizontal_margin))
+    usable_height = max(1, available_height - (2 * vertical_margin))
+    width = min(preferred_width, usable_width)
+    height = min(preferred_height, usable_height)
+    return WindowGeometryPlan(
+        width=width,
+        height=height,
+        minimum_width=min(minimum_width, width),
+        minimum_height=min(minimum_height, height),
+    )
+
+
+def fit_window_to_available_screen(
+    widget: QWidget,
+    *,
+    preferred: tuple[int, int],
+    minimum: tuple[int, int],
+    reset_size: bool = True,
+    margin: int = DEFAULT_SCREEN_MARGIN,
+) -> WindowGeometryPlan:
+    """Size and place *widget* wholly inside its current monitor work area.
+
+    ``reset_size`` applies the preferred size for a new window.  When false,
+    a restored size and position are retained where possible, then bounded and
+    moved just enough to remain reachable.
+    """
+
+    if not isinstance(widget, QWidget):
+        raise TypeError("widget must be a QWidget")
+    screen = _screen_for_widget(widget)
+    available = screen.availableGeometry()
+    plan = plan_window_geometry(
+        available.width(),
+        available.height(),
+        preferred_width=int(preferred[0]),
+        preferred_height=int(preferred[1]),
+        minimum_width=int(minimum[0]),
+        minimum_height=int(minimum[1]),
+        margin=margin,
+    )
+    widget.setMinimumSize(plan.minimum_width, plan.minimum_height)
+    if widget.isMaximized() or widget.isFullScreen():
+        return plan
+
+    horizontal_margin = min(margin, max(0, (available.width() - 1) // 2))
+    vertical_margin = min(margin, max(0, (available.height() - 1) // 2))
+    usable_left = available.left() + horizontal_margin
+    usable_top = available.top() + vertical_margin
+    usable_right = available.right() - horizontal_margin
+    usable_bottom = available.bottom() - vertical_margin
+
+    if reset_size:
+        width, height = plan.width, plan.height
+        # Center inside the full work area, not merely at the margin origin.
+        x = available.left() + max(0, (available.width() - width) // 2)
+        y = available.top() + max(0, (available.height() - height) // 2)
+    else:
+        width = min(max(1, widget.width()), plan.width)
+        height = min(max(1, widget.height()), plan.height)
+        x = widget.x()
+        y = widget.y()
+
+    maximum_x = max(usable_left, usable_right - width + 1)
+    maximum_y = max(usable_top, usable_bottom - height + 1)
+    x = min(maximum_x, max(usable_left, x))
+    y = min(maximum_y, max(usable_top, y))
+    widget.resize(width, height)
+    widget.move(x, y)
+    return plan
+
+
+def _screen_for_widget(widget: QWidget):
+    handle = widget.windowHandle()
+    if handle is not None and handle.screen() is not None:
+        return handle.screen()
+    parent = widget.parentWidget()
+    if parent is not None:
+        parent_handle = parent.window().windowHandle()
+        if parent_handle is not None and parent_handle.screen() is not None:
+            return parent_handle.screen()
+        parent_center = parent.window().frameGeometry().center()
+        screen = QApplication.screenAt(parent_center)
+        if screen is not None:
+            return screen
+    center = widget.frameGeometry().center()
+    if center != QPoint():
+        screen = QApplication.screenAt(center)
+        if screen is not None:
+            return screen
+    screen = QApplication.primaryScreen()
+    if screen is None:
+        raise RuntimeError("Qt did not provide an available screen")
+    return screen
+
+
+__all__ = [
+    "DEFAULT_SCREEN_MARGIN",
+    "WindowGeometryPlan",
+    "fit_window_to_available_screen",
+    "plan_window_geometry",
+]

pycforge_sdk/gui/visual/qt_title_controls.py

@@ -0,0 +1,333 @@
+"""Title presentation and window buttons, independent of move/resize control."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QRect, QRectF, Qt, QTimer
+from PySide6.QtGui import QColor, QCursor, QPainter, QPen
+from PySide6.QtWidgets import QHBoxLayout, QLabel, QSizePolicy, QToolButton, QWidget
+
+from .qt_branding import BrandElidedLabel
+from .visual_tokens import PYCFORGE_COLORS
+
+if TYPE_CHECKING:
+    from .qt_window_chrome import FramelessWindowChrome
+
+
+class _WindowControlButton(QToolButton):
+    """Paint one palette-aware vector window symbol without platform icons."""
+
+    def __init__(
+        self,
+        kind: str,
+        accessible_name: str,
+        tooltip: str,
+        callback: Callable[[], None],
+        parent: QWidget,
+    ) -> None:
+        super().__init__(parent)
+        self._kind = kind
+        self.setObjectName(
+            {
+                "minimize": "WindowMinimizeButton",
+                "maximize": "WindowMaximizeButton",
+                "restore": "WindowMaximizeButton",
+                "close": "WindowCloseButton",
+            }[kind]
+        )
+        self.setProperty("windowControl", True)
+        self.setProperty("windowControlKind", kind)
+        self.setProperty("windowControlKeyboardFocus", False)
+        self.setAccessibleName(accessible_name)
+        self.setAccessibleDescription(tooltip)
+        self.setToolTip(tooltip)
+        self.setFixedSize(38, 32)
+        # Mouse clicks keep focus in the editor; Tab still reaches the window
+        # controls and retains their visible keyboard-focus indication.
+        self.setFocusPolicy(Qt.FocusPolicy.TabFocus)
+        self._callback = callback
+        self.clicked.connect(self._activate)
+
+    def _set_keyboard_focus(self, visible: bool) -> None:
+        if self.property("windowControlKeyboardFocus") == visible:
+            return
+        self.setProperty("windowControlKeyboardFocus", visible)
+        self.style().unpolish(self)
+        self.style().polish(self)
+        self.update()
+
+    def focusInEvent(self, event) -> None:  # noqa: N802 - Qt API
+        self._set_keyboard_focus(event.reason() in {
+            Qt.FocusReason.TabFocusReason,
+            Qt.FocusReason.BacktabFocusReason,
+            Qt.FocusReason.ShortcutFocusReason,
+        })
+        super().focusInEvent(event)
+
+    def focusOutEvent(self, event) -> None:  # noqa: N802 - Qt API
+        self._set_keyboard_focus(False)
+        super().focusOutEvent(event)
+
+    def mousePressEvent(self, event) -> None:  # noqa: N802 - Qt API
+        self._set_keyboard_focus(False)
+        super().mousePressEvent(event)
+
+    def keyPressEvent(self, event) -> None:  # noqa: N802 - Qt API
+        self._set_keyboard_focus(True)
+        super().keyPressEvent(event)
+
+    def clear_pointer_state(self) -> None:
+        self.setDown(False)
+        self.setAttribute(Qt.WidgetAttribute.WA_UnderMouse, False)
+        self.update()
+
+    def leaveEvent(self, event) -> None:  # noqa: N802 - Qt API
+        self.clear_pointer_state()
+        super().leaveEvent(event)
+
+    def hideEvent(self, event) -> None:  # noqa: N802 - Qt API
+        self.clear_pointer_state()
+        super().hideEvent(event)
+
+    def _activate(self, _checked: bool = False) -> None:
+        # A native minimize/restore transition can skip the usual leave event.
+        self.clear_pointer_state()
+        self._callback()
+
+    def set_kind(
+        self,
+        kind: str,
+        accessible_name: str,
+        tooltip: str,
+    ) -> None:
+        """Switch the maximize symbol to restore without replacing the button."""
+
+        if kind not in {"maximize", "restore"}:
+            raise ValueError("maximize control kind must be maximize or restore")
+        self._kind = kind
+        self.setProperty("windowControlKind", kind)
+        self.setAccessibleName(accessible_name)
+        self.setAccessibleDescription(tooltip)
+        self.setToolTip(tooltip)
+        self.update()
+
+    def paintEvent(self, event) -> None:  # noqa: N802 - Qt API
+        # Native activation/movement can omit Leave. Do not let the Qt hover
+        # attribute paint a highlight at a position the pointer has left.
+        if self.underMouse() and not self.rect().contains(self.mapFromGlobal(QCursor.pos())):
+            self.setAttribute(Qt.WidgetAttribute.WA_UnderMouse, False)
+        super().paintEvent(event)
+        painter = QPainter(self)
+        painter.setRenderHint(QPainter.RenderHint.Antialiasing, True)
+        color = (
+            PYCFORGE_COLORS.error_bright
+            if self._kind == "close" and self.underMouse()
+            else PYCFORGE_COLORS.text_soft
+        )
+        pen = QPen(QColor(color))
+        pen.setWidthF(1.65)
+        pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+        pen.setJoinStyle(Qt.PenJoinStyle.RoundJoin)
+        painter.setPen(pen)
+        painter.setBrush(Qt.BrushStyle.NoBrush)
+
+        center_x = self.rect().center().x()
+        center_y = self.rect().center().y()
+        if self._kind == "minimize":
+            painter.drawLine(center_x - 6, center_y + 4, center_x + 6, center_y + 4)
+        elif self._kind == "maximize":
+            painter.drawRoundedRect(QRectF(center_x - 5.5, center_y - 5.5, 11.0, 11.0), 1.5, 1.5)
+        elif self._kind == "restore":
+            painter.drawRect(QRectF(center_x - 6.0, center_y - 3.0, 9.0, 8.0))
+            painter.drawLine(center_x - 3, center_y - 5, center_x + 6, center_y - 5)
+            painter.drawLine(center_x + 6, center_y - 5, center_x + 6, center_y + 3)
+            painter.drawLine(center_x + 3, center_y + 3, center_x + 6, center_y + 3)
+        else:
+            painter.drawLine(center_x - 5, center_y - 5, center_x + 5, center_y + 5)
+            painter.drawLine(center_x + 5, center_y - 5, center_x - 5, center_y + 5)
+
+
+class _TitleControls(QWidget):
+    """Right-hand title identity and standard window controls."""
+
+    def __init__(self, controller: "FramelessWindowChrome") -> None:
+        super().__init__(controller.window)
+        self.controller = controller
+        self.setObjectName("FramelessTitleControls")
+        self.setAccessibleName("Window title and controls")
+        self.setSizePolicy(
+            QSizePolicy.Policy.Preferred,
+            QSizePolicy.Policy.Fixed,
+        )
+
+        layout = QHBoxLayout(self)
+        layout.setContentsMargins(8, 0, 0, 0)
+        layout.setSpacing(0)
+
+        self.brand = QLabel()
+        self.brand.setObjectName("FramelessWindowBrand")
+        self.brand.setPixmap(controller.window.windowIcon().pixmap(18, 18))
+        self.brand.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.brand.setFixedSize(28, 32)
+        self.brand.setAttribute(
+            Qt.WidgetAttribute.WA_TransparentForMouseEvents,
+            True,
+        )
+        layout.addWidget(self.brand)
+
+        self.title = BrandElidedLabel(
+            controller.window.windowTitle(),
+            mode=Qt.TextElideMode.ElideMiddle,
+        )
+        self.title.setObjectName("FramelessWindowTitle")
+        self.title.setSizePolicy(
+            QSizePolicy.Policy.Fixed,
+            QSizePolicy.Policy.Preferred,
+        )
+        self.title.setAccessibleName("PyCForge window title")
+        self.title.setAttribute(
+            Qt.WidgetAttribute.WA_TransparentForMouseEvents,
+            True,
+        )
+        self._reserved_title_identity = ""
+        self._preferred_title_width = 0
+        layout.addWidget(self.title)
+
+        self.minimize_button = _WindowControlButton(
+            "minimize",
+            "Minimize window",
+            "Minimize PyCForge",
+            controller.window.showMinimized,
+            self,
+        )
+        self.maximize_button = _WindowControlButton(
+            "maximize",
+            "Maximize window",
+            "Maximize PyCForge",
+            controller.toggle_maximized,
+            self,
+        )
+        self.close_button = _WindowControlButton(
+            "close",
+            "Close window",
+            "Close PyCForge",
+            controller.window.close,
+            self,
+        )
+        layout.addWidget(self.minimize_button)
+        layout.addWidget(self.maximize_button)
+        layout.addWidget(self.close_button)
+        self._width_sync_timer = QTimer(self)
+        self._width_sync_timer.setSingleShot(True)
+        self._width_sync_timer.timeout.connect(self.sync_available_width)
+        self._reserve_title_width(self.title.text())
+
+    def sync_title(self) -> None:
+        text = self.controller.window.windowTitle()
+        self._reserve_title_width(text)
+        if self.title.text() != text:
+            self.title.set_full_text(text)
+        self.title.setToolTip(text)
+        self.title.setAccessibleDescription(text)
+
+    def sync_text_size(self) -> None:
+        """Keep the icon-only title controls clear beside larger UI text."""
+
+        height = max(32, self.fontMetrics().height() + 10)
+        width = max(38, height + 6)
+        for button in (
+            self.minimize_button,
+            self.maximize_button,
+            self.close_button,
+        ):
+            button.setFixedSize(width, height)
+        self.brand.setFixedSize(28, height)
+        self._reserved_title_identity = ""
+        self.sync_title()
+        self.updateGeometry()
+
+    def _reserve_title_width(self, text: str) -> None:
+        """Reserve clean/dirty width once per document-title identity."""
+
+        clean = text.replace(" • — ", " — ", 1)
+        if clean == self._reserved_title_identity:
+            return
+        self._reserved_title_identity = clean
+        prefix, separator, suffix = clean.partition(" — ")
+        dirty = (
+            f"{prefix} • — {suffix}"
+            if separator else f"{clean} •"
+        )
+        metrics = self.title.fontMetrics()
+        reserved = max(
+            metrics.horizontalAdvance(clean),
+            metrics.horizontalAdvance(dirty),
+        )
+        self._preferred_title_width = min(230, max(96, reserved + 18))
+        self.sync_available_width()
+
+    def sync_available_width(self) -> None:
+        """Elide title identity before it can enter menu or control geometry."""
+
+        menu = self.controller.menu_bar
+        action_right = max(
+            (menu.actionGeometry(action).right() for action in menu.actions()),
+            default=0,
+        )
+        button_width = sum(
+                button.width()
+                for button in (
+                    self.minimize_button,
+                    self.maximize_button,
+                    self.close_button,
+                )
+            )
+        menu_right = max(0, menu.contentsRect().right())
+        # The Tools/diagnostics slot can leave too little room for even a
+        # zero-width title. Give the standard controls priority over the
+        # decorative brand and its margin; restore both when space returns.
+        show_brand = menu_right + 1 >= action_right + button_width + self.brand.width() + 8 + 12
+        self.brand.setVisible(show_brand)
+        self.layout().setContentsMargins(8 if show_brand else 0, 0, 0, 0)
+        fixed = button_width + (self.brand.width() + 8 if show_brand else 0)
+        available = max(0, menu_right + 1 - action_right - fixed - 12)
+        title_width = min(self._preferred_title_width, available)
+        self.title.setFixedWidth(title_width)
+        height = max(button.height() for button in (
+                self.minimize_button,
+                self.maximize_button,
+                self.close_button,
+            ))
+        width = fixed + title_width
+        self.setFixedSize(width, height)
+        self.layout().activate()
+        # QMenuBar can retain the corner widget's earlier x-coordinate after
+        # its fixed width changes. Place the final geometry explicitly so the
+        # action row and standard controls remain disjoint on narrow screens.
+        left = max(action_right + 12, menu_right - width + 1)
+        top = max(0, (menu.height() - height) // 2)
+        target = QRect(left, top, width, height)
+        if self.geometry() != target:
+            self.setGeometry(target)
+
+    def schedule_available_width_sync(self) -> None:
+        """Repeat title placement after Qt completes the menu-bar layout."""
+
+        self._width_sync_timer.start(0)
+
+    def sync_window_state(self) -> None:
+        if self.controller.window.isMaximized():
+            self.maximize_button.set_kind(
+                "restore",
+                "Restore window",
+                "Restore PyCForge",
+            )
+        else:
+            self.maximize_button.set_kind(
+                "maximize",
+                "Maximize window",
+                "Maximize PyCForge",
+            )
+
+