gitpane 1.0.0__py3-none-any.whl

gitpane/ui/widget/busy_indicator.py

@@ -0,0 +1,106 @@
+"""Show that GitPane is still working while it waits on something outside of it, such as the user's browser."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, QRectF, QSize, Qt, QTimer
+from PySide6.QtGui import QColor, QPainter, QPalette, QPen
+from PySide6.QtWidgets import QSizePolicy, QWidget
+
+from gitpane.config import QT_ANGLE_UNITS_PER_DEGREE
+
+if TYPE_CHECKING:
+    from PySide6.QtGui import QPaintEvent
+
+# One step of the turning arc: a smooth turn without keeping the event loop busy.
+FRAME_INTERVAL_MS = 50
+ANGLE_STEP_DEGREES = 30
+FULL_TURN_DEGREES = 360
+# Length of the drawn arc, and its line width as a share of the indicator's side.
+ARC_SPAN_DEGREES = 270
+LINE_WIDTH_RATIO = 0.14
+MINIMUM_LINE_WIDTH = 1.5
+# Divides a length in two: half the line width keeps the arc inside the square, half the free space centres it.
+HALVING_DIVISOR = 2
+
+
+def paint_busy_arc(painter: QPainter, square: QRectF, angle: int, color: QColor) -> None:
+    """Draw the turning arc at its angle inside the given square, its line as thick as a share of the square's side.
+
+    The busy indicator and the "checking" rows of the recent list both draw it, so the arc and its look are defined once.
+    The painter's state is left as it was.
+    """
+    side = min(square.width(), square.height())
+    line_width = max(MINIMUM_LINE_WIDTH, side * LINE_WIDTH_RATIO)
+    inset = line_width / HALVING_DIVISOR
+    pen = QPen(color)
+    pen.setWidthF(line_width)
+    pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+    painter.save()
+    painter.setRenderHint(QPainter.RenderHint.Antialiasing)
+    painter.setPen(pen)
+    painter.drawArc(square.adjusted(inset, inset, -inset, -inset), -angle * QT_ANGLE_UNITS_PER_DEGREE, ARC_SPAN_DEGREES * QT_ANGLE_UNITS_PER_DEGREE)
+    painter.restore()
+
+
+def next_busy_angle(angle: int) -> int:
+    """Return the arc's angle one step further clockwise."""
+    return (angle + ANGLE_STEP_DEGREES) % FULL_TURN_DEGREES
+
+
+class BusyIndicator(QWidget):
+    """A small turning arc, the size of a line of text and in the theme's text colour.
+
+    It is hidden while stopped, and its timer only runs while it turns, so a stopped indicator costs nothing.
+    """
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        """Build a stopped, hidden indicator."""
+        super().__init__(parent)
+        self.angle = 0
+        self.timer = QTimer(self)
+        self.timer.setInterval(FRAME_INTERVAL_MS)
+        self.timer.timeout.connect(self._advance)
+        self.setSizePolicy(QSizePolicy.Policy.Fixed, QSizePolicy.Policy.Fixed)
+        self.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents)
+        self.hide()
+
+    def start(self) -> None:
+        """Show the indicator and start turning it."""
+        self.show()
+        self.timer.start()
+
+    def stop(self) -> None:
+        """Stop turning and hide the indicator."""
+        self.timer.stop()
+        self.hide()
+
+    def sizeHint(self) -> QSize:
+        """Take the height of a line of the current font, so the indicator sits beside its text at any scale."""
+        side = self.fontMetrics().height()
+        return QSize(side, side)
+
+    def minimumSizeHint(self) -> QSize:
+        """Never shrink below the size of a line of text."""
+        return self.sizeHint()
+
+    def changeEvent(self, event: QEvent) -> None:
+        """Follow a new font size, and repaint in the new text colour when the theme changes."""
+        super().changeEvent(event)
+        if event.type() == QEvent.Type.FontChange:
+            self.updateGeometry()
+        self.update()
+
+    def paintEvent(self, event: QPaintEvent) -> None:
+        """Draw the arc at its current angle, inside a square centred in the widget."""
+        side = min(self.width(), self.height())
+        square = QRectF((self.width() - side) / HALVING_DIVISOR, (self.height() - side) / HALVING_DIVISOR, side, side)
+        painter = QPainter(self)
+        paint_busy_arc(painter, square, self.angle, self.palette().color(QPalette.ColorRole.WindowText))
+        painter.end()
+
+    def _advance(self) -> None:
+        """Turn the arc one step clockwise."""
+        self.angle = next_busy_angle(self.angle)
+        self.update()

