gitpane 1.0.0__py3-none-any.whl

gitpane/ui/widget/system_shortcut.py

@@ -0,0 +1,75 @@
+"""Give each system its own keys for the shortcuts GitPane offers."""
+
+from __future__ import annotations
+
+import sys
+
+from PySide6.QtCore import Qt
+
+from gitpane.config import MACOS_PLATFORM
+
+# On macOS Cmd+R (Ctrl in Qt's portable notation, where Ctrl stands for the Command key) comes first so the menu shows
+# it, since a menu shows only the primary shortcut of an action; F5 stays. Windows and Linux keep F5 alone.
+REFRESH_SHORTCUTS_BY_PLATFORM: dict[str, tuple[str, ...]] = {MACOS_PLATFORM: ("Ctrl+R", "F5")}
+DEFAULT_REFRESH_SHORTCUTS: tuple[str, ...] = ("F5",)
+
+
+def refresh_shortcuts(platform: str = sys.platform) -> tuple[str, ...]:
+    """Return the portable sequences that refresh a repository window on the given system, the primary one first.
+
+    A system missing from the table keeps F5 alone rather than another system's keys.
+    """
+    return REFRESH_SHORTCUTS_BY_PLATFORM.get(platform, DEFAULT_REFRESH_SHORTCUTS)
+
+
+# The delete key of a Mac keyboard sends Backspace, and the Finder moves a file to the trash with Cmd+Backspace (Ctrl in
+# Qt, where Ctrl stands for the Command key); Delete, sent by fn+delete or a PC keyboard, keeps working. On Windows and
+# Linux Backspace erases a character and Ctrl+Backspace a word, so only Delete trashes there.
+DEFAULT_TRASH_KEY_SET: frozenset[tuple[Qt.Key, Qt.KeyboardModifier]] = frozenset({(Qt.Key.Key_Delete, Qt.KeyboardModifier.NoModifier)})
+TRASH_KEY_SET_BY_PLATFORM: dict[str, frozenset[tuple[Qt.Key, Qt.KeyboardModifier]]] = {
+    MACOS_PLATFORM: DEFAULT_TRASH_KEY_SET | {(Qt.Key.Key_Backspace, Qt.KeyboardModifier.NoModifier), (Qt.Key.Key_Backspace, Qt.KeyboardModifier.ControlModifier)},
+}
+# macOS may report the Delete key of a PC keyboard with the keypad modifier; it is the same key for the user.
+KEYPAD_MODIFIER_IGNORED_PLATFORM_SET = frozenset({MACOS_PLATFORM})
+
+
+def trash_key_set(platform: str = sys.platform) -> frozenset[tuple[Qt.Key, Qt.KeyboardModifier]]:
+    """Return the keys, each with its exact modifiers, that move the selected files to the trash on the given system.
+
+    A system missing from the table trashes with Delete alone rather than with another system's keys.
+    """
+    return TRASH_KEY_SET_BY_PLATFORM.get(platform, DEFAULT_TRASH_KEY_SET)
+
+
+def trash_key_pressed(key: int, modifiers: Qt.KeyboardModifier, platform: str = sys.platform) -> bool:
+    """Tell whether a pressed key and its modifiers ask for the trash on the given system."""
+    if platform in KEYPAD_MODIFIER_IGNORED_PLATFORM_SET:
+        modifiers = modifiers & ~Qt.KeyboardModifier.KeypadModifier
+    return (key, modifiers) in trash_key_set(platform)
+
+
+FIND_NEXT_ACTION = "next"
+FIND_PREVIOUS_ACTION = "previous"
+DEFAULT_FIND_SHORTCUTS: tuple[tuple[str, str], ...] = (("F3", FIND_NEXT_ACTION), ("Shift+F3", FIND_PREVIOUS_ACTION))
+# F3 needs Fn on a Mac laptop and Cmd+G / Cmd+Shift+G is how macOS finds the next and previous match (Ctrl in Qt's
+# portable notation); F3 stays. Windows and Linux keep F3 and Shift+F3.
+FIND_SHORTCUTS_BY_PLATFORM: dict[str, tuple[tuple[str, str], ...]] = {
+    MACOS_PLATFORM: (*DEFAULT_FIND_SHORTCUTS, ("Ctrl+G", FIND_NEXT_ACTION), ("Ctrl+Shift+G", FIND_PREVIOUS_ACTION)),
+}
+
+
+def find_shortcuts(platform: str = sys.platform) -> tuple[tuple[str, str], ...]:
+    """Return the portable sequences that find the next or previous match in a reading panel, each with its action name.
+
+    The diff and the commit message read this one table, so their keys cannot drift apart. A system missing from the
+    table keeps F3 and Shift+F3 rather than another system's keys.
+    """
+    return FIND_SHORTCUTS_BY_PLATFORM.get(platform, DEFAULT_FIND_SHORTCUTS)
+
+
+# The keys of the rebase editor window: Ctrl+Return and Ctrl+Enter of the keypad press its validating button, Ctrl+S
+# saves without answering Git. Written out because the standard keys come from the platform theme, and the offscreen
+# platform the headless tests run on has none. Ctrl stands for the Command key on macOS in Qt's portable notation, so
+# the same sequences give Cmd+Return and Cmd+S there without a table per system.
+EDITOR_VALIDATE_SHORTCUTS: tuple[str, ...] = ("Ctrl+Return", "Ctrl+Enter")
+EDITOR_SAVE_SHORTCUTS: tuple[str, ...] = ("Ctrl+S",)

