gitpane 1.0.0__py3-none-any.whl

gitpane/ui/console/error_dialog.py

@@ -0,0 +1,332 @@
+"""Present a prepared diagnostic as copyable text, blocking its window the way its opener decides."""
+
+from __future__ import annotations
+
+import math
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QRect, Qt
+from PySide6.QtGui import QTextDocument
+from PySide6.QtWidgets import QApplication, QDialog, QHBoxLayout, QLabel, QLayout, QPlainTextEdit, QPushButton, QScrollArea, QStyle, QVBoxLayout, QWidget
+from shiboken6 import isValid
+
+from gitpane.config import (
+    ERROR_HEIGHT,
+    ERROR_MAX_SCREEN_HEIGHT_RATIO,
+    ERROR_SUMMARY_MAX_SHARE,
+    ERROR_WIDTH,
+    LAYOUT_SPACING,
+    SPACING_MD,
+    SharedText,
+    control_height,
+    fit_window,
+    known_frame_margins,
+    unknown_decoration_estimate,
+    window_placement,
+)
+from gitpane.ui.look.fixed_font import body_sized_fixed_font
+from gitpane.ui.widget.long_text import FRAME_SIDE_COUNT, WrappingLabel
+from gitpane.ui.window_control.compositor_answer import after_compositor_answer
+
+if TYPE_CHECKING:
+    from PySide6.QtGui import QMoveEvent, QResizeEvent, QShowEvent
+
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+
+PLAIN_TEXT_LAST_LINE_SLACK = 1
+
+
+class ErrorDialogText(Enum):
+    """Texts the error window shows, one member per text so a misspelt name is an error."""
+
+    CLOSE = "Close diagnostic"
+    MASKED = "Some sensitive values have been hidden."
+    HELP = "Read the details, fix the cause, then try again."
+
+
+class ErrorDialog(QDialog):
+    """Keep a real, copyable cause and its details visible while other windows and tasks continue.
+
+    The details are shown from the start, in an area as tall as their text, and the window never takes more than a
+    fixed share of the usable screen height: past it, the details scroll and the actions under them stay on screen.
+    """
+
+    def __init__(self, diagnostic: PreparedDiagnostic, parent: QWidget, log_filename: str | None = None, *, recovery_command: str = "", recovery_hint: str = "") -> None:
+        """Show the cause, an optional manual recovery command and the diagnostic details, with Copy details and Close diagnostic under them."""
+        super().__init__(parent)
+        self.diagnostic = diagnostic
+        # The screen area and the title bar height the last height fit used, so the fit is made again with the same
+        # area once the window manager has added a title bar of another height.
+        self.fitted_available: QRect | None = None
+        self.fitted_decoration_height: int | None = None
+        # True until the window manager has framed the window: only then may a move or resize from the window system
+        # fit the height again, once.
+        self.awaiting_window_manager_frame = True
+        self.return_focus = parent.focusWidget()
+        self.finished.connect(self._restore_focus)
+        self.setWindowTitle(diagnostic.operation)
+        self.resize(ERROR_WIDTH, ERROR_HEIGHT)
+        layout = QVBoxLayout(self)
+        layout.setSizeConstraint(QLayout.SizeConstraint.SetNoConstraint)
+        layout.setSpacing(LAYOUT_SPACING)
+        layout.setContentsMargins(SPACING_MD, SPACING_MD, SPACING_MD, SPACING_MD)
+        self.summary_scroll = QScrollArea()
+        self.summary_scroll.setWidgetResizable(True)
+        summary = QWidget()
+        summary_layout = QVBoxLayout(summary)
+        self.summary_scroll.setWidget(summary)
+        layout.addWidget(self.summary_scroll, 0)
+        # The whole cause is shown, wrapped at words and inside words too long for a line; the summary area scrolls
+        # when it is taller than its share of the window, so the close and copy buttons below stay on screen.
+        self.cause_label = WrappingLabel(diagnostic.cause)
+        self.cause_label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse | Qt.TextInteractionFlag.TextSelectableByKeyboard)
+        self.cause_label.setWordWrap(True)
+        cause_layout = QHBoxLayout()
+        self.error_icon_label = QLabel()
+        cause_layout.addWidget(self.error_icon_label, 0, Qt.AlignmentFlag.AlignTop)
+        cause_layout.addWidget(self.cause_label, 1)
+        summary_layout.addLayout(cause_layout)
+        self.recovery_command_edit: QPlainTextEdit | None = None
+        self.copy_command_button: QPushButton | None = None
+        self.recovery_hint_label: QLabel | None = None
+        if recovery_command:
+            self.recovery_hint_label = QLabel(recovery_hint or "Manual recovery command:")
+            self.recovery_hint_label.setTextFormat(Qt.TextFormat.PlainText)
+            self.recovery_hint_label.setWordWrap(True)
+            summary_layout.addWidget(self.recovery_hint_label)
+            self.recovery_command_edit = QPlainTextEdit(recovery_command)
+            self.recovery_command_edit.setReadOnly(True)
+            self.recovery_command_edit.setAccessibleName("Manual recovery command")
+            summary_layout.addWidget(self.recovery_command_edit)
+            self.copy_command_button = QPushButton("Copy command")
+            self.copy_command_button.clicked.connect(self.copy_recovery_command)
+            summary_layout.addWidget(self.copy_command_button)
+        help_label = QLabel(ErrorDialogText.HELP.value)
+        help_label.setWordWrap(True)
+        summary_layout.addWidget(help_label)
+        if diagnostic.masked:
+            masked_label = QLabel(ErrorDialogText.MASKED.value)
+            masked_label.setWordWrap(True)
+            summary_layout.addWidget(masked_label)
+        if log_filename:
+            label = QLabel(log_filename)
+            label.setTextFormat(Qt.TextFormat.PlainText)
+            label.setWordWrap(True)
+            label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse | Qt.TextInteractionFlag.TextSelectableByKeyboard)
+            summary_layout.addWidget(label)
+        self.detail_edit = QPlainTextEdit(diagnostic.detail)
+        self.detail_edit.setReadOnly(True)
+        self.detail_edit.setAccessibleName("Diagnostic details")
+        layout.addWidget(self.detail_edit, 1)
+        self.action_layout = QVBoxLayout()
+        self.copy_button = QPushButton(SharedText.COPY_DETAILS.value)
+        # Enter closes the window: Copy details, even with the focus, never takes Close's place as the button Enter clicks.
+        self.copy_button.setAutoDefault(False)
+        self.copy_button.clicked.connect(self.copy_detail)
+        self.action_layout.addWidget(self.copy_button)
+        self.close_button = QPushButton(ErrorDialogText.CLOSE.value)
+        self.close_button.setDefault(True)
+        self.close_button.clicked.connect(self.accept)
+        self.action_layout.addWidget(self.close_button)
+        layout.addLayout(self.action_layout)
+        self.refresh_metrics()
+
+    def refresh_metrics(self, available: QRect | None = None) -> None:
+        """Use system monospace text, size the actions for the current font, then fit the window's height to its content.
+
+        ``available`` is the usable area of the screen the window is on; without it, the screen of the window it was
+        opened from is used.
+        """
+        fixed_font = body_sized_fixed_font()
+        self.detail_edit.setFont(fixed_font)
+        if self.recovery_command_edit is not None:
+            self.recovery_command_edit.setFont(fixed_font)
+            command_line_count = 4
+            self.recovery_command_edit.setFixedHeight(self.recovery_command_edit.fontMetrics().lineSpacing() * command_line_count + SPACING_MD)
+        if self.copy_command_button is not None:
+            self.copy_command_button.setMinimumHeight(control_height(self.copy_command_button.fontMetrics().height()))
+        icon_side = self.style().pixelMetric(QStyle.PixelMetric.PM_MessageBoxIconSize)
+        self.error_icon_label.setPixmap(self.style().standardIcon(QStyle.StandardPixmap.SP_MessageBoxCritical).pixmap(icon_side, icon_side))
+        for button in (self.copy_button, self.close_button):
+            button.setMinimumHeight(control_height(button.fontMetrics().height()))
+        self.fit_height_to_content(available)
+
+    def showEvent(self, event: QShowEvent) -> None:
+        """Fit the height again once the window is about to appear, before it is fitted to its content and centred on the window it was opened from.
+
+        Under X11 the title bar is not there yet: this fit counts the one borrowed from the window it was opened from, and
+        the move or resize the window manager makes when it adds the real one fits the height again if it differs. That
+        is the only later fit: the window then leaves its height and content alone whatever the window system does.
+        Where the system already gives the frame of the native window before it appears (macOS, Windows), this fit
+        counts the real title bar, so no later fit is awaited at all. Where the toolkit draws the title bar itself once
+        the window is shown (Wayland), no move or resize from the window system follows the show: the fit is made again
+        once the compositor has answered the show, which would otherwise overwrite a size asked before its answer.
+        """
+        super().showEvent(event)
+        self.fit_height_to_content()
+        if self.native_frame_margins_known():
+            self.awaiting_window_manager_frame = False
+        after_compositor_answer(self, self.refit_once_frame_known)
+
+    def refit_once_frame_known(self) -> None:
+        """Fit the height again, once, with the screen area of the last fit, when the title bar now known has another height than the last fit counted.
+
+        The window then stops waiting for its title bar, as after a move or resize from the window system. A title bar
+        still unknown leaves the window waiting: under X11 the window manager's move or resize does that work later.
+        """
+        if not self.awaiting_window_manager_frame or not self.native_frame_margins_known():
+            return
+        if self.decoration_height() != self.fitted_decoration_height:
+            self.fit_height_to_content(self.fitted_available)
+        self.awaiting_window_manager_frame = False
+
+    def moveEvent(self, event: QMoveEvent) -> None:
+        """Fit the height again when the window manager has just framed the window with a title bar of another height than the last fit counted."""
+        super().moveEvent(event)
+        self.refit_after_window_manager_frame(event)
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        """Fit the height again when the window manager has just framed the window with a title bar of another height than the last fit counted."""
+        super().resizeEvent(event)
+        self.refit_after_window_manager_frame(event)
+
+    def refit_after_window_manager_frame(self, event: QMoveEvent | QResizeEvent) -> None:
+        """Fit the height again, once, with the screen area of the last fit, when the window manager framed the window with a title bar of another height.
+
+        Workaround: under X11 the window manager adds the title bar after the window is shown, and Qt sends no event for
+        the title bar itself; the only sign of it is the move or resize the window system reports (a spontaneous event)
+        when the window manager frames the window. A fit made before that counted an estimated title bar, or none, so the
+        frame can end below the screen edge. The fit is made again only when the title bar height read now differs from
+        the one the last fit counted: the moves and resizes the fit makes itself are not spontaneous, and the window
+        system's confirmations of them find the same title bar.
+        The hook then stops at the first spontaneous event that comes with the native frame margins known, whether it
+        fitted or not: the title bar is in place, and fitting again later (borders dropped on maximize, another screen)
+        would compute the content once more and could undo a move or resize the user just made. Where the compositor
+        answers the show with a size of its own (Wayland), the hook does nothing: the fit made once the compositor has
+        answered the show does this work. The only spontaneous move there comes when the compositor puts the window on
+        another screen than Qt assumed, and it is delivered before the size of the same answer, which would overwrite a
+        fit made then and leave the frame taller than the cap.
+        """
+        if not self.awaiting_window_manager_frame or not event.spontaneous() or window_placement().size_waits_for_compositor_answer:
+            return
+        if self.decoration_height() != self.fitted_decoration_height:
+            self.fit_height_to_content(self.fitted_available)
+        if self.native_frame_margins_known():
+            self.awaiting_window_manager_frame = False
+
+    def native_frame_margins_known(self) -> bool:
+        """Say whether the window system has given the margins of the frame it put around the window, title bar included."""
+        native_window = self.windowHandle()
+        return native_window is not None and not native_window.frameMargins().isNull()
+
+    def fit_height_to_content(self, available: QRect | None = None) -> None:
+        """Give the cause and the details the height of their text at the window's width, within a share of the usable screen height.
+
+        Past that cap the window stays at the cap: the cause takes at most a share of the room left to the two text areas
+        and scrolls, the details take the rest and scroll, and the buttons stay visible under them. The screen area and
+        the title bar height used are kept, so the window can be fitted again with the same area once its real title bar
+        is known.
+        """
+        layout = self.layout()
+        margins = layout.contentsMargins()
+        decoration_height = self.decoration_height()
+        self.fitted_available = available
+        self.fitted_decoration_height = decoration_height
+        height_cap = round(ERROR_MAX_SCREEN_HEIGHT_RATIO * self.usable_screen_area(available).height()) - decoration_height
+        text_width = self.width() - margins.left() - margins.right()
+        self.action_layout.invalidate()
+        fixed_height = margins.top() + margins.bottom() + layout.spacing() * (layout.count() - 1) + self.action_layout.sizeHint().height()
+        summary_height = self.summary_content_height(text_width) + FRAME_SIDE_COUNT * self.summary_scroll.frameWidth()
+        detail_frame_height = FRAME_SIDE_COUNT * self.detail_edit.frameWidth()
+        detail_height = self.detail_text_height(text_width - detail_frame_height, height_cap) + detail_frame_height
+        window_height = fixed_height + summary_height + detail_height
+        if window_height > height_cap:
+            text_room = max(0, height_cap - fixed_height)
+            summary_height = min(summary_height, round(text_room * ERROR_SUMMARY_MAX_SHARE))
+            detail_height = text_room - summary_height
+            window_height = height_cap
+        self.summary_scroll.setFixedHeight(summary_height)
+        # The details area must not ask the layout for more than the height it was given, or the window would be too
+        # short for its layout and the buttons would be pushed out of it.
+        self.detail_edit.setMinimumHeight(min(detail_height, self.detail_edit.minimumSizeHint().height()))
+        self.resize(self.width(), window_height)
+        fit_window(self, 0, 0, available)
+
+    def usable_screen_area(self, available: QRect | None) -> QRect:
+        """Answer the usable area of the screen the window opens on: the one given, else the screen of the window it was opened from, else its own."""
+        if available is not None:
+            return available
+        parent = self.parentWidget()
+        if parent is not None and isValid(parent):
+            return parent.window().screen().availableGeometry()
+        return self.screen().availableGeometry()
+
+    def decoration_height(self) -> int:
+        """Answer the height of the title bar and borders, estimated from the window it was opened from while the window system has not added them yet.
+
+        The native window's frame margins come first: under X11 they are read again from the window manager once it has
+        framed the window, and under Wayland Qt draws the title bar itself after the window is shown, while the widget's
+        frame is a copy Qt only refreshes on a move or a resize. Then the margins the window system already gave, then
+        the estimate.
+        """
+        native_window = self.windowHandle()
+        if native_window is not None:
+            native_margins = native_window.frameMargins()
+            if not native_margins.isNull():
+                return native_margins.top() + native_margins.bottom()
+        known_margins = known_frame_margins(self)
+        if not known_margins.isNull():
+            return known_margins.top() + known_margins.bottom()
+        parent = self.parentWidget()
+        decoration = unknown_decoration_estimate(self, parent.window() if parent is not None and isValid(parent) else None)
+        return decoration.top() + decoration.bottom()
+
+    def summary_content_height(self, area_width: int) -> int:
+        """Answer the height the cause, recovery and help texts need when wrapped inside a summary area of the given width, without a scroll bar.
+
+        The width comes from the window, not from the area's viewport, because the viewport is only laid out once the
+        window is shown.
+        """
+        content = self.summary_scroll.widget()
+        content_width = max(1, area_width - FRAME_SIDE_COUNT * self.summary_scroll.frameWidth())
+        if content.hasHeightForWidth():
+            return content.heightForWidth(content_width)
+        return content.minimumSizeHint().height()
+
+    def detail_text_height(self, text_width: int, height_cap: int) -> int:
+        """Answer the height of the details text wrapped at the given width, as the details area lays it out.
+
+        A detail whose lines alone already pass the cap is not measured further: the area would be capped anyway, and a
+        long Git output would cost a full text layout for nothing.
+        """
+        text = self.detail_edit.toPlainText()
+        line_count = text.count("\n") + 1
+        if line_count * self.detail_edit.fontMetrics().lineSpacing() > height_cap:
+            return height_cap
+        document = QTextDocument()
+        document.setDefaultFont(self.detail_edit.font())
+        document.setDocumentMargin(self.detail_edit.document().documentMargin())
+        option = document.defaultTextOption()
+        option.setWrapMode(self.detail_edit.wordWrapMode())
+        document.setDefaultTextOption(option)
+        document.setTextWidth(max(1, text_width))
+        document.setPlainText(text)
+        # Workaround: a plain text area counts its last line as fully visible only when it ends one pixel above the
+        # bottom margin; at the document's exact height it keeps a scroll bar for that one line, so the pixel is added.
+        return math.ceil(document.size().height()) + PLAIN_TEXT_LAST_LINE_SLACK
+
+    def _restore_focus(self) -> None:
+        """Return focus to the trigger only when dismissing its own diagnostic."""
+        control = self.return_focus
+        if control is not None and isValid(control) and control.isVisible() and control.isEnabled():
+            control.setFocus(Qt.FocusReason.OtherFocusReason)
+
+    def copy_detail(self) -> None:
+        """Copy exactly the already-filtered text displayed in the details area."""
+        QApplication.clipboard().setText(self.diagnostic.detail)
+
+    def copy_recovery_command(self) -> None:
+        """Copy only the displayed command for manual use without executing it."""
+        if self.recovery_command_edit is not None:
+            QApplication.clipboard().setText(self.recovery_command_edit.toPlainText())