gitpane 1.0.0__py3-none-any.whl

gitpane/ui/widget/numbered_text_edit.py

@@ -0,0 +1,127 @@
+"""Edit plain text with its line numbers in a margin."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, Qt
+from PySide6.QtGui import QPainter, QPalette
+from PySide6.QtWidgets import QPlainTextEdit, QWidget
+
+from gitpane.config import LAYOUT_SPACING, LINE_SEPARATOR, QT_PARAGRAPH_SEPARATOR, SPACING_XS
+from gitpane.ui.look.theme_color import line_number_gutter_color
+
+if TYPE_CHECKING:
+    from PySide6.QtCore import QRect
+    from PySide6.QtGui import QPaintEvent, QResizeEvent
+
+# Space on each side of the numbers, so the widest one touches neither the window edge nor the text; the layout spacing
+# keeps it in step with the space between the other controls of a window.
+LINE_NUMBER_MARGIN_PADDING = LAYOUT_SPACING
+# Space in the background of the text between the gutter and the first character, on top of Qt's own document margin,
+# so the numbers do not look stuck to the text.
+LINE_NUMBER_TEXT_GAP = SPACING_XS
+# Qt counts blocks from zero, an editor numbers lines from one.
+LINE_NUMBER_OF_FIRST_BLOCK = 1
+
+
+class LineNumberMargin(QWidget):
+    """Paint the number of each line of its editor beside the text, outside what the user selects or edits."""
+
+    def __init__(self, editor: NumberedTextEdit) -> None:
+        """Sit over the left viewport margin of the editor, which places it and tells it when to repaint."""
+        super().__init__(editor)
+        self.editor = editor
+
+    def visible_numbers(self) -> list[tuple[int, int]]:
+        """Answer the number and the top of each visible line, top to bottom, as the margin paints them.
+
+        One block is one line of the file, and its number sits on its first visual line when a message wraps.
+        """
+        numbers: list[tuple[int, int]] = []
+        bottom = self.editor.viewport().height()
+        block = self.editor.firstVisibleBlock()
+        while block.isValid():
+            top = round(self.editor.blockBoundingGeometry(block).translated(self.editor.contentOffset()).top())
+            if top > bottom:
+                break
+            if block.isVisible():
+                numbers.append((block.blockNumber() + LINE_NUMBER_OF_FIRST_BLOCK, top))
+            block = block.next()
+        return numbers
+
+    def paintEvent(self, event: QPaintEvent) -> None:
+        """Paint the visible numbers right-aligned on the gutter colour, in the font of the text, then the gap before the text in the text's background colour."""
+        painter = QPainter(self)
+        gutter_width = self.editor.margin_width()
+        viewport = self.editor.viewport()
+        painter.fillRect(0, event.rect().top(), gutter_width, event.rect().height(), line_number_gutter_color(self.palette()))
+        painter.fillRect(gutter_width, event.rect().top(), self.width() - gutter_width, event.rect().height(), viewport.palette().color(viewport.backgroundRole()))
+        painter.setFont(self.editor.font())
+        painter.setPen(self.palette().color(QPalette.ColorRole.Text))
+        height = self.editor.fontMetrics().height()
+        for number, top in self.visible_numbers():
+            if top > event.rect().bottom():
+                break
+            painter.drawText(0, top, gutter_width - LINE_NUMBER_MARGIN_PADDING, height, Qt.AlignmentFlag.AlignRight, str(number))
+
+
+class NumberedTextEdit(QPlainTextEdit):
+    """Edit plain text without any colouring, its lines numbered in a margin, and give the text back as it was typed.
+
+    The caller chooses how lines wrap: the widget numbers blocks, so a wrapped line keeps a single number.
+    """
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        """Attach the margin and keep it sized to the line count and in step with scrolling."""
+        super().__init__(parent)
+        self.number_margin = LineNumberMargin(self)
+        self.blockCountChanged.connect(self.refresh_margin)
+        self.updateRequest.connect(self.follow_update_request)
+        self.refresh_margin()
+
+    def raw_text(self) -> str:
+        """Answer the text with a line feed between lines and nothing else changed.
+
+        The plain text conversion of Qt turns no-break spaces into spaces and line separators into line feeds; the raw
+        text keeps them, and only Qt's own paragraph separator stands for a line feed.
+        """
+        return self.document().toRawText().replace(QT_PARAGRAPH_SEPARATOR, LINE_SEPARATOR)
+
+    def margin_width(self) -> int:
+        """Answer the width of the gutter: the widest line number of the current font, with its padding on both sides.
+
+        The margin beside the text is wider by the gap that keeps the numbers off the first character.
+        """
+        widest_number = str(max(LINE_NUMBER_OF_FIRST_BLOCK, self.blockCount()))
+        return self.fontMetrics().horizontalAdvance(widest_number) + 2 * LINE_NUMBER_MARGIN_PADDING
+
+    def refresh_margin(self) -> None:
+        """Make room for the gutter and the gap beside the text, then place the margin there."""
+        width = self.margin_width() + LINE_NUMBER_TEXT_GAP
+        if self.viewportMargins().left() != width:
+            self.setViewportMargins(width, 0, 0, 0)
+        self.place_margin()
+
+    def place_margin(self) -> None:
+        """Put the margin over the left viewport margin, as high as the text area."""
+        contents = self.contentsRect()
+        self.number_margin.setGeometry(contents.left(), contents.top(), self.viewportMargins().left(), contents.height())
+
+    def follow_update_request(self, rectangle: QRect, scrolled_by: int) -> None:
+        """Scroll the numbers with the text, or repaint the part of the margin beside the changed text."""
+        if scrolled_by:
+            self.number_margin.scroll(0, scrolled_by)
+            return
+        self.number_margin.update(0, rectangle.y(), self.number_margin.width(), rectangle.height())
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        """Keep the margin as high as the text area."""
+        super().resizeEvent(event)
+        self.place_margin()
+
+    def changeEvent(self, event: QEvent) -> None:
+        """Resize the margin when the font changes, since the numbers take the font of the text."""
+        super().changeEvent(event)
+        if event.type() == QEvent.Type.FontChange:
+            self.refresh_margin()

