feat(ui): add box selection for thumbnail grid

Author: CyanVoxel

src/tagstudio/qt/controllers/item_thumb.py

@@ -467,7 +467,7 @@ def mouseMoveEvent(self, event: QMouseEvent) -> None:
         pos = event.position().toPoint()
         self._set_image_hovered(self._image_rect().contains(pos))
         if self._press_pos is None or event.buttons() != Qt.MouseButton.LeftButton:
-            return
+            return super().mouseMoveEvent(event)
         if (pos - self._press_pos).manhattanLength() < QApplication.startDragDistance():
             return
 

src/tagstudio/qt/controllers/main_window.py

@@ -694,7 +694,7 @@ def setup_entry_list(self, driver: QtDriver):
         self.entry_list_container = QWidget()
         self.entry_list_layout = QVBoxLayout(self.entry_list_container)
         self.entry_list_layout.setSpacing(0)
-        self.entry_list_layout.setContentsMargins(WIN_PAD, 0, 0, 0)
+        self.entry_list_layout.setContentsMargins(0, 0, 0, 0)
 
         self.entry_scroll_area = QScrollArea()
         self.entry_scroll_area.setObjectName("entry_scroll_area")
@@ -705,15 +705,18 @@ def setup_entry_list(self, driver: QtDriver):
         self.entry_scroll_area.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff)
 
         self.thumb_grid = ThumbGrid(driver, self.entry_scroll_area)
-        # Padding so floating pagination bar doesn't block bottom of scroll contents
-        self.thumb_grid.setContentsMargins(0, 0, 0, Pagination.HEIGHT)
+        # Left padding is part of the grid so box selections can start from it.
+        # Bottom padding so floating pagination bar doesn't block bottom of scroll contents.
+        self.thumb_grid.setContentsMargins(WIN_PAD, 0, 0, Pagination.HEIGHT)
         self.entry_scroll_area.setWidget(self.thumb_grid)
 
         self.banners = BannerStack()
+        self.banners.setContentsMargins(WIN_PAD, 0, 0, 0)
         self.entry_list_layout.addWidget(self.banners)
 
         self.entry_list_layout.addWidget(self.entry_scroll_area)
         self.landing_widget = LandingWidget(driver, self.devicePixelRatio())
+        self.landing_widget.setContentsMargins(WIN_PAD, 0, 0, 0)
         self.entry_list_layout.addWidget(self.landing_widget)
         self.pagination = Pagination(self.entry_list_container)
         self.central_content_layout.addWidget(self.entry_list_container)

src/tagstudio/qt/controllers/thumb_grid.py

@@ -7,9 +7,9 @@
 from typing import TYPE_CHECKING, override
 
 import structlog
-from PySide6.QtCore import QEvent, QObject, Qt, QThreadPool, QTimer, Signal
+from PySide6.QtCore import QEvent, QObject, QPoint, QRect, Qt, QThreadPool, QTimer, Signal
 from PySide6.QtGui import QColor, QKeyEvent, QMouseEvent, QPixmap
-from PySide6.QtWidgets import QScrollArea, QWidget
+from PySide6.QtWidgets import QApplication, QScrollArea, QWidget
 
 from tagstudio.core.library.alchemy.enums import ItemType
 from tagstudio.core.library.alchemy.models import Entry
@@ -18,6 +18,7 @@
 from tagstudio.qt.controllers.item_thumb import ItemThumb
 from tagstudio.qt.qt_file_renderer import QtFileRenderer
 from tagstudio.qt.views.layouts.thumb_grid_layout import ThumbGridLayout
+from tagstudio.qt.views.styles.stylesheets import box_selection_style
 
 if TYPE_CHECKING:
     from tagstudio.qt.qt_driver import QtDriver
@@ -28,9 +29,10 @@
 class ThumbGrid(QWidget):
     """A scrollable grid of item thumbnails."""
 
-    DURATION_DELAY_MS = 200  # Allows fast scrolling without getting lagged by duration labels
-    RESIZE_RENDER_DELAY_MS = 200  # Allows more responsive rapid resizing
-    SHOW_THUMBS_DELAY_MS = 200  # Allows quick renders to appear together without a loading flash
+    _BOX_SCROLL_INTERVAL_MS = 16  # Scrolls every interval while box selecting past an edge
+    _DURATION_DELAY_MS = 200  # Allows fast scrolling without getting lagged by duration labels
+    _RESIZE_RENDER_DELAY_MS = 200  # Allows more responsive rapid resizing
+    _SHOW_THUMBS_DELAY_MS = 200  # Allows quick renders to appear together without a loading flash
 
     _duration_loaded = Signal(Path, object)
     _entries_fetched = Signal(int, object, object)
@@ -42,17 +44,29 @@ def __init__(self, driver: QtDriver, scroll_area: QScrollArea) -> None:
         self._driver = driver
         self._renderer = QtFileRenderer(driver.lib, driver.settings)
 
