docs(becwidget): improvements to the bec widget base class docs; fixed type hint import for sphinx

bec_widgets/qt_utils/toolbar.py

@@ -1,4 +1,6 @@
 # pylint: disable=no-name-in-module
+from __future__ import annotations
+
 import os
 from abc import ABC, abstractmethod
 from collections import defaultdict

bec_widgets/utils/bec_widget.py

@@ -21,6 +21,23 @@ class BECWidget(BECConnector):
         gui_id: str = None,
         theme_update: bool = False,
     ):
+        """
+        Base class for all BEC widgets. This class should be used as a mixin class for all BEC widgets, e.g.:
+
+
+        >>> class MyWidget(BECWidget, QWidget):
+        >>>     def __init__(self, parent=None, client=None, config=None, gui_id=None):
+        >>>         super().__init__(client=client, config=config, gui_id=gui_id)
+        >>>         QWidget.__init__(self, parent=parent)
+
+
+        Args:
+            client(BECClient, optional): The BEC client.
+            config(ConnectionConfig, optional): The connection configuration.
+            gui_id(str, optional): The GUI ID.
+            theme_update(bool, optional): Whether to subscribe to theme updates. Defaults to False. When set to True, the
+                widget's apply_theme method will be called when the theme changes.
+        """
         if not isinstance(self, QWidget):
             raise RuntimeError(f"{repr(self)} is not a subclass of QWidget")
         super().__init__(client, config, gui_id)
@@ -52,7 +69,7 @@ class BECWidget(BECConnector):
     @Slot(str)
     def apply_theme(self, theme: str):
         """
-        Apply the theme to the plot widget.
+        Apply the theme to the widget.
 
         Args:
             theme(str, optional): The theme to be applied.

bec_widgets/widgets/dark_mode_button/dark_mode_button.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from bec_qthemes import material_icon
 from qtpy.QtCore import Property, Qt, Slot
 from qtpy.QtWidgets import QApplication, QHBoxLayout, QPushButton, QToolButton, QWidget

docs/developer/widget_development/widget_base_class.md

@@ -39,6 +39,10 @@ integrated with the BEC system by providing:
    from the `BECIPythonClient` via CLI, providing powerful control and automation capabilities. For example, you can
    remotely adjust widget settings, start/stop operations, or query the widget’s status directly from the command line.
 
+5. **Reacting to Theme Changes**: The base class provides a dedicated input flag to subscribe to theme changes, allowing
+   your widget to adapt its appearance based on the current theme (e.g., light or dark mode) and can even synchronize with the user's OS settings. The widget-specific logic can then 
+   be implemented in the `apply_theme` method, which is called whenever the theme changes. This ensures a consistent user experience across different themes and environments. 
+
 Here’s a basic example of a widget inheriting
 from [`BECWidget`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api_reference/_autosummary/bec_widgets.utils.bec_widget.BECWidget.html#bec_widgets.utils.bec_widget.BECWidget):
 
@@ -46,10 +50,9 @@ from [`BECWidget`](https://bec.readthedocs.io/projects/bec-widgets/en/latest/api
 from bec_widgets.utils.bec_widget import BECWidget
 from qtpy.QtWidgets import QWidget, QVBoxLayout
 
-
 class MyWidget(BECWidget, QWidget):
     def __init__(self, parent=None, *args, **kwargs):
-        super().__init__(*args, **kwargs)
+        super().__init__(*args, **kwargs) # disable theme updates
         QWidget.__init__(self, parent=parent)
         self.get_bec_shortcuts()  # Initialize BEC shortcuts
         self.init_ui()
@@ -58,6 +61,26 @@ class MyWidget(BECWidget, QWidget):
         layout = QVBoxLayout(self)
         # Add more UI components here
         self.setLayout(layout)
+
+
+# To enable theme updates, set theme_update=True, e.g.:
+
+class MyDynamicWidget(BECWidget, QWidget):
+    def __init__(self, parent=None, *args, **kwargs):
+        super().__init__(*args, theme_update=True, **kwargs) # enable theme updates
+        QWidget.__init__(self, parent=parent)
+        self.get_bec_shortcuts()  # Initialize BEC shortcuts
+        self.init_ui()
+
+    def init_ui(self):
+        layout = QVBoxLayout(self)
+        # Add more UI components here
+        self.setLayout(layout)
+
+    def apply_theme(self, theme):
+         # Implement theme-specific logic here
+         pass
+
 ```
 
 ### The Role of `BECConnector`