gitpane/ui/widget/unavailable_reason.py

@@ -0,0 +1,29 @@
+"""Turn the reasons of greyed buttons into visible text, since a disabled button's tooltip is easy to miss."""
+
+from __future__ import annotations
+
+
+def joined_names(names: list[str]) -> str:
+    """Join button names the way a sentence lists them: "A", "A and B", "A, B and C"."""
+    if len(names) == 1:
+        return names[0]
+    *leading_names, last_name = names
+    return ", ".join(leading_names) + " and " + last_name
+
+
+def unavailable_reason_text(reason_by_name: dict[str, str], shown_text: str = "") -> str:
+    """Name every unavailable button with its reason, one line per distinct reason, in the order the buttons are given.
+
+    Buttons that share a reason are named together so the reason is written once, and a reason already present in
+    ``shown_text`` (the text displayed next to it) is not repeated.
+    """
+    names_by_reason: dict[str, list[str]] = {}
+    for name, reason in reason_by_name.items():
+        if not reason or reason in shown_text:
+            continue
+        names_by_reason.setdefault(reason, []).append(name)
+    lines: list[str] = []
+    for reason, names in names_by_reason.items():
+        verb = " is" if len(names) == 1 else " are"
+        lines.append(joined_names(names) + verb + " unavailable: " + reason)
+    return "\n".join(lines)

gitpane/ui/widget/wheel_safe_drop_down.py