gitpane/ui/widget/plain_label.py

@@ -0,0 +1,15 @@
+"""Show untrusted text as plain, selectable, wrapped text."""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import QLabel
+
+
+def plain_label(text: str) -> QLabel:
+    """Show untrusted text such as an address or a path as plain, selectable, wrapped text."""
+    label = QLabel(text)
+    label.setTextFormat(Qt.TextFormat.PlainText)
+    label.setWordWrap(True)
+    label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse | Qt.TextInteractionFlag.TextSelectableByKeyboard)
+    return label

gitpane/ui/widget/plain_tooltip.py

@@ -0,0 +1,19 @@
+"""Qt tooltip shown as plain text, whatever the paths or names it carries contain."""
+
+from __future__ import annotations
+
+import html
+
+# Qt shows a tooltip as rich text when it looks like markup; lines are wrapped in a paragraph that keeps the spacing
+# of the text while still wrapping a long line, and joined with explicit line breaks.
+TOOLTIP_PLAIN_TEXT_START = "<p style='white-space:pre-wrap'>"
+TOOLTIP_PLAIN_TEXT_END = "</p>"
+TOOLTIP_LINE_BREAK = "<br>"
+
+
+def plain_text_tooltip(lines: list[str]) -> str:
+    """Build a tooltip that Qt shows as the given lines of plain text, whatever markup they contain."""
+    escaped_lines = []
+    for line in lines:
+        escaped_lines.append(html.escape(line))
+    return TOOLTIP_PLAIN_TEXT_START + TOOLTIP_LINE_BREAK.join(escaped_lines) + TOOLTIP_PLAIN_TEXT_END

gitpane/ui/widget/refresh_advice.py