+        self._box_scroll_timer = QTimer(self)
+        self._box_scroll_timer.setInterval(self._BOX_SCROLL_INTERVAL_MS)
         self._duration_timer = QTimer(self)
-        self._duration_timer.setInterval(self.DURATION_DELAY_MS)
+        self._duration_timer.setInterval(self._DURATION_DELAY_MS)
         self._duration_timer.setSingleShot(True)
         self._resize_render_timer = QTimer(self)
-        self._resize_render_timer.setInterval(self.RESIZE_RENDER_DELAY_MS)
+        self._resize_render_timer.setInterval(self._RESIZE_RENDER_DELAY_MS)
         self._resize_render_timer.setSingleShot(True)
         self._show_thumbs_timer = QTimer(self)
-        self._show_thumbs_timer.setInterval(self.SHOW_THUMBS_DELAY_MS)
+        self._show_thumbs_timer.setInterval(self._SHOW_THUMBS_DELAY_MS)
         self._show_thumbs_timer.setSingleShot(True)
 
+        self._box_rect = QWidget(self)
+        self._box_rect.setAttribute(Qt.WidgetAttribute.WA_StyledBackground)
+        self._box_rect.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents)
+        self._box_rect.setStyleSheet(box_selection_style())
+        self._box_rect.hide()
+
+        self._box_cursor = QPoint()
+        self._box_entries: dict[int, None] = {}  # Entries in the selection box, in grid order
+        self._box_origin: QPoint | None = None
         self._changed_while_fetching: set[int] = set()
+        self._does_box_toggle = False  # Ctrl+Drag toggles the selection instead of adding
         self._durations: dict[Path, float | None] = {}
         self._entries: dict[int, Entry] = {}
         self._entry_ids: list[int] = []
@@ -68,6 +82,7 @@ def __init__(self, driver: QtDriver, scroll_area: QScrollArea) -> None:
         self._previous_size_renders: dict[Path, QPixmap] = {}
         self._render_cutoff = 0.0
         self._renders: dict[Path, QPixmap | None] = {}
+        self._scroll_area = scroll_area
         self._scroll_to: int | None = None
 
         self.setLayout(ThumbGridLayout(scroll_area, self._create_thumb))
@@ -79,16 +94,86 @@ def layout(self) -> ThumbGridLayout[ItemThumb]:
 
     @override
     def mousePressEvent(self, event: QMouseEvent) -> None:
-        # Clear selected entries when clicking the background
         if (
             event.button() == Qt.MouseButton.LeftButton
-            and event.modifiers() == Qt.KeyboardModifier.NoModifier
+            and event.modifiers()
+            in (
+                Qt.KeyboardModifier.NoModifier,
+                Qt.KeyboardModifier.ShiftModifier,
+                Qt.KeyboardModifier.ControlModifier,
+            )
             and isinstance(self.childAt(event.position().toPoint()), ItemThumb | None)
-            and self._driver.selection.selected
         ):
-            self._driver.selection.clear()
+            # Clear selected entries when clicking the background, unless Shift/Ctrl clicking
+            if (
+                event.modifiers() == Qt.KeyboardModifier.NoModifier
+                and self._driver.selection.selected
+            ):
+                self._driver.selection.clear()
+            self._does_box_toggle = event.modifiers() == Qt.KeyboardModifier.ControlModifier
+            self._box_origin = event.position().toPoint()
+            self._box_cursor = event.globalPosition().toPoint()
+            return
         super().mousePressEvent(event)
 
+    @override
+    def mouseMoveEvent(self, event: QMouseEvent) -> None:
+        # Track the box selection if it's active
+        if self._box_origin is None:
+            return super().mouseMoveEvent(event)
+        self._box_cursor = event.globalPosition().toPoint()
+        self._update_box()
+        viewport = self._scroll_area.viewport()
+        # Mouse cursor is inside the viewport, cancel the scroll timer
+        if 0 <= viewport.mapFromGlobal(self._box_cursor).y() < viewport.height():
+            self._box_scroll_timer.stop()
+        # Mouse cursor is above or below the viewport, start scrolling in that direction on a timer
+        elif self._box_rect.isVisible() and not self._box_scroll_timer.isActive():
+            self._box_scroll_timer.start()
+
+    @override
+    def mouseReleaseEvent(self, event: QMouseEvent) -> None:
+        # End the box selection, if it was active
+        if self._box_origin is None or event.button() != Qt.MouseButton.LeftButton:
+            return super().mouseReleaseEvent(event)
+        if self._box_rect.isVisible():
+            selection = self._driver.selection
+            kept = selection.selected
+            if self._does_box_toggle:
+                kept = [entry_id for entry_id in kept if entry_id not in self._box_entries]
+            added = [
+                entry_id for entry_id in self._box_entries if not selection.is_selected(entry_id)
+            ]
+            selection.select_items([*kept, *added])
+        self._box_origin = None
+        self._box_rect.hide()
+        self._box_scroll_timer.stop()
+        self._box_entries = {}
+        self._update_selected()
+
+    def _update_box(self) -> None:
+        """Highlight entries in the selection box from the point clicked to the mouse cursor."""
+        origin = unwrap(self._box_origin)
+        end = self.mapFromGlobal(self._box_cursor)
+        if not self._box_rect.isVisible():
+            if (end - origin).manhattanLength() < QApplication.startDragDistance():
+                return
+            self._box_rect.raise_()
+            self._box_rect.show()
+        rect = QRect(origin, end).normalized()
+        self._box_rect.setGeometry(rect)
+        indices = self.layout().indices_in_rect(rect)
+        self._box_entries = dict.fromkeys(self._entry_ids[index] for index in indices)
+        self._update_selected()
+
+    def _scroll_box(self) -> None:
+        """Scroll towards the mouse cursor while it's box selecting past the top or bottom edge."""
+        viewport = self._scroll_area.viewport()
+        y = viewport.mapFromGlobal(self._box_cursor).y()
+        scroll_bar = self._scroll_area.verticalScrollBar()
+        scroll_bar.setValue(scroll_bar.value() + min(y, 0) + max(y - viewport.height(), 0))
+        self._update_box()
+
     def _connect_callbacks(self, scroll_area: QScrollArea) -> None:
         scroll_area.installEventFilter(self)
         scroll_area.verticalScrollBar().valueChanged.connect(lambda _: self.layout().update())