gitpane/ui/widget/commit_date_text.py

@@ -0,0 +1,55 @@
+"""Write the dates of a commit the way the history rows show them."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, tzinfo
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from gitpane.history.repository_value import Commit
+
+
+MINUTE_SECONDS, HOUR_SECONDS, DAY_SECONDS = 60, 3600, 86400
+MONTH_SECONDS, YEAR_SECONDS = 30 * DAY_SECONDS, 365 * DAY_SECONDS
+
+
+def format_relative_date(timestamp: int, now: datetime) -> str:
+    """Keep elapsed time compact for history rows and share it with commit details."""
+    difference = int(now.timestamp() - timestamp)
+    duration = abs(difference)
+    if duration < MINUTE_SECONDS:
+        return "just now" if difference >= 0 else "in a few seconds"
+    if duration >= MONTH_SECONDS:
+        divisor, unit = (YEAR_SECONDS, "year") if duration >= YEAR_SECONDS else (MONTH_SECONDS, "month")
+        whole_days = duration // DAY_SECONDS
+        days_per_unit = divisor // DAY_SECONDS
+        count = round(whole_days / days_per_unit)
+        unit += "s" if count != 1 else ""
+        return f"{count} {unit} ago" if difference >= 0 else f"in {count} {unit}"
+    divisor, unit = (DAY_SECONDS, "d") if duration >= DAY_SECONDS else (HOUR_SECONDS, "h") if duration >= HOUR_SECONDS else (MINUTE_SECONDS, "min")
+    return f"{duration // divisor} {unit} ago" if difference >= 0 else f"in {duration // divisor} {unit}"
+
+
+DATE_UNAVAILABLE_TEXT = "Date unavailable"
+
+
+def format_commit_time(commit: Commit, timestamp: int, now: datetime, *, relative_only: bool = False) -> str:
+    """Write one of the dates of a commit, or say it is unavailable when Git gave no readable time or no details for it."""
+    if commit.time_unavailable or commit.detail_error:
+        return DATE_UNAVAILABLE_TEXT
+    return format_commit_date(timestamp, now, relative_only=relative_only)
+
+
+def format_commit_date(timestamp: int, now: datetime, timezone: tzinfo | None = None, *, relative_only: bool = False) -> str:
+    """Validate a date and retain its absolute form for details and table tooltips."""
+    try:
+        # Windows cannot reliably convert naive local dates near the Unix epoch; start with an aware UTC date.
+        date = datetime.fromtimestamp(timestamp, UTC).astimezone(timezone)
+    except (ValueError, OverflowError, OSError):
+        return "Date unavailable (timestamp out of range)"
+    relative = format_relative_date(timestamp, now)
+    if relative_only:
+        return relative
+    offset = date.strftime("%z")
+    offset_hour_end = 3
+    return f"{relative} ({date:%Y-%m-%d %H:%M:%S} {offset[:offset_hour_end]}:{offset[offset_hour_end:]})"

gitpane/ui/widget/content_growth.py

@@ -0,0 +1,262 @@
+"""Follow a window's content with its height after the window opened, never below the height it opened at or the user set.
+
+The window opens at a starting height, fitted once to the rows it starts with after its first show is laid out. It then
+grows each time its content needs more height than the window gives it (a long path, a message, a failure written after
+the window opened would otherwise be cut under its bottom edge), and takes back a smaller height when that content goes,
+never below its reference height: the height it opened at once fitted, then the last height the user set by hand. Its
+whole frame stays inside the usable area of its screen and never grows past three quarters of its usable height, the
+content scrolling beyond that. Where the compositor keeps the top it placed the window at (Wayland), the window does not
+grow past the room under that top either, estimated when Qt sees neither the desktop's panels nor the title bar. Where
+the compositor answers a window's show with a size of its own (Wayland), the opening fit and each change of size wait
+for that answer, which would otherwise overwrite them for good.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QCoreApplication, QEvent, Qt, QTimer
+from shiboken6 import isValid
+
+from gitpane.config import fit_window, window_placement
+from gitpane.ui.widget.dialog_layout import capped_growth_height, keep_frame_inside_usable_area, resize_window_height_on_screen, window_height_on_screen
+from gitpane.ui.window_control.compositor_answer import after_compositor_answer
+
+if TYPE_CHECKING:
+    from PySide6.QtCore import QObject
+    from PySide6.QtGui import QResizeEvent, QShowEvent
+
+    from gitpane.ui.widget.content_measure import ContentMeasure
+
+
+class OpeningFit(Enum):
+    """How a window fits its height, once, to the rows it opens with."""
+
+    GROW_ONLY = "grow-only"
+    EXACT = "exact"
+
+    def missing_height(self, measure: ContentMeasure) -> int:
+        """Return the height the window lacks to show its starting rows whole, negative when it has height to give back.
+
+        ``GROW_ONLY`` keeps the opening height as a floor and grows only by what the content hides: a form that opens with
+        room under its rows keeps that room for a message that comes later. For a form that scrolls, what is hidden is the
+        vertical scroll bar's range, what such a form has always grown by, to the pixel, at every text size. ``EXACT``
+        takes the exact height the content needs at the width it has, so a window opened taller than its rows gets
+        smaller, and one opened shorter grows until nothing is hidden.
+        """
+        if self is OpeningFit.GROW_ONLY:
+            return measure.hidden_height()
+        return measure.missing_height()
+
+
+class ContentGrowthMixin:
+    """Height rule of a window whose content changes after it opened, mixed in front of the window's ``QDialog`` class.
+
+    A mixin rather than an object the window owns, so the state of the rule stays on the window, where the window's own
+    code, its tests and the window gallery read it (``starting_height``, ``first_show_fitted``, ``reference_height``,
+    ``growth_measure``) without a relay. The window gives the rule the measure of its content, by its scroll area or by
+    its own layout, when it calls ``install_content_growth`` once that content is in place; each layout request of the
+    content then measures what it needs and gives the window the height the rule aims at.
+    """
+
+    def install_content_growth(self, measure: ContentMeasure, opening_fit: OpeningFit, starting_height: int) -> None:
+        """Start following the content ``measure`` measures, the window opening at ``starting_height`` then fitted as ``opening_fit`` says.
+
+        ``starting_height`` only stands for the opening height until the first show: the opening fit then replaces it
+        with the height the window really has, which is smaller than the given one when the window was reduced to fit a
+        small screen, so a test or the window gallery that compares the window with it never reads a height it never had.
+        """
+        self.growth_measure = measure
+        self.opening_fit = opening_fit
+        # The height the form opened with: the given one until the opening fit, then the window's height once that fit is made.
+        self.starting_height = starting_height
+        # The client height the window had when the window system placed it, which bounds a growth below the top the
+        # compositor keeps: the given starting height until the opening fit reads the height the window really has.
+        self.placed_height = starting_height
+        self.starting_height_fitted = False
+        # True only while the first show waits for the compositor's answer: where nothing waits, the fit is asked in that call.
+        self.showing_first_time = False
+        # True once the first show has fitted the form to its starting rows, when they needed it.
+        self.first_show_fitted = False
+        # The height content that leaves brings the window back to: the opening height once fitted, then the last height
+        # the user set by hand. The window height its content needed when that reference was taken tells a content that
+        # asks for no more than then (the reference stays, even under its content) from one that asks for more.
+        self.reference_height = starting_height
+        self.reference_needed_height = starting_height
+        # Sizes the application gave the window since the reference was taken (the rule's resizes, Qt growing the window
+        # to its layout's minimum, and where the compositor answers activations, the reference itself): a resize from the
+        # window system to one of them is the window system repeating a size it was given, not the user.
+        self.application_given_size_set: set[tuple[int, int]] = set()
+        # The window's size its last resize event brought: a look that finds the window at another size is made while
+        # that resize is still being laid out, before its event reaches the window, and comes from the resize rather
+        # than from a change of content.
+        self.resized_size: tuple[int, int] | None = None
+        # The window's height when the rule last looked at it, or when the user last resized it: a window found taller at
+        # the next look was grown by the application, mostly by Qt to its layout's new minimum, keeping its top where it
+        # was, and its frame is brought back inside the usable area as for a growth of the rule.
+        self.looked_height = starting_height
+        # True while the rule itself resizes the window: the looks that resize causes are not a change of content.
+        self.content_growing = False
+        measure.watched_widget().installEventFilter(self)
+        range_changed = measure.range_changed()
+        if range_changed is not None:
+            range_changed.connect(self._follow_content)
+
+    def showEvent(self, event: QShowEvent) -> None:
+        """Fit the form to its starting rows once its first show is laid out, after the compositor's answer where that answer would overwrite the size.
+
+        Under Wayland the compositor answers the first show with the size it knew then, and Qt applies it: a height asked
+        before that answer would be lost for good. The wait starts here, at the show, so an activation the window gets
+        before the next turn of the event loop is seen and the fit still waits for the configure that follows it.
+        """
+        super().showEvent(event)
+        if self.starting_height_fitted:
+            return
+        self.starting_height_fitted = True
+        self.showing_first_time = True
+        try:
+            after_compositor_answer(self, self._fit_starting_height)
+        finally:
+            self.showing_first_time = False
+
+    def _fit_starting_height(self) -> None:
+        """Fit the form to its starting rows: a turn after the show where nothing waits, at once when the compositor's answer comes."""
+        if self.showing_first_time:
+            # The rows only take their final heights once the layout requests posted by the show are handled.
+            QTimer.singleShot(0, self, self._fit_starting_height_now)
+            return
+        self._fit_starting_height_now()
+
+    def _fit_starting_height_now(self) -> None:
+        """Fit the form once by the height its starting rows lack, or have in excess for the exact fit, so it opens without scrolling.
+
+        The starting height shows the starting rows at the text size it was chosen for, so nothing changes there. A larger
+        system font (Ubuntu's 11 pt) makes the same rows taller: the form then grows by the height they lack. The window
+        is checked again because the wait for the compositor's answer can end, at its bound, on a window hidden meanwhile.
+        Like any growth of the rule, the fit stops at the growth cap, three quarters of the usable height, the rows
+        beyond it scrolling. Where the compositor keeps the window's top, the window's height at this point is the one the
+        compositor placed it with, since the fit waits for its answer: the fit and every later growth then also stop at
+        the room under that top, estimated when Qt sees neither panel nor title bar. The fitted height becomes the
+        reference content that leaves brings the window back to.
+        """
+        if not isValid(self) or not self.isVisible():
+            return
+        # Where the compositor places the window, this is the size it placed, since the opening fit waits for its answer;
+        # elsewhere the rule does not use it.
+        self.placed_height = self.height()
+        self.first_show_fitted = True
+        missing_height = self.opening_fit.missing_height(self.growth_measure)
+        if missing_height != 0:
+            self.content_growing = True
+            try:
+                self.resize(self.width(), capped_growth_height(self, self.height() + missing_height, placed_height=self.placed_height))
+                fit_window(self, 0, 0)
+            finally:
+                self.content_growing = False
+        self.starting_height = self.height()
+        self._take_reference()
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        """Take a resize made through the window system as the user's height, the one content that leaves brings the window back to.
+
+        A resize the window system reports is the user's: those of the rule, of Qt growing the window to its layout's
+        minimum and of the fit to the screen are asked by the application, and never spontaneous. A spontaneous resize
+        to a size the application gave since the reference was taken is the window system repeating it, not the user:
+        under Wayland, Mutter answers the activation of a window (a form closing over it) with a configure that carries
+        the size it knew before the window's last change, and Qt applies it. That older size can be another one than the
+        content calls for now, so the rule looks at the content again, at the next turn of the event loop, and gives the
+        window its height back. A maximised or full-screen window keeps the reference it had before, which restoring it
+        brings back.
+        """
+        super().resizeEvent(event)
+        self.resized_size = (self.width(), self.height())
+        if event.spontaneous():
+            self.looked_height = self.height()
+        if not event.spontaneous() or self.content_growing or not self.first_show_fitted or self._maximized_or_full_screen():
+            return
+        if (event.size().width(), event.size().height()) in self.application_given_size_set:
+            # Posted rather than done here: the rule resizes the window, which is better not done inside its resize event.
+            QCoreApplication.postEvent(self.growth_measure.watched_widget(), QEvent(QEvent.Type.LayoutRequest))
+            return
+        self._take_reference()
+
+    def _take_reference(self) -> None:
+        """Make the window's current height the reference, with the height its content needs now at this width.
+
+        Where the compositor answers an activation with a size it knew before (Wayland), the reference size counts as
+        one the application gave: Mutter brings it back on its own after the content grew the window, which is not the
+        user. Elsewhere only the user brings it back, by hand. Under Wayland a user who drags the window to exactly that
+        height while the content needs more sees the content's height come back: the two cannot be told apart.
+        """
+        self.reference_height = self.height()
+        self.looked_height = self.height()
+        self.reference_needed_height = self.height() + self.growth_measure.missing_height()
+        self.application_given_size_set = set()
+        if window_placement().size_waits_for_compositor_answer:
+            self.application_given_size_set.add((self.width(), self.height()))
+
+    def _follow_content(self, *_arguments: object) -> None:
+        """Ask for the height the content now calls for, once the compositor has answered the show where that answer would overwrite it.
+
+        A look made while a resize of the window is still being laid out comes from that resize, not from new content: the
+        window lays out its children, and the scroll area updates its scroll bar, before the resize event reaches the
+        window, so a user's resize would otherwise be undone before the window could take it as the user's height.
+        """
+        if not isValid(self) or self.content_growing or not self.isVisible() or not self.first_show_fitted or self._maximized_or_full_screen():
+            return
+        if (self.width(), self.height()) != self.resized_size:
+            return
+        after_compositor_answer(self, self._follow_content_now)
+
+    def _follow_content_now(self) -> None:
+        """Give the window the height its content calls for now: what it needs, never below the reference height.
+
+        The content's need is measured when the change is made, not when it was asked. While it asks for no more than
+        when the reference was taken, the window takes the reference height, even one the user set under its content;
+        otherwise it takes the larger of the reference and the need. Each look computes the target again: a second look
+        at the same content (the late layout pass of a row that has a layout of its own, a scroll bar that shows) gives
+        the same target or what is still missing, and a target already reached changes nothing. The flag that keeps the
+        rule's own resize from counting as a change of content is set here, in the change the compositor's answer may
+        defer, never around the request.
+
+        A window whose layout sets its minimum size is grown by Qt itself, keeping its top, as soon as the new content
+        shows, before the rule looks: the target is then already reached, and the frame, which can now end under the
+        usable area, comes back up into it the way the rule's own growth does, and its size counts as one the application
+        gave, so the window system repeating it is not taken for the user's. A height the user set through the window
+        system is never taken for such a growth, and where the compositor places windows nothing moves.
+        """
+        if not isValid(self) or not self.isVisible() or self._maximized_or_full_screen():
+            return
+        grown_since_last_look = self.height() > self.looked_height
+        needed_height = self.height() + self.growth_measure.missing_height()
+        target_height = self.reference_height if needed_height <= self.reference_needed_height else max(self.reference_height, needed_height)
+        if grown_since_last_look:
+            self.application_given_size_set.add((self.width(), self.height()))
+        if window_height_on_screen(self, target_height, placed_height=self.placed_height) == self.height():
+            if grown_since_last_look:
+                keep_frame_inside_usable_area(self)
+            self.looked_height = self.height()
+            return
+        self.content_growing = True
+        try:
+            resize_window_height_on_screen(self, target_height, placed_height=self.placed_height)
+        finally:
+            self.content_growing = False
+        self.looked_height = self.height()
+        self.application_given_size_set.add((self.width(), self.height()))
+
+    def _maximized_or_full_screen(self) -> bool:
+        """Tell whether the window is maximised or full screen, where the rule leaves its size to the window system."""
+        state = self.windowState()
+        return bool(state & Qt.WindowState.WindowMaximized) or bool(state & Qt.WindowState.WindowFullScreen)
+
+    def eventFilter(self, watched: QObject, event: QEvent) -> bool:
+        """Look at the content's layout requests, which follow each change of its texts, and follow the content with the window's height."""
+        if event.type() != QEvent.Type.LayoutRequest:
+            return super().eventFilter(watched, event)
+        watched_widget = self.growth_measure.watched_widget()
+        if watched_widget is None or not isValid(watched_widget) or watched is not watched_widget:
+            return super().eventFilter(watched, event)
+        self._follow_content()
+        return False

