Refactor camera scan state and loaders

Introduce explicit scan state and tidy worker APIs for camera discovery.

- Add CameraScanState enum and use it as single source of truth in CameraConfigDialog (_scan_state).
- Replace ad-hoc worker checks with _set_scan_state, _finish_scan and _cleanup_scan_worker to manage UI overlays, progress/cancel controls and stability guarantees.
- Add request_scan_cancel() to request interruption and handle canceled/result flows; DetectCamerasWorker now emits result (even empty) and canceled when interrupted.
- Simplify QThread usage: remove custom finished signals, add typing annotations and clearer run() signatures in loaders; adjust worker signals (canceled) and small API refinements (request_cancel return types).
- Update UI hookup (ui_blocks) to call request_scan_cancel instead of private handler.
- Update unit and e2e tests to follow new scan lifecycle (wait for scan_started/scan_finished, helper _run_scan_and_wait, and scan state assertions).

Files changed: camera_config_dialog.py, loaders.py, ui_blocks.py and related tests to match the new scan lifecycle and worker behaviour.

Author: C-Achard

dlclivegui/gui/camera_config/camera_config_dialog.py

@@ -19,7 +19,7 @@
 
 from ...cameras.factory import CameraFactory, DetectedCamera, apply_detected_identity, camera_identity_key
 from ...config import CameraSettings, MultiCameraSettings
-from .loaders import CameraLoadWorker, CameraProbeWorker, DetectCamerasWorker
+from .loaders import CameraLoadWorker, CameraProbeWorker, CameraScanState, DetectCamerasWorker
 from .preview import PreviewSession, PreviewState, apply_crop, apply_rotation, resize_to_fit, to_display_pixmap
 from .ui_blocks import setup_camera_config_dialog_ui
 
