gitpane 1.0.0__py3-none-any.whl

gitpane/ui/window_control/dialog_modality.py

@@ -0,0 +1,122 @@
+"""One rule to open a window that blocks the window it belongs to, or the whole application, chosen by Qt platform."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from PySide6.QtCore import QCoreApplication, QEvent, Qt
+from PySide6.QtGui import QGuiApplication, QKeySequence, QShortcut
+from PySide6.QtWidgets import QDialog, QMessageBox
+
+from gitpane.config import MACOS_PLATFORM_NAME
+from gitpane.ui.look.theme_look import follow_theme
+
+# What result() holds from the moment the dialog is shown until it is answered: QDialog.open() resets the previous answer to Rejected (0),
+# and the macOS row does the same. A Cancel leaves the same value, so it never tells an unanswered dialog from a refused one.
+UNANSWERED_DIALOG_RESULT = QDialog.DialogCode.Rejected.value
+# Object name of the Quit shortcut a modal window carries, so that opening the same window again adds no second one.
+QUIT_SHORTCUT_OBJECT_NAME = "gitpane_quit_shortcut"
+# Cmd+Q: Qt names the Command key Ctrl on macOS. Written out because the standard Quit key comes from the platform theme,
+# and the offscreen platform the headless tests run on has none.
+MACOS_QUIT_KEY_SEQUENCE = "Ctrl+Q"
+
+
+@dataclass(frozen=True)
+class ModalPresentation:
+    """How a dialog that blocks the window it belongs to is shown on one Qt platform."""
+
+    uses_dialog_open: bool
+    modality: Qt.WindowModality
+    greys_extra_title_buttons: bool
+    # True where the system's Quit shortcut never reaches the application while a modal window is open, so the modal
+    # window carries it itself.
+    carries_quit_shortcut: bool = False
+
+
+DEFAULT_MODAL_PRESENTATION = ModalPresentation(uses_dialog_open=True, modality=Qt.WindowModality.WindowModal, greys_extra_title_buttons=False)
+# Workaround: Qt's Cocoa backend shows every window-modal window that has a parent as a sheet, with no title bar and no
+# close button. Application modality is the only one that keeps a real titled window there.
+MODAL_PRESENTATION_BY_PLATFORM_NAME: dict[str, ModalPresentation] = {
+    MACOS_PLATFORM_NAME: ModalPresentation(uses_dialog_open=False, modality=Qt.WindowModality.ApplicationModal, greys_extra_title_buttons=True,
+                                           carries_quit_shortcut=True),
+}
+
+
+def modal_presentation(platform_name: str) -> ModalPresentation:
+    """Return how a modal dialog opens on a Qt platform, named as QGuiApplication.platformName() names it."""
+    return MODAL_PRESENTATION_BY_PLATFORM_NAME.get(platform_name, DEFAULT_MODAL_PRESENTATION)
+
+
+def open_window_modal(dialog: QDialog, *, keeps_window_buttons: bool = False, blocks_application: bool = False, platform_name: str = "") -> None:
+    """Show a dialog that blocks its window, titled with a working close button; where no sheet exists, exactly QDialog.open().
+
+    keeps_window_buttons leaves Qt's own title bar buttons, for the operation consoles. blocks_application makes the
+    dialog block every other window of the application on every system, for a dialog shared by every window and so
+    with no parent, such as Settings: QDialog.open() would make it window-modal, which blocks nothing without a parent.
+    platform_name stands in for the session's platform, so a headless test can check the row of any system. Where the
+    system keeps its Quit shortcut from a running modal window, the window gets its own.
+    """
+    presentation = modal_presentation(platform_name or QGuiApplication.platformName())
+    modality = Qt.WindowModality.ApplicationModal if blocks_application else presentation.modality
+    if presentation.uses_dialog_open and not blocks_application:
+        dialog.open()
+        return
+    # A dialog already shown the same way is left as it is: setting its flags or, for a question on a macOS build of
+    # Qt, its modality again would hide it and show it again.
+    if dialog.isVisible() and dialog.windowModality() == modality:
+        return
+    if presentation.carries_quit_shortcut:
+        add_quit_shortcut(dialog)
+    if presentation.greys_extra_title_buttons and not keeps_window_buttons and not dialog.windowFlags() & Qt.WindowType.CustomizeWindowHint:
+        # With this hint Qt enables each title bar button only when its own hint is set: close stays, minimize and zoom
+        # turn grey, and a window that asks for minimize and maximize keeps them. Set only when missing, because
+        # setWindowFlag hides a visible window to apply its flags.
+        dialog.setWindowFlag(Qt.WindowType.CustomizeWindowHint, True)
+    dialog.setWindowModality(modality)
+    # QDialog.open() clears the previous answer the same way before showing the dialog.
+    dialog.setResult(UNANSWERED_DIALOG_RESULT)
+    dialog.show()
+
+
+def add_quit_shortcut(dialog: QDialog) -> None:
+    """Give a modal window the system's Quit shortcut, which asks the application to quit as Cmd+Q does without a modal window.
+
+    Workaround: on macOS, AppKit keeps Cmd+Q and the Dock's Quit from the application while an application-modal window
+    runs, so GitPane never hears that the user wants to quit. A shortcut of the window itself still receives the key.
+    It sends the Quit event the system would have sent, and whoever handles quitting decides what to do with the open
+    windows; the Dock's Quit stays without effect while a modal window is open. Added once per window.
+    """
+    if dialog.findChild(QShortcut, QUIT_SHORTCUT_OBJECT_NAME, Qt.FindChildOption.FindDirectChildrenOnly) is not None:
+        return
+    shortcut = QShortcut(QKeySequence(MACOS_QUIT_KEY_SEQUENCE), dialog)
+    shortcut.setObjectName(QUIT_SHORTCUT_OBJECT_NAME)
+    shortcut.activated.connect(send_application_quit)
+
+
+def send_application_quit() -> None:
+    """Send the application the Quit event the system sends when the user quits it, answered before the key press ends, as Escape answers Cancel."""
+    application = QCoreApplication.instance()
+    if application is None:
+        return
+    QCoreApplication.sendEvent(application, QEvent(QEvent.Type.Quit))
+
+
+def prepare_message_box(box: QMessageBox, title: str, *, platform_name: str = "") -> None:
+    """Keep a question a Qt window that shows its title, on every system, and give it the icon of each new appearance.
+
+    Workaround: a macOS build of Qt ignores a message box's title, even offscreen, and shows it as a native alert with no
+    title bar. Windows and Linux never use a native message box and set the title the same way, so nothing changes there.
+
+    The style redraws a question icon that cannot be read on a dark window, and a message box keeps the icon it got when
+    it was set. A question open while the appearance changes sets its own icon again, so the style draws it for the
+    new appearance; the palette follower has already given the box its new palette by then.
+
+    Where the system keeps its Quit shortcut from a running modal window, the question gets its own here, so it has it
+    whether open_window_modal shows it or its own exec() runs it. platform_name stands in for the session's platform,
+    as in open_window_modal.
+    """
+    box.setOption(QMessageBox.Option.DontUseNativeDialog, True)
+    QDialog.setWindowTitle(box, title)
+    follow_theme(box, lambda: box.setIcon(box.icon()))
+    if modal_presentation(platform_name or QGuiApplication.platformName()).carries_quit_shortcut:
+        add_quit_shortcut(box)

gitpane/ui/window_control/item_activation.py

@@ -0,0 +1,42 @@
+"""Let Enter activate the current row of an item view on every system.
+
+Qt for macOS does not emit ``activated`` when Enter is pressed in an item view: it tries to edit the current item,
+then leaves the key to the window, and only Cmd+O activates. GitPane wants Enter to open, choose or navigate as in
+Git Extensions on every system, so the views where Enter acts pass their key presses through ``activate_current_row``,
+which does what Qt does on Windows and Linux. The behaviour is the same everywhere, so nothing here depends on the
+system or the Qt platform.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, Qt
+from PySide6.QtWidgets import QAbstractItemView
+
+if TYPE_CHECKING:
+    from PySide6.QtGui import QKeyEvent
+
+ACTIVATION_KEY_SET = frozenset({Qt.Key.Key_Return, Qt.Key.Key_Enter})
+"""Keys that activate the current row: the main Enter key and the one of the numeric keypad."""
+
+
+def activate_current_row(view: QAbstractItemView, event: QEvent) -> bool:
+    """Activate the view's current row once on Enter, and let the key go on to the window; return whether Enter was handled.
+
+    Called from an event filter on the view. On Enter, while no editor is open and a row is current, the view's
+    ``activated`` signal is emitted for that row and the event is marked ignored, so the key still reaches the window,
+    where a dialog's default button reads the row just chosen. The caller returns ``True`` so the view does not act on
+    the key itself: on macOS it would try to edit the row, elsewhere it would emit ``activated`` a second time.
+    """
+    if event.type() != QEvent.Type.KeyPress:
+        return False
+    key_event: QKeyEvent = event
+    if key_event.key() not in ACTIVATION_KEY_SET or view.state() == QAbstractItemView.State.EditingState:
+        return False
+    current_index = view.currentIndex()
+    if not current_index.isValid():
+        return False
+    view.activated.emit(current_index)
+    key_event.ignore()
+    return True

