From 99d5e8e71c7f89a53d7967126f4056dde005534c Mon Sep 17 00:00:00 2001 From: wakonig_k Date: Sat, 31 Aug 2024 21:42:08 +0200 Subject: [PATCH] docs(becwidget): improvements to the bec widget base class docs; fixed type hint import for sphinx --- bec_widgets/qt_utils/toolbar.py | 2 ++ bec_widgets/utils/bec_widget.py | 19 ++++++++++++- .../dark_mode_button/dark_mode_button.py | 2 ++ .../widget_development/widget_base_class.md | 27 +++++++++++++++++-- 4 files changed, 47 insertions(+), 3 deletions(-) diff --git a/bec_widgets/qt_utils/toolbar.py b/bec_widgets/qt_utils/toolbar.py index a7fd142b..91d25d19 100644 --- a/bec_widgets/qt_utils/toolbar.py +++ b/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 diff --git a/bec_widgets/utils/bec_widget.py b/bec_widgets/utils/bec_widget.py index d4f18cba..91bb7018 100644 --- a/bec_widgets/utils/bec_widget.py +++ b/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. diff --git a/bec_widgets/widgets/dark_mode_button/dark_mode_button.py b/bec_widgets/widgets/dark_mode_button/dark_mode_button.py index 40601248..91529d1f 100644 --- a/bec_widgets/widgets/dark_mode_button/dark_mode_button.py +++ b/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 diff --git a/docs/developer/widget_development/widget_base_class.md b/docs/developer/widget_development/widget_base_class.md index 5a8211e2..b4b9fc3a 100644 --- a/docs/developer/widget_development/widget_base_class.md +++ b/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`