@@ -0,0 +1,25 @@
+"""Write the advice that sends the user to the Refresh action of the repository window, with the shortcut of the system."""
+
+from __future__ import annotations
+
+import sys
+
+from PySide6.QtGui import QKeySequence
+
+from gitpane.config import SharedText
+from gitpane.ui.widget.shortcut_text import shortcut_text
+from gitpane.ui.widget.system_shortcut import refresh_shortcuts
+
+# A menu shows only the primary shortcut of an action, so the advice names that one too.
+PRIMARY_SHORTCUT_INDEX = 0
+
+
+def refresh_advice_text(advice: SharedText, platform: str = sys.platform, **values: str) -> str:
+    """Return the text of ``advice`` with the name of the Refresh action and its shortcut on ``platform`` filled in.
+
+    The label and the key are read from the action's own label and from the shortcut table rather than written in
+    the text, so a renamed action or a changed shortcut changes every advice at once and the advice can never cite a
+    key that does nothing. ``values`` fill the other fields of the text, such as a branch name.
+    """
+    shortcut = shortcut_text(QKeySequence(refresh_shortcuts(platform)[PRIMARY_SHORTCUT_INDEX]), platform)
+    return advice.value.format(refresh=SharedText.REFRESH.value, shortcut=shortcut, **values)

gitpane/ui/widget/result_label.py