gitpane/ui/window_control/modal_focus_relay.py

@@ -0,0 +1,124 @@
+"""Bring the modal window back in front when the window system activates a window it blocks.
+
+Under Wayland, a compositor keeps a modal window in front of a window only when the modal window is that window's
+transient. A window modal for the whole application, such as Settings, has no parent: a click on a window it blocks
+makes the compositor raise and activate that window above it, while Qt still refuses that window's input. Qt's X11
+plugin already relays the focus to the modal window itself, and Windows and macOS never activate a blocked window, so
+the way to bring the modal window back is chosen per Qt platform, once, by the composition root.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QEvent, QObject, Qt
+from PySide6.QtGui import QGuiApplication, QWindow
+from shiboken6 import getCppPointer
+
+from gitpane.config import WAYLAND_PLATFORM_NAME
+from gitpane.ui.window_control.wayland_activation import activate_window_with_keyboard_token
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+ModalWindowActivator = Callable[[QWindow], bool]
+"""Bring a GitPane window to the front through the window system, and tell whether it was asked."""
+
+# Where a platform is missing (X11, Windows, macOS, the offscreen platform of the tests), the window system or Qt
+# already keeps the modal window in front of the windows it blocks.
+MODAL_WINDOW_ACTIVATOR_BY_PLATFORM_NAME: dict[str, ModalWindowActivator] = {
+    WAYLAND_PLATFORM_NAME: activate_window_with_keyboard_token,
+}
+# The only events the filter acts on; it runs on every event of the application, so it lets any other one through at once.
+WINDOW_BLOCKING_EVENT_TYPE_SET = frozenset({QEvent.Type.WindowBlocked, QEvent.Type.WindowUnblocked})
+# Place of the C++ address in what shiboken6.getCppPointer answers: index 0 is the address of the object seen as its
+# first C++ base (QObject for a QWindow, which also derives from QSurface), the same at every reading of a QWindow.
+CPP_ADDRESS_INDEX = 0
+
+
+def modal_window_activator(platform_name: str) -> ModalWindowActivator | None:
+    """Return how a Qt platform, under the name Qt gives it, brings the modal window back, or None where nothing is needed.
+
+    Pure, so the table can be checked for every platform from any machine.
+    """
+    return MODAL_WINDOW_ACTIVATOR_BY_PLATFORM_NAME.get(platform_name)
+
+
+def _window_address(window: QWindow) -> int:
+    """Return the C++ address of a window, which names it in the blocked set and still names it while it is destroyed."""
+    return getCppPointer(window)[CPP_ADDRESS_INDEX]
+
+
+def _transient_chain(window: QWindow) -> Iterator[QWindow]:
+    """Yield a window, then each of its transient parents up to the window that has none."""
+    current: QWindow | None = window
+    while current is not None:
+        yield current
+        current = current.transientParent()
+
+
+# Workaround: under Wayland, Qt sends a window modal for the whole application without any parent, so the compositor
+# does not keep it in front of the windows it blocks, and Qt's Wayland plugin, unlike its X11 plugin, does not hand the
+# focus back to the modal window when the compositor activates a blocked one. This relay follows the windows Qt
+# declares blocked; when the focus reaches one of them, it asks the window system, once, to activate the modal window
+# Qt hands the input to. A modal window that blocks only its own window is left to the compositor: it is that window's
+# transient, which the compositor already keeps in front.
+class ModalFocusRelay(QObject):
+    """Bring the application-modal window back in front when the focus reaches a window it blocks."""
+
+    def __init__(self, application: QGuiApplication, activate: ModalWindowActivator, parent: QObject | None = None) -> None:
+        """Follow the blocked windows of ``application`` and its focus window; ``activate`` brings a window back through the window system.
+
+        The relay belongs to ``parent`` rather than to the application: it runs on every event of the application, so it
+        must end with the wiring that created it.
+        """
+        super().__init__(parent)
+        self.application = application
+        self.activate = activate
+        self.blocked_window_address_set: set[int] = set()
+        # The windows whose end the relay already follows, so a window blocked again and again gets one connection.
+        self.followed_window_address_set: set[int] = set()
+        application.installEventFilter(self)
+        application.focusWindowChanged.connect(self.follow_focus_window)
+
+    def eventFilter(self, watched: QObject, event: QEvent) -> bool:
+        """Note each window Qt blocks or unblocks under a modal window, letting every event through."""
+        if event.type() not in WINDOW_BLOCKING_EVENT_TYPE_SET or not watched.isWindowType():
+            return False
+        address = _window_address(watched)
+        if event.type() == QEvent.Type.WindowUnblocked:
+            self.blocked_window_address_set.discard(address)
+            return False
+        self.blocked_window_address_set.add(address)
+        if address not in self.followed_window_address_set:
+            self.followed_window_address_set.add(address)
+            # The sets themselves are captured, not the relay: the window may outlive the relay, and its end must not reach a deleted relay.
+            watched.destroyed.connect(lambda _object=None, gone=address, blocked=self.blocked_window_address_set, followed=self.followed_window_address_set:
+                                      (blocked.discard(gone), followed.discard(gone)))
+        return False
+
+    def follow_focus_window(self, window: QWindow | None) -> None:
+        """When the focus reaches a window an application-modal window blocks, ask once to bring the modal window back.
+
+        The modal window brought back is the one Qt hands the input to, the modal window shown last; a window in its
+        chain of transient parents, or the modal window itself, is already kept behind it by the compositor.
+        """
+        if window is None or _window_address(window) not in self.blocked_window_address_set:
+            return
+        modal = QGuiApplication.modalWindow()
+        if modal is None or not blocks_whole_application(modal):
+            return
+        window_address = _window_address(window)
+        for chained in _transient_chain(modal):
+            if _window_address(chained) == window_address:
+                return
+        self.activate(modal)
+
+
+def blocks_whole_application(modal: QWindow) -> bool:
+    """Tell whether a modal window, or one of its transient parents, is modal for the whole application."""
+    for chained in _transient_chain(modal):
+        if chained.modality() == Qt.WindowModality.ApplicationModal:
+            return True
+    return False