gitpane 1.0.0__py3-none-any.whl

gitpane/ui/look/action_icon.py

@@ -0,0 +1,504 @@
+"""Draw compact native action symbols at the window's screen density."""
+
+from __future__ import annotations
+
+import functools
+import logging
+import math
+from importlib.resources import files
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QPointF, QRectF, Qt
+from PySide6.QtGui import QColor, QIcon, QPainter, QPainterPath, QPen, QPixmap, QPixmapCache
+
+from gitpane.config import ICON_SIDE, QT_ANGLE_UNITS_PER_DEGREE, UI_RESOURCE_DIR_NAME, UI_RESOURCE_PACKAGE_NAME
+from gitpane.worktree.worktree_snapshot import WorktreeColorState
+
+if TYPE_CHECKING:
+    from importlib.resources.abc import Traversable
+
+# Keys of the pixmaps this module keeps in Qt's shared pixmap cache, kept apart from any other user of that cache.
+ACTION_ICON_CACHE_PREFIX = "gitpane.action_icon/"
+PACKAGED_PIXMAP_CACHE_KIND = "packaged/"
+DRAWN_PIXMAP_CACHE_KIND = "drawn/"
+PIXMAP_CACHE_KEY_SEPARATOR = "|"
+# Colour of the Commit icon for each state of the worktree it summarizes.
+COMMIT_COLOR_BY_STATE: dict[WorktreeColorState, str] = {
+    WorktreeColorState.CLEAN: "#2a9d48", WorktreeColorState.UNSTAGED: "#ef7777", WorktreeColorState.STAGED: "#428bdb", WorktreeColorState.MIXED: "#e4b229",
+    WorktreeColorState.UNKNOWN: "#888888",
+}
+STAGING_ARROW_COLOR = "#9655ba"
+REFRESH_ARROW_COLOR = "#2a9d48"
+REVERT_ARROW_COLOR = STAGING_ARROW_COLOR
+SYMBOL_MARGIN_RATIO = 0.08
+CHECK_STROKE_RATIO = 0.12
+CHECK_START = (0.27, 0.51)
+CHECK_CORNER = (0.44, 0.68)
+CHECK_END = (0.75, 0.34)
+ARROW_SHOULDER_RATIO = 0.53
+ARROW_SHAFT_HALF_WIDTH_RATIO = 0.13
+ARROW_HEAD_HALF_WIDTH_RATIO = 0.34
+ARROW_REVERSE_DEGREES = 180
+REFRESH_RADIUS_RATIO = 0.32
+REFRESH_STROKE_RATIO = 0.14
+REFRESH_HEAD_LENGTH_RATIO = 0.29
+REFRESH_HEAD_HALF_WIDTH_RATIO = 0.19
+REFRESH_START_ANGLES = (35, 215)
+REFRESH_SWEEP_DEGREES = 130
+CENTER_RATIO = 0.5
+FULL_EXTENT_RATIO = 1.0
+TOOL_OUTLINE_WIDTH = 0.055
+DATABASE_OUTLINE_COLOR, DATABASE_FILL_COLOR = "#4b718d", "#a7cee7"
+DATABASE_BODY = QRectF(0.17, 0.23, 0.66, 0.53)
+DATABASE_CAP = QRectF(0.17, 0.11, 0.66, 0.24)
+DATABASE_BASE = QRectF(0.17, 0.64, 0.66, 0.24)
+DATABASE_DIVIDER_TOPS = (0.29, 0.47)
+HALF_CIRCLE_DEGREES = 180
+FOLDER_OUTLINE_COLOR, FOLDER_BACK_COLOR, FOLDER_FRONT_COLOR = "#a37421", "#e6b44e", "#ffda75"
+FOLDER_BACK_POINTS = ((0.08, 0.21), (0.40, 0.21), (0.50, 0.32), (0.88, 0.32), (0.88, 0.84), (0.08, 0.84))
+FOLDER_FRONT_POINTS = ((0.18, 0.44), (0.95, 0.44), (0.81, 0.84), (0.08, 0.84))
+TERMINAL_OUTLINE_COLOR, TERMINAL_FILL_COLOR = "#152631", "#304654"
+TERMINAL_BOUNDS = QRectF(0.07, 0.16, 0.86, 0.70)
+TERMINAL_CORNER_RADIUS, TERMINAL_PROMPT_WIDTH = 0.06, 0.07
+TERMINAL_PROMPT_POINTS = ((0.23, 0.36), (0.37, 0.50), (0.23, 0.64))
+TERMINAL_CURSOR_START, TERMINAL_CURSOR_END = (0.48, 0.65), (0.73, 0.65)
+GEAR_OUTLINE_COLOR, GEAR_FILL_COLOR = "#526270", "#b7c3cd"
+GEAR_TOOTH_COUNT = 8
+GEAR_TOOTH_POINTS = ((-0.5, 0.32), (-0.22, 0.45), (0.22, 0.45), (0.5, 0.32))
+GEAR_HOLE = QRectF(0.35, 0.35, 0.30, 0.30)
+TAG_RESOURCE_BY_SYMBOL = {"tag_create": "TagCreate.png", "tag_delete": "TagDelete.png", "tag": "Tag.png"}
+TRANSPORT_RESOURCE_BY_SYMBOL = {"fetch": "ArrowDown.png", "push": "ArrowUp.png"}
+CONFLICT_RESOURCE_BY_SYMBOL = {"stash": "Stash.png", "resolve": "Unmerged.png"}
+HISTORY_RESOURCE_BY_SYMBOL = {
+    "copy_hash": "CopyToClipboard.png",
+    "checkout_commit": "checkout.png",
+    "branch_checkout": "BranchCheckout.png",
+    "branch_create": "BranchCreate.png",
+    "branch_rename": "Renamed.png",
+    "branch_delete": "BranchDelete.png",
+    "reset_current": "ResetCurrentBranchToHere.png",
+    "reset_other": "ResetAnotherBranchToHere.png",
+}
+CHERRY_FRUIT_COLOR, CHERRY_FRUIT_OUTLINE_COLOR, CHERRY_HIGHLIGHT_COLOR = "#d42a32", "#8f161c", "#ffb3ab"
+CHERRY_STEM_COLOR, CHERRY_LEAF_COLOR = "#3c8a2c", "#5db444"
+CHERRY_FRUIT_RADIUS = 0.17
+CHERRY_FRUIT_CENTERS = ((0.26, 0.72), (0.74, 0.72))
+CHERRY_OUTLINE_WIDTH = 0.04
+CHERRY_HIGHLIGHT_OFFSET = (-0.06, -0.06)
+CHERRY_HIGHLIGHT_RADIUS = 0.045
+CHERRY_STEM_WIDTH = 0.08
+CHERRY_STEM_JOIN = (0.55, 0.13)
+CHERRY_STEM_CONTROLS = ((0.32, 0.30), (0.64, 0.34))
+CHERRY_LEAF_TIP = (0.88, 0.14)
+CHERRY_LEAF_CONTROLS = ((0.70, 0.00), (0.72, 0.26))
+# "Choose another revision": an original GitPane drawing of a list sheet with one row picked out and a pointer on it.
+REVISION_CHOICE_SHEET_COLOR, REVISION_CHOICE_OUTLINE_COLOR = "#ffffff", "#5b6b7a"
+REVISION_CHOICE_ROW_COLOR, REVISION_CHOICE_HIGHLIGHT_COLOR = "#9aa7b2", "#3d8ee6"
+REVISION_CHOICE_POINTER_COLOR, REVISION_CHOICE_POINTER_OUTLINE_COLOR = "#1d2429", "#ffffff"
+REVISION_CHOICE_SHEET = QRectF(0.08, 0.06, 0.70, 0.80)
+REVISION_CHOICE_CORNER_RADIUS = 0.08
+REVISION_CHOICE_ROW_LEFT, REVISION_CHOICE_ROW_RIGHT = 0.20, 0.66
+REVISION_CHOICE_ROW_TOPS = (0.24, 0.66)
+REVISION_CHOICE_ROW_WIDTH = 0.08
+REVISION_CHOICE_HIGHLIGHT = QRectF(0.13, 0.36, 0.60, 0.20)
+REVISION_CHOICE_POINTER_POINTS = ((0.58, 0.44), (0.58, 0.98), (0.71, 0.86), (0.80, 1.00), (0.90, 0.95), (0.81, 0.81), (0.97, 0.80))
+REVISION_CHOICE_POINTER_OUTLINE_WIDTH = 0.06
+# "Rebase": an original GitPane drawing of a grey target branch with blue commits that a curved arrow brings down onto it.
+REBASE_TARGET_COLOR, REBASE_MOVED_COLOR = "#6e6e6e", "#00a2e8"
+REBASE_LANE_WIDTH = 0.08
+REBASE_COMMIT_RADIUS = 0.11
+REBASE_TARGET_X, REBASE_TARGET_TOP, REBASE_TARGET_BOTTOM = 0.24, 0.04, 0.96
+REBASE_TARGET_COMMIT_YS = (0.15, 0.50, 0.85)
+REBASE_MOVED_X, REBASE_MOVED_TOP, REBASE_MOVED_BOTTOM = 0.78, 0.12, 0.40
+REBASE_MOVED_COMMIT_YS = (0.12, 0.40)
+REBASE_CURVE_WIDTH = 0.12
+REBASE_CURVE_CONTROL, REBASE_CURVE_END = (0.80, 0.85), (0.55, 0.85)
+REBASE_ARROW_TIP = (0.38, 0.85)
+REBASE_ARROW_TAIL_X = 0.58
+REBASE_ARROW_HEAD_LENGTH, REBASE_ARROW_HEAD_HALF_HEIGHT = 0.19, 0.16
+# Stash and Stash pop: original GitPane drawings of a sheet in a gold tray, laid out on a 16-unit grid so the one-unit outlines land on
+# whole pixels at native size. tools/draw_conflict_icon.py imports this geometry to regenerate the packaged Stash picture.
+STASH_CANVAS_UNITS = 16
+STASH_OUTLINE_WIDTH = 1.0
+STASH_PAPER_COLOR = "#fff7da"
+STASH_TRAY_POINTS = ((2, 8), (5, 8), (5, 10), (11, 10), (11, 8), (14, 8), (13, 14), (3, 14))
+STASH_TRAY_LIP_START, STASH_TRAY_LIP_END = (5, 12), (11, 12)
+# Stash pop raises the sheet out of the tray and puts a green arrow pointing up on it.
+STASH_POP_PAPER_BOUNDS = QRectF(4, 0.5, 8, 8)
+STASH_POP_ARROW_OUTLINE_COLOR = "#1d6e33"
+STASH_POP_ARROW_OUTLINE_WIDTH = 0.8
+STASH_POP_ARROW_CENTER_X, STASH_POP_ARROW_TOP, STASH_POP_ARROW_BOTTOM = 8, 1.5, 7.5
+STASH_POP_ARROW_HEAD_HALF_WIDTH, STASH_POP_ARROW_SHAFT_HALF_WIDTH, STASH_POP_ARROW_HEAD_LENGTH = 2.8, 1.1, 3.0
+# Add and remove signs for list buttons: a green plus adds an entry, a red minus removes the selected one. Both colors keep
+# at least a 3:1 contrast on light and dark window backgrounds.
+ADD_SYMBOL_COLOR = "#2ea043"
+REMOVE_SYMBOL_COLOR = "#e5383b"
+SIGN_STROKE_RATIO = 0.1875
+SIGN_MARGIN_RATIO = 0.1875
+
+
+@functools.cache
+def packaged_resource_bytes(resource: Traversable) -> bytes:
+    """Read one packaged picture once per session instead of at every menu, toolbar or density refresh.
+
+    The key is the resolved resource, a full path rather than a file name, so a package replaced by another one is
+    read again. A failed read raises and is never remembered: only successful reads are kept.
+    """
+    return resource.read_bytes()
+
+
+def action_icon(symbol: str, density: float = 1.0, state: WorktreeColorState = WorktreeColorState.UNKNOWN) -> QIcon:
+    """Render recognizable action symbols with transparent corners and crisp screen scaling.
+
+    Decoded and drawn pixmaps are kept in Qt's own pixmap cache, which is bounded and emptied with the application,
+    so the same symbol at the same density and state is neither decoded nor drawn twice. A missing or unreadable
+    packaged picture is never cached: every use gives a null icon and the same warning.
+    """
+    resource_by_symbol = {**TAG_RESOURCE_BY_SYMBOL, **TRANSPORT_RESOURCE_BY_SYMBOL, **HISTORY_RESOURCE_BY_SYMBOL, **CONFLICT_RESOURCE_BY_SYMBOL}
+    if symbol in resource_by_symbol:
+        # Resolving the resource does not touch the disk; it gives the full path the caches are keyed on.
+        resource = files(UI_RESOURCE_PACKAGE_NAME).joinpath(UI_RESOURCE_DIR_NAME, resource_by_symbol[symbol])
+        cache_key = ACTION_ICON_CACHE_PREFIX + PACKAGED_PIXMAP_CACHE_KIND + PIXMAP_CACHE_KEY_SEPARATOR.join((str(resource), str(density)))
+        cached_pixmap = QPixmapCache.find(cache_key)
+        if cached_pixmap is not None:
+            return QIcon(cached_pixmap)
+        pixmap = QPixmap()
+        try:
+            content = packaged_resource_bytes(resource)
+            if not pixmap.loadFromData(content, "PNG"):
+                raise ValueError("Invalid packaged PNG")
+        except (OSError, ValueError):
+            logging.getLogger(__name__).warning("Cannot load packaged action icon %s; keeping the action label", resource_by_symbol[symbol])
+            return QIcon()
+        side = round(ICON_SIDE * density)
+        pixmap = pixmap.scaled(side, side, Qt.AspectRatioMode.KeepAspectRatio, Qt.TransformationMode.SmoothTransformation)
+        pixmap.setDevicePixelRatio(density)
+        QPixmapCache.insert(cache_key, pixmap)
+        return QIcon(pixmap)
+    cache_key = ACTION_ICON_CACHE_PREFIX + DRAWN_PIXMAP_CACHE_KIND + PIXMAP_CACHE_KEY_SEPARATOR.join((symbol, str(density), state.value))
+    cached_pixmap = QPixmapCache.find(cache_key)
+    if cached_pixmap is not None:
+        return QIcon(cached_pixmap)
+    pixmap = QPixmap(round(ICON_SIDE * density), round(ICON_SIDE * density))
+    pixmap.setDevicePixelRatio(density)
+    pixmap.fill(Qt.GlobalColor.transparent)
+    painter = QPainter(pixmap)
+    painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+    painter.scale(ICON_SIDE, ICON_SIDE)
+    painter.setPen(Qt.PenStyle.NoPen)
+    if symbol == "commit":
+        painter.setBrush(QColor(COMMIT_COLOR_BY_STATE[state]))
+        inset = SYMBOL_MARGIN_RATIO
+        diameter = FULL_EXTENT_RATIO - inset - inset
+        painter.drawEllipse(QRectF(inset, inset, diameter, diameter))
+        painter.setBrush(Qt.BrushStyle.NoBrush)
+        painter.setPen(QPen(Qt.GlobalColor.white, CHECK_STROKE_RATIO, Qt.PenStyle.SolidLine, Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin))
+        check = QPainterPath(QPointF(*CHECK_START))
+        check.lineTo(QPointF(*CHECK_CORNER))
+        check.lineTo(QPointF(*CHECK_END))
+        painter.drawPath(check)
+    elif symbol in ("stage", "unstage"):
+        if symbol == "unstage":
+            painter.translate(FULL_EXTENT_RATIO, FULL_EXTENT_RATIO)
+            painter.rotate(ARROW_REVERSE_DEGREES)
+        painter.setBrush(QColor(STAGING_ARROW_COLOR))
+        arrow = QPainterPath(QPointF(CENTER_RATIO - ARROW_SHAFT_HALF_WIDTH_RATIO, SYMBOL_MARGIN_RATIO))
+        arrow.lineTo(CENTER_RATIO + ARROW_SHAFT_HALF_WIDTH_RATIO, SYMBOL_MARGIN_RATIO)
+        arrow.lineTo(CENTER_RATIO + ARROW_SHAFT_HALF_WIDTH_RATIO, ARROW_SHOULDER_RATIO)
+        arrow.lineTo(CENTER_RATIO + ARROW_HEAD_HALF_WIDTH_RATIO, ARROW_SHOULDER_RATIO)
+        arrow.lineTo(CENTER_RATIO, FULL_EXTENT_RATIO - SYMBOL_MARGIN_RATIO)
+        arrow.lineTo(CENTER_RATIO - ARROW_HEAD_HALF_WIDTH_RATIO, ARROW_SHOULDER_RATIO)
+        arrow.lineTo(CENTER_RATIO - ARROW_SHAFT_HALF_WIDTH_RATIO, ARROW_SHOULDER_RATIO)
+        arrow.closeSubpath()
+        painter.drawPath(arrow)
+    elif symbol == "refresh":
+        _paint_refresh(painter, REFRESH_ARROW_COLOR)
+    elif symbol == "repository":
+        _paint_database(painter)
+    elif symbol == "folder":
+        _paint_folder(painter)
+    elif symbol == "terminal":
+        _paint_terminal(painter)
+    elif symbol == "settings":
+        _paint_gear(painter)
+    elif symbol == "cherry_pick":
+        _paint_cherry(painter)
+    elif symbol == "revert":
+        _paint_refresh(painter, REVERT_ARROW_COLOR)
+    elif symbol == "choose_revision":
+        _paint_revision_choice(painter)
+    elif symbol == "rebase":
+        _paint_rebase(painter)
+    elif symbol == "stash_pop":
+        _paint_stash_pop(painter)
+    elif symbol == "add_remote":
+        _paint_add_sign(painter, density)
+    elif symbol == "remove_remote":
+        _paint_remove_sign(painter, density)
+    else:
+        painter.end()
+        raise ValueError("Unknown action icon: " + symbol)
+    painter.end()
+    QPixmapCache.insert(cache_key, pixmap)
+    return QIcon(pixmap)
+
+
+def _sign_bars(density: float) -> tuple[QRectF, QRectF]:
+    """Return the horizontal and upright bars of the signs, laid on whole screen pixels so their edges stay sharp.
+
+    The bar thickness keeps the parity of the icon side, so a bar centred in the icon starts and ends on pixel borders at
+    every density instead of being smeared over two half-covered rows.
+    """
+    side_pixels = round(ICON_SIDE * density)
+    thickness_pixels = side_pixels - 2 * round((side_pixels - side_pixels * SIGN_STROKE_RATIO) / 2)
+    margin_pixels = round(side_pixels * SIGN_MARGIN_RATIO)
+    bar_start_pixels = (side_pixels - thickness_pixels) // 2
+    length_pixels = side_pixels - 2 * margin_pixels
+    pixel = FULL_EXTENT_RATIO / (ICON_SIDE * density)
+    horizontal = QRectF(margin_pixels * pixel, bar_start_pixels * pixel, length_pixels * pixel, thickness_pixels * pixel)
+    upright = QRectF(bar_start_pixels * pixel, margin_pixels * pixel, thickness_pixels * pixel, length_pixels * pixel)
+    return horizontal, upright
+
+
+def _paint_add_sign(painter: QPainter, density: float) -> None:
+    """Draw a green plus centred in the icon, the usual picture for adding an entry to a list."""
+    horizontal, upright = _sign_bars(density)
+    _fill_pixel_aligned(painter, (horizontal, upright), ADD_SYMBOL_COLOR)
+
+
+def _paint_remove_sign(painter: QPainter, density: float) -> None:
+    """Draw a red minus with the same bar as the plus, the usual picture for removing the selected entry."""
+    horizontal, _upright = _sign_bars(density)
+    _fill_pixel_aligned(painter, (horizontal,), REMOVE_SYMBOL_COLOR)
+
+
+def _fill_pixel_aligned(painter: QPainter, rectangles: tuple[QRectF, ...], color: str) -> None:
+    """Fill rectangles that already sit on pixel borders without smoothing, so rounding never leaves a faint edge column."""
+    painter.save()
+    painter.setRenderHint(QPainter.RenderHint.Antialiasing, False)
+    for rectangle in rectangles:
+        painter.fillRect(rectangle, QColor(color))
+    painter.restore()
+
+
+def _paint_cherry(painter: QPainter) -> None:
+    """Draw a pair of red cherries hanging from joined green stems with a small leaf, the familiar picture of picking one fruit."""
+    painter.setBrush(Qt.BrushStyle.NoBrush)
+    painter.setPen(QPen(QColor(CHERRY_STEM_COLOR), CHERRY_STEM_WIDTH, Qt.PenStyle.SolidLine, Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin))
+    for (center_x, center_y), control in zip(CHERRY_FRUIT_CENTERS, CHERRY_STEM_CONTROLS, strict=True):
+        stem = QPainterPath(QPointF(center_x, center_y - CHERRY_FRUIT_RADIUS))
+        stem.quadTo(QPointF(*control), QPointF(*CHERRY_STEM_JOIN))
+        painter.drawPath(stem)
+    upper_leaf_control, lower_leaf_control = CHERRY_LEAF_CONTROLS
+    leaf = QPainterPath(QPointF(*CHERRY_STEM_JOIN))
+    leaf.quadTo(QPointF(*upper_leaf_control), QPointF(*CHERRY_LEAF_TIP))
+    leaf.quadTo(QPointF(*lower_leaf_control), QPointF(*CHERRY_STEM_JOIN))
+    painter.setPen(Qt.PenStyle.NoPen)
+    painter.setBrush(QColor(CHERRY_LEAF_COLOR))
+    painter.drawPath(leaf)
+    highlight_offset_x, highlight_offset_y = CHERRY_HIGHLIGHT_OFFSET
+    for center_x, center_y in CHERRY_FRUIT_CENTERS:
+        painter.setPen(QPen(QColor(CHERRY_FRUIT_OUTLINE_COLOR), CHERRY_OUTLINE_WIDTH))
+        painter.setBrush(QColor(CHERRY_FRUIT_COLOR))
+        painter.drawEllipse(QPointF(center_x, center_y), CHERRY_FRUIT_RADIUS, CHERRY_FRUIT_RADIUS)
+        painter.setPen(Qt.PenStyle.NoPen)
+        painter.setBrush(QColor(CHERRY_HIGHLIGHT_COLOR))
+        painter.drawEllipse(QPointF(center_x + highlight_offset_x, center_y + highlight_offset_y), CHERRY_HIGHLIGHT_RADIUS, CHERRY_HIGHLIGHT_RADIUS)
+
+
+def _paint_revision_choice(painter: QPainter) -> None:
+    """Draw a list sheet with one highlighted row and a mouse pointer on it, for the button that picks another commit.
+
+    The drawing is GitPane's own: it says "pick one entry from a list" with shapes every desktop user knows, so the
+    replay form does not need artwork from another program.
+    """
+    painter.setPen(QPen(QColor(REVISION_CHOICE_OUTLINE_COLOR), TOOL_OUTLINE_WIDTH))
+    painter.setBrush(QColor(REVISION_CHOICE_SHEET_COLOR))
+    painter.drawRoundedRect(REVISION_CHOICE_SHEET, REVISION_CHOICE_CORNER_RADIUS, REVISION_CHOICE_CORNER_RADIUS)
+    painter.setPen(QPen(QColor(REVISION_CHOICE_ROW_COLOR), REVISION_CHOICE_ROW_WIDTH, Qt.PenStyle.SolidLine, Qt.PenCapStyle.FlatCap))
+    for top in REVISION_CHOICE_ROW_TOPS:
+        painter.drawLine(QPointF(REVISION_CHOICE_ROW_LEFT, top), QPointF(REVISION_CHOICE_ROW_RIGHT, top))
+    painter.setPen(Qt.PenStyle.NoPen)
+    painter.setBrush(QColor(REVISION_CHOICE_HIGHLIGHT_COLOR))
+    painter.drawRect(REVISION_CHOICE_HIGHLIGHT)
+    first_point, *remaining_points = REVISION_CHOICE_POINTER_POINTS
+    pointer = QPainterPath(QPointF(*first_point))
+    for point in remaining_points:
+        pointer.lineTo(*point)
+    pointer.closeSubpath()
+    painter.setPen(QPen(QColor(REVISION_CHOICE_POINTER_OUTLINE_COLOR), REVISION_CHOICE_POINTER_OUTLINE_WIDTH, Qt.PenStyle.SolidLine, Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin))
+    painter.setBrush(QColor(REVISION_CHOICE_POINTER_COLOR))
+    painter.drawPath(pointer)
+
+
+def paint_polygon(painter: QPainter, points: tuple[tuple[float, float], ...]) -> None:
+    """Fill and outline one closed shape given as a sequence of vertices, with the painter's current pen and brush."""
+    first_point, *remaining_points = points
+    path = QPainterPath(QPointF(*first_point))
+    for point in remaining_points:
+        path.lineTo(QPointF(*point))
+    path.closeSubpath()
+    painter.drawPath(path)
+
+
+def paint_stash_tray(painter: QPainter) -> None:
+    """Draw the gold tray of the Stash drawings in the 16-unit canvas, in front of whatever sheet was painted before it."""
+    painter.setPen(QPen(QColor(FOLDER_OUTLINE_COLOR), STASH_OUTLINE_WIDTH))
+    painter.setBrush(QColor(FOLDER_FRONT_COLOR))
+    paint_polygon(painter, STASH_TRAY_POINTS)
+    painter.drawLine(QPointF(*STASH_TRAY_LIP_START), QPointF(*STASH_TRAY_LIP_END))
+
+
+def _paint_stash_pop(painter: QPainter) -> None:
+    """Draw the Stash tray with its sheet raised out of it and a green arrow pointing up on the sheet: saved work coming back out.
+
+    The drawing is GitPane's own, built from the Stash drawing so both toolbar buttons read as a pair.
+    """
+    painter.scale(1 / STASH_CANVAS_UNITS, 1 / STASH_CANVAS_UNITS)
+    painter.setPen(QPen(QColor(FOLDER_OUTLINE_COLOR), STASH_OUTLINE_WIDTH))
+    painter.setBrush(QColor(STASH_PAPER_COLOR))
+    painter.drawRect(STASH_POP_PAPER_BOUNDS)
+    center_x, top, bottom = STASH_POP_ARROW_CENTER_X, STASH_POP_ARROW_TOP, STASH_POP_ARROW_BOTTOM
+    head_half, shaft_half = STASH_POP_ARROW_HEAD_HALF_WIDTH, STASH_POP_ARROW_SHAFT_HALF_WIDTH
+    shoulder = top + STASH_POP_ARROW_HEAD_LENGTH
+    painter.setPen(QPen(QColor(STASH_POP_ARROW_OUTLINE_COLOR), STASH_POP_ARROW_OUTLINE_WIDTH))
+    painter.setBrush(QColor(REFRESH_ARROW_COLOR))
+    paint_polygon(painter, ((center_x, top), (center_x + head_half, shoulder), (center_x + shaft_half, shoulder), (center_x + shaft_half, bottom),
+                            (center_x - shaft_half, bottom), (center_x - shaft_half, shoulder), (center_x - head_half, shoulder)))
+    paint_stash_tray(painter)
+
+
+def _paint_lane(painter: QPainter, color_name: str, x: float, top: float, bottom: float, commit_ys: tuple[float, ...]) -> None:
+    """Draw one vertical branch line with a round commit dot at each given height, like a lane of the history graph."""
+    color = QColor(color_name)
+    painter.setPen(QPen(color, REBASE_LANE_WIDTH, Qt.PenStyle.SolidLine, Qt.PenCapStyle.FlatCap))
+    painter.drawLine(QPointF(x, top), QPointF(x, bottom))
+    painter.setPen(Qt.PenStyle.NoPen)
+    painter.setBrush(color)
+    for commit_y in commit_ys:
+        painter.drawEllipse(QPointF(x, commit_y), REBASE_COMMIT_RADIUS, REBASE_COMMIT_RADIUS)
+
+
+def _paint_rebase(painter: QPainter) -> None:
+    """Draw commits being moved onto another branch: a grey target lane, blue commits beside it and a curved blue arrow landing on the target.
+
+    The drawing is GitPane's own, made from the maintainer's sketch, so the rebase entry no longer borrows the reset picture.
+    """
+    _paint_lane(painter, REBASE_TARGET_COLOR, REBASE_TARGET_X, REBASE_TARGET_TOP, REBASE_TARGET_BOTTOM, REBASE_TARGET_COMMIT_YS)
+    _paint_lane(painter, REBASE_MOVED_COLOR, REBASE_MOVED_X, REBASE_MOVED_TOP, REBASE_MOVED_BOTTOM, REBASE_MOVED_COMMIT_YS)
+    moved_color = QColor(REBASE_MOVED_COLOR)
+    curve = QPainterPath(QPointF(REBASE_MOVED_X, REBASE_MOVED_BOTTOM))
+    curve.quadTo(QPointF(*REBASE_CURVE_CONTROL), QPointF(*REBASE_CURVE_END))
+    painter.setPen(QPen(moved_color, REBASE_CURVE_WIDTH, Qt.PenStyle.SolidLine, Qt.PenCapStyle.FlatCap))
+    painter.setBrush(Qt.BrushStyle.NoBrush)
+    painter.drawPath(curve)
+    tip_x, tip_y = REBASE_ARROW_TIP
+    head_base_x = tip_x + REBASE_ARROW_HEAD_LENGTH
+    shaft_half_height = REBASE_CURVE_WIDTH * CENTER_RATIO
+    arrow = QPainterPath(QPointF(tip_x, tip_y))
+    arrow.lineTo(head_base_x, tip_y - REBASE_ARROW_HEAD_HALF_HEIGHT)
+    arrow.lineTo(head_base_x, tip_y - shaft_half_height)
+    arrow.lineTo(REBASE_ARROW_TAIL_X, tip_y - shaft_half_height)
+    arrow.lineTo(REBASE_ARROW_TAIL_X, tip_y + shaft_half_height)
+    arrow.lineTo(head_base_x, tip_y + shaft_half_height)
+    arrow.lineTo(head_base_x, tip_y + REBASE_ARROW_HEAD_HALF_HEIGHT)
+    arrow.closeSubpath()
+    painter.setPen(Qt.PenStyle.NoPen)
+    painter.setBrush(moved_color)
+    painter.drawPath(arrow)
+
+
+def _paint_database(painter: QPainter) -> None:
+    """Draw a stacked cylinder that identifies a repository as a stored collection."""
+    painter.setPen(QPen(QColor(DATABASE_OUTLINE_COLOR), TOOL_OUTLINE_WIDTH))
+    painter.setBrush(QColor(DATABASE_FILL_COLOR))
+    painter.drawEllipse(DATABASE_BASE)
+    painter.setPen(Qt.PenStyle.NoPen)
+    painter.drawRect(DATABASE_BODY)
+    painter.setPen(QPen(QColor(DATABASE_OUTLINE_COLOR), TOOL_OUTLINE_WIDTH))
+    painter.drawLine(DATABASE_BODY.topLeft(), DATABASE_BODY.bottomLeft())
+    painter.drawLine(DATABASE_BODY.topRight(), DATABASE_BODY.bottomRight())
+    painter.setBrush(Qt.BrushStyle.NoBrush)
+    for top in DATABASE_DIVIDER_TOPS:
+        bounds = QRectF(DATABASE_CAP)
+        bounds.moveTop(top)
+        painter.drawArc(bounds, HALF_CIRCLE_DEGREES * QT_ANGLE_UNITS_PER_DEGREE, HALF_CIRCLE_DEGREES * QT_ANGLE_UNITS_PER_DEGREE)
+    painter.setBrush(QColor(DATABASE_FILL_COLOR).lighter())
+    painter.drawEllipse(DATABASE_CAP)
+
+
+def _paint_folder(painter: QPainter) -> None:
+    """Draw a yellow folder with a raised tab and an open front."""
+    painter.setPen(QPen(QColor(FOLDER_OUTLINE_COLOR), TOOL_OUTLINE_WIDTH, Qt.PenStyle.SolidLine, Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin))
+    for points, color in ((FOLDER_BACK_POINTS, FOLDER_BACK_COLOR), (FOLDER_FRONT_POINTS, FOLDER_FRONT_COLOR)):
+        path = QPainterPath()
+        first_point, *remaining_points = points
+        path.moveTo(*first_point)
+        for point in remaining_points:
+            path.lineTo(*point)
+        path.closeSubpath()
+        painter.setBrush(QColor(color))
+        painter.drawPath(path)
+
+
+def _paint_terminal(painter: QPainter) -> None:
+    """Draw a dark terminal window with a high-contrast prompt and cursor."""
+    painter.setPen(QPen(QColor(TERMINAL_OUTLINE_COLOR), TOOL_OUTLINE_WIDTH))
+    painter.setBrush(QColor(TERMINAL_FILL_COLOR))
+    painter.drawRoundedRect(TERMINAL_BOUNDS, TERMINAL_CORNER_RADIUS, TERMINAL_CORNER_RADIUS)
+    painter.setPen(QPen(Qt.GlobalColor.white, TERMINAL_PROMPT_WIDTH, Qt.PenStyle.SolidLine, Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin))
+    first_point, *remaining_points = TERMINAL_PROMPT_POINTS
+    prompt = QPainterPath(QPointF(*first_point))
+    for point in remaining_points:
+        prompt.lineTo(*point)
+    painter.setBrush(Qt.BrushStyle.NoBrush)
+    painter.drawPath(prompt)
+    painter.drawLine(QPointF(*TERMINAL_CURSOR_START), QPointF(*TERMINAL_CURSOR_END))
+
+
+def _paint_gear(painter: QPainter) -> None:
+    """Draw eight teeth around an open center so settings remains legible at small sizes."""
+    path = QPainterPath()
+    started = False
+    for tooth in range(GEAR_TOOTH_COUNT):
+        for offset, radius in GEAR_TOOTH_POINTS:
+            angle = (tooth + offset) * math.tau / GEAR_TOOTH_COUNT
+            point = QPointF(CENTER_RATIO + radius * math.cos(angle), CENTER_RATIO + radius * math.sin(angle))
+            if not started:
+                path.moveTo(point)
+                started = True
+            else:
+                path.lineTo(point)
+    path.closeSubpath()
+    path.addEllipse(GEAR_HOLE)
+    path.setFillRule(Qt.FillRule.OddEvenFill)
+    painter.setPen(QPen(QColor(GEAR_OUTLINE_COLOR), TOOL_OUTLINE_WIDTH, Qt.PenStyle.SolidLine, Qt.PenCapStyle.RoundCap, Qt.PenJoinStyle.RoundJoin))
+    painter.setBrush(QColor(GEAR_FILL_COLOR))
+    painter.drawPath(path)
+
+
+def _paint_refresh(painter: QPainter, color_name: str = REFRESH_ARROW_COLOR) -> None:
+    """Draw two circulating arrows whose heads remain distinct at toolbar size.
+
+    The color is a parameter so Revert can reuse the same circular motif in purple, reading as "go back" without a second drawing.
+    """
+    color = QColor(color_name)
+    radius = REFRESH_RADIUS_RATIO
+    diameter = radius + radius
+    bounds = QRectF(CENTER_RATIO - radius, CENTER_RATIO - radius, diameter, diameter)
+    for start_angle in REFRESH_START_ANGLES:
+        painter.setBrush(Qt.BrushStyle.NoBrush)
+        painter.setPen(QPen(color, REFRESH_STROKE_RATIO, Qt.PenStyle.SolidLine, Qt.PenCapStyle.RoundCap))
+        painter.drawArc(bounds, start_angle * QT_ANGLE_UNITS_PER_DEGREE, REFRESH_SWEEP_DEGREES * QT_ANGLE_UNITS_PER_DEGREE)
+        angle = math.radians(start_angle + REFRESH_SWEEP_DEGREES)
+        endpoint = QPointF(CENTER_RATIO + radius * math.cos(angle), CENTER_RATIO - radius * math.sin(angle))
+        tangent = QPointF(-math.sin(angle), -math.cos(angle))
+        normal = QPointF(math.cos(angle), -math.sin(angle))
+        base = endpoint - tangent * REFRESH_HEAD_LENGTH_RATIO
+        arrow = QPainterPath(endpoint)
+        arrow.lineTo(base + normal * REFRESH_HEAD_HALF_WIDTH_RATIO)
+        arrow.lineTo(base - normal * REFRESH_HEAD_HALF_WIDTH_RATIO)
+        arrow.closeSubpath()
+        painter.setPen(Qt.PenStyle.NoPen)
+        painter.setBrush(color)
+        painter.drawPath(arrow)