@@ -0,0 +1,227 @@
+"""Show the result of an action in the colour of its tone: bold green success, bold red failure, bold orange attention, ordinary text otherwise."""
+
+from __future__ import annotations
+
+import weakref
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, Qt, QTimer
+from PySide6.QtGui import QColor, QPalette
+from PySide6.QtWidgets import QApplication
+from shiboken6 import isValid
+
+from gitpane.config import ERROR_DARK_COLOR, ERROR_LIGHT_COLOR, SUCCESS_DARK_COLOR, SUCCESS_LIGHT_COLOR, WARNING_DARK_COLOR, WARNING_LIGHT_COLOR
+from gitpane.ui.look.theme_color import is_dark_palette
+from gitpane.ui.look.theme_look import PALETTE_EVENT_TYPE_SET
+from gitpane.ui.widget.long_text import LineLimitedLabel, WrappingLabel
+
+if TYPE_CHECKING:
+    from PySide6.QtCore import QObject
+    from PySide6.QtWidgets import QWidget
+
+RESULT_STYLE_TEMPLATE = "color: {color}; font-weight: bold;"
+NEUTRAL_STYLE = ""
+# Events after which Qt may have drawn the label again from another palette or font than its style sheet's: a theme,
+# style, font or polish change. The colour of a shown result is checked again once they are over.
+RESTYLE_EVENT_TYPE_SET = PALETTE_EVENT_TYPE_SET | frozenset({QEvent.Type.StyleChange, QEvent.Type.FontChange, QEvent.Type.ApplicationFontChange,
+                                                             QEvent.Type.PolishRequest, QEvent.Type.ThemeChange})
+# Events after which the label may sit in another window than the one it watches for theme changes.
+WINDOW_TRACKING_EVENT_TYPE_SET = frozenset({QEvent.Type.Show, QEvent.Type.ParentChange})
+
+
+class ResultTone(Enum):
+    """Say whether the text shown is a success, a failure, a request to switch to another method, or none of these."""
+
+    NEUTRAL = "neutral"
+    SUCCESS = "success"
+    FAILURE = "failure"
+    WARNING = "warning"
+
+
+# Light and dark colour of each coloured tone; ordinary text has no colour of its own.
+COLOR_PAIR_BY_TONE = {
+    ResultTone.SUCCESS: (SUCCESS_LIGHT_COLOR, SUCCESS_DARK_COLOR),
+    ResultTone.FAILURE: (ERROR_LIGHT_COLOR, ERROR_DARK_COLOR),
+    ResultTone.WARNING: (WARNING_LIGHT_COLOR, WARNING_DARK_COLOR),
+}
+
+
+def result_color(tone: ResultTone, dark: bool) -> str:
+    """Return the colour of a tone in the theme's variant, or an empty text for ordinary text, which has none of its own."""
+    color_pair = COLOR_PAIR_BY_TONE.get(tone)
+    if color_pair is None:
+        return ""
+    light_color, dark_color = color_pair
+    return dark_color if dark else light_color
+
+
+def result_style_sheet(tone: ResultTone, dark: bool) -> str:
+    """Return the style sheet of a tone: bold green, red or orange in the theme's variant, nothing for ordinary text."""
+    color = result_color(tone, dark)
+    if not color:
+        return NEUTRAL_STYLE
+    return RESULT_STYLE_TEMPLATE.format(color=color)
+
+
+class ToneStyleMixin:
+    """Keep a widget drawn bold in the colour of its current tone, in the light or dark variant of the appearance in effect.
+
+    Mixed in front of a Qt widget class. The colour is carried by a style sheet, never by markup in the text, so a
+    diagnostic can never inject formatting. After any theme, style, font or polish change, the widget checks, once the
+    change is over, that it is still drawn bold in its tone's colour, and styles itself again if Qt drew it from another
+    palette or font.
+
+    A widget inside a window never hears of a theme change itself: its style sheet gives it a palette of its own, and
+    Qt only passes a new application palette to widgets without one. The widget therefore watches its window, which
+    does hear of it, from the moment it is shown or moved to another parent. The window is held through a weak
+    reference, so a closed window is never kept alive by one of its own widgets.
+
+    The state starts as class attributes so the widget's own constructor can already show text in a tone.
+    """
+
+    tone = ResultTone.NEUTRAL
+    style_check_pending = False
+    restyling = False
+    watched_window_reference: weakref.ReferenceType[QWidget] | None = None
+
+    def changeEvent(self, event: QEvent) -> None:
+        """Pick the light or dark colour again when the theme changes while a coloured text is shown."""
+        super().changeEvent(event)
+        if event.type() in PALETTE_EVENT_TYPE_SET:
+            self._apply_style()
+
+    def event(self, event: QEvent) -> bool:
+        """Check again, once the change is over, that a coloured text is still drawn in its colour after a theme, style, font or polish change."""
+        handled = super().event(event)
+        if event.type() in WINDOW_TRACKING_EVENT_TYPE_SET:
+            self._watch_window()
+        if event.type() in RESTYLE_EVENT_TYPE_SET:
+            self._schedule_style_check()
+        return handled
+
+    def eventFilter(self, watched: QObject, event: QEvent) -> bool:
+        """Check the colour again when the window the widget sits in changes palette; the event goes on as usual."""
+        if event.type() in PALETTE_EVENT_TYPE_SET and watched is self._watched_window():
+            self._schedule_style_check()
+        return super().eventFilter(watched, event)
+
+    def _watch_window(self) -> None:
+        """Watch the theme changes of the window the widget sits in now, and stop watching the one it left.
+
+        A widget that is a window itself receives them directly and watches nothing.
+        """
+        window = self.window()
+        current_window = None if window is self else window
+        previous_window = self._watched_window()
+        if current_window is previous_window:
+            return
+        if previous_window is not None:
+            previous_window.removeEventFilter(self)
+        self.watched_window_reference = None if current_window is None else weakref.ref(current_window)
+        if current_window is not None:
+            current_window.installEventFilter(self)
+
+    def _watched_window(self) -> QWidget | None:
+        """Answer the window watched for theme changes while it still exists, or nothing."""
+        if self.watched_window_reference is None:
+            return None
+        window = self.watched_window_reference()
+        if window is None or not isValid(window):
+            return None
+        return window
+
+    def _apply_style(self) -> None:
+        """Set the style of the current tone and theme, only when it differs, so a restyle never triggers another one."""
+        style_sheet = result_style_sheet(self.tone, is_dark_palette(QApplication.palette()))
+        if self.styleSheet() != style_sheet:
+            self.setStyleSheet(style_sheet)
+
+    def _schedule_style_check(self) -> None:
+        """Check the drawn colour once the current burst of style events is over; while restyling, the widget's own events are ignored."""
+        if self.style_check_pending or self.restyling or self.tone is ResultTone.NEUTRAL:
+            return
+        self.style_check_pending = True
+        QTimer.singleShot(0, self, self._check_style)
+
+    def _check_style(self) -> None:
+        """Style the widget again when a coloured text is no longer drawn bold in its tone's colour.
+
+        Setting the same style sheet again changes nothing in Qt, so the style is polished again instead. Polishing sends
+        palette and font events to the widget; they are ignored meanwhile, so one check never starts another.
+        """
+        self.style_check_pending = False
+        self._apply_style()
+        color = result_color(self.tone, is_dark_palette(QApplication.palette()))
+        if not color:
+            return
+        if self.palette().color(QPalette.ColorRole.WindowText) == QColor(color) and self.font().bold():
+            return
+        self.restyling = True
+        try:
+            self.style().unpolish(self)
+            self.style().polish(self)
+            self.update()
+        finally:
+            self.restyling = False
+
+
+class ResultToneMixin(ToneStyleMixin):
+    """Colour handling shared by every label that shows the result of an action: bold green, red or orange, or ordinary text.
+
+    Mixed in front of a ``QLabel`` subclass, so the label's own ``setText`` (wrapping, line limit) still lays the text
+    out. A result lost in ordinary text is easy to miss, so ``show_success`` and ``show_failure`` draw it bold green or
+    bold red, and ``show_warning`` draws in bold orange a result that is no error but needs the user's attention. Any
+    other text written with ``setText`` or ``clear`` (a wait message, an information line) goes back to the ordinary
+    look, so a wait never keeps the colour of the previous result. A shown result keeps its colour until other text
+    replaces it, through every theme change.
+    """
+
+    def setText(self, text: str) -> None:
+        """Show ordinary text, dropping the colour of any previous result."""
+        self.show_result(text, ResultTone.NEUTRAL)
+
+    def clear(self) -> None:
+        """Empty the label and drop the colour of any previous result."""
+        self.show_result("", ResultTone.NEUTRAL)
+
+    def show_success(self, text: str) -> None:
+        """Show the text of an action that worked, in bold green."""
+        self.show_result(text, ResultTone.SUCCESS)
+
+    def show_failure(self, text: str) -> None:
+        """Show the text of an action that failed or needs attention, in bold red."""
+        self.show_result(text, ResultTone.FAILURE)
+
+    def show_warning(self, text: str) -> None:
+        """Show, in bold orange, a result that is not an error but needs the user's attention."""
+        self.show_result(text, ResultTone.WARNING)
+
+    def show_result(self, text: str, tone: ResultTone) -> None:
+        """Show a text in the given tone; the text and its colour always change together."""
+        super().setText(text)
+        self.tone = tone
+        self._apply_style()
+
+
+class ResultLabel(ResultToneMixin, WrappingLabel):
+    """Plain, selectable, wrapped text whose colour says at a glance whether the last action worked.
+
+    Long words such as URLs wrap like in any other wrapping label, so a diagnostic never widens its window.
+    """
+
+    def __init__(self, text: str = "", parent: QWidget | None = None) -> None:
+        """Build the label with the same rendering as the other plain Settings labels, in the ordinary tone."""
+        super().__init__("", parent)
+        self.setTextFormat(Qt.TextFormat.PlainText)
+        self.setWordWrap(True)
+        self.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse | Qt.TextInteractionFlag.TextSelectableByKeyboard)
+        self.setText(text)
+
+
+class LineLimitedResultLabel(ResultToneMixin, LineLimitedLabel):
+    """Status text kept to a fixed number of lines, ending with an ellipsis when cut, whose colour says whether it is a result that needs attention.
+
+    The lines are measured with the font the label is drawn with, bold included, so a coloured result never runs past
+    the edge or past its last line.
+    """

