Fix macOS tooltip flicker and overlap

Author: NDevDrone

ardupilot_methodic_configurator/frontend_tkinter_show.py

@@ -13,14 +13,16 @@
 import tkinter as tk
 from platform import system as platform_system
 from tkinter import messagebox, ttk
-from typing import Any, NamedTuple, Optional, cast
+from typing import Any, ClassVar, NamedTuple, Optional, cast
 from weakref import WeakKeyDictionary
 
 from ardupilot_methodic_configurator import _
 
 # Tooltip positioning constants
 TOOLTIP_MAX_OFFSET = 100  # Maximum horizontal offset from widget edge
 TOOLTIP_VERTICAL_OFFSET = 10  # Vertical offset when positioning above widget
+TOOLTIP_SHOW_DELAY_MS = 250  # Delay before showing to avoid flicker while moving across dense UIs
+TOOLTIP_HIDE_DELAY_MS = 75  # Small delay prevents leave/enter jitter from leaving stale tooltips behind
 
 
 class MonitorBounds(NamedTuple):
@@ -456,6 +458,8 @@ class Tooltip:
     Creates a tooltip that appears when the mouse hovers over a widget and disappears when the mouse leaves the widget.
     """
 
+    _active_tooltip: ClassVar[Optional["Tooltip"]] = None
+
     def __init__(  # pylint: disable=too-many-arguments, too-many-positional-arguments
         self,
         widget: tk.Widget,
@@ -470,15 +474,17 @@ def __init__(  # pylint: disable=too-many-arguments, too-many-positional-argumen
         self.position_below: bool = position_below
         self.toplevel_class = toplevel_class or tk.Toplevel
         self.hide_timer: Optional[str] = None
+        self.show_timer: Optional[str] = None
 
         # Bind the <Enter> and <Leave> events to show and hide the tooltip
         if platform_system() == "Darwin":
-            # On macOS, only create the tooltip when the mouse enters the widget
+            # On macOS, defer tooltip creation slightly to avoid flashing while
+            # moving through dense tables and controls.
             if tag_name and isinstance(self.widget, tk.Text):
-                self.widget.tag_bind(tag_name, "<Enter>", self.create_show, "+")
+                self.widget.tag_bind(tag_name, "<Enter>", self.schedule_show, "+")
                 self.widget.tag_bind(tag_name, "<Leave>", self.destroy_hide, "+")
             else:
-                self.widget.bind("<Enter>", self.create_show, "+")
+                self.widget.bind("<Enter>", self.schedule_show, "+")
                 self.widget.bind("<Leave>", self.destroy_hide, "+")
         else:
             if tag_name and isinstance(self.widget, tk.Text):
@@ -499,25 +505,50 @@ def __init__(  # pylint: disable=too-many-arguments, too-many-positional-argumen
             self.tooltip.bind("<Enter>", self._cancel_hide)
             self.tooltip.bind("<Leave>", self.hide)
 
+    def _cancel_show(self) -> None:
+        """Cancel any pending show timer."""
+        if self.show_timer:
+            self.widget.after_cancel(self.show_timer)
+            self.show_timer = None
+
     def show(self, event: Optional[tk.Event] = None) -> None:  # noqa: ARG002 # pylint: disable=unused-argument
         """On non-macOS, tooltip already exists, show it on events."""
         self._cancel_hide()
+        self._hide_active_tooltip()
         if self.tooltip:
             self.position_tooltip()
             self.tooltip.deiconify()
+            Tooltip._active_tooltip = self
 
     def _cancel_hide(self, event: Optional[tk.Event] = None) -> None:  # noqa: ARG002 # pylint: disable=unused-argument
         """Cancel the hide timer."""
         if self.hide_timer:
             self.widget.after_cancel(self.hide_timer)
             self.hide_timer = None
 
+    def _hide_active_tooltip(self) -> None:
+        """Hide another active tooltip before showing this one."""
+        if Tooltip._active_tooltip and Tooltip._active_tooltip is not self:
+            Tooltip._active_tooltip.force_hide()
+
+    def schedule_show(self, event: Optional[tk.Event] = None) -> None:  # noqa: ARG002 # pylint: disable=unused-argument
+        """Delay tooltip creation slightly to avoid flicker during pointer movement."""
+        self._cancel_hide()
+        self._cancel_show()
+        self.show_timer = self.widget.after(TOOLTIP_SHOW_DELAY_MS, self.create_show)
+
     def create_show(self, event: Optional[tk.Event] = None) -> None:  # noqa: ARG002 # pylint: disable=unused-argument
         """On macOS, only create the tooltip when the mouse enters the widget."""
+        self._cancel_show()
+        self._cancel_hide()
+        self._hide_active_tooltip()
+
         if self.tooltip:
+            Tooltip._active_tooltip = self
             return  # Avoid redundant tooltip creation
 
         self.tooltip = cast("tk.Toplevel", self.toplevel_class(self.widget))
+        self.tooltip.withdraw()
 
         try:
             self.tooltip.tk.call(
@@ -537,9 +568,8 @@ def create_show(self, event: Optional[tk.Event] = None) -> None:  # noqa: ARG002
         )
         tooltip_label.pack()
         self.position_tooltip()
-        # Bind to tooltip to prevent hiding when mouse is over it
-        self.tooltip.bind("<Enter>", self._cancel_hide)
-        self.tooltip.bind("<Leave>", self.destroy_hide)
+        self.tooltip.deiconify()
+        Tooltip._active_tooltip = self
 
     def position_tooltip(self) -> None:
         """Position tooltip within monitor bounds, handling widget destruction gracefully."""
@@ -580,20 +610,32 @@ def position_tooltip(self) -> None:
     def hide(self, event: Optional[tk.Event] = None) -> None:  # noqa: ARG002 # pylint: disable=unused-argument
         """Hide the tooltip after a delay on non-macOS."""
         self._cancel_hide()
-        self.hide_timer = self.widget.after(10, self._do_hide)
+        self.hide_timer = self.widget.after(TOOLTIP_HIDE_DELAY_MS, self._do_hide)
 
     def _do_hide(self) -> None:
         """Actually hide or destroy the tooltip depending on platform."""
         if self.tooltip:
             self.tooltip.withdraw()
+        if Tooltip._active_tooltip is self:
+            Tooltip._active_tooltip = None
         self.hide_timer = None
 
-    def destroy_hide(self, event: Optional[tk.Event] = None) -> None:  # noqa: ARG002 # pylint: disable=unused-argument
-        """On macOS, fully destroy the tooltip when the mouse leaves the widget."""
+    def force_hide(self) -> None:
+        """Immediately hide or destroy the tooltip, depending on platform."""
+        self._cancel_show()
         self._cancel_hide()
         if self.tooltip:
-            self.tooltip.destroy()
-            self.tooltip = None
+            if platform_system() == "Darwin":
+                self.tooltip.destroy()
+                self.tooltip = None
+            else:
+                self.tooltip.withdraw()
+        if Tooltip._active_tooltip is self:
+            Tooltip._active_tooltip = None
+
+    def destroy_hide(self, event: Optional[tk.Event] = None) -> None:  # noqa: ARG002 # pylint: disable=unused-argument
+        """On macOS, fully destroy the tooltip when the mouse leaves the widget."""
+        self.force_hide()
 
 
 def show_tooltip(widget: tk.Widget, text: str, position_below: bool = True) -> Tooltip:

tests/bdd_frontend_tkinter_show.py

@@ -24,6 +24,8 @@
 
 from ardupilot_methodic_configurator.frontend_tkinter_show import (
     MonitorBounds,
+    TOOLTIP_HIDE_DELAY_MS,
+    TOOLTIP_SHOW_DELAY_MS,
     Tooltip,
     calculate_tooltip_position,
     get_monitor_bounds,
@@ -656,6 +658,13 @@ def test_system_accepts_large_multi_monitor_setups(self, mock_widget: MagicMock)
 class TestTooltipFunctionality:  # pylint: disable=too-many-public-methods
     """Test the Tooltip class and related functions."""
 
+    @pytest.fixture(autouse=True)
+    def reset_active_tooltip(self) -> None:
+        """Ensure tooltip singleton state does not leak across tests."""
+        Tooltip._active_tooltip = None
+        yield
+        Tooltip._active_tooltip = None
+
     @pytest.fixture
     def mock_widget(self) -> MagicMock:
         """Create a mock widget for testing."""
@@ -766,7 +775,7 @@ def test_tooltip_initialization_macos(self, mock_widget: MagicMock) -> None:
         # Check that tooltip is None initially
         assert tooltip.tooltip is None
         # Check bindings
-        mock_widget.bind.assert_any_call("<Enter>", tooltip.create_show, "+")
+        mock_widget.bind.assert_any_call("<Enter>", tooltip.schedule_show, "+")
         mock_widget.bind.assert_any_call("<Leave>", tooltip.destroy_hide, "+")
 
     def test_tooltip_create_show_on_macos(self, mock_widget: MagicMock, mock_toplevel: MagicMock) -> None:
@@ -781,14 +790,18 @@ def test_tooltip_create_show_on_macos(self, mock_widget: MagicMock, mock_topleve
             patch("ardupilot_methodic_configurator.frontend_tkinter_show.platform_system", return_value="Darwin"),
             patch("tkinter.Toplevel", return_value=mock_toplevel),
             patch("tkinter.ttk.Label") as mock_label,
+            patch(
+                "ardupilot_methodic_configurator.frontend_tkinter_show.get_monitor_bounds",
+                return_value=MonitorBounds(0, 0, 1920, 1080),
+            ),
         ):
             tooltip = Tooltip(mock_widget, "Test text")
             tooltip.create_show()
 
             assert tooltip.tooltip == mock_toplevel
             mock_label.assert_called_once()
-            mock_toplevel.bind.assert_any_call("<Enter>", tooltip._cancel_hide)
-            mock_toplevel.bind.assert_any_call("<Leave>", tooltip.destroy_hide)
+            mock_toplevel.withdraw.assert_called_once()
+            mock_toplevel.deiconify.assert_called_once()
 
     def test_tooltip_position_tooltip(self, mock_widget, mock_toplevel) -> None:
         """