@@ -0,0 +1,24 @@
+"""Offer a drop-down list that leaves the mouse wheel to the form around it."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtWidgets import QComboBox
+
+if TYPE_CHECKING:
+    from PySide6.QtGui import QWheelEvent
+    from PySide6.QtWidgets import QWidget
+
+
+class UrlSelector(QComboBox):
+    """Require deliberate selection while letting wheel input scroll the containing form."""
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        """Keep long URLs from expanding the remote editor beyond its screen."""
+        super().__init__(parent)
+        self.setSizeAdjustPolicy(QComboBox.SizeAdjustPolicy.AdjustToMinimumContentsLengthWithIcon)
+
+    def wheelEvent(self, event: QWheelEvent) -> None:
+        """Ignore wheel input so navigation cannot change an edited URL accidentally."""
+        event.ignore()

gitpane/ui/window_control/button_focus.py

@@ -0,0 +1,42 @@
+"""Disable a button while its work runs without Qt handing its focus to the next field, then give it back."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import Qt
+
+if TYPE_CHECKING:
+    from PySide6.QtWidgets import QAbstractButton
+
+# Set on a button whose focus was parked on its window while it was disabled, so only that button takes it back.
+PARKED_FOCUS_PROPERTY = "gitpaneParkedFocus"
+
+
+def set_button_enabled(button: QAbstractButton, enabled: bool) -> None:
+    """Enable or disable a button that may hold the focus of its window, leaving every other widget as it was.
+
+    Disabling the widget that holds the focus of its window makes Qt move that focus to the next widget of the tab
+    chain, as a Tab press would. A line edit reached that way selects all its text, so clicking a check button
+    selected a field the user never touched. Before the button is disabled its focus is parked on the window itself,
+    which takes no input and selects nothing; once enabled again, the button takes the focus back if it is still
+    parked there. A focus the user moved elsewhere meanwhile is left where the user put it.
+    """
+    if not enabled:
+        _disable_keeping_focus(button)
+        return
+    button.setEnabled(True)
+    parked = bool(button.property(PARKED_FOCUS_PROPERTY))
+    button.setProperty(PARKED_FOCUS_PROPERTY, False)
+    window = button.window()
+    if parked and window.focusWidget() is window and button.isVisible():
+        button.setFocus(Qt.FocusReason.OtherFocusReason)
+
+
+def _disable_keeping_focus(button: QAbstractButton) -> None:
+    """Park the focus of the button on its window when the button holds it, then disable the button."""
+    window = button.window()
+    if window is not button and window.focusWidget() is button:
+        window.setFocus(Qt.FocusReason.OtherFocusReason)
+        button.setProperty(PARKED_FOCUS_PROPERTY, True)
+    button.setEnabled(False)

gitpane/ui/window_control/compositor_answer.py