gitpane/ui/widget/result_status_bar.py

@@ -0,0 +1,53 @@
+"""Show a status bar message in the colour of its result tone until another message replaces it."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtWidgets import QStatusBar
+
+from gitpane.ui.widget.result_label import ResultTone, ToneStyleMixin
+
+if TYPE_CHECKING:
+    from PySide6.QtWidgets import QWidget
+
+
+class ResultStatusBar(ToneStyleMixin, QStatusBar):
+    """A status bar that can show a failure bold red, in the error red of the appearance in effect, so a refusal there is not missed.
+
+    ``QStatusBar`` draws its message with the ``WindowText`` colour of its palette and with its own font, so the tone's
+    style sheet, set on the bar, colours and bolds the message. Any other message, written by ``showMessage``, by Qt
+    itself (a status tip, a message that times out) or cleared, goes back to the ordinary look: the red belongs to the
+    failure it was shown with. The colour follows a light or dark switch while the failure is shown.
+    """
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        """Build the bar in the ordinary tone, ready to drop a tone as soon as another message replaces the one it coloured."""
+        super().__init__(parent)
+        self.toned_message = ""
+        self.messageChanged.connect(self._drop_tone_of_replaced_message)
+
+    def showMessage(self, text: str, timeout: int = 0) -> None:
+        """Show an ordinary message, dropping the colour of any previous one, even when the text is the same."""
+        self.show_message_in_tone(text, ResultTone.NEUTRAL, timeout)
+
+    def show_failure(self, text: str) -> None:
+        """Show the message of an action that failed, in bold red, until another message replaces it."""
+        self.show_message_in_tone(text, ResultTone.FAILURE)
+
+    def show_message_in_tone(self, text: str, tone: ResultTone, timeout: int = 0) -> None:
+        """Show a message in the given tone; the message and its colour always change together."""
+        self.toned_message = text
+        self.tone = tone
+        self._apply_style()
+        super().showMessage(text, timeout)
+
+    def _drop_tone_of_replaced_message(self, text: str) -> None:
+        """Go back to the ordinary look once the bar shows another text than the one its tone was given with."""
+        if text == self.toned_message:
+            return
+        self.toned_message = text
+        if self.tone is ResultTone.NEUTRAL:
+            return
+        self.tone = ResultTone.NEUTRAL
+        self._apply_style()

gitpane/ui/widget/scrolled_text.py

@@ -0,0 +1,69 @@
+"""Show a text that may be longer than its window can hold in an area that scrolls, never asking the window's layout for more than a few lines.
+
+A label laid directly in a window makes the window's layout ask for the whole text as its minimum height, and Qt grows
+a window to its layout's minimum by itself: a Git or hook output of a hundred lines then makes the window taller than
+the screen, with the buttons under the text out of reach. In this area the layout counts the text at most at Qt's own
+minimum height of a scroll area, and at the text's height when it is shorter; the growth rule of the window then gives
+it the text's whole height up to its cap, and the text scrolls beyond.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, QSize, Qt
+from PySide6.QtWidgets import QFrame, QScrollArea
+
+from gitpane.ui.widget.dialog_layout import scrolled_content_missing_height
+
+if TYPE_CHECKING:
+    from PySide6.QtGui import QResizeEvent
+    from PySide6.QtWidgets import QLabel, QWidget
+
+
+class ScrolledText(QScrollArea):
+    """Hold one label in a frameless area, drawn on the window's own background, that scrolls once the window gives it less height than the text needs."""
+
+    def __init__(self, label: QLabel, parent: QWidget | None = None) -> None:
+        """Hold ``label``, which wraps to the area's width and scrolls only vertically."""
+        super().__init__(parent)
+        self.setFrameShape(QFrame.Shape.NoFrame)
+        self.setWidgetResizable(True)
+        self.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff)
+        self.setWidget(label)
+        # setWidget makes the label fill its background, and the viewport fills its own with the input colour: the text
+        # keeps the window's background instead, as when it was laid directly in the window.
+        label.setAutoFillBackground(False)
+        self.viewport().setAutoFillBackground(False)
+
+    def needed_height(self) -> int:
+        """Return the area's height that shows the whole text without scrolling, measured at the width the text has without a scroll bar."""
+        return self.height() + scrolled_content_missing_height(self)
+
+    def minimumSizeHint(self) -> QSize:
+        """Ask the window's layout for Qt's minimum height of a scroll area, or for the text's height when the text is shorter."""
+        hint = super().minimumSizeHint()
+        return QSize(hint.width(), min(hint.height(), self.needed_height()))
+
+    def sizeHint(self) -> QSize:
+        """Prefer the text's whole height, so a window with room to spare shows the text without scrolling."""
+        hint = super().sizeHint()
+        return QSize(hint.width(), self.needed_height())
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        """Tell the window's layout that the text's height changed with the area's width.
+
+        Qt keeps the size hints it read from the area until the area asks it to read them again, and the text's height
+        depends on the width: an area hidden when its window opened was measured at the size it was built with, wider
+        than the window gives it, and an area the user narrows takes more lines. Measured at the older width, the text
+        would hide its last lines behind a scroll bar while the window had room for them.
+        """
+        super().resizeEvent(event)
+        if event.oldSize().width() != event.size().width():
+            self.updateGeometry()
+
+    def viewportEvent(self, event: QEvent) -> bool:
+        """Tell the window's layout that the text changed, since the label only asks its own parent, the viewport, to lay it out again."""
+        if event.type() == QEvent.Type.LayoutRequest:
+            self.updateGeometry()
+        return super().viewportEvent(event)