@@ -100,6 +185,7 @@ def _connect_callbacks(self, scroll_area: QScrollArea) -> None:
         self._renderer.updated.connect(self._on_rendered)
         self._resize_render_timer.timeout.connect(self._request_renders)
         self._show_thumbs_timer.timeout.connect(self._show_held_entries)
+        self._box_scroll_timer.timeout.connect(self._scroll_box)
         self._duration_timer.timeout.connect(self._queue_durations)
         self._entries_fetched.connect(self._on_entries_fetched)
         self._duration_loaded.connect(self._on_duration_loaded)
@@ -121,7 +207,7 @@ def set_entries(self, entry_ids: list[int]) -> None:
         if self._fetch_pool is not None:
             self._fetch_pool.clear()
         now = time.monotonic()
-        if now - self._last_entries_time < self.SHOW_THUMBS_DELAY_MS / 1000:
+        if now - self._last_entries_time < self._SHOW_THUMBS_DELAY_MS / 1000:
             # Show entries immediately if the results are changing quickly.
             # Traversing pages or searching quickly feels much more responsive.
             self._show_thumbs_timer.stop()
@@ -240,7 +326,20 @@ def _index_in_direction(self, index: int, key: Qt.Key) -> int:
     def _update_selected(self) -> None:
         for _, thumb in self.layout().assigned_items():
             if thumb not in self._held:
-                thumb.set_selected(self._driver.selection.is_selected(thumb.item_id))
+                thumb.set_selected(self._shows_selected(thumb.item_id))
+
+    def _shows_selected(self, entry_id: int) -> bool:
+        """Whether an item shows as selected, including an unreleased selection box's changes.
+
+        A selection box won't truly select items until released, but items are allowed to
+        appear selected under the box before the selection is completed.
+
+        NOTE: This mimics macOS Finder behavior, and prevents rapid Inspector updates.
+        """
+        selected = self._driver.selection.is_selected(entry_id)
+        if entry_id not in self._box_entries:
+            return selected
+        return not selected if self._does_box_toggle else True
 
     def _create_thumb(self) -> ItemThumb:
         size = self._driver.main_window.thumb_size
@@ -285,7 +384,7 @@ def _show_entry(self, thumb: ItemThumb) -> None:
             self._show_loading_image(thumb)
         else:
             self._assign_entry(thumb, entry)
-        thumb.set_selected(self._driver.selection.is_selected(thumb.item_id))
+        thumb.set_selected(self._shows_selected(thumb.item_id))
 
     def _clear_thumb(self, thumb: ItemThumb) -> None:
         """Remove the entry details and image a thumbnail is showing."""

src/tagstudio/qt/selection_state.py

@@ -33,6 +33,7 @@ def selected(self) -> list[T]:
 
     @property
     def cursor(self) -> T | None:
+        """The last item clicked or moved to with arrow keys and where they continue from."""
         return self._selection_cursor
 
     def is_selected(self, item_id: T) -> bool:
@@ -106,6 +107,16 @@ def deselect(self, item_ids: Iterable[T]) -> None:
             self._selection_cursor = self._selection_anchor
         self.changed.emit()
 
+    def select_items(self, item_ids: Iterable[T]) -> None:
+        """Set the selection to these items, setting the last one as the anchor and cursor."""
+        previous = self.selected
+        self._selected = dict.fromkeys(item_ids)
+        self._existing_selection = self.selected
+        self._selection_anchor = next(reversed(self._selected), None)
+        self._selection_cursor = self._selection_anchor
+        if self.selected != previous:
+            self.changed.emit()
+
     def move_selection(self, order: Sequence[T], target: int, extend: bool) -> int:
         """Move or extend the selection to `order[target]`, like with an arrow key.