gitpane/ui/look/application_icon.py

@@ -0,0 +1,78 @@
+"""Draw the GitPane logo, a hand-written two-colour "X", as vector geometry so it stays sharp at every icon size."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QPointF, QRectF, Qt
+from PySide6.QtGui import QColor, QIcon, QImage, QPainter, QPixmap, QPolygonF
+
+if TYPE_CHECKING:
+    from PySide6.QtWidgets import QApplication
+
+LOGO_RED_COLOR = "#ed1c24"
+LOGO_GREEN_COLOR = "#22b14c"
+# Windows picks the closest of these for the title bar, the taskbar, Alt+Tab and Explorer views.
+APPLICATION_ICON_SIDES = (16, 24, 32, 48, 64, 256)
+# The geometry is kept in the pixel coordinates of the maintainer's original hand drawing, so a later retouch can be measured
+# against that picture directly. One uniform scale then fits the drawing into any square canvas.
+LOGO_GREEN_ARROW_POINTS = ((9.5, 2.0), (24.5, 11.8), (5.5, 21.0))
+LOGO_GREEN_STROKE_POINTS = ((9.5, 14.0), (20.0, 14.0), (52.25, 68.0), (43.25, 68.0))
+LOGO_RED_STROKE_POINTS = ((42.5, 7.0), (51.75, 7.0), (14.75, 68.0), (5.5, 68.0))
+# The box that holds every vertex above; the drawing is scaled and centered from it.
+LOGO_SOURCE_BOUNDS = QRectF(5.5, 2.0, 46.75, 66.0)
+LOGO_MARGIN_RATIO = 0.04
+# Share of the square's side that moves the painter origin to the square's centre.
+CENTRE_RATIO = 0.5
+
+
+def paint_application_logo(painter: QPainter, side: float) -> None:
+    """Paint the logo centered in a ``side`` by ``side`` square starting at the painter origin.
+
+    The green stroke and its arrow head come first and the red stroke is painted over them, as in the hand drawing.
+    The drawing keeps its proportions: its height fills the square minus the margin, and it is centered horizontally.
+    """
+    scale = side * (1 - 2 * LOGO_MARGIN_RATIO) / LOGO_SOURCE_BOUNDS.height()
+    painter.save()
+    painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+    painter.translate(side * CENTRE_RATIO, side * CENTRE_RATIO)
+    painter.scale(scale, scale)
+    painter.translate(-LOGO_SOURCE_BOUNDS.center())
+    painter.setPen(Qt.PenStyle.NoPen)
+    painter.setBrush(QColor(LOGO_GREEN_COLOR))
+    painter.drawPolygon(_polygon(LOGO_GREEN_STROKE_POINTS))
+    painter.drawPolygon(_polygon(LOGO_GREEN_ARROW_POINTS))
+    painter.setBrush(QColor(LOGO_RED_COLOR))
+    painter.drawPolygon(_polygon(LOGO_RED_STROKE_POINTS))
+    painter.restore()
+
+
+def _polygon(points: tuple[tuple[float, float], ...]) -> QPolygonF:
+    """Build a closed Qt polygon from a named tuple of vertices."""
+    polygon = QPolygonF()
+    for x, y in points:
+        polygon.append(QPointF(x, y))
+    return polygon
+
+
+def application_icon_image(side: int) -> QImage:
+    """Render the logo on a transparent square image of ``side`` pixels, ready to save or to turn into a pixmap."""
+    image = QImage(side, side, QImage.Format.Format_ARGB32)
+    image.fill(Qt.GlobalColor.transparent)
+    painter = QPainter(image)
+    paint_application_logo(painter, side)
+    painter.end()
+    return image
+
+
+def application_icon() -> QIcon:
+    """Build the window icon with one pixmap per standard size, so Qt and Windows never have to scale a single picture."""
+    icon = QIcon()
+    for side in APPLICATION_ICON_SIDES:
+        icon.addPixmap(QPixmap.fromImage(application_icon_image(side)))
+    return icon
+
+
+def install_application_icon(application: QApplication) -> None:
+    """Make the logo the icon of every GitPane window, so no window has to set one and the taskbar shows the same picture."""
+    application.setWindowIcon(application_icon())