gitpane/ui/widget/shortcut_text.py

@@ -0,0 +1,31 @@
+"""Write the text of a keyboard shortcut the way the user's system writes it."""
+
+from __future__ import annotations
+
+import sys
+
+from PySide6.QtGui import QKeySequence
+
+from gitpane.config import MACOS_PLATFORM
+
+# macOS writes its shortcuts with Apple key symbols; Windows and Linux write them in words, Qt's portable format.
+SHORTCUT_FORMAT_BY_PLATFORM: dict[str, QKeySequence.SequenceFormat] = {MACOS_PLATFORM: QKeySequence.SequenceFormat.NativeText}
+
+
+def shortcut_text(sequence: QKeySequence, platform: str = sys.platform) -> str:
+    """Return the text of a shortcut as the given system writes it.
+
+    Qt writes the text from the sequence itself, so it follows any change of the shortcut, and on macOS it puts the
+    Apple symbols in Apple's order with Ctrl standing for the Command key. A system missing from the table gets the
+    worded format rather than another system's symbols.
+    """
+    sequence_format = SHORTCUT_FORMAT_BY_PLATFORM.get(platform, QKeySequence.SequenceFormat.PortableText)
+    return sequence.toString(sequence_format)
+
+
+def with_shortcut(description: str, shortcut: str, platform: str = sys.platform) -> str:
+    """Return a tooltip made of a description followed by the text of its shortcut between parentheses.
+
+    The shortcut is the same portable sequence the action reacts to, so the tooltip can never cite another key.
+    """
+    return description + " (" + shortcut_text(QKeySequence(shortcut), platform) + ")"

