3.4.1

Automatically generated by python-semantic-release

CHANGELOG.md

@@ -1,6 +1,31 @@
 # CHANGELOG
 
 
+## v3.4.1 (2026-04-01)
+
+### Bug Fixes
+
+- **hover_widget**: Make it fancy + mouse tracking
+  ([`e25b660`](https://github.com/bec-project/bec_widgets/commit/e25b6604d195804bbd6ea6aac395d44dc00d6155))
+
+- **ring**: Changed inheritance to BECWidget and added cleanup
+  ([`2f75aae`](https://github.com/bec-project/bec_widgets/commit/2f75aaea16a178e180e68d702cd1bdf85a768bcf))
+
+- **ring**: Hook update hover to update method
+  ([`90ecd8e`](https://github.com/bec-project/bec_widgets/commit/90ecd8ea87faf06c3f545e3f9241f403b733d7eb))
+
+- **ring**: Minor general fixes
+  ([`6775509`](https://github.com/bec-project/bec_widgets/commit/677550931b28fbf35fd55880bf6e001f7351b99b))
+
+- **ring_progress_bar**: Added hover mouse effect
+  ([`96b5179`](https://github.com/bec-project/bec_widgets/commit/96b5179658c41fb39df7a40f4d96e82092605791))
+
+### Testing
+
+- **ring_progress_bar**: Add unit tests for hover behavior
+  ([`6e5f6e7`](https://github.com/bec-project/bec_widgets/commit/6e5f6e7fbb6f9680f6d026e105e6840d24c6591c))
+
+
 ## v3.4.0 (2026-03-26)
 
 ### Bug Fixes

bec_widgets/widgets/containers/main_window/addons/hover_widget.py

@@ -1,27 +1,83 @@
 import sys
 
+from qtpy import QtGui, QtWidgets
 from qtpy.QtCore import QPoint, Qt
-from qtpy.QtWidgets import QApplication, QHBoxLayout, QLabel, QProgressBar, QVBoxLayout, QWidget
+from qtpy.QtWidgets import (
+    QApplication,
+    QFrame,
+    QHBoxLayout,
+    QLabel,
+    QProgressBar,
+    QVBoxLayout,
+    QWidget,
+)
 
 
 class WidgetTooltip(QWidget):
     """Frameless, always-on-top window that behaves like a tooltip."""
 
     def __init__(self, content: QWidget) -> None:
-        super().__init__(None, Qt.ToolTip | Qt.FramelessWindowHint | Qt.WindowStaysOnTopHint)
-        self.setAttribute(Qt.WA_ShowWithoutActivating)
+        super().__init__(
+            None,
+            Qt.WindowType.ToolTip
+            | Qt.WindowType.FramelessWindowHint
+            | Qt.WindowType.WindowStaysOnTopHint,
+        )
+        self.setAttribute(Qt.WidgetAttribute.WA_ShowWithoutActivating)
+        self.setAttribute(Qt.WidgetAttribute.WA_TranslucentBackground)
         self.setMouseTracking(True)
         self.content = content
 
         layout = QVBoxLayout(self)
-        layout.setContentsMargins(6, 6, 6, 6)
-        layout.addWidget(self.content)
+        layout.setContentsMargins(14, 14, 14, 14)
+
+        self._card = QFrame(self)
+        self._card.setObjectName("WidgetTooltipCard")
+        card_layout = QVBoxLayout(self._card)
+        card_layout.setContentsMargins(12, 10, 12, 10)
+        card_layout.addWidget(self.content)
+
+        shadow = QtWidgets.QGraphicsDropShadowEffect(self._card)
+        shadow.setBlurRadius(18)
+        shadow.setOffset(0, 2)
+        shadow.setColor(QtGui.QColor(0, 0, 0, 140))
+        self._card.setGraphicsEffect(shadow)
+
+        layout.addWidget(self._card)
+        self.apply_theme()
         self.adjustSize()
 
     def leaveEvent(self, _event) -> None:
         self.hide()
 
+    def apply_theme(self) -> None:
+        palette = QApplication.palette()
+        base = palette.color(QtGui.QPalette.ColorRole.Base)
+        text = palette.color(QtGui.QPalette.ColorRole.Text)
+        border = palette.color(QtGui.QPalette.ColorRole.Mid)
+        background = QtGui.QColor(base)
+        background.setAlpha(242)
+        self._card.setStyleSheet(f"""
+            QFrame#WidgetTooltipCard {{
+                background: {background.name(QtGui.QColor.NameFormat.HexArgb)};
+                border: 1px solid {border.name()};
+                border-radius: 12px;
+            }}
+            QFrame#WidgetTooltipCard QLabel {{
+                color: {text.name()};
+                background: transparent;
+            }}
+            """)
+
     def show_above(self, global_pos: QPoint, offset: int = 8) -> None:
+        """
+        Show the tooltip above a global position, adjusting to stay within screen bounds.
+
+        Args:
+            global_pos(QPoint): The global position to show above.
+            offset(int, optional): The vertical offset from the global position. Defaults to 8 pixels.
+        """
+        self.apply_theme()
         self.adjustSize()
         screen = QApplication.screenAt(global_pos) or QApplication.primaryScreen()
         screen_geo = screen.availableGeometry()
@@ -30,11 +86,43 @@ class WidgetTooltip(QWidget):
         x = global_pos.x() - geom.width() // 2
         y = global_pos.y() - geom.height() - offset
 
+        self._navigate_screen_coordinates(screen_geo, geom, x, y)
+
+    def show_near(self, global_pos: QPoint, offset: QPoint | None = None) -> None:
+        """
+        Show the tooltip near a global position, adjusting to stay within screen bounds.
+        By default, it will try to show below and to the right of the position,
+        but if that would cause it to go off-screen, it will flip to the other side.
+
+        Args:
+            global_pos(QPoint): The global position to show near.
+            offset(QPoint, optional): The offset from the global position. Defaults to QPoint(12, 16).
+        """
+
+        self.apply_theme()
+        self.adjustSize()
+        offset = offset or QPoint(12, 16)
+        screen = QApplication.screenAt(global_pos) or QApplication.primaryScreen()
+        screen_geo = screen.availableGeometry()
+        geom = self.geometry()
+
+        x = global_pos.x() + offset.x()
+        y = global_pos.y() + offset.y()
+
+        if x + geom.width() > screen_geo.right():
+            x = global_pos.x() - geom.width() - abs(offset.x())
+        if y + geom.height() > screen_geo.bottom():
+            y = global_pos.y() - geom.height() - abs(offset.y())
+
+        self._navigate_screen_coordinates(screen_geo, geom, x, y)
+
+    def _navigate_screen_coordinates(self, screen_geo, geom, x, y):
         x = max(screen_geo.left(), min(x, screen_geo.right() - geom.width()))
         y = max(screen_geo.top(), min(y, screen_geo.bottom() - geom.height()))
 
         self.move(x, y)
         self.show()
+        self.raise_()
 
 
 class HoverWidget(QWidget):

bec_widgets/widgets/progress/ring_progress_bar/ring.py

@@ -9,7 +9,8 @@ from qtpy import QtCore, QtGui
 from qtpy.QtGui import QColor
 from qtpy.QtWidgets import QWidget
 
-from bec_widgets.utils.bec_connector import BECConnector, ConnectionConfig
+from bec_widgets import BECWidget
+from bec_widgets.utils.bec_connector import ConnectionConfig
 from bec_widgets.utils.colors import Colors
 from bec_widgets.utils.error_popups import SafeProperty, SafeSlot
 
@@ -40,7 +41,7 @@ class ProgressbarConfig(ConnectionConfig):
     line_width: int = Field(20, description="Line widths for the progress bars.")
     start_position: int = Field(
         90,
-        description="Start position for the progress bars in degrees. Default is 90 degrees - corespons to "
+        description="Start position for the progress bars in degrees. Default is 90 degrees - corresponds to "
         "the top of the ring.",
     )
     min_value: int | float = Field(0, description="Minimum value for the progress bars.")
@@ -59,7 +60,7 @@ class ProgressbarConfig(ConnectionConfig):
     )
 
 
-class Ring(BECConnector, QWidget):
+class Ring(BECWidget, QWidget):
     USER_ACCESS = [
         "set_value",
         "set_color",
@@ -82,8 +83,26 @@ class Ring(BECConnector, QWidget):
         self.registered_slot: tuple[Callable, str | EndpointInfo] | None = None
         self.RID = None
         self._gap = 5
+        self._hovered = False
+        self._hover_progress = 0.0
+        self._hover_animation = QtCore.QPropertyAnimation(self, b"hover_progress", parent=self)
+        self._hover_animation.setDuration(180)
+        easing_curve = (
+            QtCore.QEasingCurve.Type.OutCubic
+            if hasattr(QtCore.QEasingCurve, "Type")
+            else QtCore.QEasingCurve.Type.OutCubic
+        )
+        self._hover_animation.setEasingCurve(easing_curve)
         self.set_start_angle(self.config.start_position)
 
+    def _request_update(self, *, refresh_tooltip: bool = True):
+        # NOTE why not just overwrite update() to always refresh the tooltip?
+        # Because in some cases (e.g. hover animation) we want to update the widget without refreshing the tooltip, to avoid performance issues.
+        if refresh_tooltip:
+            if self.progress_container and self.progress_container.is_ring_hovered(self):
+                self.progress_container.refresh_hover_tooltip(self)
+        self.update()
+
     def set_value(self, value: int | float):
         """
         Set the value for the ring widget
@@ -107,7 +126,7 @@ class Ring(BECConnector, QWidget):
         if self.config.link_colors:
             self._auto_set_background_color()
 
-        self.update()
+        self._request_update()
 
     def set_background(self, color: str | tuple | QColor):
         """
@@ -122,7 +141,7 @@ class Ring(BECConnector, QWidget):
 
         self._background_color = self.convert_color(color)
         self.config.background_color = self._background_color.name()
-        self.update()
+        self._request_update()
 
     def _auto_set_background_color(self):
         """
@@ -133,7 +152,7 @@ class Ring(BECConnector, QWidget):
         bg_color = Colors.subtle_background_color(self._color, bg)
         self.config.background_color = bg_color.name()
         self._background_color = bg_color
-        self.update()
+        self._request_update()
 
     def set_colors_linked(self, linked: bool):
         """
@@ -146,7 +165,7 @@ class Ring(BECConnector, QWidget):
         self.config.link_colors = linked
         if linked:
             self._auto_set_background_color()
-        self.update()
+        self._request_update()
 
     def set_line_width(self, width: int):
         """
@@ -156,7 +175,7 @@ class Ring(BECConnector, QWidget):
             width(int): Line width for the ring widget
         """
         self.config.line_width = width
-        self.update()
+        self._request_update()
 
     def set_min_max_values(self, min_value: int | float, max_value: int | float):
         """
@@ -168,7 +187,7 @@ class Ring(BECConnector, QWidget):
         """
         self.config.min_value = min_value
         self.config.max_value = max_value
-        self.update()
+        self._request_update()
 
     def set_start_angle(self, start_angle: int):
         """
@@ -178,7 +197,7 @@ class Ring(BECConnector, QWidget):
             start_angle(int): Start angle for the ring widget in degrees
         """
         self.config.start_position = start_angle
-        self.update()
+        self._request_update()
 
     def set_update(
         self, mode: Literal["manual", "scan", "device"], device: str = "", signal: str = ""
@@ -237,7 +256,7 @@ class Ring(BECConnector, QWidget):
             precision(int): Precision for the ring widget
         """
         self.config.precision = precision
-        self.update()
+        self._request_update()
 
     def set_direction(self, direction: int):
         """
@@ -247,7 +266,7 @@ class Ring(BECConnector, QWidget):
             direction(int): Direction for the ring widget. -1 for clockwise, 1 for counter-clockwise.
         """
         self.config.direction = direction
-        self.update()
+        self._request_update()
 
     def _get_signals_for_device(self, device: str) -> dict[str, list[str]]:
         """
@@ -424,8 +443,11 @@ class Ring(BECConnector, QWidget):
         rect.adjust(max_ring_size, max_ring_size, -max_ring_size, -max_ring_size)
 
         # Background arc
+        base_line_width = float(self.config.line_width)
+        hover_line_delta = min(3.0, round(base_line_width * 0.6, 1))
+        current_line_width = base_line_width + (hover_line_delta * self._hover_progress)
         painter.setPen(
-            QtGui.QPen(self._background_color, self.config.line_width, QtCore.Qt.PenStyle.SolidLine)
+            QtGui.QPen(self._background_color, current_line_width, QtCore.Qt.PenStyle.SolidLine)
         )
 
         gap: int = self.gap  # type: ignore
@@ -433,13 +455,25 @@ class Ring(BECConnector, QWidget):
         # Important: Qt uses a 16th of a degree for angles. start_position is therefore multiplied by 16.
         start_position: float = self.config.start_position * 16  # type: ignore
 
-        adjusted_rect = QtCore.QRect(
+        adjusted_rect = QtCore.QRectF(
             rect.left() + gap, rect.top() + gap, rect.width() - 2 * gap, rect.height() - 2 * gap
         )
+        if self._hover_progress > 0.0:
+            hover_radius_delta = 4.0
+            base_radius = adjusted_rect.width() / 2
+            if base_radius > 0:
+                target_radius = base_radius + (hover_radius_delta * self._hover_progress)
+                scale = target_radius / base_radius
+                center = adjusted_rect.center()
+                new_width = adjusted_rect.width() * scale
+                new_height = adjusted_rect.height() * scale
+                adjusted_rect = QtCore.QRectF(
+                    center.x() - new_width / 2, center.y() - new_height / 2, new_width, new_height
+                )
         painter.drawArc(adjusted_rect, start_position, 360 * 16)
 
         # Foreground arc
-        pen = QtGui.QPen(self.color, self.config.line_width, QtCore.Qt.PenStyle.SolidLine)
+        pen = QtGui.QPen(self.color, current_line_width, QtCore.Qt.PenStyle.SolidLine)
         pen.setCapStyle(QtCore.Qt.PenCapStyle.RoundCap)
         painter.setPen(pen)
         proportion = (self.config.value - self.config.min_value) / (
@@ -449,7 +483,17 @@ class Ring(BECConnector, QWidget):
         painter.drawArc(adjusted_rect, start_position, angle)
         painter.end()
 
-    def convert_color(self, color: str | tuple | QColor) -> QColor:
+    def set_hovered(self, hovered: bool):
+        if hovered == self._hovered:
+            return
+        self._hovered = hovered
+        self._hover_animation.stop()
+        self._hover_animation.setStartValue(self._hover_progress)
+        self._hover_animation.setEndValue(1.0 if hovered else 0.0)
+        self._hover_animation.start()
+
+    @staticmethod
+    def convert_color(color: str | tuple | QColor) -> QColor:
         """
         Convert the color to QColor
 
@@ -485,7 +529,7 @@ class Ring(BECConnector, QWidget):
     @gap.setter
     def gap(self, value: int):
         self._gap = value
-        self.update()
+        self._request_update()
 
     @SafeProperty(bool)
     def link_colors(self) -> bool:
@@ -522,7 +566,7 @@ class Ring(BECConnector, QWidget):
             float(max(self.config.min_value, min(self.config.max_value, value))),
             self.config.precision,
         )
-        self.update()
+        self._request_update()
 
     @SafeProperty(float)
     def min_value(self) -> float:
@@ -531,7 +575,7 @@ class Ring(BECConnector, QWidget):
     @min_value.setter
     def min_value(self, value: float):
         self.config.min_value = value
-        self.update()
+        self._request_update()
 
     @SafeProperty(float)
     def max_value(self) -> float:
@@ -540,7 +584,7 @@ class Ring(BECConnector, QWidget):
     @max_value.setter
     def max_value(self, value: float):
         self.config.max_value = value
-        self.update()
+        self._request_update()
 
     @SafeProperty(str)
     def mode(self) -> str:
@@ -549,6 +593,7 @@ class Ring(BECConnector, QWidget):
     @mode.setter
     def mode(self, value: str):
         self.set_update(value)
+        self._request_update()
 
     @SafeProperty(str)
     def device(self) -> str:
@@ -557,6 +602,7 @@ class Ring(BECConnector, QWidget):
     @device.setter
     def device(self, value: str):
         self.config.device = value
+        self._request_update()
 
     @SafeProperty(str)
     def signal(self) -> str:
@@ -565,6 +611,7 @@ class Ring(BECConnector, QWidget):
     @signal.setter
     def signal(self, value: str):
         self.config.signal = value
+        self._request_update()
 
     @SafeProperty(int)
     def line_width(self) -> int:
@@ -573,7 +620,7 @@ class Ring(BECConnector, QWidget):
     @line_width.setter
     def line_width(self, value: int):
         self.config.line_width = value
-        self.update()
+        self._request_update()
 
     @SafeProperty(int)
     def start_position(self) -> int:
@@ -582,7 +629,7 @@ class Ring(BECConnector, QWidget):
     @start_position.setter
     def start_position(self, value: int):
         self.config.start_position = value
-        self.update()
+        self._request_update()
 
     @SafeProperty(int)
     def precision(self) -> int:
@@ -591,7 +638,7 @@ class Ring(BECConnector, QWidget):
     @precision.setter
     def precision(self, value: int):
         self.config.precision = value
-        self.update()
+        self._request_update()
 
     @SafeProperty(int)
     def direction(self) -> int:
@@ -600,7 +647,27 @@ class Ring(BECConnector, QWidget):
     @direction.setter
     def direction(self, value: int):
         self.config.direction = value
-        self.update()
+        self._request_update()
+
+    @SafeProperty(float)
+    def hover_progress(self) -> float:
+        return self._hover_progress
+
+    @hover_progress.setter
+    def hover_progress(self, value: float):
+        self._hover_progress = value
+        self._request_update(refresh_tooltip=False)
+
+    def cleanup(self):
+        """
+        Cleanup the ring widget.
+        Disconnect any registered slots.
+        """
+        if self.registered_slot is not None:
+            self.bec_dispatcher.disconnect_slot(*self.registered_slot)
+            self.registered_slot = None
+        self._hover_animation.stop()
+        super().cleanup()
 
 
 if __name__ == "__main__":  # pragma: no cover

bec_widgets/widgets/progress/ring_progress_bar/ring_progress_bar.py

@@ -3,7 +3,7 @@ from typing import Literal
 
 import pyqtgraph as pg
 from bec_lib.logger import bec_logger
-from qtpy.QtCore import QSize, Qt
+from qtpy.QtCore import QPointF, QSize, Qt
 from qtpy.QtWidgets import QHBoxLayout, QLabel, QVBoxLayout, QWidget
 
 from bec_widgets.utils import Colors
@@ -12,6 +12,7 @@ from bec_widgets.utils.error_popups import SafeProperty
 from bec_widgets.utils.settings_dialog import SettingsDialog
 from bec_widgets.utils.toolbars.actions import MaterialIconAction
 from bec_widgets.utils.toolbars.toolbar import ModularToolBar
+from bec_widgets.widgets.containers.main_window.addons.hover_widget import WidgetTooltip
 from bec_widgets.widgets.progress.ring_progress_bar.ring import Ring
 from bec_widgets.widgets.progress.ring_progress_bar.ring_progress_settings_cards import RingSettings
 
@@ -29,7 +30,16 @@ class RingProgressContainerWidget(QWidget):
         self.rings: list[Ring] = []
         self.gap = 20  # Gap between rings
         self.color_map: str = "turbo"
+        self._hovered_ring: Ring | None = None
+        self._last_hover_global_pos = None
+        self._hover_tooltip_label = QLabel()
+        self._hover_tooltip_label.setWordWrap(True)
+        self._hover_tooltip_label.setTextFormat(Qt.TextFormat.PlainText)
+        self._hover_tooltip_label.setMaximumWidth(260)
+        self._hover_tooltip_label.setStyleSheet("font-size: 12px;")
+        self._hover_tooltip = WidgetTooltip(self._hover_tooltip_label)
         self.setLayout(QHBoxLayout())
+        self.setMouseTracking(True)
         self.initialize_bars()
         self.initialize_center_label()
 
@@ -59,6 +69,7 @@ class RingProgressContainerWidget(QWidget):
         """
         ring = Ring(parent=self)
         ring.setGeometry(self.rect())
+        ring.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents, True)
         ring.gap = self.gap * len(self.rings)
         ring.set_value(0)
         self.rings.append(ring)
@@ -88,6 +99,10 @@ class RingProgressContainerWidget(QWidget):
             index = self.num_bars - 1
         index = self._validate_index(index)
         ring = self.rings[index]
+        if ring is self._hovered_ring:
+            self._hovered_ring = None
+            self._last_hover_global_pos = None
+            self._hover_tooltip.hide()
         ring.cleanup()
         ring.close()
         ring.deleteLater()
@@ -106,6 +121,7 @@ class RingProgressContainerWidget(QWidget):
 
         self.center_label = QLabel("", parent=self)
         self.center_label.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.center_label.setAttribute(Qt.WidgetAttribute.WA_TransparentForMouseEvents, True)
         layout.addWidget(self.center_label)
 
     def _calculate_minimum_size(self):
@@ -150,6 +166,130 @@ class RingProgressContainerWidget(QWidget):
         for ring in self.rings:
             ring.setGeometry(self.rect())
 
+    def enterEvent(self, event):
+        self.setMouseTracking(True)
+        super().enterEvent(event)
+
+    def mouseMoveEvent(self, event):
+        pos = event.position() if hasattr(event, "position") else QPointF(event.pos())
+        self._last_hover_global_pos = (
+            event.globalPosition().toPoint()
+            if hasattr(event, "globalPosition")
+            else event.globalPos()
+        )
+        ring = self._ring_at_pos(pos)
+        self._set_hovered_ring(ring, event)
+        super().mouseMoveEvent(event)
+
+    def leaveEvent(self, event):
+        self._last_hover_global_pos = None
+        self._set_hovered_ring(None, event)
+        super().leaveEvent(event)
+
+    def _set_hovered_ring(self, ring: Ring | None, event=None):
+        if ring is self._hovered_ring:
+            if ring is not None:
+                self.refresh_hover_tooltip(ring, event)
+            return
+        if self._hovered_ring is not None:
+            self._hovered_ring.set_hovered(False)
+        self._hovered_ring = ring
+        if self._hovered_ring is not None:
+            self._hovered_ring.set_hovered(True)
+            self.refresh_hover_tooltip(self._hovered_ring, event)
+        else:
+            self._hover_tooltip.hide()
+
+    def _ring_at_pos(self, pos: QPointF) -> Ring | None:
+        if not self.rings:
+            return None
+        size = min(self.width(), self.height())
+        if size <= 0:
+            return None
+        x_offset = (self.width() - size) / 2
+        y_offset = (self.height() - size) / 2
+        center_x = x_offset + size / 2
+        center_y = y_offset + size / 2
+        dx = pos.x() - center_x
+        dy = pos.y() - center_y
+        distance = (dx * dx + dy * dy) ** 0.5
+
+        max_ring_size = self.get_max_ring_size()
+        base_radius = (size - 2 * max_ring_size) / 2
+        if base_radius <= 0:
+            return None
+
+        best_ring: Ring | None = None
+        best_delta: float | None = None
+        for ring in self.rings:
+            radius = base_radius - ring.gap
+            if radius <= 0:
+                continue
+            half_width = ring.config.line_width / 2
+            inner = radius - half_width
+            outer = radius + half_width
+            if inner <= distance <= outer:
+                delta = abs(distance - radius)
+                if best_delta is None or delta < best_delta:
+                    best_delta = delta
+                    best_ring = ring
+
+        return best_ring
+
+    def is_ring_hovered(self, ring: Ring) -> bool:
+        return ring is self._hovered_ring
+
+    def refresh_hover_tooltip(self, ring: Ring, event=None):
+        text = self._build_tooltip_text(ring)
+        if event is not None:
+            self._last_hover_global_pos = (
+                event.globalPosition().toPoint()
+                if hasattr(event, "globalPosition")
+                else event.globalPos()
+            )
+        if self._last_hover_global_pos is None:
+            return
+        self._hover_tooltip_label.setText(text)
+        self._hover_tooltip.apply_theme()
+        self._hover_tooltip.show_near(self._last_hover_global_pos)
+
+    @staticmethod
+    def _build_tooltip_text(ring: Ring) -> str:
+        mode = ring.config.mode
+        mode_label = {"manual": "Manual", "scan": "Scan progress", "device": "Device"}.get(
+            mode, mode
+        )
+
+        precision = int(ring.config.precision)
+        value = ring.config.value
+        min_value = ring.config.min_value
+        max_value = ring.config.max_value
+        range_span = max(max_value - min_value, 1e-9)
+        progress = max(0.0, min(100.0, ((value - min_value) / range_span) * 100))
+
+        lines = [
+            f"Mode: {mode_label}",
+            f"Progress: {value:.{precision}f} / {max_value:.{precision}f} ({progress:.1f}%)",
+        ]
+        if min_value != 0:
+            lines.append(f"Range: {min_value:.{precision}f} -> {max_value:.{precision}f}")
+        if mode == "device" and ring.config.device:
+            if ring.config.signal:
+                lines.append(f"Device: {ring.config.device}:{ring.config.signal}")
+            else:
+                lines.append(f"Device: {ring.config.device}")
+
+        return "\n".join(lines)
+
+    def closeEvent(self, event):
+        # Ensure the hover tooltip is properly cleaned up when this widget closes
+        tooltip = getattr(self, "_hover_tooltip", None)
+        if tooltip is not None:
+            tooltip.close()
+            tooltip.deleteLater()
+            self._hover_tooltip = None
+        super().closeEvent(event)
+
     def set_colors_from_map(self, colormap, color_format: Literal["RGB", "HEX"] = "RGB"):
         """
         Set the colors for the progress bars from a colormap.
@@ -230,6 +370,9 @@ class RingProgressContainerWidget(QWidget):
         """
         Clear all rings from the widget.
         """
+        self._hovered_ring = None
+        self._last_hover_global_pos = None
+        self._hover_tooltip.hide()
         for ring in self.rings:
             ring.close()
             ring.deleteLater()

bec_widgets/widgets/progress/ring_progress_bar/ring_progress_settings_cards.py

@@ -63,7 +63,8 @@ class RingCardWidget(QFrame):
         self.mode_combo.setCurrentText(self._get_display_mode_string(self.ring.config.mode))
         self._set_widget_mode_enabled(self.ring.config.mode)
 
-    def _get_theme_color(self, color_name: str) -> QColor | None:
+    @staticmethod
+    def _get_theme_color(color_name: str) -> QColor | None:
         app = QApplication.instance()
         if not app:
             return
@@ -249,12 +250,13 @@ class RingCardWidget(QFrame):
     def _on_signal_changed(self, signal: str):
         device = self.ui.device_combo_box.currentText()
         signal = self.ui.signal_combo_box.get_signal_name()
-        if not device or device not in self.container.bec_dispatcher.client.device_manager.devices:
+        if not device or device not in self.ring.bec_dispatcher.client.device_manager.devices:
             return
         self.ring.set_update("device", device=device, signal=signal)
         self.ring.config.signal = signal
 
-    def _unify_mode_string(self, mode: str) -> str:
+    @staticmethod
+    def _unify_mode_string(mode: str) -> str:
         """Convert mode string to a unified format"""
         mode = mode.lower()
         if mode == "scan progress":
@@ -263,7 +265,8 @@ class RingCardWidget(QFrame):
             return "device"
         return mode
 
-    def _get_display_mode_string(self, mode: str) -> str:
+    @staticmethod
+    def _get_display_mode_string(mode: str) -> str:
         """Convert mode string to display format"""
         match mode:
             case "manual":

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bec_widgets"
-version = "3.4.0"
+version = "3.4.1"
 description = "BEC Widgets"
 requires-python = ">=3.11"
 classifiers = [

tests/unit_tests/test_ring_progress_bar.py

@@ -1,14 +1,18 @@
 # pylint: disable=missing-function-docstring, missing-module-docstring, unused-import
 
 import json
+from unittest.mock import MagicMock
 
 import pytest
-from bec_lib.endpoints import MessageEndpoints
-from pydantic import ValidationError
-from qtpy.QtGui import QColor
+from qtpy.QtCore import QEvent, QPoint, QPointF, Qt
+from qtpy.QtGui import QColor, QMouseEvent
+from qtpy.QtWidgets import QApplication
 
 from bec_widgets.utils import Colors
-from bec_widgets.widgets.progress.ring_progress_bar.ring_progress_bar import RingProgressBar
+from bec_widgets.widgets.progress.ring_progress_bar.ring_progress_bar import (
+    RingProgressBar,
+    RingProgressContainerWidget,
+)
 
 from .client_mocks import mocked_client
 
@@ -432,8 +436,6 @@ def test_gap_affects_ring_positioning(ring_progress_bar):
     for _ in range(3):
         ring_progress_bar.add_ring()
 
-    initial_gap = ring_progress_bar.gap
-
     # Change gap
     new_gap = 30
     ring_progress_bar.set_gap(new_gap)
@@ -467,3 +469,275 @@ def test_rings_property_returns_correct_list(ring_progress_bar):
     # Should return the same list
     assert rings_via_property is rings_direct
     assert len(rings_via_property) == 3
+
+
+###################################
+# Hover behavior tests
+###################################
+
+
+@pytest.fixture
+def container(qtbot):
+    widget = RingProgressContainerWidget()
+    qtbot.addWidget(widget)
+    widget.resize(200, 200)
+    yield widget
+
+
+def _ring_center_pos(container):
+    """Return (center_x, center_y, base_radius) for a square container."""
+    size = min(container.width(), container.height())
+    center_x = container.width() / 2
+    center_y = container.height() / 2
+    max_ring_size = container.get_max_ring_size()
+    base_radius = (size - 2 * max_ring_size) / 2
+    return center_x, center_y, base_radius
+
+
+def _send_mouse_move(widget, pos: QPoint):
+    global_pos = widget.mapToGlobal(pos)
+    event = QMouseEvent(
+        QEvent.Type.MouseMove,
+        QPointF(pos),
+        QPointF(global_pos),
+        Qt.MouseButton.NoButton,
+        Qt.MouseButton.NoButton,
+        Qt.KeyboardModifier.NoModifier,
+    )
+    QApplication.sendEvent(widget, event)
+
+
+def test_ring_at_pos_no_rings(container):
+    assert container._ring_at_pos(QPointF(100, 100)) is None
+
+
+def test_ring_at_pos_center_is_inside_rings(container):
+    """The center of the widget is inside all rings; _ring_at_pos should return None."""
+    container.add_ring()
+    assert container._ring_at_pos(QPointF(100, 100)) is None
+
+
+def test_ring_at_pos_on_single_ring(container):
+    """A point on the ring arc should resolve to that ring."""
+    ring = container.add_ring()
+    cx, cy, base_radius = _ring_center_pos(container)
+    # Point exactly on the ring centerline
+    pos = QPointF(cx + base_radius, cy)
+    assert container._ring_at_pos(pos) is ring
+
+
+def test_ring_at_pos_outside_all_rings(container):
+    """A point well outside the outermost ring returns None."""
+    container.add_ring()
+    cx, cy, base_radius = _ring_center_pos(container)
+    line_width = container.rings[0].config.line_width
+    # Place point clearly beyond the outer edge
+    pos = QPointF(cx + base_radius + line_width + 5, cy)
+    assert container._ring_at_pos(pos) is None
+
+
+def test_ring_at_pos_selects_correct_ring_from_multiple(qtbot):
+    """With multiple rings, each position resolves to the right ring."""
+    container = RingProgressContainerWidget()
+    qtbot.addWidget(container)
+    container.resize(300, 300)
+
+    ring0 = container.add_ring()
+    ring1 = container.add_ring()
+
+    size = min(container.width(), container.height())
+    cx = container.width() / 2
+    cy = container.height() / 2
+    max_ring_size = container.get_max_ring_size()
+    base_radius = (size - 2 * max_ring_size) / 2
+
+    radius0 = base_radius - ring0.gap
+    radius1 = base_radius - ring1.gap
+
+    assert container._ring_at_pos(QPointF(cx + radius0, cy)) is ring0
+    assert container._ring_at_pos(QPointF(cx + radius1, cy)) is ring1
+
+
+def test_set_hovered_ring_sets_flag(container):
+    """_set_hovered_ring marks the ring as hovered and updates _hovered_ring."""
+    ring = container.add_ring()
+    assert container._hovered_ring is None
+    container._set_hovered_ring(ring)
+    assert container._hovered_ring is ring
+    assert ring._hovered is True
+
+
+def test_set_hovered_ring_to_none_clears_flag(container):
+    """Calling _set_hovered_ring(None) un-hovers the current ring."""
+    ring = container.add_ring()
+    container._set_hovered_ring(ring)
+    container._set_hovered_ring(None)
+    assert container._hovered_ring is None
+    assert ring._hovered is False
+
+
+def test_set_hovered_ring_switches_between_rings(qtbot):
+    """Switching hover from one ring to another correctly updates both flags."""
+    container = RingProgressContainerWidget()
+    qtbot.addWidget(container)
+    ring0 = container.add_ring()
+    ring1 = container.add_ring()
+
+    container._set_hovered_ring(ring0)
+    assert ring0._hovered is True
+    assert ring1._hovered is False
+
+    container._set_hovered_ring(ring1)
+    assert ring0._hovered is False
+    assert ring1._hovered is True
+    assert container._hovered_ring is ring1
+
+
+def test_build_tooltip_text_manual_mode(container):
+    """Manual mode tooltip contains mode label, value, max and percentage."""
+    ring = container.add_ring()
+    ring.set_value(50)
+    ring.set_min_max_values(0, 100)
+
+    text = RingProgressContainerWidget._build_tooltip_text(ring)
+    assert "Manual" in text
+    assert "50.0%" in text
+    assert "100" in text
+
+
+def test_build_tooltip_text_scan_mode(container):
+    """Scan mode tooltip labels the mode as 'Scan progress'."""
+    ring = container.add_ring()
+    ring.config.mode = "scan"
+    ring.set_value(25)
+
+    text = RingProgressContainerWidget._build_tooltip_text(ring)
+    assert "Scan progress" in text
+
+
+def test_build_tooltip_text_device_mode_with_signal(container):
+    """Device mode tooltip shows device:signal when both are set."""
+    ring = container.add_ring()
+    ring.config.mode = "device"
+    ring.config.device = "samx"
+    ring.config.signal = "readback"
+    ring.set_value(10)
+
+    text = RingProgressContainerWidget._build_tooltip_text(ring)
+    assert "Device" in text
+    assert "samx:readback" in text
+
+
+def test_build_tooltip_text_device_mode_without_signal(container):
+    """Device mode tooltip shows only device name when signal is absent."""
+    ring = container.add_ring()
+    ring.config.mode = "device"
+    ring.config.device = "samy"
+    ring.config.signal = None
+    ring.set_value(10)
+
+    text = RingProgressContainerWidget._build_tooltip_text(ring)
+    assert "samy" in text
+    assert ":" not in text.split("Device:")[-1].split("\n")[0]
+
+
+def test_build_tooltip_text_nonzero_min_shows_range(container):
+    """Tooltip includes Range line when min_value is not 0."""
+    ring = container.add_ring()
+    ring.set_min_max_values(10, 90)
+    ring.set_value(50)
+
+    text = RingProgressContainerWidget._build_tooltip_text(ring)
+    assert "Range" in text
+
+
+def test_build_tooltip_text_zero_min_no_range(container):
+    """Tooltip omits Range line when min_value is 0."""
+    ring = container.add_ring()
+    ring.set_min_max_values(0, 100)
+    ring.set_value(50)
+
+    text = RingProgressContainerWidget._build_tooltip_text(ring)
+    assert "Range" not in text
+
+
+def test_refresh_hover_tooltip_updates_label_on_value_change(container):
+    """refresh_hover_tooltip updates the label text after the ring value changes."""
+    ring = container.add_ring()
+    ring.set_value(30)
+    container._hovered_ring = ring
+    container._last_hover_global_pos = QPoint(100, 100)
+
+    container.refresh_hover_tooltip(ring)
+    text_before = container._hover_tooltip_label.text()
+
+    ring.set_value(70)
+    container.refresh_hover_tooltip(ring)
+    text_after = container._hover_tooltip_label.text()
+
+    assert text_before != text_after
+    assert "70" in text_after
+
+
+def test_refresh_hover_tooltip_no_pos_does_not_crash(container):
+    """refresh_hover_tooltip with no stored position should return without raising."""
+    ring = container.add_ring()
+    container._last_hover_global_pos = None
+    # Should not raise
+    container.refresh_hover_tooltip(ring)
+
+
+def test_mouse_move_sets_hovered_ring_and_updates_tooltip(qtbot, container):
+    ring = container.add_ring()
+    container._hover_tooltip.show_near = MagicMock()
+    container.show()
+    qtbot.waitExposed(container)
+
+    cx, cy, base_radius = _ring_center_pos(container)
+    _send_mouse_move(container, QPoint(int(cx + base_radius), int(cy)))
+
+    assert container._hovered_ring is ring
+    assert ring._hovered is True
+    assert "Mode: Manual" in container._hover_tooltip_label.text()
+    container._hover_tooltip.show_near.assert_called_once()
+
+
+def test_mouse_move_switches_hover_between_rings(qtbot):
+    container = RingProgressContainerWidget()
+    qtbot.addWidget(container)
+    container.resize(300, 300)
+    ring0 = container.add_ring()
+    ring1 = container.add_ring()
+    container._hover_tooltip.show_near = MagicMock()
+    container.show()
+    qtbot.waitExposed(container)
+
+    cx, cy, base_radius = _ring_center_pos(container)
+    radius0 = base_radius - ring0.gap
+    radius1 = base_radius - ring1.gap
+    _send_mouse_move(container, QPoint(int(cx + radius0), int(cy)))
+
+    assert container._hovered_ring is ring0
+
+    _send_mouse_move(container, QPoint(int(cx + radius1), int(cy)))
+
+    assert container._hovered_ring is ring1
+    assert ring0._hovered is False
+    assert ring1._hovered is True
+
+
+def test_leave_event_clears_hover_and_hides_tooltip(qtbot, container):
+    ring = container.add_ring()
+    container._hover_tooltip.hide = MagicMock()
+    container.show()
+    qtbot.waitExposed(container)
+
+    cx, cy, base_radius = _ring_center_pos(container)
+    _send_mouse_move(container, QPoint(int(cx + base_radius), int(cy)))
+
+    QApplication.sendEvent(container, QEvent(QEvent.Type.Leave))
+
+    assert container._hovered_ring is None
+    assert ring._hovered is False
+    assert container._last_hover_global_pos is None
+    container._hover_tooltip.hide.assert_called()

tests/unit_tests/test_ring_progress_bar_ring.py

@@ -240,6 +240,36 @@ def test_set_start_angle(ring_widget):
     assert ring_widget.config.start_position == 180
 
 
+def test_set_hovered_updates_animation_target(ring_widget):
+    ring_widget.set_hovered(True)
+
+    assert ring_widget._hovered is True
+    assert ring_widget._hover_animation.endValue() == 1.0
+
+    ring_widget.set_hovered(False)
+
+    assert ring_widget._hovered is False
+    assert ring_widget._hover_animation.endValue() == 0.0
+
+
+def test_refresh_hover_tooltip_delegates_to_container(ring_widget):
+    ring_widget.progress_container = MagicMock()
+    ring_widget.progress_container.is_ring_hovered.return_value = True
+
+    ring_widget._request_update()
+
+    ring_widget.progress_container.refresh_hover_tooltip.assert_called_once_with(ring_widget)
+
+
+def test_refresh_hover_tooltip_skips_when_ring_is_not_hovered(ring_widget):
+    ring_widget.progress_container = MagicMock()
+    ring_widget.progress_container.is_ring_hovered.return_value = False
+
+    ring_widget._request_update()
+
+    ring_widget.progress_container.refresh_hover_tooltip.assert_not_called()
+
+
 ###################################
 # Color management tests
 ###################################