@@ -0,0 +1,152 @@
+"""Hold a size change asked just after a window is shown until the window system has answered that show.
+
+Workaround: a compositor that places the windows itself (Mutter under Wayland) answers the first show of a window with a
+configure that carries the activated state and the size it knew when it read the window's first commit, and Qt applies
+that size. A size GitPane asks a few milliseconds after the show, before Qt has applied that configure, is overwritten by
+it for good: it is not undone then applied again, as under X11. Such a size change therefore waits for the answer, which
+is two facts, in either order: the activation delivered to the window (``WindowActivate``), and a configure Qt applied
+while the window has the keyboard.
+
+``isActiveWindow()`` only tells that the compositor has given the window the keyboard: Qt Wayland reports it true as soon
+as the keyboard arrives, which comes with the activated configure, before Qt applies that configure at the end of the
+frame in progress. ``WindowActivate`` is no proof either: Qt delivers it after a round trip to the compositor, which can
+end before the configure is applied. A configure applied reaches Python as a spontaneous ``WindowStateChange`` that Qt
+Wayland sends the native window each time it applies one, whether the size changed or not, or as a spontaneous resize
+when the size changed. The configure applied before the window has the keyboard answers the window's first commit, not
+its activation, and does not count.
+
+A window the compositor never activates (opened while the user is in another application), or a Qt that stops sending
+that state change, still gets its size change once ``COMPOSITOR_ANSWER_TIMEOUT_MS`` has passed. Only the answer to the
+last show is waited for: once it has come, a later change is made in the call, even while the window is inactive, until
+the window is hidden and shown again. Where the window system has no such answer (X11, Windows, macOS), the change is
+made in the call, as it always was.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, QObject, Qt, QTimer
+from PySide6.QtWidgets import QApplication
+from shiboken6 import isValid
+
+from gitpane.config import COMPOSITOR_ANSWER_TIMEOUT_MS, window_placement
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from PySide6.QtGui import QWindow
+    from PySide6.QtWidgets import QWidget
+
+# Name of the object that follows, for one window, whether the compositor has answered its last show.
+ANSWER_WATCH_OBJECT_NAME = "gitpane_compositor_answer_watch"
+
+
+class _CompositorAnswerWatch(QObject):
+    """Follow whether the compositor has answered the window's last show, and keep the size changes asked before that answer.
+
+    It is a child of the window, so it and its bounding timer go with the window: a window deleted before the answer
+    never runs its pending changes. It stays for the window's life, so a window shown again waits for the new answer.
+    It watches the window and its native window, where Qt reports each configure it applies. It reaches the window as
+    its parent and keeps no reference of its own to it, so no reference cycle holds the window longer than its owners.
+    """
+
+    def __init__(self, window: QWidget, answered: bool) -> None:
+        """Watch the window's shows and the compositor's answers; a window still waiting gets the bound started."""
+        super().__init__(window)
+        self.setObjectName(ANSWER_WATCH_OBJECT_NAME)
+        self.actions: list[Callable[[], None]] = []
+        self.answered = answered
+        self.activated = answered
+        self.configure_applied = answered
+        self.native_window: QWindow | None = None
+        self.bound_timer = QTimer(self)
+        self.bound_timer.setSingleShot(True)
+        self.bound_timer.setInterval(COMPOSITOR_ANSWER_TIMEOUT_MS)
+        self.bound_timer.timeout.connect(self.make_pending_changes)
+        if not answered:
+            self.bound_timer.start()
+        window.installEventFilter(self)
+        self.follow_native_window()
+
+    def follow_native_window(self) -> None:
+        """Watch the window's current native window, where Qt reports the configures it applies; nothing while it has none."""
+        native_window = self.parent().windowHandle()
+        if native_window is self.native_window:
+            return
+        if self.native_window is not None and isValid(self.native_window):
+            self.native_window.removeEventFilter(self)
+        self.native_window = native_window
+        if native_window is not None:
+            native_window.installEventFilter(self)
+
+    def eventFilter(self, watched: QObject, event: QEvent) -> bool:
+        """Wait again at each show the application makes; note the activation and the configure applied that answer it.
+
+        A show the window system makes (a window restored from the dock) is not a new first show, and is not waited for.
+        A state change or a resize the application makes itself is no configure of the compositor.
+        """
+        event_type = event.type()
+        if watched is self.parent():
+            if event_type == QEvent.Type.Show and not event.spontaneous():
+                self.wait_for_new_answer()
+            elif event_type == QEvent.Type.WindowActivate:
+                self.activated = True
+                self.make_changes_if_answered()
+            elif event_type == QEvent.Type.Resize and event.spontaneous():
+                self.note_configure_applied()
+        elif event_type == QEvent.Type.WindowStateChange and event.spontaneous():
+            self.note_configure_applied()
+        return False
+
+    def wait_for_new_answer(self) -> None:
+        """Forget the last answer and start the bound again, for a show the compositor will answer anew."""
+        self.answered = False
+        self.activated = False
+        self.configure_applied = False
+        self.bound_timer.start()
+        self.follow_native_window()
+
+    def note_configure_applied(self) -> None:
+        """Count a configure Qt applied only while the window has the keyboard: the one before answers the first commit."""
+        if not self.parent().isActiveWindow():
+            return
+        self.configure_applied = True
+        self.make_changes_if_answered()
+
+    def make_changes_if_answered(self) -> None:
+        """Make the pending changes once both the activation and a configure applied with the keyboard have come."""
+        if self.activated and self.configure_applied:
+            self.make_pending_changes()
+
+    def make_pending_changes(self) -> None:
+        """Note that the compositor has answered, then make every pending change once, in the order asked."""
+        if self.answered:
+            return
+        self.answered = True
+        self.bound_timer.stop()
+        actions = self.actions
+        self.actions = []
+        for action in actions:
+            action()
+
+
+def after_compositor_answer(window: QWidget, action: Callable[[], None], *, platform_name: str = "") -> None:
+    """Make a size change of a window now, or once the compositor has answered the window's show where that answer would overwrite it.
+
+    The change is made in the call when the platform's placement row does not wait, when the window is hidden (there is
+    no show to answer), or when the compositor already answered its last show. A window first seen here is taken as
+    answered only when it is already the application's active window, which Qt makes it once the activation is
+    delivered; otherwise it is taken as just shown, and only the events it then receives say the answer came.
+    ``platform_name`` is Qt's platform name, read from Qt when not given.
+    """
+    if not window_placement(platform_name).size_waits_for_compositor_answer or not window.isVisible():
+        action()
+        return
+    watch = window.findChild(QObject, ANSWER_WATCH_OBJECT_NAME, Qt.FindChildOption.FindDirectChildrenOnly)
+    if not isinstance(watch, _CompositorAnswerWatch):
+        watch = _CompositorAnswerWatch(window, QApplication.activeWindow() is window)
+    if watch.answered:
+        action()
+        return
+    watch.actions.append(action)

