improve how JABS handles multiple windows

gbeane · gbeane · commit b9956cef2ae0 · 2026-01-03T19:38:50.000-05:00
diff --git a/src/jabs/resources/docs/user_guide/gui.md b/src/jabs/resources/docs/user_guide/gui.md
@@ -190,6 +190,11 @@ Clicking the Brightness or Contrast controls will reset the brightness or contra
   - **Features→Enable Lixit Features:** toggle using lixit features (v5+ projects with lixit static object)
   - **Features→Enable Food_hopper Features:** toggle using food hopper features (v5+ projects with food hopper static object)
   - **Features→Enable Segmentation Features:** toggle using segmentation features (v6+ projects)
+- **Window:** Menu for managing JABS windows.
+  - **Window→Minimize:** Minimize the main window (⌘M on macOS, Ctrl+M on other platforms)
+  - **Window→Zoom:** Toggle between normal and maximized window state
+  - **Window→Bring All to Front:** Bring all JABS windows to the front
+  - The Window menu also displays a list of all open JABS windows (main window, user guide, training reports, etc.) with a checkmark (✓) next to the currently active window. Click any window in the list to activate and bring it to the front.
 
 ## Overlays
 
diff --git a/src/jabs/resources/docs/user_guide/keyboard-shortcuts.md b/src/jabs/resources/docs/user_guide/keyboard-shortcuts.md
@@ -2,11 +2,11 @@
 
 ## Application
 
-| Action                      | Shortcut       |
-| --------------------------- | -------------- |
-| Quit JABS                   | Ctrl+Q / Cmd+Q |
-| Export training data        | Ctrl+T / Cmd+T |
-| Open behavior search dialog | Ctrl+F / Cmd+F |
+| Action                      | Shortcut      |
+| --------------------------- | ------------- |
+| Quit JABS                   | Ctrl+Q / ⌘Q   |
+| Export training data        | Ctrl+T / ⌘T   |
+| Open behavior search dialog | Ctrl+F / ⌘F   |
 
 ## Video Navigation
 
@@ -26,7 +26,7 @@
 | Clear labels from selection              | x              |
 | Label selection as not behavior          | c              |
 | Exit select mode without making a change | Esc            |
-| Select all frames                        | Ctrl+A / Cmd+A |
+| Select all frames                        | Ctrl+A / ⌘A   |
 
 ## Identity & Overlays
 
@@ -36,6 +36,6 @@
 | Toggle track overlay              | t                 |
 | Toggle pose overlay               | p                 |
 | Toggle landmark overlay           | l                 |
-| Toggle Minimalist Identity Labels | Ctrl+I / Cmd+I    |
+| Toggle Minimalist Identity Labels | Ctrl+I / ⌘I   |
 
 > **Note:** Next/previous subject order follows the "Identity Selection" dropdown ordering.
diff --git a/src/jabs/ui/central_widget.py b/src/jabs/ui/central_widget.py
@@ -6,7 +6,7 @@
 import numpy as np
 from PySide6 import QtCore, QtWidgets
 from PySide6.QtCore import Qt
-from PySide6.QtWidgets import QDialog
+from PySide6.QtWidgets import QApplication, QDialog
 from shapely.geometry import Point
 
 import jabs.feature_extraction
