gitpane 1.0.0__py3-none-any.whl

gitpane/ui/widget/dialog_layout.py

@@ -0,0 +1,668 @@
+"""Lay out the dialogs of GitPane with native form metrics."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QMargins, QPoint, QRect, QSize, Qt
+from PySide6.QtGui import QColor, QPainter, QPalette
+from PySide6.QtWidgets import (
+    QAbstractScrollArea,
+    QApplication,
+    QComboBox,
+    QDialog,
+    QFormLayout,
+    QGridLayout,
+    QHBoxLayout,
+    QLabel,
+    QLayout,
+    QLineEdit,
+    QPushButton,
+    QScrollArea,
+    QSizePolicy,
+    QStyle,
+    QStyleOptionButton,
+    QTabWidget,
+    QVBoxLayout,
+    QWidget,
+)
+
+from gitpane.config import SCREEN_MARGIN, SPACING_MD, SPACING_SM, control_height, fit_window, frame_position_inside, known_frame_margins, uncounted_decoration_estimate, unknown_decoration_estimate, window_placement
+from gitpane.ui.look.theme_color import is_dark_palette, theme_band_color, theme_line_color
+from gitpane.ui.look.theme_look import follow_theme
+from gitpane.ui.look.theme_palette import BODY_LIGHT_COLOR, WINDOWS_CONTROL_LIGHT_COLOR
+from gitpane.ui.look.windows_control_look import BUTTON_TEXT_SIDE_PADDING, WINDOWS_CAPTURE_TEXT_HEIGHT, apply_windows_button_look, plain_form_color, windows_field_height
+from gitpane.ui.widget.long_text import SelectionSummaryRow, WrappingLabel, largest_client_size
+from gitpane.ui.window_control.compositor_growth_cap import decoration_height_estimate, growth_frame_cap, usable_height_estimate
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from PySide6.QtGui import QPaintEvent
+
+
+# Git Extensions draws the buttons of its dialogs on a light grey strip under the body, the strip starting with a
+# slightly darker line. These light theme values were sampled from its Cherry pick commit capture.
+BUTTON_BAND_LIGHT_COLOR = "#eeeeee"
+BUTTON_BAND_SEPARATOR_LIGHT_COLOR = "#d9d9d9"
+BUTTON_BAND_SEPARATOR_WIDTH = 1
+# Space Qt's push buttons leave between their icon and their text.
+PUSH_BUTTON_ICON_TEXT_SPACING = 4
+
+
+@dataclass(frozen=True)
+class ButtonBandStyle:
+    """Where a button band puts its buttons and how it looks, measured on the Windows window it reproduces."""
+
+    space_above: int
+    space_below: int
+    right_margin: int
+    spacing: int
+    separator: bool
+    light_band_color: str
+    # The smallest size of a button the band sizes itself: the standard button of the reproduced window.
+    button_size: QSize
+
+
+class BandButtonSizing(Enum):
+    """Who sizes the buttons of a button band: the band itself, or the window that copies their sizes from its capture."""
+
+    BAND = "band"
+    WINDOW = "window"
+
+    @property
+    def text_side_padding(self) -> int:
+        """Return the room the light Windows look keeps between a button's text and each side of its frame.
+
+        A button the band sizes is at least the standard button of its band and grows with its text, keeping this room
+        so a long caption never touches the frame. A window that sizes its buttons from its capture keeps the
+        capture's look, which has none, so its buttons do not change.
+        """
+        if self == BandButtonSizing.BAND:
+            return BUTTON_TEXT_SIDE_PADDING
+        return 0
+
+
+# Size of the Clone button of the capture; the other buttons of the band never get smaller.
+FORM_BAND_BUTTON_MIN_SIZE = QSize(75, 23)
+# Git Extensions forms: a one-pixel line, then 8 px above the buttons and 9 px below, 14 px from the right edge, 8 px apart.
+FORM_BUTTON_BAND = ButtonBandStyle(space_above=8, space_below=9, right_margin=14, spacing=8, separator=True, light_band_color=BUTTON_BAND_LIGHT_COLOR,
+                                   button_size=FORM_BAND_BUTTON_MIN_SIZE)
+# The Windows message box of the Git Extensions capture: a 32 px icon 19 px from the left and 23 px from the top and
+# bottom of the white area, the question 8 px after the icon and centred on it, 29 px free on its right, 73 x 21 buttons.
+MESSAGE_BOX_BODY_MARGINS = QMargins(19, 23, 29, 23)
+MESSAGE_BOX_ICON_SIDE = 32
+MESSAGE_BOX_ICON_TO_TEXT_SPACE = 8
+MESSAGE_BOX_BUTTON_SIZE = QSize(73, 21)
+# Windows message box: no line, 11 px above the buttons and 10 px below, 16 px from the right edge, 9 px apart.
+MESSAGE_BOX_BUTTON_BAND = ButtonBandStyle(space_above=11, space_below=10, right_margin=16, spacing=9, separator=False, light_band_color=WINDOWS_CONTROL_LIGHT_COLOR,
+                                          button_size=MESSAGE_BOX_BUTTON_SIZE)
+# Grid of the Git Extensions forms that put a caption, a field and a button on each row, measured on the Clone window
+# capture in client pixels at 100 %: captions from x 19, fields from x 149 to 532, Browse buttons (540, y, 92, 23), one
+# row every 31 px, and the block under the rows 17 px below the last one. Every window built on this grid shares these
+# values, so a change here moves all of them together.
+# The bottom margin is small because a form of fixed height leaves the space under its content from the window height:
+# a message added to the form uses that space rather than making the body scroll.
+FORM_GRID_BODY_MARGINS = QMargins(14, 16, 16, 2)
+FORM_GRID_CAPTION_INDENT = 5
+FORM_GRID_CAPTION_WIDTH = 127
+FORM_GRID_COLUMN_SPACING = 8
+FORM_GRID_ROW_SPACING = 8
+FORM_GRID_SIDE_BUTTON_MIN_WIDTH = 92
+FORM_GRID_ROWS_TO_BLOCK_SPACE = 17
+CAPTION_COLUMN, FIELD_COLUMN, BUTTON_COLUMN = 0, 1, 2
+# The narrowest space the Git Extensions captures leave between the end of a caption's text and the control after it:
+# 7 empty pixel columns after "Select branches" in Delete branch, where Qt's text box at Segoe UI 9 pt ends one column
+# after the ink (the other captions leave 11 to 14). A caption column that a wider system text pushes past its capture's
+# width keeps this space after its widest caption; with the captures' font every caption already leaves more, so the
+# column keeps the capture's width.
+CAPTION_TO_FIELD_MIN_SPACE = 6
+BROWSE_TEXT = "Browse…"
+# What QLayout.indexOf answers for a widget the layout does not hold.
+WIDGET_NOT_IN_LAYOUT_INDEX = -1
+
+def apply_form_metrics(widget: QWidget) -> None:
+    """Size ordinary fields and text buttons, preserving native and zero-margin sublayouts."""
+    if isinstance(widget, QLabel):
+        if isinstance(widget, WrappingLabel) and widget.wordWrap() and widget.buddy() is None and not isinstance(widget.parentWidget(), SelectionSummaryRow):
+            policy = widget.sizePolicy()
+            policy.setHorizontalPolicy(QSizePolicy.Policy.Ignored)
+            widget.setSizePolicy(policy)
+        return
+    if isinstance(widget, (QComboBox, QPushButton, QLineEdit)):
+        if isinstance(widget, QLineEdit) and isinstance(widget.parentWidget(), QComboBox):
+            return
+        if isinstance(widget, QPushButton) and not widget.text():
+            return
+        widget.setMinimumHeight(control_height(widget.fontMetrics().height()))
+        return
+    if isinstance(widget, QScrollArea):
+        if widget.widget() is not None:
+            apply_form_metrics(widget.widget())
+        return
+    if isinstance(widget, QTabWidget):
+        for index in range(widget.count()):
+            apply_form_metrics(widget.widget(index))
+        return
+    if isinstance(widget, QAbstractScrollArea):
+        return
+    layout = widget.layout()
+    if layout is None:
+        return
+    # Workaround: PySide keeps the Python wrapper of every item QLayout.itemAt returns, as a child of the layout's
+    # wrapper, until the layout itself is deleted. A layout item is not a QObject, so Python is never told when Qt
+    # deletes one, which Qt does when a widget moves to another cell of its grid or leaves its layout: the wrapper stays
+    # registered at the freed address, and the next object Qt creates there and hands to Python (the copy of its text
+    # document a wrapping label measures) arrives as that dead layout item, whose missing methods then raise. The walk
+    # therefore never asks a layout for its items: it finds the nested layouts and the widgets as QObject children,
+    # whose deletion Python follows, and asks each layout whether it holds a widget.
+    layouts = _nested_layouts(layout)
+    for current in layouts:
+        current.setSpacing(SPACING_SM)
+        if any(current.getContentsMargins()):
+            current.setContentsMargins(SPACING_MD, SPACING_MD, SPACING_MD, SPACING_MD)
+    # Qt makes the widget that holds a layout the parent of every widget added to that layout or to a layout nested in it.
+    for child in widget.findChildren(QWidget, options=Qt.FindChildOption.FindDirectChildrenOnly):
+        if _is_held_by_one_of(child, layouts):
+            apply_form_metrics(child)
+
+
+def _nested_layouts(layout: QLayout) -> list[QLayout]:
+    """Return a layout with every layout nested in it, found as QObject children: Qt makes a layout the parent of each layout added to it."""
+    layouts = []
+    pending_layouts = [layout]
+    while pending_layouts:
+        current = pending_layouts.pop()
+        layouts.append(current)
+        pending_layouts.extend(current.findChildren(QLayout, options=Qt.FindChildOption.FindDirectChildrenOnly))
+    return layouts
+
+
+def _is_held_by_one_of(widget: QWidget, layouts: list[QLayout]) -> bool:
+    """Tell whether one of the layouts holds the widget; asked by widget, so no layout item reaches Python."""
+    for layout in layouts:
+        if layout.indexOf(widget) != WIDGET_NOT_IN_LAYOUT_INDEX:
+            return True
+    return False
+
+
+def apply_left_aligned_form(form: QFormLayout) -> None:
+    """Keep a form's captions and fields on the left and let its fields grow, whatever the style would choose.
+
+    These are Fusion's own values, written into the form so that it reads the same under every style: Qt's macOS style
+    centres a form, right-aligns its captions and keeps its fields at their own size.
+    """
+    form.setFormAlignment(Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignTop)
+    form.setLabelAlignment(Qt.AlignmentFlag.AlignLeft)
+    form.setFieldGrowthPolicy(QFormLayout.FieldGrowthPolicy.AllNonFixedFieldsGrow)
+
+
+def fit_form(dialog: QDialog, available: QRect | None = None) -> None:
+    """Apply shared spacing without turning the initial dialog size into a resize minimum."""
+    apply_form_metrics(dialog)
+    fit_window(dialog, 0, 0, available)
+
+
+@dataclass(frozen=True)
+class BandedDialogColors:
+    """Colors of a dialog drawn as a body above a button band."""
+
+    body: QColor
+    band: QColor
+    separator: QColor
+
+
+def banded_dialog_colors(palette: QPalette, band_style: ButtonBandStyle = FORM_BUTTON_BAND) -> BandedDialogColors:
+    """Use the Git Extensions colors in a light theme and greys worked out from the palette in a dark one.
+
+    The captures only exist in a light theme; copying their white body into a dark desktop would glare. A dark body takes
+    the window color, so fields, lists and check boxes, drawn on the darker input background, stand out from it; the band
+    is a grey a little lighter than the body, and its line the theme's line grey.
+    """
+    if is_dark_palette(palette):
+        return BandedDialogColors(palette.color(QPalette.ColorRole.Window), theme_band_color(palette), theme_line_color(palette))
+    return BandedDialogColors(QColor(BODY_LIGHT_COLOR), QColor(band_style.light_band_color), QColor(BUTTON_BAND_SEPARATOR_LIGHT_COLOR))
+
+
+def paint_plain_form(dialog: QDialog) -> None:
+    """Paint a dialog's background with the plain-window color of the current application palette."""
+    palette = dialog.palette()
+    palette.setColor(QPalette.ColorRole.Window, plain_form_color(QApplication.palette()))
+    dialog.setPalette(palette)
+    dialog.setAutoFillBackground(True)
+
+
+def install_plain_form_palette(dialog: QDialog) -> None:
+    """Paint a dialog as one plain surface of the plain-window color, like the Git Extensions windows without a button band.
+
+    The color is laid again whenever the application switches between light and dark while the dialog is open.
+    """
+    paint_plain_form(dialog)
+    follow_theme(dialog, lambda: paint_plain_form(dialog))
+
+
+def refresh_style_sheet_fonts(window: QWidget) -> None:
+    """Make every child of the window that carries a style sheet take the font it inherits now.
+
+    Workaround: Qt keeps the font a child with a style sheet resolved when the sheet was polished, so an application
+    font change (Windows' "Make text bigger") reaches every other control but leaves these ones at the old size.
+    Polishing them again makes them resolve the inherited font again; it changes nothing else.
+    """
+    for widget in window.findChildren(QWidget):
+        if not widget.styleSheet():
+            continue
+        style = widget.style()
+        style.unpolish(widget)
+        style.polish(widget)
+
+
+class FormCaption(QLabel):
+    """Caption of a form's left column: the capture's column width, or its own text's width when that is wider.
+
+    The width is reported as both the size hint and the minimum size hint rather than set as an explicit minimum
+    width: an explicit minimum is what a layout short of room squeezes the caption down to, which cut "Repository to
+    clone:" to the capture's width under a larger system font. Reported this way, the caption follows each font change
+    on its own and a layout can never make it narrower than its text.
+    """
+
+    def sizeHint(self) -> QSize:
+        """Return the text's own size, widened to the capture's caption column."""
+        hint = super().sizeHint()
+        return QSize(max(FORM_GRID_CAPTION_WIDTH, hint.width()), hint.height())
+
+    def minimumSizeHint(self) -> QSize:
+        """Refuse any width below the size hint, so the text is never cut."""
+        return self.sizeHint()
+
+
+def add_form_caption(grid: QGridLayout, row: int, text: str, field: QWidget) -> QLabel:
+    """Put a caption of the left column of a Git Extensions form on its row, naming its field, and return it.
+
+    The caption has the indent and width measured on the Git Extensions Clone window capture, so every form built on
+    this grid lines its fields up at the same x. That width is a minimum: the caption keeps exactly its text's width
+    when a larger system text size needs more, following each font change on its own, so the text is never cut.
+    """
+    caption = FormCaption(text)
+    caption_policy = caption.sizePolicy()
+    caption_policy.setHorizontalPolicy(QSizePolicy.Policy.Fixed)
+    caption.setSizePolicy(caption_policy)
+    caption.setContentsMargins(FORM_GRID_CAPTION_INDENT, 0, 0, 0)
+    caption.setBuddy(field)
+    grid.addWidget(caption, row, CAPTION_COLUMN)
+    return caption
+
+
+def fit_caption_to_other_form(caption: QLabel, other_captions: Sequence[str]) -> None:
+    """Give a form caption the width the widest caption of another form needs in the same font, so both put their fields at one x.
+
+    Each caption of ``add_form_caption`` keeps the capture's width, or exactly its text's width when a larger system
+    text needs more. The other form's captions are measured the same way, so the column stays at the capture's width
+    where every caption fits in it (the Windows default text size) and follows the widest one otherwise.
+    """
+    width = FORM_GRID_CAPTION_WIDTH
+    for text in (caption.text(), *other_captions):
+        probe = QLabel(text)
+        probe.setFont(caption.font())
+        probe.setContentsMargins(caption.contentsMargins())
+        width = max(width, probe.sizeHint().width())
+    caption.setMinimumWidth(width)
+
+
+def fit_side_buttons(buttons: Sequence[QPushButton], other_form_texts: Sequence[str] = ()) -> None:
+    """Give the buttons of a form's right-hand column the field height and one common width, for their current font.
+
+    The width is the capture's Browse… width, or more when a caption needs it; set any icon first, since it counts in
+    the width. Both sizes follow the text, so call it again after a font change. ``other_form_texts`` are the captions
+    of another form's plain side buttons that this column lines up with: they are measured with the first button's
+    font and look, so both columns take one width when a larger system text widens one of them.
+    """
+    side_width = FORM_GRID_SIDE_BUTTON_MIN_WIDTH
+    for button in buttons:
+        side_width = max(side_width, button.sizeHint().width())
+    for text in other_form_texts:
+        probe = QPushButton(text)
+        probe.setFont(buttons[0].font())
+        probe.setStyleSheet(buttons[0].styleSheet())
+        side_width = max(side_width, probe.sizeHint().width())
+    for button in buttons:
+        button.setFixedSize(side_width, windows_field_height(button))
+
+
+def push_button_content_size(button: QPushButton) -> QSize:
+    """Return the room a push button's icon and text take, without the frame and padding its style draws around them."""
+    text_size = button.fontMetrics().size(Qt.TextFlag.TextShowMnemonic, button.text())
+    if button.icon().isNull():
+        return text_size
+    icon_size = button.iconSize()
+    return QSize(icon_size.width() + PUSH_BUTTON_ICON_TEXT_SPACING + text_size.width(), max(icon_size.height(), text_size.height()))
+
+
+def push_button_shows_whole_content(button: QPushButton, size: QSize) -> bool:
+    """Tell whether a push button of this size holds its whole icon and text inside the area its style draws them in."""
+    option = QStyleOptionButton()
+    button.initStyleOption(option)
+    option.rect = QRect(QPoint(0, 0), size)
+    contents = button.style().subElementRect(QStyle.SubElement.SE_PushButtonContents, option, button)
+    content = push_button_content_size(button)
+    return content.width() <= contents.width() and content.height() <= contents.height()
+
+
+def capture_control_size(widget: QWidget, capture_size: QSize) -> QSize:
+    """Return the size a control copied from a capture needs: at least the capture's size, at least its text's size.
+
+    The captures were taken on Windows with Segoe UI 9 pt, where every text fits its control. A wider font (Ubuntu
+    11 pt, or a text size the user enlarged) would cut the text at the capture's size, so the control gets the room its
+    current text, icon and look ask for; it never becomes smaller than the capture.
+
+    A push button at the captures' text height keeps exactly the capture's size whenever its icon and text fit inside
+    the frame its style draws. Its size hint is not used there: the dark Fusion button asks for 80 px at least and for
+    more padding than the Windows button of the capture, which would move every control of the captured layout while
+    the text already fits. A taller text gets at least the size hint, as any other control.
+    """
+    if isinstance(widget, QPushButton) and widget.fontMetrics().height() <= WINDOWS_CAPTURE_TEXT_HEIGHT and push_button_shows_whole_content(widget, capture_size):
+        return QSize(capture_size)
+    return capture_size.expandedTo(widget.sizeHint())
+
+
+def fit_capture_control(widget: QWidget, capture_size: QSize) -> None:
+    """Fix a control at its capture's size, or larger when its text needs it; call it again after a font or look change.
+
+    With the captures' font the control keeps exactly the capture's size, so the Windows windows do not change.
+    """
+    widget.setFixedSize(capture_control_size(widget, capture_size))
+
+
+def caption_column_need(caption: QLabel) -> int:
+    """Return the width a caption of a form's left column needs: its text, then the space every caption keeps before its control.
+
+    The space is part of the caption's own width because the captured forms put their controls right after the caption
+    column, with no layout spacing between them.
+    """
+    return caption.sizeHint().width() + CAPTION_TO_FIELD_MIN_SPACE
+
+
+def fit_caption_column(captions: Sequence[QLabel], capture_width: int) -> int:
+    """Give the captions of a form's left column one width, the capture's or what the widest caption needs when wider, and return it.
+
+    The Git Extensions captures were taken with Segoe UI 9 pt, where every caption fits its column with room to spare.
+    A wider font (Ubuntu 11 pt, macOS 13 pt, or a text size the user enlarged) would cut a caption held at the capture's
+    width, so the column takes the width its widest text needs plus the space kept before the controls; the fields
+    after it move right and the window grows when it is shown. With the captures' font the column keeps exactly the
+    capture's width. Call it again after a font change, and move anything lined up on the column (a row indented by
+    the column's width) by the width returned.
+    """
+    width = capture_width
+    for caption in captions:
+        width = max(width, caption_column_need(caption))
+    for caption in captions:
+        caption.setFixedWidth(width)
+    return width
+
+
+def apply_side_button_look(buttons: Sequence[QPushButton], other_form_texts: Sequence[str] = ()) -> None:
+    """Give the buttons of a form's right-hand column the Windows 10 look, then the field height and one common width.
+
+    The look comes first: its style sheet changes the width a caption needs. ``other_form_texts`` is passed on to
+    ``fit_side_buttons``.
+    """
+    for button in buttons:
+        apply_windows_button_look(button)
+    fit_side_buttons(buttons, other_form_texts)
+
+
+class ButtonBand(QWidget):
+    """Full-width strip under a window body that carries its buttons on the right, as in Git Extensions.
+
+    A button that stands apart from the window's actions, like Settings… on the Git Extensions start page, can sit
+    on the left of the band instead.
+    """
+
+    def __init__(self, buttons: list[QPushButton], colors: BandedDialogColors, band_style: ButtonBandStyle = FORM_BUTTON_BAND,
+                 leading_buttons: list[QPushButton] | None = None) -> None:
+        """Right-align the buttons with the spacing and margins measured on the reproduced window, leading buttons on the left.
+
+        Without leading buttons the band has no left margin, exactly as every band measured on a capture; with them,
+        the left margin mirrors the right one so the leading buttons sit as far from the left edge as the others from
+        the right edge.
+        """
+        super().__init__()
+        self.colors = colors
+        self.band_style = band_style
+        leading_buttons = leading_buttons or []
+        separator_width = BUTTON_BAND_SEPARATOR_WIDTH if band_style.separator else 0
+        left_margin = band_style.right_margin if leading_buttons else 0
+        self.setContentsMargins(left_margin, separator_width + band_style.space_above, band_style.right_margin, band_style.space_below)
+        self.row = QHBoxLayout(self)
+        self.row.setContentsMargins(0, 0, 0, 0)
+        self.row.setSpacing(band_style.spacing)
+        for button in leading_buttons:
+            self.row.addWidget(button)
+        self.row.addStretch()
+        for button in buttons:
+            self.row.addWidget(button)
+        self.setSizePolicy(QSizePolicy.Policy.Preferred, QSizePolicy.Policy.Fixed)
+
+    def paintEvent(self, event: QPaintEvent) -> None:
+        """Fill the band and, for the Git Extensions forms, draw its separator line along the top edge."""
+        painter = QPainter(self)
+        painter.fillRect(self.rect(), self.colors.band)
+        if self.band_style.separator:
+            painter.fillRect(QRect(0, 0, self.width(), BUTTON_BAND_SEPARATOR_WIDTH), self.colors.separator)
+
+
+DEFAULT_BODY_MARGINS = QMargins(SPACING_MD, SPACING_MD, SPACING_MD, SPACING_MD)
+
+
+def paint_banded_window(window: QWidget, band_style: ButtonBandStyle, source: QPalette) -> BandedDialogColors:
+    """Paint a banded window's background with its body color and return the colors its band has to use.
+
+    ``source`` is the palette the colors are worked out from. It is passed in rather than read from the window because
+    a window painted before already carries the body color set that time: a window that follows a theme change takes
+    the application palette instead.
+    """
+    colors = banded_dialog_colors(source, band_style)
+    palette = window.palette()
+    palette.setColor(QPalette.ColorRole.Window, colors.body)
+    window.setPalette(palette)
+    window.setAutoFillBackground(True)
+    return colors
+
+
+def install_banded_layout(window: QWidget, body: QLayout, buttons: list[QPushButton], band_style: ButtonBandStyle = FORM_BUTTON_BAND,
+                          body_margins: QMargins = DEFAULT_BODY_MARGINS, *, leading_buttons: list[QPushButton] | None = None,
+                          button_sizing: BandButtonSizing = BandButtonSizing.BAND) -> ButtonBand:
+    """Lay a dialog or a plain window out as its body above a full-width button band, and paint it with the body color.
+
+    The window's own background is the body color, so any spacing between body and band never shows another color.
+    ``buttons`` sit on the right of the band and ``leading_buttons`` on its left. All of them get the Windows 10 look
+    of the reproduced window in a light theme. The body, the band and the buttons' look are laid again whenever the
+    application switches between light and dark while the window is open.
+
+    By default the band sizes its buttons: at least the standard button of ``band_style``, wider with room on both
+    sides when the text needs it. A window that copies its buttons' sizes from a capture passes
+    ``BandButtonSizing.WINDOW`` and keeps them.
+    """
+    colors = paint_banded_window(window, band_style, QApplication.palette())
+    outer = QVBoxLayout(window)
+    outer.setContentsMargins(0, 0, 0, 0)
+    outer.setSpacing(0)
+    body.setContentsMargins(body_margins)
+    outer.addLayout(body, 1)
+    band = ButtonBand(buttons, colors, band_style, leading_buttons)
+    band_buttons = [*(leading_buttons or []), *buttons]
+    for button in band_buttons:
+        if button_sizing == BandButtonSizing.BAND:
+            button.setMinimumSize(band_style.button_size)
+        apply_windows_button_look(button, button_sizing.text_side_padding)
+    outer.addWidget(band)
+
+    def apply_band_theme_look() -> None:
+        """Paint the body and the band with the new theme's colors and give the band's buttons that theme's look."""
+        band.colors = paint_banded_window(window, band.band_style, QApplication.palette())
+        band.update()
+        for band_button in band_buttons:
+            apply_windows_button_look(band_button, button_sizing.text_side_padding)
+
+    follow_theme(window, apply_band_theme_look)
+    return band
+
+
+def content_height(dialog: QDialog) -> int:
+    """Return the height the dialog layout needs at the dialog's current width, wrapped labels included."""
+    layout = dialog.layout()
+    layout.activate()
+    if layout.hasHeightForWidth():
+        return max(layout.totalHeightForWidth(dialog.width()), layout.totalMinimumSize().height())
+    return layout.totalSizeHint().height()
+
+
+def _content_height_at(content: QWidget, width: int) -> int:
+    """Return the height a scroll area's content needs at ``width``, wrapped labels included."""
+    return content.heightForWidth(width) if content.hasHeightForWidth() else content.minimumSizeHint().height()
+
+
+def scrolled_content_needed_size(scroll_area: QScrollArea) -> QSize:
+    """Return the width a scroll area's content gets without a vertical scroll bar, and the height it needs at that width.
+
+    The content of a resizable scroll area wraps to the viewport's width, and the vertical scroll bar goes away once the
+    content fits, so the content is measured at the width it has without that scroll bar.
+    """
+    content = scroll_area.widget()
+    viewport = scroll_area.viewport()
+    if content is None:
+        return viewport.size()
+    width = viewport.width()
+    scroll_bar = scroll_area.verticalScrollBar()
+    if scroll_bar.isVisible():
+        width += scroll_bar.width()
+    return QSize(width, _content_height_at(content, width))
+
+
+def scrolled_content_missing_height(scroll_area: QScrollArea) -> int:
+    """Return how many pixels a scroll area's viewport lacks to show its whole content without scrolling, or a negative number when it has room.
+
+    The content is measured at the width it gets without the vertical scroll bar. Workaround: while that scroll bar
+    shows, Qt only hides it once the content fits at the narrower width the scroll bar leaves, since it measures the
+    content at the viewport's current width; content that wraps on one more line there (a long branch name cut at its
+    dashes) would keep the scroll bar, with a few pixels left to scroll, in a viewport tall enough for it at the full
+    width. The lack is then at least what the content needs at that narrower width beyond the viewport, Qt's own
+    measure. It is measured on the content rather than read from the scroll bar's range: the scroll area only updates
+    that range on a later layout pass, so right after a change of content or of size the range still says what the
+    content scrolled before, and a window sized by it would grow again by what scrolled at its previous height.
+    """
+    missing_height = scrolled_content_needed_size(scroll_area).height() - scroll_area.viewport().height()
+    content = scroll_area.widget()
+    if content is None or not scroll_area.verticalScrollBar().isVisible():
+        return missing_height
+    viewport = scroll_area.viewport()
+    return max(missing_height, _content_height_at(content, viewport.width()) - viewport.height())
+
+
+GROWTH_USABLE_HEIGHT_SHARE = 0.75
+"""Largest share of its screen's usable height that a window's frame, title bar included, reaches by growing to its content.
+
+Beyond it the content scrolls: a grown window takes no more than three quarters of the usable height, so it never hides
+everything behind it. That usable height is estimated where Qt counts the whole screen as usable (Wayland), panels it
+does not see taken off.
+"""
+
+
+def _decoration_reference(window: QWidget) -> QWidget | None:
+    """Return the window whose title bar a window not decorated yet borrows: its parent's window, or none for a window without a parent."""
+    parent = window.parentWidget()
+    return parent.window() if parent is not None else None
+
+
+def growth_height_cap(window: QWidget, platform_name: str = "", *, placed_height: int | None = None) -> int:
+    """Return the tallest client height the growth rule gives a window: GROWTH_USABLE_HEIGHT_SHARE of its usable height, frame included, and below a kept top no more than the room under it.
+
+    The frame is what is bounded, title bar included: the margins the window system gave count, and so does the title
+    bar borrowed from the parent's window while the window is not decorated yet; a decorated window of which Qt knows no
+    margin, its title bar drawn by the compositor, counts an estimated title bar. The usable height is Qt's, less an
+    estimated panel where Qt counts the whole screen. Where GitPane moves a growing window back up itself, the share is
+    the whole cap. Where the compositor places windows and keeps a growing window's top, the frame also stays within the
+    room under the top the window was centred at with ``placed_height``, the client height it had when the window system
+    placed it; ``None`` for a window the rule does not follow, which only gets the share. ``platform_name`` is Qt's
+    platform name, read from Qt when not given.
+    """
+    known = known_frame_margins(window, platform_name)
+    uncounted = uncounted_decoration_estimate(window, _decoration_reference(window), platform_name)
+    decorated = not window.windowFlags() & Qt.WindowType.FramelessWindowHint
+    decoration_height = decoration_height_estimate(known.top() + known.bottom() + uncounted.top() + uncounted.bottom(), decorated)
+    screen = window.screen()
+    usable_height = usable_height_estimate(screen.availableGeometry().height(), screen.geometry().height())
+    keeps_top = placed_height is not None and not window_placement(platform_name).requests_position
+    placed_frame_height = placed_height + decoration_height if keeps_top else None
+    return growth_frame_cap(usable_height, GROWTH_USABLE_HEIGHT_SHARE, placed_frame_height) - decoration_height
+
+
+def capped_growth_height(window: QWidget, wanted_height: int, platform_name: str = "", *, placed_height: int | None = None) -> int:
+    """Return the height a window gets when its content asks for ``wanted_height``: never past the growth cap, never made smaller by it.
+
+    The cap only stops a growth: a window its own code opened taller than the cap keeps its height, and a fit that
+    gives height back still does. ``placed_height`` is the client height the window had when the window system placed
+    it, ``None`` for a window the rule does not follow. ``platform_name`` is Qt's platform name, read from Qt when not
+    given.
+    """
+    return min(wanted_height, max(window.height(), growth_height_cap(window, platform_name, placed_height=placed_height)))
+
+
+def window_height_on_screen(window: QWidget, wanted_height: int, platform_name: str = "", *, placed_height: int | None = None) -> int:
+    """Return the height a shown window gets when asked for ``wanted_height``, capped by the growth share of its screen and by its usable area.
+
+    A window its own code opened taller than the growth share keeps its height when asked for more, and a smaller
+    height is always granted. ``placed_height`` is the client height the window had when the window system placed it,
+    ``None`` for a window the rule does not follow. ``platform_name`` is Qt's platform name, read from Qt when not given.
+    """
+    decoration_reference = _decoration_reference(window)
+    available = window.screen().availableGeometry()
+    largest_height = largest_client_size(window, available.marginsRemoved(uncounted_decoration_estimate(window, decoration_reference, platform_name)), platform_name).height()
+    return capped_growth_height(window, min(wanted_height, largest_height), platform_name, placed_height=placed_height)
+
+
+def resize_window_height_on_screen(window: QWidget, wanted_height: int, *, platform_name: str = "", placed_height: int | None = None) -> None:
+    """Give a shown window the wanted height, taller or shorter, capped by the growth share of its screen and by its usable area.
+
+    Only the height changes; the width stays the one the window has. A height above the cap stops at it, while a
+    smaller height is always applied, so a window gives back the room its content no longer needs. The frame, title bar
+    included, stays inside the usable area with its margin where GitPane places its windows: a window the window system
+    has not decorated yet borrows the title bar of its parent's window, and a window sitting low on the screen comes
+    back up just enough. Where the compositor places windows itself, the window is not moved: the compositor ignores
+    the position, and the cap keeps the frame within the room under the top it was placed at. ``placed_height`` is the
+    client height the window had when the window system placed it, ``None`` for a window the rule does not follow.
+    ``platform_name`` is Qt's platform name, read from Qt when not given.
+    """
+    height = window_height_on_screen(window, wanted_height, platform_name, placed_height=placed_height)
+    if height == window.height():
+        return
+    window.resize(window.width(), height)
+    keep_frame_inside_usable_area(window, platform_name=platform_name)
+
+
+def keep_frame_inside_usable_area(window: QWidget, *, platform_name: str = "") -> None:
+    """Move a shown window just enough for its whole frame, title bar included, to sit inside the usable area of its screen with its margin.
+
+    A window the window system has not decorated yet borrows the title bar of its parent's window. Where the compositor
+    places windows itself, nothing moves: the compositor ignores the position. ``platform_name`` is Qt's platform name,
+    read from Qt when not given.
+    """
+    if not window_placement(platform_name).requests_position:
+        return
+    decoration = unknown_decoration_estimate(window, _decoration_reference(window), platform_name)
+    available = window.screen().availableGeometry()
+    frame = window.frameGeometry().marginsAdded(decoration)
+    usable = available.adjusted(SCREEN_MARGIN, SCREEN_MARGIN, -SCREEN_MARGIN, -SCREEN_MARGIN)
+    window.move(frame_position_inside(frame, usable) + QPoint(decoration.left(), decoration.top()))
+
+
+def fit_banded_form(dialog: QDialog, available: QRect | None = None) -> None:
+    """Give a banded dialog exactly the height of its content, then keep it on screen.
+
+    The shared form metrics are not applied: banded dialogs reproduce a Git Extensions window and set their own
+    measured spacing and control sizes.
+    """
+    dialog.layout().activate()
+    dialog.resize(dialog.width(), content_height(dialog))
+    fit_window(dialog, 0, 0, available)