gitpane/ui/window_control/compositor_growth_cap.py

@@ -0,0 +1,73 @@
+"""Bound the frame of a window that grows below the top the compositor placed it at.
+
+Under Wayland the compositor centres a window when it opens, then can keep its top when the window grows, and GitPane
+cannot move the window back up there. Qt sees neither the desktop's panels (its usable area is the whole screen) nor a
+title bar the compositor draws itself (the window reports no frame margin). Elsewhere GitPane moves a growing window back
+up itself, and only the estimated usable height counts there.
+
+Margin of the estimates: a frame of height h0 centred in the usable height A has its top at (A - h0) / 2, and grown
+keeping that top it stays inside A as long as it is no taller than (A + h0) / 2. Centring halves an error on A or on the
+title bar, so the frame stays above the real panels as long as the real panels and the real title bar together take at
+most both estimates plus twice ``SCREEN_MARGIN``, whatever h0.
+"""
+
+from __future__ import annotations
+
+from gitpane.config import SCREEN_MARGIN
+
+UNSEEN_PANEL_HEIGHT_ESTIMATE = 48
+"""Height taken off a usable area that Qt counts as the whole screen, for the panels it does not see there.
+
+Qt reports the whole screen as usable when it does not know the desktop's panels, as under Wayland; the default Plasma
+panel reserves 46 px.
+"""
+
+UNSEEN_TITLE_BAR_HEIGHT_ESTIMATE = 32
+"""Height counted for a decorated window's title bar when Qt knows no margin of its frame (the compositor draws it).
+
+The Breeze title bar KWin draws is 28 px with the default title font; the rest leaves room for a slightly larger font.
+"""
+
+CENTRED_SIDE_COUNT = 2
+"""Sides a centred window leaves equal room on: the room left by its frame is split between them."""
+
+
+def usable_height_estimate(qt_usable_height: int, qt_screen_height: int) -> int:
+    """Return the height a window can use on its screen: Qt's usable height, less an unseen panel when Qt counts the whole screen.
+
+    A usable height smaller than the screen means Qt already took the panels off (X11, Windows, macOS), so it is kept as
+    it is. Qt cannot tell a screen without panels from panels it does not know, so both lose the estimate.
+    """
+    if qt_usable_height < qt_screen_height:
+        return qt_usable_height
+    return qt_usable_height - UNSEEN_PANEL_HEIGHT_ESTIMATE
+
+
+def decoration_height_estimate(known_decoration_height: int, decorated: bool) -> int:
+    """Return the height a window's title bar and borders take: what Qt knows, nothing for a frameless window, otherwise the estimated title bar."""
+    if known_decoration_height > 0:
+        return known_decoration_height
+    if not decorated:
+        return 0
+    return UNSEEN_TITLE_BAR_HEIGHT_ESTIMATE
+
+
+def kept_top_frame_cap(usable_height: int, placed_frame_height: int) -> int:
+    """Return the tallest frame that, grown below the top it had when centred at ``placed_frame_height``, still ends ``SCREEN_MARGIN`` above the usable height's bottom.
+
+    A window placed with a frame taller than the usable height less both margins gets a cap no taller than that frame,
+    so it does not grow.
+    """
+    return (usable_height + placed_frame_height) // CENTRED_SIDE_COUNT - SCREEN_MARGIN
+
+
+def growth_frame_cap(usable_height: int, share: float, placed_frame_height: int | None) -> int:
+    """Return the tallest frame a growing window reaches: ``share`` of the usable height, and no more than the room under its kept top when it has one.
+
+    ``placed_frame_height`` is the frame the window had when the compositor placed it, given only where the compositor
+    keeps that top; ``None`` where GitPane moves a growing window back up itself, so the share alone counts.
+    """
+    share_cap = int(usable_height * share)
+    if placed_frame_height is None:
+        return share_cap
+    return min(share_cap, kept_top_frame_cap(usable_height, placed_frame_height))