@@ -64,6 +64,7 @@ def __init__(
 
         # Camera detection worker
         self._scan_worker: DetectCamerasWorker | None = None
+        self._scan_state: CameraScanState = CameraScanState.IDLE
 
         # UI elements for eventFilter (assigned in _setup_ui)
         self._settings_scroll: QScrollArea | None = None
@@ -171,7 +172,8 @@ def _on_close_cleanup(self) -> None:
                 pass
             # Keep this short to reduce UI freeze
             sw.wait(300)
-        self._scan_worker = None
+        self._set_scan_state(CameraScanState.IDLE)
+        self._cleanup_scan_worker()
 
         # Cancel probe worker
         pw = getattr(self, "_probe_worker", None)
@@ -260,7 +262,7 @@ def _connect_signals(self) -> None:
         self.cancel_btn.clicked.connect(self.reject)
         self.scan_started.connect(lambda _: setattr(self, "_dialog_active", True))
         self.scan_finished.connect(lambda: setattr(self, "_dialog_active", False))
-        self.scan_cancel_btn.clicked.connect(self._on_scan_cancel)
+        self.scan_cancel_btn.clicked.connect(self.request_scan_cancel)
 
         def _mark_dirty(*_args):
             self.apply_settings_btn.setEnabled(True)
@@ -312,29 +314,6 @@ def _update_button_states(self) -> None:
         available_row = self.available_cameras_list.currentRow()
         self.add_camera_btn.setEnabled(available_row >= 0 and not scan_running)
 
-    def _sync_scan_ui(self) -> None:
-        """
-        Sync *scan-related* UI controls based on scan state.
-
-        Conservative policy during scan:
-        - Allow editing/previewing already configured cameras (Active list)
-        - Disallow structural changes (add/remove/reorder) and available-list actions
-        """
-        scanning = self._is_scan_running()
-
-        # Discovery controls
-        self.backend_combo.setEnabled(not scanning)
-        self.refresh_btn.setEnabled(not scanning)
-
-        # Available camera list + add flow is blocked during scan
-        self.available_cameras_list.setEnabled(not scanning)
-        self.add_camera_btn.setEnabled(False if scanning else (self.available_cameras_list.currentRow() >= 0))
-
-        # Scan cancel button visibility is already managed in your scan start/finish,
-        # but keeping enabled state here makes it robust.
-        if hasattr(self, "scan_cancel_btn"):
-            self.scan_cancel_btn.setEnabled(scanning)
-
     def _sync_preview_ui(self) -> None:
         """Update buttons/overlays based on preview state only."""
         st = self._preview.state
@@ -478,93 +457,158 @@ def _on_backend_changed(self, _index: int) -> None:
         self._refresh_available_cameras()
 
     def _is_scan_running(self) -> bool:
-        return bool(self._scan_worker and self._scan_worker.isRunning())
+        return self._scan_state in (CameraScanState.RUNNING, CameraScanState.CANCELING)
+
+    def _set_scan_state(self, state: CameraScanState, message: str | None = None) -> None:
+        """Single source of truth for scan-related UI controls."""
+        self._scan_state = state
+
+        scanning = state in (CameraScanState.RUNNING, CameraScanState.CANCELING)
+
+        # Overlay message
+        if scanning:
+            self._show_scan_overlay(
+                message or ("Canceling discovery…" if state == CameraScanState.CANCELING else "Discovering cameras…")
+            )
+        else:
+            self._hide_scan_overlay()
+
+        # Progress + cancel controls
+        self.scan_progress.setVisible(scanning)
+        if scanning:
+            self.scan_progress.setRange(0, 0)  # indeterminate
+        self.scan_cancel_btn.setVisible(scanning)
+        self.scan_cancel_btn.setEnabled(state == CameraScanState.RUNNING)  # disabled while canceling
+
+        # Disable discovery inputs while scanning
+        self.backend_combo.setEnabled(not scanning)
+        self.refresh_btn.setEnabled(not scanning)
+
+        # Available list + add flow blocked while scanning (structure edits disallowed)
+        self.available_cameras_list.setEnabled(not scanning)
+        self.add_camera_btn.setEnabled(False if scanning else (self.available_cameras_list.currentRow() >= 0))
+
+        self._update_button_states()
+
+    def _cleanup_scan_worker(self) -> None:
+        # worker is truly finished now
+        w = self._scan_worker
+        self._scan_worker = None
+        if w is not None:
+            w.deleteLater()
+
+    def _finish_scan(self, reason: str) -> None:
+        """Mark scan UX complete (idempotent) and emit scan_finished queued."""
+        if self._scan_state in (CameraScanState.DONE, CameraScanState.IDLE):
+            return
+
+        # Transition scan UX to DONE (UI controls restored)
+        self._set_scan_state(CameraScanState.DONE)
+
+        QTimer.singleShot(0, self.scan_finished.emit)
+
+        LOGGER.debug("[Scan] finished reason=%s", reason)
 
     def _refresh_available_cameras(self) -> None:
         """Refresh the list of available cameras asynchronously."""
-        backend = self.backend_combo.currentData()
-        if not backend:
-            backend = self.backend_combo.currentText().split()[0]
+        backend = self.backend_combo.currentData() or self.backend_combo.currentText().split()[0]
 
-        # If already scanning, ignore new requests to avoid races
-        if getattr(self, "_scan_worker", None) and self._scan_worker.isRunning():
+        if self._is_scan_running():
             self._show_scan_overlay("Already discovering cameras…")
             return
 
-        # Reset list UI and show progress
+        # Reset UI/list
         self.available_cameras_list.clear()
         self._detected_cameras = []
-        msg = f"Discovering {backend} cameras…"
-        self._show_scan_overlay(msg)
-        self.scan_progress.setRange(0, 0)
-        self.scan_progress.setVisible(True)
-        self.scan_cancel_btn.setVisible(True)
-        self.available_cameras_list.setEnabled(False)
-        self.add_camera_btn.setEnabled(False)
-        self.refresh_btn.setEnabled(False)
-        self.backend_combo.setEnabled(False)
-
-        self._sync_scan_ui()
-        self._update_button_states()
+
+        self._set_scan_state(CameraScanState.RUNNING, message=f"Discovering {backend} cameras…")
 
         # Start worker
-        self._scan_worker = DetectCamerasWorker(backend, max_devices=10, parent=self)
-        self._scan_worker.progress.connect(self._on_scan_progress)
-        self._scan_worker.result.connect(self._on_scan_result)
-        self._scan_worker.error.connect(self._on_scan_error)
-        self._scan_worker.finished.connect(self._on_scan_finished)
+        w = DetectCamerasWorker(backend, max_devices=10, parent=self)
+        self._scan_worker = w
+
+        w.progress.connect(self._on_scan_progress)
+        w.result.connect(self._on_scan_result)
+        w.error.connect(self._on_scan_error)
+        w.canceled.connect(self._on_scan_canceled)
+
+        # Cleanup only
+        w.finished.connect(self._cleanup_scan_worker)
+
         self.scan_started.emit(f"Scanning {backend} cameras…")
-        self._scan_worker.start()
+        w.start()
 
     def _on_scan_progress(self, msg: str) -> None:
+        if self._scan_state not in (CameraScanState.RUNNING, CameraScanState.CANCELING):
+            return
         self._show_scan_overlay(msg or "Discovering cameras…")
 
     def _on_scan_result(self, cams: list) -> None:
+        if self._scan_state not in (CameraScanState.RUNNING, CameraScanState.CANCELING):
+            return
+
+        # Apply results to UI first (stability guarantee)
         self._detected_cameras = cams or []
-        self.available_cameras_list.clear()  # replace list contents
+        self.available_cameras_list.clear()
 
         if not self._detected_cameras:
             placeholder = QListWidgetItem("No cameras detected.")
             placeholder.setFlags(Qt.ItemIsEnabled)
             self.available_cameras_list.addItem(placeholder)
-            return
-
-        for cam in self._detected_cameras:
-            item = QListWidgetItem(f"{cam.label} (index {cam.index})")
-            item.setData(Qt.ItemDataRole.UserRole, cam)
-            self.available_cameras_list.addItem(item)
+        else:
+            for cam in self._detected_cameras:
+                item = QListWidgetItem(f"{cam.label} (index {cam.index})")
+                item.setData(Qt.ItemDataRole.UserRole, cam)
+                self.available_cameras_list.addItem(item)
+            self.available_cameras_list.setCurrentRow(0)
 
-        self.available_cameras_list.setCurrentRow(0)
+        # Now UI is stable: finish scan UX and emit scan_finished queued
+        self._finish_scan("result")
 
     def _on_scan_error(self, msg: str) -> None:
+        if self._scan_state not in (CameraScanState.RUNNING, CameraScanState.CANCELING):
+            return
+
         QMessageBox.warning(self, "Camera Scan", f"Failed to detect cameras:\n{msg}")
 
-    def _on_scan_finished(self) -> None:
-        self._hide_scan_overlay()
-        self.scan_progress.setVisible(False)
-        self._scan_worker = None
+        # Ensure UI is stable (list is stable even if empty) before finishing
+        if self.available_cameras_list.count() == 0:
+            placeholder = QListWidgetItem("Scan failed.")
+            placeholder.setFlags(Qt.ItemIsEnabled)
+            self.available_cameras_list.addItem(placeholder)
 
-        self.scan_cancel_btn.setVisible(False)
-        self.scan_cancel_btn.setEnabled(True)
-        self.available_cameras_list.setEnabled(True)
-        self.refresh_btn.setEnabled(True)
-        self.backend_combo.setEnabled(True)
+        self._finish_scan("error")
 
-        self._sync_scan_ui()
-        self._update_button_states()
-        self.scan_finished.emit()
+    def request_scan_cancel(self) -> None:
+        if not self._is_scan_running():
+            return
 
-    def _on_scan_cancel(self) -> None:
-        """User requested to cancel discovery."""
-        if self._scan_worker and self._scan_worker.isRunning():
+        self._set_scan_state(CameraScanState.CANCELING, message="Canceling discovery…")
+
+        w = self._scan_worker
+        if w is not None:
             try:
-                self._scan_worker.requestInterruption()
+                w.requestInterruption()
             except Exception:
                 pass
-            # Keep the busy bar, update texts
-            self._show_scan_overlay("Canceling discovery…")
-            self.scan_progress.setVisible(True)  # stay visible as indeterminate
-            self.scan_cancel_btn.setEnabled(False)
+
+        # Guarantee UI stability before scan_finished:
+        if self.available_cameras_list.count() == 0:
+            placeholder = QListWidgetItem("Scan canceled.")
+            placeholder.setFlags(Qt.ItemIsEnabled)
+            self.available_cameras_list.addItem(placeholder)
+
+        self._finish_scan("cancel")
+
+    def _on_scan_canceled(self) -> None:
+        self._set_scan_state(CameraScanState.CANCELING, message="Finalizing cancellation…")
+        # If cancel is requested without clicking cancel (e.g., dialog closing), ensure UI finishes
+        if self._scan_state in (CameraScanState.RUNNING, CameraScanState.CANCELING):
+            if self.available_cameras_list.count() == 0:
+                placeholder = QListWidgetItem("Scan canceled.")
+                placeholder.setFlags(Qt.ItemIsEnabled)
+                self.available_cameras_list.addItem(placeholder)
+            self._finish_scan("canceled")
 
     def _on_available_camera_selected(self, row: int) -> None:
         if self._scan_worker and self._scan_worker.isRunning():