@@ -853,7 +866,7 @@ def test_tooltip_hide(self, mock_widget, mock_toplevel) -> None:
 
             tooltip.hide()
 
-            mock_widget.after.assert_called_once_with(10, tooltip._do_hide)
+            mock_widget.after.assert_called_once_with(TOOLTIP_HIDE_DELAY_MS, tooltip._do_hide)
 
     def test_tooltip_cancel_hide(self, mock_widget) -> None:
         """
@@ -893,6 +906,47 @@ def test_tooltip_destroy_hide_on_macos(self, mock_widget: MagicMock, mock_toplev
         mock_toplevel.destroy.assert_called_once()
         assert tooltip.tooltip is None
 
+    def test_tooltip_schedule_show_on_macos(self, mock_widget: MagicMock) -> None:
+        """
+        Test tooltip show is scheduled on macOS instead of appearing immediately.
+
+        GIVEN: macOS platform
+        WHEN: Mouse enters widget
+        THEN: Tooltip creation is delayed slightly
+        """
+        with patch("ardupilot_methodic_configurator.frontend_tkinter_show.platform_system", return_value="Darwin"):
+            tooltip = Tooltip(mock_widget, "Test text")
+
+        tooltip.schedule_show()
+
+        mock_widget.after.assert_called_once_with(TOOLTIP_SHOW_DELAY_MS, tooltip.create_show)
+
+    def test_tooltip_create_show_hides_previous_active_tooltip(self, mock_widget: MagicMock, mock_toplevel: MagicMock) -> None:
+        """
+        Test macOS only keeps one active tooltip visible at a time.
+
+        GIVEN: Another tooltip is already active
+        WHEN: A new tooltip is shown
+        THEN: The previous tooltip is hidden first
+        """
+        previous_tooltip = MagicMock()
+
+        with (
+            patch("ardupilot_methodic_configurator.frontend_tkinter_show.platform_system", return_value="Darwin"),
+            patch("tkinter.Toplevel", return_value=mock_toplevel),
+            patch("tkinter.ttk.Label"),
+            patch(
+                "ardupilot_methodic_configurator.frontend_tkinter_show.get_monitor_bounds",
+                return_value=MonitorBounds(0, 0, 1920, 1080),
+            ),
+        ):
+            Tooltip._active_tooltip = previous_tooltip
+            tooltip = Tooltip(mock_widget, "Test text")
+            tooltip.create_show()
+
+        previous_tooltip.force_hide.assert_called_once()
+        Tooltip._active_tooltip = None
+
     def test_tooltip_handles_widget_destruction_during_positioning(self, mock_widget, mock_toplevel) -> None:
         """
         Test tooltip handles widget destruction during positioning.
@@ -966,6 +1020,10 @@ def test_tooltip_create_show_avoids_redundant_creation(self, mock_widget, mock_t
             patch("ardupilot_methodic_configurator.frontend_tkinter_show.platform_system", return_value="Darwin"),
             patch("tkinter.Toplevel", return_value=mock_toplevel) as mock_toplevel_class,
             patch("tkinter.ttk.Label"),
+            patch(
+                "ardupilot_methodic_configurator.frontend_tkinter_show.get_monitor_bounds",
+                return_value=MonitorBounds(0, 0, 1920, 1080),
+            ),
         ):
             tooltip = Tooltip(mock_widget, "Test text")
             tooltip.create_show()