gitpane 1.0.0__py3-none-any.whl

gitpane/ui/widget/long_text.py

@@ -0,0 +1,542 @@
+"""Keep long texts readable in narrow windows: labels that wrap or elide, windows grown to show them."""
+
+from __future__ import annotations
+
+from math import ceil
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, QPoint, QRect, QSize, Qt
+from PySide6.QtGui import QFontMetricsF, QPainter, QPalette, QTextDocument, QTextLayout, QTextOption
+from PySide6.QtWidgets import (
+    QCheckBox,
+    QComboBox,
+    QGridLayout,
+    QLabel,
+    QRadioButton,
+    QScrollArea,
+    QSizePolicy,
+    QStyle,
+    QStyleOptionButton,
+    QStylePainter,
+    QWidget,
+)
+from shiboken6 import Shiboken
+
+from gitpane.config import SCREEN_MARGIN, SPACING_MD, SPACING_SM, control_height, fit_window, known_frame_margins
+
+if TYPE_CHECKING:
+    from PySide6.QtGui import QPaintEvent, QResizeEvent
+
+# A widget frame is drawn on both sides, so its width counts twice across a widget.
+FRAME_SIDE_COUNT = 2
+
+
+def fit_window_to_content(window: QWidget, available: QRect | None = None) -> None:
+    """Grow a window just enough to show all its content, never making it smaller and never past the usable screen area.
+
+    Many window sizes are copied from Git Extensions captures, taken on Windows with Segoe UI 9 pt. A larger system font
+    (Ubuntu 11 pt, or a font the user enlarged) needs more room, and at the copied size texts are cut, wrapped texts lose
+    their last lines and controls overlap. The size the window's code gave stays the minimum, so with the captures' font
+    nothing changes. The width grows to the layout's minimum, to what the form inside a scroll area needs and to what the
+    one-line texts that must open whole need, then the height to what the content needs at that width, wrapped texts included. ``available`` is the usable area of the screen the window opens on; without it, the
+    window's own screen is used.
+    """
+    layout = window.layout()
+    if layout is None:
+        return
+    # Activating the layout may already grow the window to the layout's minimum size.
+    layout.activate()
+    minimum = layout.totalMinimumSize()
+    width = max(window.width(), minimum.width(), window.width() + scroll_areas_missing_width(window), window.width() + elided_texts_missing_width(window))
+    height = max(window.height(), minimum.height())
+    if layout.hasHeightForWidth():
+        height = max(height, layout.totalMinimumHeightForWidth(width))
+    screen_area = available if available is not None else window.screen().availableGeometry()
+    largest = largest_client_size(window, screen_area)
+    width = min(width, largest.width())
+    height = min(height, largest.height())
+    if width != window.width() or height != window.height():
+        window.resize(width, height)
+    # A layout minimum larger than the screen keeps the window from shrinking to the size asked: the minimum is relaxed.
+    if window.width() > largest.width() or window.height() > largest.height():
+        fit_window(window, window.minimumWidth(), window.minimumHeight(), screen_area)
+
+
+def scroll_area_missing_width(scroll_area: QScrollArea) -> int:
+    """Return how many pixels a resizable scroll area lacks to show its content's minimum width, or a negative number when it has room.
+
+    A scroll area reports almost no minimum size of its own, whatever it holds, so a window measured on its layout alone
+    never sees that the form inside needs more width: the form is then squeezed or scrolled sideways.
+    """
+    content = scroll_area.widget()
+    if content is None or not scroll_area.widgetResizable():
+        return 0
+    needed = content.minimumSizeHint().expandedTo(content.minimumSize()).width()
+    available = scroll_area.width() - FRAME_SIDE_COUNT * scroll_area.frameWidth()
+    if scroll_area.verticalScrollBarPolicy() == Qt.ScrollBarPolicy.ScrollBarAlwaysOn:
+        available -= scroll_area.verticalScrollBar().sizeHint().width()
+    return needed - available
+
+
+def scroll_areas_missing_width(window: QWidget) -> int:
+    """Return the largest width any shown resizable scroll area of the window lacks for its content, 0 when they all have room.
+
+    Scroll areas on a page that is not shown (another tab, another page of a stack) are left out: their size is not the
+    one they will get once shown.
+    """
+    missing_width = 0
+    for scroll_area in window.findChildren(QScrollArea):
+        if not scroll_area.isVisibleTo(window):
+            continue
+        missing_width = max(missing_width, scroll_area_missing_width(scroll_area))
+    return missing_width
+
+
+def elided_texts_missing_width(window: QWidget) -> int:
+    """Return the largest width a shown text that must open whole lacks to be shown without its ellipsis, 0 when they all fit.
+
+    ``ElidedLabel`` and ``ElidedCheckBox`` ask for no width of their own, so a layout never reports that one of them cuts
+    its text. Those created with ``open_whole`` hold a fixed sentence of the window rather than a value of any length,
+    and the window grows at its first show until each of them is whole; a window the user narrows later cuts them again.
+    """
+    missing_width = 0
+    for widget in window.findChildren(QWidget):
+        if not isinstance(widget, (ElidedLabel, ElidedCheckBox)) or not widget.open_whole or not widget.isVisibleTo(window):
+            continue
+        missing_width = max(missing_width, widget.whole_text_width() - widget.width())
+    return missing_width
+
+
+def largest_client_size(window: QWidget, available: QRect, platform_name: str = "") -> QSize:
+    """Return the largest client size whose frame, title bar and borders included, fits the usable area with its margin.
+
+    ``platform_name`` is Qt's platform name, read from Qt when not given.
+    """
+    usable = available.adjusted(SCREEN_MARGIN, SCREEN_MARGIN, -SCREEN_MARGIN, -SCREEN_MARGIN)
+    decoration = known_frame_margins(window, platform_name)
+    return QSize(usable.width() - decoration.left() - decoration.right(), usable.height() - decoration.top() - decoration.bottom())
+
+
+LONG_WORD_WRAP_MODE = QTextOption.WrapMode.WrapAtWordBoundaryOrAnywhere
+
+
+def long_word_text_option(document: QTextDocument) -> QTextOption:
+    """Return the document's own text option with a fallback that breaks words too long for one line."""
+    option = document.defaultTextOption()
+    option.setWrapMode(LONG_WORD_WRAP_MODE)
+    return option
+
+
+class WrappingLabel(QLabel):
+    """Wrap long literal Git values while retaining native text selection and copying."""
+
+    def __init__(self, text: str = "", parent: QWidget | None = None) -> None:
+        """Use Qt's text document so hashes and URLs need no inserted display characters."""
+        super().__init__(text, parent)
+        self.setTextFormat(Qt.TextFormat.PlainText)
+        self.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+
+    def heightForWidth(self, width: int) -> int:
+        """Measure the same complete wrapped document that the native label will paint."""
+        height = super().heightForWidth(width)
+        if not self.wordWrap():
+            return height
+        # QLabel exposes only word wrapping and resets that choice during layout. Its native text document
+        # supplies the missing long-word fallback without changing literal text or implementing selection ourselves.
+        # The measurement runs on a detached copy: every option or width change on the painted document asks the
+        # label to repaint, so measuring on it from a paint would keep the label repainting forever.
+        document = self.findChild(QTextDocument)
+        if document is None:
+            return height
+        # Workaround: PySide records the copy returned by clone() as a Python-side child of the native document, so it
+        # is never destroyed and every measure would leave one copy alive. setParent(None) drops that record (Qt itself
+        # gave the copy no parent), then the copy is deleted explicitly; deleting it while still recorded as a child
+        # crashes the process once the label is destroyed. The copy must not become a child of the label either:
+        # findChild would then return it instead of the native document, here and in paintEvent.
+        measured_document = document.clone()
+        measured_document.setParent(None)
+        try:
+            measured_document.setDefaultFont(document.defaultFont())
+            measured_document.setDocumentMargin(document.documentMargin())
+            measured_document.setDefaultTextOption(long_word_text_option(document))
+            measured_document.setTextWidth(max(1, width - self.margin() * 2 - self.contentsMargins().left() - self.contentsMargins().right()))
+            return ceil(measured_document.size().height()) + self.margin() * 2 + self.contentsMargins().top() + self.contentsMargins().bottom()
+        finally:
+            Shiboken.delete(measured_document)
+
+    def paintEvent(self, event: QPaintEvent) -> None:
+        """Restore long-word wrapping and the current width after native font or geometry changes before painting."""
+        document = self.findChild(QTextDocument)
+        if not self.wordWrap() or document is None:
+            super().paintEvent(event)
+            return
+        # Workaround: QLabel applies its own wrap mode lazily, the next time it lays out changed text, font or
+        # wrapping, and a pending one would overwrite the long-word fallback during the native paint. Only QLabel's
+        # own height measurement runs that pending layout, and it briefly changes the document width, which would ask
+        # for another paint and repaint the label forever. The document layout's signals are held for that call only.
+        document_layout = document.documentLayout()
+        signals_were_blocked = document_layout.blockSignals(True)
+        try:
+            super().heightForWidth(self.width())
+        finally:
+            document_layout.blockSignals(signals_were_blocked)
+        # Each document change schedules one more paint, so only a real difference is written; an unchanged label then stays idle.
+        if document.defaultTextOption().wrapMode() != LONG_WORD_WRAP_MODE:
+            document.setDefaultTextOption(long_word_text_option(document))
+        paint_width = max(1, self.contentsRect().width() - self.margin() * 2)
+        if document.textWidth() != paint_width:
+            document.setTextWidth(paint_width)
+        super().paintEvent(event)
+
+
+def exact_text_width(widget: QWidget, text: str) -> int:
+    """Return the smallest whole number of pixels that holds a text in the widget's font, so eliding at that width keeps it whole.
+
+    ``QFontMetrics.horizontalAdvance`` rounds the text's fractional width to the nearest pixel, which can be a fraction
+    short of it; ``elidedText`` compares the fractional width and would then cut the text at that rounded width.
+    """
+    return ceil(QFontMetricsF(widget.font(), widget).horizontalAdvance(text))
+
+
+class ElidedLabel(QLabel):
+    """One-line label that cuts a text too long for its width with an ellipsis and shows the whole text as its tooltip.
+
+    Qt has no label that elides: a QLabel either wraps its text or asks for the whole text's width, which widens the
+    window. This label keeps the whole text (``text()`` returns it), paints only what fits, never asks for more width
+    than it is given, and offers the whole text as a tooltip only while it is cut.
+    """
+
+    def __init__(self, text: str = "", parent: QWidget | None = None, *, open_whole: bool = False) -> None:
+        """Take any width the layout offers and keep a one-line height.
+
+        ``open_whole`` is for a fixed sentence of the window rather than a value of any length: the window then opens
+        wide enough to show it whole (see ``fit_window_to_content``), and only a window the user narrows cuts it.
+        """
+        super().__init__(parent)
+        self.open_whole = open_whole
+        self.setTextFormat(Qt.TextFormat.PlainText)
+        policy = self.sizePolicy()
+        policy.setHorizontalPolicy(QSizePolicy.Policy.Ignored)
+        self.setSizePolicy(policy)
+        self.setText(text)
+
+    def setText(self, text: str) -> None:
+        """Keep the whole text and recompute whether it has to be cut."""
+        super().setText(text)
+        self._update_tooltip()
+
+    def _text_width(self) -> int:
+        """Return the width available to the text inside the label's margins."""
+        return max(0, self.contentsRect().width() - self.margin() * 2 - max(0, self.indent()))
+
+    def whole_text_width(self) -> int:
+        """Return the label width that shows the whole text, margins included."""
+        margins = self.contentsMargins()
+        return exact_text_width(self, self.text()) + self.margin() * 2 + max(0, self.indent()) + margins.left() + margins.right()
+
+    def displayed_text(self) -> str:
+        """Return the text as painted: whole when it fits, cut with an ellipsis otherwise."""
+        return self.fontMetrics().elidedText(self.text(), Qt.TextElideMode.ElideRight, self._text_width())
+
+    def _update_tooltip(self) -> None:
+        """Offer the whole text as a tooltip only while the label cuts it."""
+        self.setToolTip(self.text() if self.displayed_text() != self.text() else "")
+
+    def sizeHint(self) -> QSize:
+        """Ask for one line of text, and no width of its own."""
+        margins = self.contentsMargins()
+        return QSize(0, self.fontMetrics().height() + self.margin() * 2 + margins.top() + margins.bottom())
+
+    def minimumSizeHint(self) -> QSize:
+        """Allow any width down to nothing, at one line of height."""
+        return self.sizeHint()
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        """Recompute the tooltip, since a new width may cut the text or show it whole."""
+        super().resizeEvent(event)
+        self._update_tooltip()
+
+    def changeEvent(self, event: QEvent) -> None:
+        """Recompute the tooltip when a new font changes the text's width."""
+        super().changeEvent(event)
+        if event.type() == QEvent.Type.FontChange:
+            self._update_tooltip()
+
+    def paintEvent(self, event: QPaintEvent) -> None:
+        """Paint the text as it fits, with the label's alignment and the palette's text color."""
+        painter = QPainter(self)
+        rectangle = self.contentsRect().adjusted(self.margin() + max(0, self.indent()), self.margin(), -self.margin(), -self.margin())
+        self.style().drawItemText(painter, rectangle, int(self.alignment()), self.palette(), self.isEnabled(), self.displayed_text(), QPalette.ColorRole.WindowText)
+
+
+# The character Qt ends an elided text with.
+ELLIPSIS = "\u2026"
+PARAGRAPH_SEPARATOR = "\n"
+WORD_SEPARATOR = " "
+
+
+class LineLimitedLabel(QLabel):
+    """Label that wraps its text over at most a fixed number of lines and ends the last one with an ellipsis when cut.
+
+    ``text()`` answers the whole text, as ``ElidedLabel`` does, so every reader keeps seeing what was set; what the
+    native label holds and paints is the fitted text, which keeps native selection and painting. The label never asks
+    for a width of its own, so a long text cannot widen its window.
+    """
+
+    def __init__(self, text: str = "", line_count: int = 1, parent: QWidget | None = None) -> None:
+        """Keep the number of visible lines and take any width the layout offers."""
+        super().__init__(parent)
+        self.line_count = line_count
+        self.whole_text = ""
+        self.setTextFormat(Qt.TextFormat.PlainText)
+        self.setWordWrap(True)
+        policy = self.sizePolicy()
+        policy.setHorizontalPolicy(QSizePolicy.Policy.Ignored)
+        self.setSizePolicy(policy)
+        self.setText(text)
+
+    def setText(self, text: str) -> None:
+        """Keep the whole text and show what fits in the allowed lines at the current width."""
+        self.whole_text = text
+        self._fit()
+
+    def text(self) -> str:
+        """Answer the whole text, not the fitted one the native label paints.
+
+        Workaround: QLabel.text() is not virtual, so this override only answers Python callers; Qt itself keeps working
+        on the fitted text, which is what it must select and paint.
+        """
+        return self.whole_text
+
+    def displayed_text(self) -> str:
+        """Answer the text as painted: one line per visible line, the last one ending with an ellipsis when cut."""
+        return super().text()
+
+    def _text_width(self) -> int:
+        """Return the width available to the text inside the label's margins."""
+        return max(0, self.contentsRect().width() - self.margin() * 2 - max(0, self.indent()))
+
+    def _wrapped_lines(self, width: int) -> list[str]:
+        """Break the whole text into the lines it takes at this width, stopping one line past the allowed number.
+
+        Words too long for one line are broken anywhere, so an object ID or a path cannot run past the edge.
+        """
+        option = QTextOption()
+        option.setWrapMode(QTextOption.WrapMode.WrapAtWordBoundaryOrAnywhere)
+        lines: list[str] = []
+        for paragraph in self.whole_text.split(PARAGRAPH_SEPARATOR):
+            layout = QTextLayout(paragraph, self.font())
+            layout.setTextOption(option)
+            layout.beginLayout()
+            paragraph_line_count = 0
+            while len(lines) <= self.line_count:
+                line = layout.createLine()
+                if not line.isValid():
+                    break
+                line.setLineWidth(width)
+                lines.append(paragraph[line.textStart():line.textStart() + line.textLength()].rstrip())
+                paragraph_line_count += 1
+            layout.endLayout()
+            if not paragraph_line_count:
+                lines.append("")
+            if len(lines) > self.line_count:
+                break
+        return lines
+
+    def _fitted_text(self) -> str:
+        """Return the whole text when it fits in the allowed lines, otherwise those lines with an ellipsis at the end."""
+        width = self._text_width()
+        if width <= 0 or not self.whole_text:
+            return self.whole_text
+        lines = self._wrapped_lines(width)
+        if len(lines) <= self.line_count:
+            return PARAGRAPH_SEPARATOR.join(lines)
+        last_index = self.line_count - 1
+        # The line after the last visible one makes the last line too long, so Qt cuts it and adds its ellipsis.
+        last_line = self.fontMetrics().elidedText(lines[last_index] + WORD_SEPARATOR + lines[last_index + 1], Qt.TextElideMode.ElideRight, width)
+        if not last_line.endswith(ELLIPSIS):
+            last_line = self.fontMetrics().elidedText(lines[last_index] + ELLIPSIS, Qt.TextElideMode.ElideRight, width)
+        return PARAGRAPH_SEPARATOR.join([*lines[:last_index], last_line])
+
+    def _fit(self) -> None:
+        """Give the native label the fitted text, only when it differs, so an unchanged width never starts a new layout."""
+        fitted_text = self._fitted_text()
+        if super().text() != fitted_text:
+            super().setText(fitted_text)
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        """Fit the text again, since a new width changes where its lines break."""
+        super().resizeEvent(event)
+        self._fit()
+
+    def changeEvent(self, event: QEvent) -> None:
+        """Fit the text again when a new font changes the width of its characters."""
+        super().changeEvent(event)
+        if event.type() == QEvent.Type.FontChange:
+            self._fit()
+
+
+class ElidedCheckBox(QCheckBox):
+    """Check box that cuts a text too long for its width with an ellipsis and shows the whole text as its tooltip.
+
+    Like ``ElidedLabel`` for a check box: ``text()`` keeps the whole text, only what fits after the square is painted,
+    the box never asks for more width than it is given, and the tooltip carries the whole text only while it is cut.
+    """
+
+    def __init__(self, text: str = "", parent: QWidget | None = None, *, open_whole: bool = False) -> None:
+        """Take any width the layout offers and keep the check box's own height.
+
+        ``open_whole`` is for a fixed caption rather than one holding a value of any length: the window then opens wide
+        enough to show it whole (see ``fit_window_to_content``), and only a window the user narrows cuts it.
+        """
+        super().__init__(parent)
+        self.open_whole = open_whole
+        policy = self.sizePolicy()
+        policy.setHorizontalPolicy(QSizePolicy.Policy.Ignored)
+        self.setSizePolicy(policy)
+        self.setText(text)
+
+    def setText(self, text: str) -> None:
+        """Keep the whole text and recompute whether it has to be cut."""
+        super().setText(text)
+        self._update_tooltip()
+
+    def _indicator_space(self) -> int:
+        """Return the width the style gives the square and the space between it and the text."""
+        style = self.style()
+        return style.pixelMetric(QStyle.PixelMetric.PM_IndicatorWidth, None, self) + style.pixelMetric(QStyle.PixelMetric.PM_CheckBoxLabelSpacing, None, self)
+
+    def whole_text_width(self) -> int:
+        """Return the check box width that shows the square and the whole text."""
+        return self._indicator_space() + exact_text_width(self, self.text())
+
+    def displayed_text(self) -> str:
+        """Return the text as painted: whole when it fits after the square, cut with an ellipsis otherwise."""
+        return self.fontMetrics().elidedText(self.text(), Qt.TextElideMode.ElideRight, max(0, self.width() - self._indicator_space()))
+
+    def _update_tooltip(self) -> None:
+        """Offer the whole text as a tooltip only while the check box cuts it."""
+        self.setToolTip(self.text() if self.displayed_text() != self.text() else "")
+
+    def sizeHint(self) -> QSize:
+        """Ask for the square and the check box's height, and no width for the text."""
+        return QSize(self._indicator_space(), super().sizeHint().height())
+
+    def minimumSizeHint(self) -> QSize:
+        """Allow any width down to the square, at the check box's height."""
+        return self.sizeHint()
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        """Recompute the tooltip, since a new width may cut the text or show it whole."""
+        super().resizeEvent(event)
+        self._update_tooltip()
+
+    def changeEvent(self, event: QEvent) -> None:
+        """Recompute the tooltip when a new font or style changes the text's width."""
+        super().changeEvent(event)
+        if event.type() in (QEvent.Type.FontChange, QEvent.Type.StyleChange):
+            self._update_tooltip()
+
+    def paintEvent(self, event: QPaintEvent) -> None:
+        """Paint the native square, focus and state with the text as it fits."""
+        option = QStyleOptionButton()
+        self.initStyleOption(option)
+        option.text = self.displayed_text()
+        painter = QStylePainter(self)
+        painter.drawControl(QStyle.ControlElement.CE_CheckBox, option)
+
+
+class SelectionSummaryRow(QWidget):
+    """Keep a short counter beside a selector and reflow long explanations below it."""
+
+    def __init__(self, caption: QLabel, selector: QComboBox, summary: QLabel) -> None:
+        """Own one stable grid so reflow never reparents the live controls."""
+        super().__init__()
+        self.caption = caption
+        self.selector = selector
+        self.summary = summary
+        self.summary.setWordWrap(True)
+        self.summary_below = False
+        self.grid = QGridLayout(self)
+        self.grid.setContentsMargins(0, 0, 0, 0)
+        self.grid.setSpacing(SPACING_SM)
+        caption_column, selector_column, summary_column, selection_row = 0, 1, 2, 0
+        self.grid.addWidget(caption, selection_row, caption_column)
+        self.grid.addWidget(selector, selection_row, selector_column)
+        self.grid.addWidget(summary, selection_row, summary_column)
+        self.grid.setColumnStretch(selector_column, 1)
+
+    def event(self, event: QEvent) -> bool:
+        """Reconsider placement when text, font or available row width changes."""
+        result = super().event(event)
+        if event.type() in (QEvent.Type.Resize, QEvent.Type.LayoutRequest) and hasattr(self, "grid"):
+            self.place_summary()
+        return result
+
+    def place_summary(self) -> None:
+        """Put the explanation beside the selector while the row's width holds all three, below it otherwise.
+
+        The row decides on its own at its next layout pass; a window that measures its height right after the
+        explanation changed calls it first, so the measure sees the explanation where it will be shown.
+        """
+        required_width = self.caption.sizeHint().width() + self.selector.minimumSizeHint().width() + self.summary.sizeHint().width() + SPACING_SM * 2
+        below = required_width > self.width()
+        if below == self.summary_below:
+            return
+        self.summary_below = below
+        selection_row, explanation_row, first_column, summary_column, column_count = 0, 1, 0, 2, 3
+        self.grid.addWidget(self.summary, explanation_row if below else selection_row, first_column if below else summary_column, 1, column_count if below else 1)
+
+
+class WrappingRadioButton(QRadioButton):
+    """Keep native radio interaction while allowing its full description to wrap."""
+
+    def __init__(self, text: str, parent: QWidget | None = None) -> None:
+        """Delegate text layout to a label without intercepting mouse or keyboard input."""
+        super().__init__(text, parent)
+        self.description_label = WrappingLabel(text, self)
+        self.description_label.setWordWrap(True)
+        self.description_label.setTextFormat(Qt.TextFormat.PlainText)
+        self.description_label.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents)
+        policy = QSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)
+        policy.setHeightForWidth(True)
+        self.setSizePolicy(policy)
+
+    def _text_rect(self, width: int, height: int) -> QRect:
+        """Use the current native indicator and stylesheet padding to position the label."""
+        option = QStyleOptionButton()
+        self.initStyleOption(option)
+        option.rect = QRect(0, 0, width, height)
+        return self.style().subElementRect(QStyle.SubElement.SE_RadioButtonContents, option, self)
+
+    def heightForWidth(self, width: int) -> int:
+        """Reserve the full wrapped text height plus the band's shared vertical padding."""
+        text_rect = self._text_rect(width, self.fontMetrics().height() + SPACING_MD)
+        text_height = self.description_label.heightForWidth(max(1, text_rect.width()))
+        return control_height(max(self.fontMetrics().height(), text_height) + SPACING_SM)
+
+    def minimumSizeHint(self) -> QSize:
+        """Allow a narrow band to grow vertically instead of forcing horizontal scrolling."""
+        return QSize(SPACING_MD * 2, control_height(self.fontMetrics().height() + SPACING_SM))
+
+    def sizeHint(self) -> QSize:
+        """Keep the natural multiline width when space is available."""
+        width = super().sizeHint().width()
+        return QSize(width, self.heightForWidth(width))
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        """Place the passive description inside the native radio's text area."""
+        super().resizeEvent(event)
+        self.description_label.setGeometry(self._text_rect(self.width(), self.height()))
+
+    def paintEvent(self, event: QPaintEvent) -> None:
+        """Paint the styled native indicator and focus while the child paints wrapped text."""
+        option = QStyleOptionButton()
+        self.initStyleOption(option)
+        option.text = ""
+        painter = QStylePainter(self)
+        painter.drawControl(QStyle.ControlElement.CE_RadioButton, option)
+
+    def hitButton(self, position: QPoint) -> bool:
+        """Keep every visible wrapped line clickable as part of the same radio button."""
+        return self.rect().contains(position)

gitpane/ui/widget/mnemonic.py

@@ -0,0 +1,13 @@
+"""Qt keyboard mnemonics: a single ampersand in the text of a button or menu becomes a keyboard shortcut instead of being shown."""
+
+from __future__ import annotations
+
+# Qt turns a single "&" of a button or menu text into a keyboard mnemonic: the character after it is the key.
+MNEMONIC_MARKER = "&"
+# A doubled mnemonic marker is shown by Qt as a single "&" instead of a keyboard mnemonic.
+ESCAPED_MNEMONIC_MARKER = MNEMONIC_MARKER + MNEMONIC_MARKER
+
+
+def escape_mnemonic(text: str) -> str:
+    """Return text that a Qt button or menu shows exactly as given, instead of hiding each "&" as a mnemonic."""
+    return text.replace(MNEMONIC_MARKER, ESCAPED_MNEMONIC_MARKER)