gitpane/ui/window_control/desktop_activation.py

@@ -0,0 +1,203 @@
+"""Tell the desktop when the user last acted in GitPane, so a window opened for that action comes to the front.
+
+What the desktop needs depends on the Qt platform, chosen in one table: under X11 a startup identifier carrying the
+time of the user's last action, read from the window property Qt keeps for the window manager; under Wayland an
+activation token the compositor hands out for that action; elsewhere nothing, the system deciding alone.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import functools
+import logging
+import os
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from PySide6.QtGui import QGuiApplication
+
+from gitpane.config import WAYLAND_PLATFORM_NAME, X11_PLATFORM_NAME
+from gitpane.system.startup_activation import StartupActivation, StartupHandoff
+from gitpane.ui.window_control.wayland_activation import wayland_activation_token
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+X11_LIBRARY_NAME = "X11"
+STARTUP_ID_PREFIX = "gitpane-"
+STARTUP_ID_TIME_SEPARATOR = "_TIME"
+USER_TIME_ATOM_NAME = b"_NET_WM_USER_TIME"
+USER_TIME_WINDOW_ATOM_NAME = b"_NET_WM_USER_TIME_WINDOW"
+# Arguments of XInternAtom and XGetWindowProperty: read one 32-bit value of any type, never create an atom, never delete the property.
+ONLY_IF_EXISTS = True
+PROPERTY_OFFSET = 0
+SINGLE_VALUE_LENGTH = 1
+KEEP_PROPERTY = False
+ANY_PROPERTY_TYPE = 0
+X_SUCCESS = 0
+VALUE_FORMAT_BITS = 32
+FIRST_VALUE_INDEX = 0
+# X server times are 32-bit milliseconds that wrap around; a time is later when it is less than half the range ahead.
+X_TIME_RANGE = 1 << 32
+X_TIME_HALF_RANGE = 1 << 31
+
+# Xlib error handler signature: int handler(Display *, XErrorEvent *).
+X_ERROR_HANDLER_TYPE = ctypes.CFUNCTYPE(ctypes.c_int, ctypes.c_void_p, ctypes.c_void_p)
+
+
+def _ignore_x_error(_display: int | None, _error: int | None) -> int:
+    """Let a window that closed during the read give no value instead of ending GitPane, as Xlib's default handler would."""
+    return 0
+
+
+# Kept at module level: Xlib calls this pointer, so it must outlive every read.
+IGNORE_X_ERROR_HANDLER = X_ERROR_HANDLER_TYPE(_ignore_x_error)
+
+
+def startup_id_for_time(user_time: int | None) -> str:
+    """Build the startup identifier that hands an X server time to the program GitPane asks to show a window.
+
+    The window manager reads the time after the "_TIME" suffix and lets the new window come to the front when that
+    time is not older than the user's last action in the active window. The identifier holds only GitPane's process
+    number and that time, never a path or any text from the user. No time, or time zero (which means "do not
+    activate"), gives the empty identifier GitPane sent before.
+    """
+    if not user_time:
+        return ""
+    return f"{STARTUP_ID_PREFIX}{os.getpid()}{STARTUP_ID_TIME_SEPARATOR}{user_time}"
+
+
+def desktop_startup_id() -> str:
+    """Return the X11 startup identifier for the user's last action in GitPane, or an empty one when no time is found.
+
+    Read on the GUI thread when the user asks for the action, before any worker starts, so the time is the one of
+    that request. Only the X11 row of the startup activation table calls it.
+    """
+    window_ids: list[int] = []
+    for window in QGuiApplication.topLevelWindows():
+        if window.isVisible():
+            window_ids.append(int(window.winId()))
+    if not window_ids:
+        return ""
+    try:
+        user_time = _latest_user_time(window_ids)
+    except (OSError, AttributeError, ctypes.ArgumentError) as error:
+        logging.getLogger(__name__).debug("Cannot read the time of the last user action: %s", error)
+        user_time = None
+    return startup_id_for_time(user_time)
+
+
+# Workaround: Qt keeps the time of the user's last click or key press in a window property for the window manager but
+# does not give it to Python. Without that time in the startup identifier, Cinnamon's focus stealing prevention keeps
+# the file manager opened by the Show in folder entry behind GitPane. This reads the property through the X11 library that every
+# X11 desktop already has, on a separate read-only connection: nothing is written to the server.
+@functools.cache
+def _x11_library() -> ctypes.CDLL:
+    """Load the X11 library once and declare the calls this module makes."""
+    library_name = ctypes.util.find_library(X11_LIBRARY_NAME)
+    if library_name is None:
+        raise OSError("The X11 library is not installed.")
+    library = ctypes.CDLL(library_name)
+    library.XOpenDisplay.argtypes = [ctypes.c_char_p]
+    library.XOpenDisplay.restype = ctypes.c_void_p
+    library.XCloseDisplay.argtypes = [ctypes.c_void_p]
+    library.XCloseDisplay.restype = ctypes.c_int
+    library.XSetErrorHandler.argtypes = [ctypes.c_void_p]
+    library.XSetErrorHandler.restype = ctypes.c_void_p
+    library.XInternAtom.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_int]
+    library.XInternAtom.restype = ctypes.c_ulong
+    library.XGetWindowProperty.argtypes = [ctypes.c_void_p, ctypes.c_ulong, ctypes.c_ulong, ctypes.c_long, ctypes.c_long, ctypes.c_int, ctypes.c_ulong,
+                                           ctypes.POINTER(ctypes.c_ulong), ctypes.POINTER(ctypes.c_int), ctypes.POINTER(ctypes.c_ulong),
+                                           ctypes.POINTER(ctypes.c_ulong), ctypes.POINTER(ctypes.c_void_p)]
+    library.XGetWindowProperty.restype = ctypes.c_int
+    library.XFree.argtypes = [ctypes.c_void_p]
+    library.XFree.restype = ctypes.c_int
+    return library
+
+
+def _latest_user_time(window_ids: list[int]) -> int | None:
+    """Return the latest user action time recorded on GitPane's visible windows, or None when none has one."""
+    library = _x11_library()
+    display = library.XOpenDisplay(None)
+    if not display:
+        raise OSError("The X server cannot be reached.")
+    previous_handler = library.XSetErrorHandler(ctypes.cast(IGNORE_X_ERROR_HANDLER, ctypes.c_void_p))
+    try:
+        user_time_atom = library.XInternAtom(display, USER_TIME_ATOM_NAME, ONLY_IF_EXISTS)
+        user_time_window_atom = library.XInternAtom(display, USER_TIME_WINDOW_ATOM_NAME, ONLY_IF_EXISTS)
+        if not user_time_atom:
+            return None
+        latest_time: int | None = None
+        for window_id in window_ids:
+            # Qt may keep the time on a small helper window that the main window names, as the desktop standard allows.
+            user_time_window_id = _window_property_value(library, display, window_id, user_time_window_atom) if user_time_window_atom else None
+            user_time = _window_property_value(library, display, user_time_window_id or window_id, user_time_atom)
+            if user_time and (latest_time is None or _is_later_x_time(user_time, latest_time)):
+                latest_time = user_time
+        return latest_time
+    finally:
+        library.XSetErrorHandler(previous_handler)
+        library.XCloseDisplay(display)
+
+
+def _window_property_value(library: ctypes.CDLL, display: int, window_id: int, atom: int) -> int | None:
+    """Read the first 32-bit value of a window property, or None when the window or the property is gone."""
+    actual_type = ctypes.c_ulong()
+    actual_format = ctypes.c_int()
+    item_count = ctypes.c_ulong()
+    bytes_after = ctypes.c_ulong()
+    data = ctypes.c_void_p()
+    status = library.XGetWindowProperty(display, window_id, atom, PROPERTY_OFFSET, SINGLE_VALUE_LENGTH, KEEP_PROPERTY, ANY_PROPERTY_TYPE,
+                                        ctypes.byref(actual_type), ctypes.byref(actual_format), ctypes.byref(item_count), ctypes.byref(bytes_after), ctypes.byref(data))
+    try:
+        if status != X_SUCCESS or actual_format.value != VALUE_FORMAT_BITS or not item_count.value or not data.value:
+            return None
+        # Xlib hands 32-bit property values back as C longs.
+        return ctypes.cast(data, ctypes.POINTER(ctypes.c_ulong))[FIRST_VALUE_INDEX]
+    finally:
+        if data.value:
+            library.XFree(data)
+
+
+def _is_later_x_time(candidate: int, reference: int) -> bool:
+    """Compare two X server times the way the window manager does, across the 32-bit wrap-around."""
+    return candidate != reference and (candidate - reference) % X_TIME_RANGE < X_TIME_HALF_RANGE
+
+
+def _no_startup_value() -> str:
+    """Answer no startup value, on a Qt platform whose desktop takes none."""
+    return ""
+
+
+@dataclass(frozen=True)
+class StartupActivationSource:
+    """How a Qt platform's desktop learns that the user asked for a program: the handoff, and the reader of its value."""
+
+    handoff: StartupHandoff
+    read: Callable[[], str]
+
+
+NO_STARTUP_ACTIVATION_SOURCE = StartupActivationSource(StartupHandoff.NONE, _no_startup_value)
+# Where a platform is missing (Windows, macOS, the offscreen platform of the tests), the system decides alone whether a
+# started program's window comes to the front.
+STARTUP_ACTIVATION_SOURCE_BY_PLATFORM_NAME: dict[str, StartupActivationSource] = {
+    X11_PLATFORM_NAME: StartupActivationSource(StartupHandoff.X11_STARTUP_ID, desktop_startup_id),
+    WAYLAND_PLATFORM_NAME: StartupActivationSource(StartupHandoff.WAYLAND_ACTIVATION_TOKEN, wayland_activation_token),
+}
+
+
+def startup_activation_source(platform_name: str) -> StartupActivationSource:
+    """Return how a Qt platform, under the name Qt gives it, hands the user's action to a started program."""
+    return STARTUP_ACTIVATION_SOURCE_BY_PLATFORM_NAME.get(platform_name, NO_STARTUP_ACTIVATION_SOURCE)
+
+
+def desktop_activation(platform_name: str = "") -> StartupActivation:
+    """Read the startup value of the user's click, with the way the started program receives it.
+
+    Called on the window's thread when the user asks for a program, before any worker starts, and never otherwise: a
+    Wayland token starts the compositor's startup notice. platform_name stands in for the session's platform, so a
+    headless test can check the row of any system.
+    """
+    source = startup_activation_source(platform_name or QGuiApplication.platformName())
+    return StartupActivation(source.handoff, source.read())