pyqt_reactive.widgets.mixins

PyQt6 Widget Utilities

Shared utility functions for PyQt6 widgets, mirroring patterns from the Textual TUI.

pyqt_reactive.widgets.mixins.preserve_selection_during_update(list_widget: QListWidget, get_identifier_func: Callable[[Any], str], should_preserve_func: Callable[[], bool], update_func: Callable[[], None])

Execute a list update function while preserving selection.

Parameters:

• list_widget – The QListWidget to update

• get_identifier_func – Function to extract unique ID from item data

• should_preserve_func – Function that returns True if selection should be preserved

• update_func – Function that updates the list widget contents

pyqt_reactive.widgets.mixins.restore_selection_by_id(list_widget: QListWidget, item_id: str, get_identifier_func: Callable[[Any], str])

Restore selection to an item by its identifier.

Parameters:

• list_widget – The QListWidget to update

• item_id – Identifier of the item to select

• get_identifier_func – Function to extract unique ID from item data

pyqt_reactive.widgets.mixins.handle_selection_change_with_prevention(list_widget: QListWidget, get_selected_func: Callable, get_identifier_func: Callable[[Any], str], should_preserve_func: Callable[[], bool], get_current_id_func: Callable[[], str], on_selected_func: Callable, on_cleared_func: Callable)

Handle selection changes with automatic deselection prevention.

Parameters:

• list_widget – The QListWidget to manage

• get_selected_func – Function that returns currently selected items

• get_identifier_func – Function to extract unique ID from item data

• should_preserve_func – Function that returns True if deselection should be prevented

• get_current_id_func – Function that returns the current selection ID

• on_selected_func – Function to call when items are selected (receives selected items)

• on_cleared_func – Function to call when selection is cleared (no args)

class pyqt_reactive.widgets.mixins.CrossWindowPreviewMixin

Helpers for widgets that respond to cross-window preview updates.

SIMPLIFIED: Any change triggers a debounced full refresh. No complex field path matching - just refresh everything.

Usage:

class MyWidget(QWidget, CrossWindowPreviewMixin):

def __init__(self):

super().__init__() self._init_cross_window_preview_mixin()

# Configure which fields to show in previews self.enable_preview_for_field(‘napari_streaming_config’,

format_streaming_indicator)

# Implement _handle_full_preview_refresh()…

PREVIEW_UPDATE_DEBOUNCE_MS = 20

enable_preview_for_field(field_path: str, formatter: Callable[[Any], str] | None = None, *, scope_root: str | None = None, fallback_resolver: Callable[[Any, Dict[str, Any]], Any] | None = None) → None

Enable preview label for a specific field.

Parameters:

• field_path – Dot-separated field path (e.g., ‘napari_streaming_config’)

• formatter – Optional formatter function. If None, uses str().

• scope_root – IGNORED (kept for backward compatibility)

• fallback_resolver – Optional resolver for computing value from context

disable_preview_for_field(field_path: str) → None

Disable preview label for a specific field.

is_preview_enabled(field_path: str) → bool

Check if preview is enabled for a specific field.

format_preview_value(field_path: str, value: Any) → str

Format a value for preview display using the registered formatter.

get_enabled_preview_fields() → Set[str]

Get the set of all enabled preview field paths.

Modules

cross_window_preview_mixin	Mixin for widgets that consume cross-window ParameterFormManager updates.
selection_preservation_mixin	Selection Preservation Utilities for PyQt6 List Widgets