gitpane/ui/widget/content_measure.py

@@ -0,0 +1,99 @@
+"""Measure the height a window's content lacks, on its scroll area or on its own layout.
+
+A window whose height follows its content hands the growth rule one of these measures: the content of a form that
+scrolls is the scroll area's widget, measured at the width the viewport gives it; the content of a form without a
+scroll area is the window's own layout, measured at the window's width, with each text that scrolls inside it counted at
+its whole height. Each measure also names the widget whose layout requests tell that the content changed, and the
+signal, if any, that tells an overflow changed without one.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from gitpane.ui.widget.dialog_layout import scrolled_content_missing_height
+from gitpane.ui.widget.scrolled_text import ScrolledText
+
+if TYPE_CHECKING:
+    from PySide6.QtCore import SignalInstance
+    from PySide6.QtWidgets import QScrollArea, QWidget
+
+
+def layout_minimum_height(window: QWidget) -> int:
+    """Return the smallest height the window's layout needs at the window's current width, wrapped labels included.
+
+    The layout is activated first, so a widget just shown or hidden counts. The minimum is measured and never the
+    preferred height: a table that stretches prefers more rows than it needs, and a window sized by that preference
+    would grow again at each look.
+    """
+    layout = window.layout()
+    layout.activate()
+    if layout.hasHeightForWidth():
+        return layout.totalMinimumHeightForWidth(window.width())
+    return layout.totalMinimumSize().height()
+
+
+class ScrolledContentMeasure:
+    """Measure the content of a window whose form scrolls: the scroll area's widget, at the width its viewport gives it."""
+
+    def __init__(self, scroll_area: QScrollArea) -> None:
+        """Measure the content of ``scroll_area``, which already holds it."""
+        self.scroll_area = scroll_area
+
+    def watched_widget(self) -> QWidget:
+        """Return the scrolled content, whose layout requests follow each change of its texts."""
+        return self.scroll_area.widget()
+
+    def missing_height(self) -> int:
+        """Return the height the viewport lacks to show the whole content without scrolling, negative when it has room."""
+        return scrolled_content_missing_height(self.scroll_area)
+
+    def hidden_height(self) -> int:
+        """Return the height the vertical scroll bar hides, zero when nothing scrolls."""
+        return max(0, self.scroll_area.verticalScrollBar().maximum())
+
+    def range_changed(self) -> SignalInstance | None:
+        """Return the scroll bar's range signal, which tells an overflow changed even without a layout request of the content."""
+        return self.scroll_area.verticalScrollBar().rangeChanged
+
+
+def scrolled_text_extra_height(window: QWidget) -> int:
+    """Return the height the window's shown scrolled texts need beyond what its layout counts for them.
+
+    The layout counts such a text at most at a few lines, so a long output never makes Qt grow the window past the
+    screen; the window's content still needs the whole text, which the growth rule gives it up to its cap.
+    """
+    extra_height = 0
+    for scrolled_text in window.findChildren(ScrolledText):
+        if scrolled_text.window() is not window or not scrolled_text.isVisibleTo(window):
+            continue
+        extra_height += max(0, scrolled_text.needed_height() - scrolled_text.minimumSizeHint().height())
+    return extra_height
+
+
+class LayoutContentMeasure:
+    """Measure the content of a window without a scroll area for its whole form: its own layout at the window's width, each scrolled text at its whole height."""
+
+    def __init__(self, window: QWidget) -> None:
+        """Measure the layout of ``window``, which already has it."""
+        self.window = window
+
+    def watched_widget(self) -> QWidget:
+        """Return the window itself, whose layout requests follow each change of its rows."""
+        return self.window
+
+    def missing_height(self) -> int:
+        """Return the height the window lacks for its layout's minimum at its width and its scrolled texts' whole height, negative when it has room."""
+        return layout_minimum_height(self.window) + scrolled_text_extra_height(self.window) - self.window.height()
+
+    def hidden_height(self) -> int:
+        """Return the height the window lacks for its whole content, zero when it has room: what its layout lacks is cut, what its scrolled texts lack scrolls."""
+        return max(0, self.missing_height())
+
+    def range_changed(self) -> SignalInstance | None:
+        """Return nothing: without a scroll area, the window's layout requests are the only sign that its content changed."""
+        return None
+
+
+ContentMeasure = ScrolledContentMeasure | LayoutContentMeasure
+"""The measure a window gives the growth rule: by its scroll area, or by its own layout."""