@@ -271,6 +271,21 @@ def id_overlay_mode(self, mode: PlayerWidget.IdentityOverlayMode) -> None:
         """
         self._player_widget.id_overlay_mode = mode
 
+    def get_open_dialogs(self) -> list[tuple[str, QtWidgets.QWidget]]:
+        """Get a list of open dialogs managed by this widget.
+
+        Returns:
+            List of (title, widget) tuples for all visible dialogs.
+        """
+        dialogs = []
+
+        if self._training_report_dialog is not None and self._training_report_dialog.isVisible():
+            dialogs.append(
+                (self._training_report_dialog.windowTitle(), self._training_report_dialog)
+            )
+
+        return dialogs
+
     def set_project(self, project: Project) -> None:
         """set the currently opened project"""
         self._project = project
@@ -736,31 +751,86 @@ def _training_thread_complete(self, elapsed_ms) -> None:
 
         # Display training report if available
         if self._training_report_markdown:
-            # Close any existing training report dialog before showing new one
-            if self._training_report_dialog is not None:
+            # Check if any JABS window has focus (main window or any child)
+            jabs_app_has_focus = QApplication.activeWindow() is not None
+
+            # If any JABS window has focus and a dialog exists, close it and create new one
+            # This is the only reliable way to switch focus on macOS
+            if jabs_app_has_focus and self._training_report_dialog is not None:
+                # Save the old position and size before closing
+                old_geometry = self._training_report_dialog.geometry()
                 self._training_report_dialog.close()
                 self._training_report_dialog = None
 
-            self._training_report_dialog = TrainingReportDialog(
-                self._training_report_markdown,
-                title=f"Training Report: {self._controls.current_behavior}",
-                parent=self,
-            )
-            # Connect to cleanup when dialog is closed
-            self._training_report_dialog.finished.connect(
-                lambda: setattr(self, "_training_report_dialog", None)
-            )
+                # Create new dialog
+                self._training_report_dialog = TrainingReportDialog(
+                    self._training_report_markdown,
+                    title=f"Training Report: {self._controls.current_behavior}",
+                    parent=self,
+                )
 
-            # Temporarily set stay-on-top to ensure it appears in front
-            self._training_report_dialog.setWindowFlags(
-                self._training_report_dialog.windowFlags() | Qt.WindowType.WindowStaysOnTopHint
-            )
-            self._training_report_dialog.show()
-            self._training_report_dialog.raise_()
-            self._training_report_dialog.activateWindow()
+                # Connect to cleanup when dialog is closed
+                self._training_report_dialog.finished.connect(
+                    lambda: setattr(self, "_training_report_dialog", None)
+                )
+
+                # Show with aggressive focus-stealing
+                self._training_report_dialog.setWindowFlags(
+                    self._training_report_dialog.windowFlags() | Qt.WindowType.WindowStaysOnTopHint
+                )
+                self._training_report_dialog.show()
+                # Restore geometry AFTER show() to preserve position
+                self._training_report_dialog.setGeometry(old_geometry)
+                # Force processing of events to ensure window system updates
+                QtCore.QCoreApplication.processEvents()
+                self._training_report_dialog.raise_()
+                self._training_report_dialog.activateWindow()
+                # Try to force repaint/update
+                self._training_report_dialog.repaint()
+                QtCore.QCoreApplication.processEvents()
+
+                # Remove stay-on-top flag after a brief delay
+                QtCore.QTimer.singleShot(100, lambda: self._remove_stay_on_top_flag())
+
+            elif self._training_report_dialog is not None:
+                # JABS doesn't have focus - just update existing dialog quietly
+                self._training_report_dialog.update_content(
+                    self._training_report_markdown,
+                    title=f"Training Report: {self._controls.current_behavior}",
+                )
+                # Ensure dialog is visible (in case it was minimized or hidden)
+                if self._training_report_dialog.isMinimized():
+                    self._training_report_dialog.showNormal()
+                elif not self._training_report_dialog.isVisible():
+                    self._training_report_dialog.show()
+            else:
+                # No existing dialog - create new one
+                self._training_report_dialog = TrainingReportDialog(
+                    self._training_report_markdown,
+                    title=f"Training Report: {self._controls.current_behavior}",
+                    parent=self,
+                )
+                # Connect to cleanup when dialog is closed
+                self._training_report_dialog.finished.connect(
+                    lambda: setattr(self, "_training_report_dialog", None)
+                )
 
-            # Remove stay-on-top flag after a brief delay so user can manage windows normally
-            QtCore.QTimer.singleShot(100, lambda: self._remove_stay_on_top_flag())
+                # Show the dialog
+                self._training_report_dialog.show()
+
+                # Only bring to front and activate if JABS has focus
+                if jabs_app_has_focus:
+                    # Temporarily set stay-on-top to ensure it appears in front
+                    self._training_report_dialog.setWindowFlags(
+                        self._training_report_dialog.windowFlags()
+                        | Qt.WindowType.WindowStaysOnTopHint
+                    )
+                    self._training_report_dialog.show()  # Need to call show() again after changing flags
+                    self._training_report_dialog.raise_()
+                    self._training_report_dialog.activateWindow()
+
+                    # Remove stay-on-top flag after a brief delay so user can manage windows normally
+                    QtCore.QTimer.singleShot(100, lambda: self._remove_stay_on_top_flag())
 
             self._training_report_markdown = None  # Clear after displaying
 
diff --git a/src/jabs/ui/main_window.py b/src/jabs/ui/main_window.py
@@ -112,6 +112,7 @@ def __init__(self, app_name: str, app_name_long: str, *args, **kwargs) -> None:
         file_menu = menu.addMenu("File")
         view_menu = menu.addMenu("View")
         feature_menu = menu.addMenu("Features")
+        self._window_menu = menu.addMenu("Window")
 
         # Setup App Menu
         # about app
@@ -401,6 +402,29 @@ def __init__(self, app_name: str, app_name_long: str, *args, **kwargs) -> None:
         )
         feature_menu.addAction(self.enable_segmentation_features)
 
+        # Setup Window Menu
+        # Minimize action
+        minimize_action = QtGui.QAction("Minimize", self)
+        minimize_action.setShortcut(QtGui.QKeySequence("Ctrl+M"))
+        minimize_action.triggered.connect(self.showMinimized)
+        self._window_menu.addAction(minimize_action)
+
+        # Zoom action
+        zoom_action = QtGui.QAction("Zoom", self)
+        zoom_action.triggered.connect(self._toggle_zoom)
+        self._window_menu.addAction(zoom_action)
+
+        # Bring All to Front action
+        bring_all_to_front_action = QtGui.QAction("Bring All to Front", self)
+        bring_all_to_front_action.triggered.connect(self._bring_all_windows_to_front)
+        self._window_menu.addAction(bring_all_to_front_action)
+
+        self._window_menu.addSeparator()
+
+        # Dynamic window list will be added here
+        # Connect aboutToShow to update the window list when menu is opened
+        self._window_menu.aboutToShow.connect(self._update_window_menu)
+
         # select all action
         select_all_action = QtGui.QAction(self)
         select_all_action.setShortcut(QtGui.QKeySequence.StandardKey.SelectAll)
@@ -1082,3 +1106,67 @@ def _view_license(self) -> None:
         """View the license agreement (JABS->View License Agreement menu action)"""
         dialog = LicenseAgreementDialog(self, view_only=True)
         dialog.exec_()
+
+    def _toggle_zoom(self) -> None:
+        """Toggle between normal and maximized window state."""
+        if self.isMaximized():
+            self.showNormal()
+        else:
+            self.showMaximized()
+
+    def _bring_all_windows_to_front(self) -> None:
+        """Bring all JABS windows to the front."""
+        for widget in QtWidgets.QApplication.topLevelWidgets():
+            if widget.isVisible() and not widget.isMinimized():
+                widget.raise_()
+                widget.activateWindow()
+
+    def _update_window_menu(self) -> None:
+        """Update the Window menu with the current list of open windows."""
+        # Remove all dynamic window items (everything after the separator)
+        actions = self._window_menu.actions()
+        separator_found = False
+        items_to_remove = []
+
+        for action in actions:
+            if separator_found:
+                items_to_remove.append(action)
+            elif action.isSeparator():
+                separator_found = True
+
+        for action in items_to_remove:
+            self._window_menu.removeAction(action)
+
+        # Add Main Window
+        main_window_action = QtGui.QAction("Main Window", self)
+        main_window_action.setCheckable(True)
+        main_window_action.setChecked(self.isActiveWindow())
+        main_window_action.triggered.connect(lambda: self._activate_window(self))
+        self._window_menu.addAction(main_window_action)
+
+        # Add User Guide window if open
+        if self._user_guide_window is not None and self._user_guide_window.isVisible():
+            guide_action = QtGui.QAction(self._user_guide_window.windowTitle(), self)
+            guide_action.setCheckable(True)
+            guide_action.setChecked(self._user_guide_window.isActiveWindow())
+            guide_action.triggered.connect(lambda: self._activate_window(self._user_guide_window))
+            self._window_menu.addAction(guide_action)
+
+        # Add any open dialogs from the central widget
+        for title, dialog in self._central_widget.get_open_dialogs():
+            dialog_action = QtGui.QAction(title, self)
+            dialog_action.setCheckable(True)
+            dialog_action.setChecked(dialog.isActiveWindow())
+            dialog_action.triggered.connect(lambda checked, w=dialog: self._activate_window(w))
+            self._window_menu.addAction(dialog_action)
+
+    def _activate_window(self, window: QtWidgets.QWidget) -> None:
+        """Activate and bring a window to the front.
+
+        Args:
+            window: The window to activate
+        """
+        if window.isMinimized():
+            window.showNormal()
+        window.raise_()
+        window.activateWindow()
diff --git a/src/jabs/ui/training_report.py b/src/jabs/ui/training_report.py
@@ -3,6 +3,7 @@
 from textwrap import dedent
 
 import markdown2
+from PySide6 import QtCore
 from PySide6.QtGui import QIcon
 from PySide6.QtWebEngineWidgets import QWebEngineView
 from PySide6.QtWidgets import (
@@ -39,10 +40,14 @@ def __init__(self, markdown_content: str, title: str = "Training Report", parent
         main_layout.setContentsMargins(0, 0, 0, 0)
         main_layout.setSpacing(0)
 
-        # Convert markdown to HTML and create web view
-        html_content = self._markdown_to_html(markdown_content)
+        # Create web view for content
         self.web_view = QWebEngineView()
-        self.web_view.setHtml(html_content)
+
+        # Defer HTML content setting to avoid "Compositor returned null texture" errors
+        # (even though these are harmless because Qt will retry rendering)
+        # The compositor needs the window to be shown before it can create rendering surfaces
+        html_content = self._markdown_to_html(markdown_content)
+        QtCore.QTimer.singleShot(0, lambda: self.web_view.setHtml(html_content))
 
         main_layout.addWidget(self.web_view)
 
@@ -70,6 +75,28 @@ def _copy_markdown_to_clipboard(self):
         clipboard = QApplication.clipboard()
         clipboard.setText(self._markdown_content)
 
+    def update_content(self, markdown_content: str, title: str | None = None):
+        """Update the dialog with new markdown content.
+
+        This allows reusing an existing dialog instead of creating a new one,
+        which preserves the user's window position and size.
+
+        Args:
+            markdown_content: New markdown-formatted training report content
+            title: Optional new window title
+        """
+        # Update stored markdown content
+        self._markdown_content = markdown_content
+
+        # Update title if provided
+        if title:
+            self.setWindowTitle(title)
+
+        # Convert new markdown to HTML and update web view
+        # Defer to avoid compositor errors
+        html_content = self._markdown_to_html(markdown_content)
+        QtCore.QTimer.singleShot(0, lambda: self.web_view.setHtml(html_content))
+
     def _markdown_to_html(self, markdown_text: str) -> str:
         """Convert markdown text to HTML.
 
diff --git a/src/jabs/ui/user_guide_dialog.py b/src/jabs/ui/user_guide_dialog.py
@@ -107,7 +107,6 @@ def __init__(self, app_name: str, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self.setWindowTitle(f"{app_name} User Guide")
         self.setWindowModality(QtCore.Qt.WindowModality.NonModal)
-        self.setWindowFlag(QtCore.Qt.WindowType.Tool)
         self.resize(1200, 700)
 
         # Navigation history tracking
@@ -155,9 +154,10 @@ def __init__(self, app_name: str, *args: Any, **kwargs: Any) -> None:
 
         self.setLayout(layout)
 
-        # Build tree and load initial content
+        # Build tree and defer initial content loading to avoid "Compositor returned null texture" errors
+        # The compositor needs the window to be shown before it can create rendering surfaces
         self._build_tree()
-        self._load_content_from_path("overview.md")
+        QtCore.QTimer.singleShot(0, lambda: self._load_content_from_path("overview.md"))
 
     def _build_tree(self) -> None:
         """Build the hierarchical tree structure for documentation navigation.
