gitpane 1.0.0__py3-none-any.whl

gitpane/ui/setting/setting_dialog.py

@@ -0,0 +1,750 @@
+"""Keep editable tool settings separate from accepted application preferences."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QRect, Qt, Signal
+from PySide6.QtGui import QFont
+from PySide6.QtWidgets import QComboBox, QDialog, QFileDialog, QFrame, QGroupBox, QHBoxLayout, QLabel, QLayout, QLineEdit, QListWidget, QMessageBox, QPushButton, QScrollArea, QStackedWidget, QVBoxLayout, QWidget
+from shiboken6 import isValid
+
+from gitpane.config import LAYOUT_SPACING, SETTING_HEIGHT, SETTING_MIN_HEIGHT, SETTING_MIN_WIDTH, SETTING_WIDTH, SPACING_MD, SharedText, control_height, fit_window
+from gitpane.system.path_identity import canonical_path
+from gitpane.text.typed_path import session_typed_path, typed_path_value
+from gitpane.text.typed_text import typed_value
+from gitpane.tool.app_bundle import chosen_application_program
+from gitpane.tool.editor_recipe import EDITOR_PLATFORM, EditorRecipe, chosen_program, editor_preset, offered_editor_presets, recipe_for_preset
+from gitpane.tool.kdiff3 import tool_program_usable
+from gitpane.tool.mergetool_recipe import MERGETOOL_DEFAULT_COMMAND
+from gitpane.ui.setting.account_page import ACCOUNTS_PAGE_NAME
+from gitpane.ui.setting.setting_block import block_group
+from gitpane.ui.setting.utility_page import UtilityPageText
+from gitpane.ui.widget.long_text import FRAME_SIDE_COUNT, largest_client_size
+from gitpane.ui.widget.result_label import ResultLabel
+from gitpane.ui.window_control.button_focus import set_button_enabled
+from gitpane.ui.window_control.dialog_modality import open_window_modal, prepare_message_box
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from PySide6.QtGui import QShowEvent
+
+    from gitpane.account.ssh import SshConfiguration
+    from gitpane.operation.diagnostic import PreparedDiagnostic
+    from gitpane.tool.editor_recipe import EditorPreset
+    from gitpane.ui.setting.account_page import AccountPage
+    from gitpane.ui.setting.git_setting_widget import GitSettingWidget
+    from gitpane.ui.setting.ssh_widget import SshWidget
+    from gitpane.ui.setting.utility_page import UtilityPage
+
+TOOLS_PAGE_NAME = "Tools"
+GIT_PAGE_NAME = "Git"
+SSH_PAGE_NAME = "SSH"
+SETTING_PAGE_NAMES = (TOOLS_PAGE_NAME, GIT_PAGE_NAME, ACCOUNTS_PAGE_NAME, SSH_PAGE_NAME, UtilityPageText.PAGE_NAME.value)
+# Narrower than the repository window's navigation: the page names are single short words, and the pages need the room.
+SETTING_NAVIGATION_WIDTH = 140
+NAVIGATION_TEXT_COLUMN = 0
+NO_NAVIGATION_ROW = -1
+UNSAVED_TITLE = "Unsaved changes"
+UNSAVED_TEXT_PREFIX = "Unsaved changes in: "
+UNSAVED_PLACE_SEPARATOR = ", "
+DISCARD_AND_CLOSE_TEXT = "Discard and close"
+KEEP_EDITING_TEXT = "Keep editing"
+GIT_AVAILABLE_TEMPLATE = "Git available: {version}"
+GIT_VERIFIED_TEMPLATE = "Git is working.\n{version}\n{git_filename}"
+# Lines of the status and of the Verify Git box, joined when a warning about the accepted Git follows them.
+STATUS_LINE_SEPARATOR = "\n"
+VERIFIED_WARNING_SEPARATOR = "\n\n"
+
+
+class SettingDialogText(Enum):
+    """Texts the Settings window shows, one member per text so a misspelt name is an error."""
+
+    BROWSE = "Browse"
+    SCOPE = "Tool settings apply to all repositories. Git values can be global or repository-specific."
+    GIT_EXECUTABLE = "Git executable"
+    """The title of the Git group, the name of its path field and the title of the file chooser."""
+    GIT_DETECT = "Detect Git"
+    GIT_VERIFY = "Verify Git"
+    """The button that checks the chosen Git, and the title of the window that answers."""
+    GIT_VERIFYING = "Verifying Git…"
+    SAVE = "Save settings"
+    CANCEL = "Cancel changes"
+    TEXT_EDITOR = "Text editor"
+    """The title of the group choosing the program that Show in text editor starts."""
+    TEXT_EDITOR_PRESET = "Text editor preset"
+    TEXT_EDITOR_EXECUTABLE = "Text editor executable"
+    """The name of the text editor's path field and the title of its file chooser."""
+    TEXT_EDITOR_BROWSE = "Browse for text editor executable"
+    TEXT_EDITOR_ARGUMENTS = "Text editor arguments"
+    TEXT_EDITOR_HELP = "Use {file} as a separate argument, or omit it to append the filename. Put arguments containing spaces in double quotes."
+
+
+@dataclass(frozen=True)
+class ToolDraft:
+    """What the Tools page would check and save, each typed value taken without the blanks around it.
+
+    The program paths also have ``~`` read as the home folder where that is the usage: Save writes these values, the full
+    path every reader of the preferences starts, never the ``~`` text.
+    """
+
+    git_filename: str
+    difftool_filename: str
+    difftool_command: str
+    mergetool_filename: str
+    mergetool_command: str
+    editor_recipe: EditorRecipe
+
+
+class SettingDialog(QDialog):
+    """Edit shared Git and comparison settings while the settings controller handles validation."""
+
+    validation_requested = Signal(str, bool)
+    git_verify_requested = Signal(str)
+    detection_requested = Signal()
+    draft_changed = Signal()
+
+    def __init__(self, git_filename: str, parent: QWidget | None = None, *, difftool_filename: str = "", difftool_command: str = "", git_setting_widget: GitSettingWidget | None = None,
+                 account_page: AccountPage | None = None, ssh_widget: SshWidget | None = None, utility_page: UtilityPage | None = None,
+                 mergetool_filename: str = "", mergetool_command: str = MERGETOOL_DEFAULT_COMMAND, mergetool_suggested: bool = False, editor_recipe: EditorRecipe | None = None,
+                 kdiff3_install_line: str = "", typed_path: Callable[[str], str] = session_typed_path) -> None:
+        """Show one page per settings area beside a navigation list, keeping save controls outside the scrolling pages.
+
+        A non-empty ``kdiff3_install_line`` is shown under the diff or merge tool field while that field leads to no usable
+        program: the caller gives it only while no KDiff3 is found, and a tool of the user's own needs no KDiff3.
+        ``typed_path`` reads ``~`` in the program paths where that is the usage; tests hand their own system and home
+        folder.
+        """
+        super().__init__(parent)
+        self.typed_path = typed_path
+        self.kdiff3_install_line = kdiff3_install_line
+        self.setWindowTitle(SharedText.SETTING.value)
+        self.resize(SETTING_WIDTH, SETTING_HEIGHT)
+        # The first show widens the window, within the screen, when the Accounts page needs more than the default width.
+        self.starting_width_fitted = False
+        layout = QVBoxLayout(self)
+        layout.setSizeConstraint(QLayout.SizeConstraint.SetNoConstraint)
+        layout.setSpacing(LAYOUT_SPACING)
+        layout.setContentsMargins(SPACING_MD, SPACING_MD, SPACING_MD, SPACING_MD)
+        tools_page = QWidget()
+        tools_layout = QVBoxLayout(tools_page)
+        tools_layout.setContentsMargins(0, 0, 0, 0)
+        tools_layout.setSpacing(SPACING_MD)
+        scope_label = QLabel(SettingDialogText.SCOPE.value)
+        scope_label.setWordWrap(True)
+        tools_layout.addWidget(scope_label)
+        tools_layout.addWidget(self._build_git_group(git_filename))
+        tools_layout.addWidget(self._build_difftool_group(difftool_filename, difftool_command, kdiff3_install_line))
+        tools_layout.addWidget(self._build_mergetool_group(mergetool_filename, mergetool_command, mergetool_suggested, kdiff3_install_line))
+        tools_layout.addWidget(self._build_editor_group(editor_recipe or EditorRecipe()))
+        tools_layout.addStretch()
+        self.git_setting_widget = git_setting_widget
+        self.ssh_widget = ssh_widget
+        self.utility_page = utility_page
+        # Accounts are saved by the buttons of their own blocks, never by the Save button below, so the account list does
+        # not invalidate the Git check that Save relies on.
+        self.account_page = account_page
+        self.navigation_list = QListWidget()
+        self.navigation_list.setAccessibleName("Settings pages")
+        self.page_stack = QStackedWidget()
+        self.scroll_area_by_page: dict[str, QScrollArea] = {}
+        page_by_name: dict[str, QWidget | None] = {TOOLS_PAGE_NAME: tools_page, GIT_PAGE_NAME: git_setting_widget, ACCOUNTS_PAGE_NAME: account_page, SSH_PAGE_NAME: ssh_widget,
+                                                  UtilityPageText.PAGE_NAME.value: utility_page}
+        for page_name in SETTING_PAGE_NAMES:
+            self.navigation_list.addItem(page_name)
+            self._add_scrolling_page(page_name, page_by_name[page_name])
+        if git_setting_widget is not None:
+            git_setting_widget.draft_changed.connect(self._draft_changed)
+            git_setting_widget.save_attention.connect(self.show_git_result)
+            self.scroll_area_by_page[GIT_PAGE_NAME].verticalScrollBar().rangeChanged.connect(self._reveal_git_result)
+        if ssh_widget is not None:
+            ssh_widget.draft_changed.connect(self._draft_changed)
+        self.body_layout = QHBoxLayout()
+        self.body_layout.setSpacing(SPACING_MD)
+        self.body_layout.addWidget(self.navigation_list)
+        self.body_layout.addWidget(self.page_stack, 1)
+        layout.addLayout(self.body_layout, 1)
+        self.status_label = ResultLabel()
+        layout.addWidget(self.status_label)
+        action_layout = QHBoxLayout()
+        action_layout.addStretch()
+        self.save_button = QPushButton(SettingDialogText.SAVE.value)
+        self.save_button.setDefault(True)
+        self.save_button.clicked.connect(lambda: self.validation_requested.emit(self.typed_git_filename(), True))
+        self.cancel_button = QPushButton(SettingDialogText.CANCEL.value)
+        self.cancel_button.clicked.connect(self.reject)
+        action_layout.addWidget(self.cancel_button)
+        action_layout.addWidget(self.save_button)
+        layout.addLayout(action_layout)
+        QWidget.setTabOrder(self.cancel_button, self.save_button)
+        self.navigation_list.currentRowChanged.connect(self._navigation_row_changed)
+        self.show_page(TOOLS_PAGE_NAME)
+        self.path_edit.textChanged.connect(self._draft_changed)
+        self.difftool_path_edit.textChanged.connect(self._draft_changed)
+        self.difftool_command_edit.textChanged.connect(self._draft_changed)
+        self.mergetool_path_edit.textChanged.connect(self._draft_changed)
+        self.mergetool_command_edit.textChanged.connect(self._draft_changed)
+        for path_edit, install_label in ((self.difftool_path_edit, self.difftool_install_label), (self.mergetool_path_edit, self.mergetool_install_label)):
+            self._update_install_label(path_edit, install_label)
+            path_edit.textChanged.connect(lambda _text, path_edit=path_edit, install_label=install_label: self._update_install_label(path_edit, install_label))
+        self.editor_path_edit.textChanged.connect(self._draft_changed)
+        self.editor_argument_edit.textChanged.connect(self._draft_changed)
+        self.editor_preset_combo.currentIndexChanged.connect(self._draft_changed)
+        self.refresh_metrics()
+        self.path_edit.setFocus()
+        self.path_edit.selectAll()
+        self.close_confirmation: QMessageBox | None = None
+        self.git_verified_box: QMessageBox | None = None
+        self.tool_baseline = self.tool_draft()
+        self.ssh_baseline = self._ssh_values()
+
+    def tool_draft(self) -> ToolDraft:
+        """Capture what the Tools page would check and save, read once for the check, the save and the unsaved-changes question.
+
+        Every typed value loses the blanks around it, so a path pasted with a space still names the file, and a value
+        changed only by such blanks does not count as a change when Settings closes. The program paths also have ``~``
+        read as the home folder where that is the usage, so Save writes the full path.
+        """
+        return ToolDraft(self.typed_git_filename(), typed_path_value(self.difftool_path_edit.text(), self.typed_path), typed_value(self.difftool_command_edit.text()),
+                         typed_path_value(self.mergetool_path_edit.text(), self.typed_path), typed_value(self.mergetool_command_edit.text()), self.editor_recipe())
+
+    def typed_git_filename(self) -> str:
+        """Return the Git path as typed, without the blanks around it and with ``~`` read as the home folder: the one value both checked and saved.
+
+        Verify, Save and every later check read it here, so a path verified once is the very path Save compares and
+        writes, even when it was pasted with a space around it. ``~`` is read where that is the usage, so the path saved
+        is the full path, the one the Verify Git box showed.
+        """
+        return typed_path_value(self.path_edit.text(), self.typed_path)
+
+    def _ssh_values(self) -> SshConfiguration | None:
+        """Capture what the SSH page would save; a dialog built without that page has nothing to compare."""
+        if self.ssh_widget is None:
+            return None
+        return self.ssh_widget.configuration()
+
+    def unsaved_place_names(self) -> list[str]:
+        """Name the places holding unsaved work, in navigation order, so closing can say what would be lost."""
+        place_names = []
+        if self.tool_draft() != self.tool_baseline:
+            place_names.append(TOOLS_PAGE_NAME)
+        if self.git_setting_widget is not None and (self.git_setting_widget.dirty_target_set or self.git_setting_widget.push_tracking_changed()):
+            place_names.append(GIT_PAGE_NAME)
+        if self.account_page is not None:
+            place_names.extend(self.account_page.unsaved_place_names())
+        if self._ssh_values() != self.ssh_baseline:
+            place_names.append(SSH_PAGE_NAME)
+        return place_names
+
+    def mark_saved(self) -> None:
+        """Take the current Tools and SSH values as saved after a bottom Save that left Settings open, so a later close does not list them."""
+        self.tool_baseline = self.tool_draft()
+        self.ssh_baseline = self._ssh_values()
+
+    def reject(self) -> None:
+        """Close at once when nothing would be lost; otherwise ask first without blocking the application.
+
+        The title bar close button, Escape and Cancel changes all end up here. Keep editing is the default and the answer
+        of Escape, and there is deliberately no way to save everything from the question.
+        """
+        if self.close_confirmation is not None and isValid(self.close_confirmation):
+            self.close_confirmation.raise_()
+            self.close_confirmation.activateWindow()
+            return
+        place_names = self.unsaved_place_names()
+        if not place_names:
+            QDialog.reject(self)
+            return
+        box = QMessageBox(QMessageBox.Icon.Warning, UNSAVED_TITLE, UNSAVED_TEXT_PREFIX + UNSAVED_PLACE_SEPARATOR.join(place_names), parent=self)
+        prepare_message_box(box, UNSAVED_TITLE)
+        box.setTextFormat(Qt.TextFormat.PlainText)
+        discard_button = box.addButton(DISCARD_AND_CLOSE_TEXT, QMessageBox.ButtonRole.DestructiveRole)
+        keep_button = box.addButton(KEEP_EDITING_TEXT, QMessageBox.ButtonRole.RejectRole)
+        box.setDefaultButton(keep_button)
+        box.setEscapeButton(keep_button)
+        self.close_confirmation = box
+
+        def finished() -> None:
+            """Close Settings only on an explicit Discard and close; any other ending keeps the drafts."""
+            self.close_confirmation = None
+            discarded = box.clickedButton() is discard_button
+            box.deleteLater()
+            if discarded:
+                self.discard_and_close()
+
+        box.finished.connect(finished)
+        open_window_modal(box)
+
+    def discard_and_close(self) -> None:
+        """Close without saving or asking: used by Discard and close, by the application shutdown, and to clean up tests.
+
+        Closing emits finished, so whoever owns Settings still cancels a sign-in in progress.
+        """
+        box = self.close_confirmation
+        self.close_confirmation = None
+        if box is not None and isValid(box):
+            box.reject()
+        self._close_git_verified_box()
+        QDialog.reject(self)
+
+    def show_success_with_warning(self, text: str, warning: str = "") -> None:
+        """Show a result that worked in bold green, or in bold orange followed by the warning that still needs the user's attention."""
+        if not warning:
+            self.status_label.show_success(text)
+            return
+        self.status_label.show_warning(text + STATUS_LINE_SEPARATOR + warning)
+
+    def show_git_available(self, version: str, warning: str = "") -> None:
+        """Show the version of an accepted Git as ordinary text, or in bold orange followed by the warning that comes with it."""
+        status_text = GIT_AVAILABLE_TEMPLATE.format(version=version)
+        if not warning:
+            self.status_label.setText(status_text)
+            return
+        self.status_label.show_warning(status_text + STATUS_LINE_SEPARATOR + warning)
+
+    def show_git_verified(self, version: str, git_filename: str, warning: str = "") -> None:
+        """Show a successful Verify Git in bold green and confirm it in a box naming the version and the checked path.
+
+        The check takes a few milliseconds and used to rewrite the same ordinary line Settings opens with, so the click
+        looked like it did nothing. The box is modal to Settings only and never runs a blocking loop of its own; the
+        version comes from Git and the path from the user, so both are shown as plain text. Closing the box gives the
+        focus back to Verify Git. A ``warning`` about the accepted Git turns the line orange and ends the box, which then
+        carries the warning icon.
+        """
+        self.show_success_with_warning(GIT_AVAILABLE_TEMPLATE.format(version=version), warning)
+        box_text = GIT_VERIFIED_TEMPLATE.format(version=version, git_filename=git_filename)
+        icon = QMessageBox.Icon.Information
+        if warning:
+            box_text += VERIFIED_WARNING_SEPARATOR + warning
+            icon = QMessageBox.Icon.Warning
+        self._close_git_verified_box()
+        box = QMessageBox(icon, SettingDialogText.GIT_VERIFY.value, box_text, QMessageBox.StandardButton.Ok, self)
+        prepare_message_box(box, SettingDialogText.GIT_VERIFY.value)
+        box.setTextFormat(Qt.TextFormat.PlainText)
+        self.git_verified_box = box
+
+        def finished() -> None:
+            """Forget the closed box and put the focus back on the button that asked for the check."""
+            if self.git_verified_box is box:
+                self.git_verified_box = None
+            box.deleteLater()
+            button = self.verify_button
+            if isValid(button) and button.isVisible() and button.isEnabled():
+                button.setFocus(Qt.FocusReason.OtherFocusReason)
+
+        box.finished.connect(finished)
+        open_window_modal(box)
+
+    def _close_git_verified_box(self) -> None:
+        """Close the box confirming a successful Verify Git, if one is still open."""
+        box = self.git_verified_box
+        self.git_verified_box = None
+        if box is not None and isValid(box):
+            box.reject()
+
+    def _add_scrolling_page(self, page_name: str, page: QWidget | None) -> None:
+        """Give a page its own scroll area so a long page never pushes the navigation or the save controls away; a missing page stays empty."""
+        scroll_area = QScrollArea()
+        scroll_area.setWidgetResizable(True)
+        scroll_area.setFrameShape(QFrame.Shape.NoFrame)
+        scroll_area.setWidget(page if page is not None else QWidget())
+        self.scroll_area_by_page[page_name] = scroll_area
+        self.page_stack.addWidget(scroll_area)
+
+    def _build_git_group(self, git_filename: str) -> QGroupBox:
+        """Frame the Git executable path with its browse, detect and verify actions."""
+        self.git_group, group_layout = block_group(SettingDialogText.GIT_EXECUTABLE.value)
+        self.path_edit = QLineEdit(git_filename)
+        self.path_edit.setAccessibleName(SettingDialogText.GIT_EXECUTABLE.value)
+        label = QLabel("Executable")
+        label.setBuddy(self.path_edit)
+        group_layout.addWidget(label)
+        self.browse_button = QPushButton(SettingDialogText.BROWSE.value)
+        self.browse_button.setAccessibleName("Browse for Git executable")
+        self.browse_button.clicked.connect(self._browse)
+        git_path_layout = QHBoxLayout()
+        git_path_layout.addWidget(self.path_edit, 1)
+        git_path_layout.addWidget(self.browse_button)
+        group_layout.addLayout(git_path_layout)
+        self.detect_button = QPushButton(SettingDialogText.GIT_DETECT.value)
+        self.detect_button.clicked.connect(self.detection_requested)
+        self.verify_button = QPushButton(SettingDialogText.GIT_VERIFY.value)
+        self.verify_button.clicked.connect(lambda: self.git_verify_requested.emit(self.typed_git_filename()))
+        git_action_layout = QHBoxLayout()
+        git_action_layout.addWidget(self.detect_button)
+        git_action_layout.addWidget(self.verify_button)
+        git_action_layout.addStretch()
+        group_layout.addLayout(git_action_layout)
+        return self.git_group
+
+    def _build_install_label(self, install_line: str) -> QLabel:
+        """Say under a tool field how to install KDiff3, as selectable text so its command can be copied; shown by _update_install_label.
+
+        The line is bold so the command is seen under the field. Only the weight is set: the colour stays the text colour
+        of the palette, so it follows the light or dark appearance, and the family and size still follow the fonts of the
+        application.
+        """
+        label = QLabel(install_line)
+        # A font with only its weight set: every other attribute is still inherited from the application and the window.
+        weight_only_font = QFont()
+        weight_only_font.setBold(True)
+        label.setFont(weight_only_font)
+        label.setTextFormat(Qt.TextFormat.PlainText)
+        label.setWordWrap(True)
+        label.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse)
+        label.setVisible(False)
+        return label
+
+    def _update_install_label(self, path_edit: QLineEdit, install_label: QLabel) -> None:
+        """Show how to install KDiff3 under a tool field only while no KDiff3 is found and the field leads to no usable program, as typed or browsed.
+
+        The line follows the path the action would use, ``~`` read as the home folder where that is the usage.
+        """
+        install_label.setVisible(bool(self.kdiff3_install_line) and not tool_program_usable(typed_path_value(path_edit.text(), self.typed_path)))
+
+    def _build_difftool_group(self, difftool_filename: str, difftool_command: str, install_line: str) -> QGroupBox:
+        """Frame the external comparison executable, how to install KDiff3 when none is found, and its argument template."""
+        self.difftool_group, group_layout = block_group("External diff tool")
+        self.difftool_path_edit = QLineEdit(difftool_filename)
+        self.difftool_path_edit.setAccessibleName("External diff tool executable")
+        executable_label = QLabel("Executable")
+        executable_label.setBuddy(self.difftool_path_edit)
+        group_layout.addWidget(executable_label)
+        self.difftool_browse_button = QPushButton("Browse…")
+        self.difftool_browse_button.setAccessibleName("Browse for external diff tool executable")
+        self.difftool_browse_button.clicked.connect(self._browse_difftool)
+        difftool_path_layout = QHBoxLayout()
+        difftool_path_layout.addWidget(self.difftool_path_edit, 1)
+        difftool_path_layout.addWidget(self.difftool_browse_button)
+        group_layout.addLayout(difftool_path_layout)
+        self.difftool_install_label = self._build_install_label(install_line)
+        group_layout.addWidget(self.difftool_install_label)
+        self.difftool_command_edit = QLineEdit(difftool_command)
+        self.difftool_command_edit.setAccessibleName("External diff tool arguments")
+        argument_label = QLabel("Arguments (advanced)")
+        argument_label.setBuddy(self.difftool_command_edit)
+        group_layout.addWidget(argument_label)
+        group_layout.addWidget(self.difftool_command_edit)
+        help_label = QLabel('The default arguments are ready to use. Edit only if your tool needs extra options or a different file order. '
+                            '$LOCAL and $REMOTE are replaced with the two files to compare. Put arguments containing spaces in double quotes.')
+        help_label.setWordWrap(True)
+        self.difftool_command_edit.setToolTip(help_label.text() + " If your tool starts a separate process, add its option to wait until the comparison closes.")
+        group_layout.addWidget(help_label)
+        return self.difftool_group
+
+    def _build_mergetool_group(self, mergetool_filename: str, mergetool_command: str, mergetool_suggested: bool, install_line: str) -> QGroupBox:
+        """Frame the merge executable, how to install KDiff3 when none is found, its not-yet-saved notice and its argument template."""
+        self.mergetool_group, group_layout = block_group("External merge tool")
+        self.mergetool_path_edit = QLineEdit(mergetool_filename)
+        self.mergetool_path_edit.setAccessibleName("External merge tool executable")
+        merge_executable_label = QLabel("Executable")
+        merge_executable_label.setBuddy(self.mergetool_path_edit)
+        group_layout.addWidget(merge_executable_label)
+        self.mergetool_browse_button = QPushButton("Browse…")
+        self.mergetool_browse_button.setAccessibleName("Browse for external merge tool executable")
+        self.mergetool_browse_button.clicked.connect(self._browse_mergetool)
+        mergetool_path_layout = QHBoxLayout()
+        mergetool_path_layout.addWidget(self.mergetool_path_edit, 1)
+        mergetool_path_layout.addWidget(self.mergetool_browse_button)
+        group_layout.addLayout(mergetool_path_layout)
+        self.mergetool_install_label = self._build_install_label(install_line)
+        group_layout.addWidget(self.mergetool_install_label)
+        self.mergetool_save_notice_label = QLabel("This merge tool is not saved yet. Click Save to use it for conflict resolution.")
+        self.mergetool_save_notice_label.setWordWrap(True)
+        self.mergetool_save_notice_label.setVisible(mergetool_suggested)
+        group_layout.addWidget(self.mergetool_save_notice_label)
+        self.mergetool_command_edit = QLineEdit(mergetool_command)
+        self.mergetool_command_edit.setAccessibleName("External merge tool arguments")
+        merge_argument_label = QLabel("Arguments (advanced)")
+        merge_argument_label.setBuddy(self.mergetool_command_edit)
+        group_layout.addWidget(merge_argument_label)
+        group_layout.addWidget(self.mergetool_command_edit)
+        merge_help_label = QLabel('The default arguments are ready for KDiff3. $BASE, $LOCAL and $REMOTE are the available conflict versions; '
+                                 '$MERGED is the output file. Keep all four parameters. Put arguments containing spaces in double quotes.')
+        merge_help_label.setWordWrap(True)
+        self.mergetool_command_edit.setToolTip(merge_help_label.text())
+        group_layout.addWidget(merge_help_label)
+        return self.mergetool_group
+
+    def _build_editor_group(self, recipe: EditorRecipe) -> QGroupBox:
+        """Frame the text editor that Show in text editor starts: its preset, executable and arguments."""
+        self.editor_group, form = block_group(SettingDialogText.TEXT_EDITOR.value)
+        self.editor_preset_combo = QComboBox()
+        self.editor_preset_combo.setAccessibleName(SettingDialogText.TEXT_EDITOR_PRESET.value)
+        for preset in self._offered_editor_presets():
+            self.editor_preset_combo.addItem(preset.label, preset.preset_id)
+        if self.editor_preset_combo.findData(recipe.preset_id) < 0:
+            self.editor_preset_combo.addItem("Saved editor", recipe.preset_id)
+        self.editor_preset_combo.setCurrentIndex(self.editor_preset_combo.findData(recipe.preset_id))
+        label = QLabel("Preset")
+        label.setBuddy(self.editor_preset_combo)
+        form.addWidget(label)
+        form.addWidget(self.editor_preset_combo)
+        self.editor_path_edit = QLineEdit(recipe.program_filename)
+        self.editor_path_edit.setAccessibleName(SettingDialogText.TEXT_EDITOR_EXECUTABLE.value)
+        label = QLabel("Executable")
+        label.setBuddy(self.editor_path_edit)
+        form.addWidget(label)
+        self.editor_browse_button = QPushButton("Browse…")
+        self.editor_browse_button.setAccessibleName(SettingDialogText.TEXT_EDITOR_BROWSE.value)
+        self.editor_browse_button.clicked.connect(self._browse_editor)
+        row = QHBoxLayout()
+        row.addWidget(self.editor_path_edit, 1)
+        row.addWidget(self.editor_browse_button)
+        form.addLayout(row)
+        self.editor_argument_edit = QLineEdit(recipe.argument_template)
+        self.editor_argument_edit.setAccessibleName(SettingDialogText.TEXT_EDITOR_ARGUMENTS.value)
+        label = QLabel("Arguments")
+        label.setBuddy(self.editor_argument_edit)
+        form.addWidget(label)
+        form.addWidget(self.editor_argument_edit)
+        self.editor_help_label = QLabel(SettingDialogText.TEXT_EDITOR_HELP.value)
+        self.editor_help_label.setWordWrap(True)
+        form.addWidget(self.editor_help_label)
+        self.editor_status_label = QLabel()
+        self.editor_status_label.setTextFormat(Qt.TextFormat.PlainText)
+        self.editor_status_label.setWordWrap(True)
+        form.addWidget(self.editor_status_label)
+        self.editor_settings_button = QPushButton("Open Settings")
+        self.editor_settings_button.clicked.connect(self.show_editor_setting)
+        form.addWidget(self.editor_settings_button)
+        self.editor_preset_combo.activated.connect(self._select_editor_preset)
+        self._show_editor_status(recipe)
+        return self.editor_group
+
+    def _navigation_row_changed(self, row: int) -> None:
+        """Follow a click or keyboard move in the navigation list; a cleared selection keeps the current page."""
+        if row == NO_NAVIGATION_ROW:
+            return
+        self.show_page(SETTING_PAGE_NAMES[row])
+
+    def show_page(self, name: str) -> None:
+        """Show one page and hide the bottom Save and Cancel on Accounts, whose blocks have their own save buttons.
+
+        The bottom Save never records an account choice, so offering it there would suggest it does. The Utilities page
+        saves nothing itself, so Save and Cancel stay there and still apply to the drafts of the other pages.
+        """
+        self.navigation_list.setCurrentRow(SETTING_PAGE_NAMES.index(name))
+        self.page_stack.setCurrentWidget(self.scroll_area_by_page[name])
+        bottom_action_visible = name != ACCOUNTS_PAGE_NAME
+        self.save_button.setVisible(bottom_action_visible)
+        self.cancel_button.setVisible(bottom_action_visible)
+
+    def current_page_name(self) -> str:
+        """Name the page currently shown on the right of the navigation list."""
+        current_scroll_area = self.page_stack.currentWidget()
+        for page_name, scroll_area in self.scroll_area_by_page.items():
+            if scroll_area is current_scroll_area:
+                return page_name
+        return TOOLS_PAGE_NAME
+
+    def reveal_widget(self, page_name: str, widget: QWidget) -> None:
+        """Show the page holding a widget and scroll that page until the widget is in view."""
+        self.show_page(page_name)
+        scroll_area = self.scroll_area_by_page[page_name]
+        page_layout = scroll_area.widget().layout()
+        if page_layout is not None:
+            page_layout.activate()
+        scroll_area.ensureWidgetVisible(widget)
+
+    def _show_editor_status(self, recipe: EditorRecipe) -> None:
+        """Explain an unavailable editor without replacing the user's saved executable; an empty one is a valid choice, with no error."""
+        try:
+            recipe.validate()
+        except ValueError as error:
+            self.editor_status_label.setText(str(error))
+            self.editor_settings_button.show()
+        else:
+            self.editor_status_label.clear()
+            self.editor_settings_button.hide()
+
+    @staticmethod
+    def _offered_editor_presets() -> list[EditorPreset]:
+        """List the editor presets of this system; on macOS and Linux only those whose program is found, by reading files only."""
+        return offered_editor_presets(EDITOR_PLATFORM, lambda preset: bool(recipe_for_preset(preset).program_filename))
+
+    def _select_editor_preset(self, index: int) -> None:
+        """Apply a preset only after explicit selection; Custom preserves the free-form draft."""
+        preset_id = self.editor_preset_combo.itemData(index)
+        if preset_id == "custom":
+            return
+        for preset in self._offered_editor_presets():
+            if preset.preset_id != preset_id:
+                continue
+            recipe = recipe_for_preset(preset)
+            self.editor_path_edit.setText(recipe.program_filename)
+            self.editor_argument_edit.setText(recipe.argument_template)
+            self._show_editor_status(recipe)
+            return
+
+    def editor_recipe(self) -> EditorRecipe:
+        """Capture the current editable recipe without publishing or launching it, path and arguments without the blanks around them.
+
+        The program path also has ``~`` read as the home folder where that is the usage; the arguments are not a path.
+        """
+        return EditorRecipe(self.editor_preset_combo.currentData() or "custom", typed_path_value(self.editor_path_edit.text(), self.typed_path), typed_value(self.editor_argument_edit.text()))
+
+    def show_editor_setting(self) -> None:
+        """Show the Tools page on the editor fields while preserving an existing unsaved draft."""
+        self.reveal_widget(TOOLS_PAGE_NAME, self.editor_path_edit)
+        self.editor_path_edit.setFocus(Qt.FocusReason.OtherFocusReason)
+
+    def _browse_editor(self) -> None:
+        """Choose the actual editor executable without starting it or saving the draft.
+
+        A picked application becomes the program it declares; a program that is not the current preset's switches to
+        Custom. TextEdit selects its own preset.
+        """
+        start_filename = typed_path_value(self.editor_path_edit.text(), self.typed_path)
+        filename, _ = QFileDialog.getOpenFileName(self, SettingDialogText.TEXT_EDITOR_EXECUTABLE.value, start_filename)
+        if filename:
+            self._apply_chosen_editor(filename)
+        self.editor_path_edit.setFocus()
+
+    def _apply_chosen_editor(self, filename: str) -> None:
+        """Put a picked editor in the draft, as its preset when the pick stands for one that this system offers.
+
+        An editor application that stands for a preset brings the command-line tool of the very application picked, which
+        may not be the copy the preset found. When that preset is not offered, for a copy outside the applications folders,
+        the tool still comes with the preset's arguments, under Custom.
+        """
+        program_filename, preset_id = chosen_program(filename, EDITOR_PLATFORM)
+        preset_index = self.editor_preset_combo.findData(preset_id) if preset_id else -1
+        if preset_index >= 0:
+            self.editor_preset_combo.setCurrentIndex(preset_index)
+            self._select_editor_preset(preset_index)
+            if program_filename:
+                self.editor_path_edit.setText(program_filename)
+                self._show_editor_status(self.editor_recipe())
+            return
+        if preset_id and not program_filename:
+            # Only macOS offers the preset of an application that only macOS ships; elsewhere the pick is a plain program.
+            program_filename = chosen_application_program(filename)
+        self.editor_path_edit.setText(program_filename)
+        if not self._is_current_preset_program(program_filename):
+            custom_index = self.editor_preset_combo.findData("custom")
+            self.editor_preset_combo.setCurrentIndex(custom_index)
+            self._select_editor_preset(custom_index)
+        preset = editor_preset(preset_id) if preset_id else None
+        if preset is not None and program_filename:
+            self.editor_argument_edit.setText(preset.arguments)
+        self._show_editor_status(self.editor_recipe())
+
+    def _is_current_preset_program(self, program_filename: str) -> bool:
+        """Tell whether ``program_filename`` is the program the selected preset, other than Custom, would fill in.
+
+        Both sides are compared as the disk names them, so a link to the preset's program, such as /usr/local/bin/code
+        for VS Code, keeps the preset.
+        """
+        preset_id = self.editor_preset_combo.currentData()
+        if preset_id == "custom":
+            return False
+        for preset in self._offered_editor_presets():
+            if preset.preset_id == preset_id:
+                preset_program_filename = recipe_for_preset(preset).program_filename
+                return bool(preset_program_filename) and canonical_path(preset_program_filename) == canonical_path(program_filename)
+        return False
+
+    def showEvent(self, event: QShowEvent) -> None:
+        """Open, the first time only, wide enough for the Accounts page; the user's own width is kept when the window is shown again."""
+        super().showEvent(event)
+        if self.starting_width_fitted:
+            return
+        self.starting_width_fitted = True
+        largest = largest_client_size(self, self.screen().availableGeometry())
+        width = min(max(self.width(), self.starting_width()), largest.width())
+        if width > self.width():
+            self.resize(width, self.height())
+
+    def starting_width(self) -> int:
+        """Return the default width, or the width at which the Accounts page shows its Connected accounts list whole.
+
+        The page sits beside the navigation list in a scroll area, whose vertical scroll bar is counted since a long
+        page shows one.
+        """
+        if self.account_page is None:
+            return SETTING_WIDTH
+        scroll_area = self.scroll_area_by_page[ACCOUNTS_PAGE_NAME]
+        margins = self.layout().contentsMargins()
+        page_area_width = self.account_page.needed_width() + scroll_area.verticalScrollBar().sizeHint().width() + scroll_area.frameWidth() * FRAME_SIDE_COUNT
+        width = margins.left() + self.navigation_list.minimumWidth() + self.body_layout.spacing() + page_area_width + margins.right()
+        return max(SETTING_WIDTH, width)
+
+    def refresh_metrics(self, available: QRect | None = None) -> None:
+        """Keep save and cancel visible while the pages scroll on small screens, and keep every page name readable in the navigation."""
+        text_width = self.navigation_list.sizeHintForColumn(NAVIGATION_TEXT_COLUMN) + self.navigation_list.frameWidth() * FRAME_SIDE_COUNT + SPACING_MD
+        self.navigation_list.setFixedWidth(max(SETTING_NAVIGATION_WIDTH, text_width))
+        for control in (self.path_edit, self.browse_button, self.detect_button, self.verify_button, self.difftool_path_edit, self.difftool_command_edit,
+                        self.editor_preset_combo, self.editor_path_edit, self.editor_argument_edit, self.editor_browse_button,
+                        self.difftool_browse_button, self.mergetool_path_edit, self.mergetool_command_edit, self.mergetool_browse_button, self.save_button, self.cancel_button):
+            control.setMinimumHeight(control_height(control.fontMetrics().height()))
+        fit_window(self, SETTING_MIN_WIDTH, SETTING_MIN_HEIGHT, available)
+        if self.git_setting_widget is not None:
+            self.git_setting_widget.refresh_metrics()
+        if self.utility_page is not None:
+            self.utility_page.refresh_metrics()
+
+    def show_git_result(self) -> None:
+        """Show the Git page on a user-triggered failed save and allow keyboard copying of each result."""
+        if self.git_setting_widget is None:
+            return
+        result_label = self.git_setting_widget.status_label
+        self.reveal_widget(GIT_PAGE_NAME, result_label)
+        result_label.setFocus(Qt.FocusReason.OtherFocusReason)
+        self._reveal_git_result()
+
+    def show_mergetool_setting(self) -> None:
+        """Show the Tools page and focus the merge executable while preserving an already open draft."""
+        self.reveal_widget(TOOLS_PAGE_NAME, self.mergetool_path_edit)
+        self.mergetool_path_edit.setFocus(Qt.FocusReason.OtherFocusReason)
+
+    def _reveal_git_result(self) -> None:
+        """Keep a focused save result visible as wrapped content changes the Git page's scroll range."""
+        if self.git_setting_widget is None:
+            return
+        result_label = self.git_setting_widget.status_label
+        if result_label.hasFocus():
+            self.scroll_area_by_page[GIT_PAGE_NAME].ensureWidgetVisible(result_label)
+
+    def set_loading(self, loading: bool) -> None:
+        """Prevent duplicate submissions while keeping the draft editable and cancellable."""
+        set_button_enabled(self.save_button, not loading)
+        set_button_enabled(self.verify_button, not loading)
+        if loading:
+            self.status_label.setText(SettingDialogText.GIT_VERIFYING.value)
+
+    def show_failure(self, diagnostic: PreparedDiagnostic) -> None:
+        """Keep the exact draft visible with a safe explanation of failed validation."""
+        self.set_loading(False)
+        self.status_label.show_failure(diagnostic.cause)
+
+    def _draft_changed(self) -> None:
+        """Invalidate a displayed version as soon as its source path changes."""
+        self.set_loading(False)
+        self.status_label.clear()
+        self.draft_changed.emit()
+
+    def _browse(self) -> None:
+        """Use a native file chooser without changing the draft when cancelled."""
+        git_filename, _ = QFileDialog.getOpenFileName(self, SettingDialogText.GIT_EXECUTABLE.value, self.typed_git_filename())
+        if git_filename:
+            self.path_edit.setText(git_filename)
+        self.path_edit.setFocus()
+
+    def _browse_difftool(self) -> None:
+        """Choose the actual comparison executable without starting it; a picked application becomes the program it declares."""
+        start_filename = typed_path_value(self.difftool_path_edit.text(), self.typed_path)
+        filename, _ = QFileDialog.getOpenFileName(self, "External diff tool executable", start_filename)
+        if filename:
+            self.difftool_path_edit.setText(chosen_application_program(filename))
+
+    def _browse_mergetool(self) -> None:
+        """Choose the merge executable without starting it or saving the draft; a picked application becomes the program it declares."""
+        start_filename = typed_path_value(self.mergetool_path_edit.text(), self.typed_path)
+        filename, _ = QFileDialog.getOpenFileName(self, "External merge tool executable", start_filename)
+        if filename:
+            self.mergetool_path_edit.setText(chosen_application_program(filename))
+        self.mergetool_path_edit.setFocus()