gallery_widget

def set_pagination(self, page: int, total_pages: int, total_count: int) -> None:
    """Update only the pagination label and button states.

    Cheap enough to call on the UI thread — touches no cells and issues
    no DB query — so a background poll refresh can keep the page counter
    current without disturbing (or re-spinning) the visible thumbnails.

    Args:
        page: Current zero-based page index.
        total_pages: Total number of pages.
        total_count: Total number of results.
    """
    self._current_page = page
    self._total_pages = total_pages
    self._page_label.value = self._page_text(page, total_pages, total_count)
    self._first_btn.disabled = page <= 0
    self._prev_btn.disabled = page <= 0
    self._next_btn.disabled = page >= total_pages - 1

def begin_page(self, page: int, total_pages: int, total_count: int, n_loading: int) -> None:
    """Flip to *page* instantly, showing spinners while images load.

    Called on the UI thread the moment the user navigates so the page
    turns without waiting on the DB query or image decode: the first
    *n_loading* cells show a loading spinner and the rest are cleared.
    Filenames, scores, and images are filled in afterwards from a
    background thread. This is what makes ``Next``/``Previous``
    non-blocking.

    Args:
        page: Current zero-based page index.
        total_pages: Total number of pages.
        total_count: Total number of results.
        n_loading: Number of leading cells to put in the loading state.
    """
    self.set_pagination(page, total_pages, total_count)
    for i, cell in enumerate(self._cells):
        if i < n_loading:
            cell.mark_loading()
            cell.widget.layout.display = ""
        else:
            cell.clear()
            if self._setup_mode:
                cell.widget.layout.display = "none"

def update_page(
    self,
    results: list[dict],
    page: int,
    total_pages: int,
    total_count: int,
    image_loader: Callable[[str], bytes | None] | None = None,
) -> None:
    """Fill the grid cells from a page of DB results.

    Args:
        results: List of dicts with keys ``filename``, ``score``, and
            an optional ``display`` caption to show instead of
            ``filename`` (defaults to ``filename``).
        page: Current zero-based page index.
        total_pages: Total number of pages.
        total_count: Total number of results.
        image_loader: Callable that returns PNG bytes for a filename,
            or None if unavailable.
    """
    self._current_page = page
    self._total_pages = total_pages

    for i, cell in enumerate(self._cells):
        if i < len(results):
            r = results[i]
            img_bytes = b""
            if image_loader:
                loaded = image_loader(r["filename"])
                if loaded:
                    img_bytes = loaded
            cell.update(r["filename"], r["score"], img_bytes, display_name=r.get("display"))
            cell.widget.layout.display = ""
        else:
            cell.clear()
            # In setup_mode the gallery shows a finite candidate
            # list; rendering "Waiting for results…" placeholders
            # in the leftover slots is just noise (#427 follow-up).
            # Score-mode galleries leave them visible — a short
            # last page next to a populated previous one reads
            # better as placeholders than as empty space.
            if self._setup_mode:
                cell.widget.layout.display = "none"

    self._page_label.value = self._page_text(page, total_pages, total_count)
    self._first_btn.disabled = page <= 0
    self._prev_btn.disabled = page <= 0
    self._next_btn.disabled = page >= total_pages - 1

def get_sort_mode(self) -> str:
    """Return the current sort key.

    Returns:
        Sort key string (e.g. ``"score_desc"``).
    """
    return self._sort_mode

def set_on_sort_change(self, callback: Callable[[], None]) -> None:
    """Register a callback for sort mode changes.

    Args:
        callback: Called when the user clicks a different sort button.
    """
    self._on_sort_change = callback

def set_on_page_change(self, callback: Callable[[int], None]) -> None:
    """Register a callback for page changes.

    Args:
        callback: Called with the new page index.
    """
    self._on_page_change = callback

def set_on_scale_change(self, callback: Callable[[], None]) -> None:
    """Register a callback for slider changes.

    The consumer should re-render the current page using the new
    :attr:`effective_page_size` so paging tracks what's visible.

    Args:
        callback: Zero-arg callable invoked after the slider's CSS
            update has been applied.
    """
    self._on_scale_change_callback = callback