gitpane/ui/widget/standard_icon_label.py

@@ -0,0 +1,55 @@
+"""Show one of the style's standard icons, drawn again whenever the palette changes."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent
+from PySide6.QtGui import QPixmap
+from PySide6.QtWidgets import QLabel
+
+from gitpane.ui.look.theme_look import PALETTE_EVENT_TYPE_SET
+
+if TYPE_CHECKING:
+    from PySide6.QtCore import QSize
+    from PySide6.QtWidgets import QStyle, QWidget
+
+# Events after which the style may draw the icon differently: another palette (a switch between the light and the dark
+# appearance) or another style.
+REDRAW_EVENT_TYPE_SET = PALETTE_EVENT_TYPE_SET | frozenset({QEvent.Type.StyleChange})
+
+
+class StandardIconLabel(QLabel):
+    """A fixed-size label showing a standard icon of the style, which follows a change of appearance while its window is open.
+
+    The style draws some icons after the palette they are shown on (the warning icon in the light or the dark warning
+    color, the question icon in the text color of a dark theme). An image set once would keep the look of the appearance
+    the window was opened in, so the label keeps which icon it shows and asks the style for it again after each palette
+    or style change. It must never get a style sheet: Qt does not pass palette changes on to a widget that has one.
+    """
+
+    def __init__(self, side: QSize, standard_pixmap: QStyle.StandardPixmap | None = None, parent: QWidget | None = None) -> None:
+        """Build the label at the icon's size, showing that icon, or nothing until one is chosen."""
+        super().__init__(parent)
+        self.side = side
+        self.standard_pixmap = standard_pixmap
+        self.setFixedSize(side)
+        self._draw_icon()
+
+    def set_standard_pixmap(self, standard_pixmap: QStyle.StandardPixmap | None) -> None:
+        """Show another standard icon, or no image at all, and keep it drawn after later palette changes."""
+        self.standard_pixmap = standard_pixmap
+        self._draw_icon()
+
+    def changeEvent(self, event: QEvent) -> None:
+        """Draw the icon again from the style once the palette or the style the label is shown with has changed."""
+        if event.type() in REDRAW_EVENT_TYPE_SET:
+            self._draw_icon()
+        super().changeEvent(event)
+
+    def _draw_icon(self) -> None:
+        """Lay the image of the chosen icon at the label's size, as the style draws it for this label's palette now."""
+        if self.standard_pixmap is None:
+            self.setPixmap(QPixmap())
+            return
+        self.setPixmap(self.style().standardIcon(self.standard_pixmap, None, self).pixmap(self.side))