bec-widgets 0.61.0__py3-none-any.whl → 0.63.0__py3-none-any.whl

CHANGELOG.md

@@ -2,6 +2,42 @@
 
 
 
+## v0.63.0 (2024-06-13)
+
+### Documentation
+
+* docs: add documentation ([`bc709c4`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/bc709c4184c985d4e721f9ea7d1b3dad5e9153a7))
+
+### Feature
+
+* feat: add textbox widget ([`d9d4e3c`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/d9d4e3c9bf73ab2a5629c2867b50fc91e69489ec))
+
+### Refactor
+
+* refactor: add pydantic config, add change_theme ([`6b8432f`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/6b8432f5b20a71175a3537b5f6832b76e3b67d73))
+
+### Test
+
+* test: add test for text box ([`b49462a`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/b49462abeb186e56bac79d2ef0b0add1ef28a1a5))
+
+### Unknown
+
+* Revert "feat: implement non-polling, interruptible waiting of gui instruction response with timeout"
+
+This reverts commit abc6caa2d0b6141dfbe1f3d025f78ae14deddcb3 ([`fe04dd8`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/fe04dd80e59a0e74f7fdea603e0642707ecc7c2a))
+
+
+## v0.62.0 (2024-06-12)
+
+### Feature
+
+* feat: implement non-polling, interruptible waiting of gui instruction response with timeout ([`abc6caa`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/abc6caa2d0b6141dfbe1f3d025f78ae14deddcb3))
+
+### Unknown
+
+* doc: add documentation about creating custom GUI applications embedding BEC Widgets ([`17a0068`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/17a00687579f5efab1990cd83862ec0e78198633))
+
+
 ## v0.61.0 (2024-06-12)
 
 ### Feature
@@ -131,33 +167,3 @@
 
 
 ## v0.57.5 (2024-06-06)
-
-### Documentation
-
-* docs(figure): docs adjusted to be compatible with new signature ([`c037b87`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/c037b87675af91b26e8c7c60e76622d4ed4cf5d5))
-
-### Fix
-
-* fix(waveform): added .plot method with the same signature as BECFigure.plot ([`8479caf`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/8479caf53a7325788ca264e5bd9aee01f1d4c5a0))
-
-* fix(plot_base): .plot removed from plot_base.py, because there is no use case for it ([`82e2c89`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/82e2c898d2e26f786b2d481f85c647472675e75b))
-
-### Refactor
-
-* refactor(figure): logic for .add_image and .image consolidated; logic for .add_plot and .plot consolidated ([`52bc322`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/52bc322b2b8d3ef92ff3480e61bddaf32464f976))
-
-
-## v0.57.4 (2024-06-06)
-
-### Fix
-
-* fix(docks): set_title do update dock internal _name now ([`15cbc21`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/15cbc21e5bb3cf85f5822d44a2b3665b5aa2f346))
-
-* fix(docks): docks widget_list adn dockarea panels return values fixed ([`ffae5ee`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/ffae5ee54e6b43da660131092452adff195ba4fb))
-
-
-## v0.57.3 (2024-06-06)
-
-### Documentation
-
-* docs(bar): docs updated ([`4be0d14`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/4be0d14b7445c2322c2aef86257db168a841265c))

PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bec_widgets
-Version: 0.61.0
+Version: 0.63.0
 Summary: BEC Widgets
 Project-URL: Bug Tracker, https://gitlab.psi.ch/bec/bec_widgets/issues
 Project-URL: Homepage, https://gitlab.psi.ch/bec/bec_widgets

bec_widgets/cli/client.py

@@ -17,6 +17,7 @@ class Widgets(str, enum.Enum):
     BECDockArea = "BECDockArea"
     BECFigure = "BECFigure"
     SpiralProgressBar = "SpiralProgressBar"
+    TextBox = "TextBox"
     WebsiteWidget = "WebsiteWidget"
 
 
@@ -1897,6 +1898,48 @@ class SpiralProgressBar(RPCBase):
         """
 
 
+class StopButton(RPCBase):
+    @property
+    @rpc_call
+    def config_dict(self) -> "dict":
+        """
+        Get the configuration of the widget.
+
+        Returns:
+            dict: The configuration of the widget.
+        """
+
+    @rpc_call
+    def get_all_rpc(self) -> "dict":
+        """
+        Get all registered RPC objects.
+        """
+
+
+class TextBox(RPCBase):
+    @rpc_call
+    def set_color(self, background_color: str, font_color: str) -> None:
+        """
+        Set the background color of the Widget.
+
+        Args:
+            background_color (str): The color to set the background in HEX.
+            font_color (str): The color to set the font in HEX.
+        """
+
+    @rpc_call
+    def set_text(self, text: str) -> None:
+        """
+        Set the text of the Widget
+        """
+
+    @rpc_call
+    def set_font_size(self, size: int) -> None:
+        """
+        Set the font size of the text in the Widget.
+        """
+
+
 class WebsiteWidget(RPCBase):
     @rpc_call
     def set_url(self, url: str) -> None:

bec_widgets/cli/rpc_wigdet_handler.py

@@ -1,6 +1,7 @@
 from bec_widgets.utils import BECConnector
 from bec_widgets.widgets.figure import BECFigure
 from bec_widgets.widgets.spiral_progress_bar.spiral_progress_bar import SpiralProgressBar
+from bec_widgets.widgets.text_box.text_box import TextBox
 from bec_widgets.widgets.website.website import WebsiteWidget
 
 
@@ -11,6 +12,7 @@ class RPCWidgetHandler:
         "BECFigure": BECFigure,
         "SpiralProgressBar": SpiralProgressBar,
         "Website": WebsiteWidget,
+        "TextBox": TextBox,
     }
 
     @staticmethod

bec_widgets/widgets/text_box/text_box.py

@@ -0,0 +1,127 @@
+import re
+
+from pydantic import Field, field_validator
+from qtpy.QtWidgets import QTextEdit
+
+from bec_widgets.utils.bec_connector import BECConnector, ConnectionConfig
+from bec_widgets.utils.colors import Colors
+
+
+class TextBoxConfig(ConnectionConfig):
+
+    theme: str = Field("dark", description="The theme of the figure widget.")
+    font_color: str = Field("#FFF", description="The font color of the text")
+    background_color: str = Field("#000", description="The background color of the widget.")
+    font_size: int = Field(16, description="The font size of the text in the widget.")
+    text: str = Field("", description="The text to display in the widget.")
+
+    @classmethod
+    @field_validator("theme")
+    def validate_theme(cls, v):
+        """Validate the theme of the figure widget."""
+        if v not in ["dark", "light"]:
+            raise ValueError("Theme must be either 'dark' or 'light'")
+        return v
+
+    _validate_font_color = field_validator("font_color")(Colors.validate_color)
+    _validate_background_color = field_validator("background_color")(Colors.validate_color)
+
+
+class TextBox(BECConnector, QTextEdit):
+
+    USER_ACCESS = ["set_color", "set_text", "set_font_size"]
+
+    def __init__(self, text: str = "", parent=None, client=None, config=None, gui_id=None):
+        if config is None:
+            config = TextBoxConfig(widget_class=self.__class__.__name__)
+        else:
+            if isinstance(config, dict):
+                config = TextBoxConfig(**config)
+            self.config = config
+        super().__init__(client=client, config=config, gui_id=gui_id)
+        QTextEdit.__init__(self, parent=parent)
+
+        self.config = config
+        self.setReadOnly(True)
+        self.setGeometry(self.rect())
+        self.set_color(self.config.background_color, self.config.font_color)
+        if not text:
+            text = "<h1>Welcome to the BEC Widget TextBox</h1><p>A widget that allows user to display text in plain and HTML format.</p><p>This is an example of displaying HTML text.</p>"
+        self.set_text(text)
+
+    def change_theme(self) -> None:
+        """
+        Change the theme of the figure widget.
+        """
+        if self.config.theme == "dark":
+            theme = "light"
+            font_color = "#000"
+            background_color = "#FFF"
+        else:
+            theme = "dark"
+            font_color = "#FFF"
+            background_color = "#000"
+        self.config.theme = theme
+        self.set_color(background_color, font_color)
+
+    def set_color(self, background_color: str, font_color: str) -> None:
+        """Set the background color of the widget.
+
+        Args:
+            background_color (str): The color to set the background in HEX.
+            font_color (str): The color to set the font in HEX.
+
+        """
+        self.config.background_color = background_color
+        self.config.font_color = font_color
+        self._update_stylesheet()
+
+    def set_font_size(self, size: int) -> None:
+        """Set the font size of the text in the widget.
+
+        Args:
+            size (int): The font size to set.
+        """
+        self.config.font_size = size
+        self._update_stylesheet()
+
+    def _update_stylesheet(self):
+        """Update the stylesheet of the widget."""
+        self.setStyleSheet(
+            f"background-color: {self.config.background_color}; color: {self.config.font_color}; font-size: {self.config.font_size}px"
+        )
+
+    def set_text(self, text: str) -> None:
+        """Set the text of the widget.
+
+        Args:
+            text (str): The text to set.
+        """
+        if self.is_html(text):
+            self.setHtml(text)
+        else:
+            self.setPlainText(text)
+        self.config.text = text
+
+    def is_html(self, text: str) -> bool:
+        """Check if the text contains HTML tags.
+
+        Args:
+            text (str): The text to check.
+
+        Returns:
+            bool: True if the text contains HTML tags, False otherwise.
+        """
+        return bool(re.search(r"<[a-zA-Z/][^>]*>", text))
+
+
+if __name__ == "__main__":
+    import sys
+
+    from qtpy.QtWidgets import QApplication
+
+    app = QApplication(sys.argv)
+
+    widget = TextBox()
+    widget.show()
+    sys.exit(app.exec())

{bec_widgets-0.61.0.dist-info → bec_widgets-0.63.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bec_widgets
-Version: 0.61.0
+Version: 0.63.0
 Summary: BEC Widgets
 Project-URL: Bug Tracker, https://gitlab.psi.ch/bec/bec_widgets/issues
 Project-URL: Homepage, https://gitlab.psi.ch/bec/bec_widgets

{bec_widgets-0.61.0.dist-info → bec_widgets-0.63.0.dist-info}/RECORD

@@ -2,11 +2,11 @@
 .gitlab-ci.yml,sha256=3PU2LONUl10zIOD4UCPQgA6vVBtniabww1MQkTMce7I,7995
 .pylintrc,sha256=OstrgmEyP0smNFBKoIN5_26-UmNZgMHnbjvAWX0UrLs,18535
 .readthedocs.yaml,sha256=aSOc277LqXcsTI6lgvm_JY80lMlr69GbPKgivua2cS0,603
-CHANGELOG.md,sha256=M5IR-g_0B-sq_qGAYP4A8BReh6U9HcGKxeAmMGGjPHs,6792
+CHANGELOG.md,sha256=SSIvLIsLoMqELDdBJGpxD-i6mL6yHf9zOfv5Sslx0ZA,6807
 LICENSE,sha256=YRKe85CBRyP7UpEAWwU8_qSIyuy5-l_9C-HKg5Qm8MQ,1511
-PKG-INFO,sha256=nwiL8DuDWzYjWMcR_JGIZL2uTa8UFyC-NfJHBKxSpEI,1302
+PKG-INFO,sha256=7zmXAhyzvbGnDsRQ9BIOv4jDaDOHgaiY6X2dXspqEM4,1302
 README.md,sha256=y4jB6wvArS7N8_iTbKWnSM_oRAqLA2GqgzUR-FMh5sU,2645
-pyproject.toml,sha256=itvsOSpNTbXMXrClzMA00l9i7ATGsAqrSifK5IB2u5I,2115
+pyproject.toml,sha256=sZcekDO1IZEFkY_FiioZBTW4i6p__x-iQpMLbVq_rqk,2115
 .git_hooks/pre-commit,sha256=n3RofIZHJl8zfJJIUomcMyYGFi_rwq4CC19z0snz3FI,286
 .gitlab/issue_templates/bug_report_template.md,sha256=gAuyEwl7XlnebBrkiJ9AqffSNOywmr8vygUFWKTuQeI,386
 .gitlab/issue_templates/documentation_update_template.md,sha256=FHLdb3TS_D9aL4CYZCjyXSulbaW5mrN2CmwTaeLPbNw,860
@@ -17,11 +17,11 @@ bec_widgets/assets/bec_widgets_icon.png,sha256=K8dgGwIjalDh9PRHUsSQBqgdX7a00nM3i
 bec_widgets/assets/terminal_icon.png,sha256=bJl7Tft4Fi2uxvuXI8o14uMHnI9eAWKSU2uftXCH9ws,3889
 bec_widgets/cli/__init__.py,sha256=d0Q6Fn44e7wFfLabDOBxpcJ1DPKWlFunGYDUBmO-4hA,22
 bec_widgets/cli/auto_updates.py,sha256=DyBV3HnjMSH-cvVkYNcDiYKVf0Xut4Qy2qGQqkW47Bw,4833
-bec_widgets/cli/client.py,sha256=6mzmRe_pjuz-3CoBJZkxaa05VzAmPLi_cDJ3uljmw8Y,54363
+bec_widgets/cli/client.py,sha256=PkKPeR4KJjJP-DOPTq3yYJIuWlwXLHjTyZunCYSsU1I,55332
 bec_widgets/cli/client_utils.py,sha256=7u8P9EYgLPJuAcHxnFiZi-gCZohO3vAn0W7dqsSrs4M,10660
 bec_widgets/cli/generate_cli.py,sha256=DIaGz7nhwef3ebIaP4LtiUC3q7MoM1swJ_e0SgAO2jo,6901
 bec_widgets/cli/rpc_register.py,sha256=QxXUZu5XNg00Yf5O3UHWOXg3-f_pzKjjoZYMOa-MOJc,2216
-bec_widgets/cli/rpc_wigdet_handler.py,sha256=VRLujiICU_Gq0mO1Hr15YwjlxU7OcAzqeoM8QHqSubM,1032
+bec_widgets/cli/rpc_wigdet_handler.py,sha256=1oE2TSbwQdfLEaZiscyDX2eExHsenp2BF5Lwy8PE6LA,1118
 bec_widgets/cli/server.py,sha256=rsj31Vsx6ayThNe4PQelQFahGjYXFZjfrNyB2fnm6Ro,5737
 bec_widgets/examples/__init__.py,sha256=WWQ0cu7m8sA4Ehy-DWdTIqSISjaHsbxhsNmNrMnhDZU,202
 bec_widgets/examples/jupyter_console/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -87,6 +87,8 @@ bec_widgets/widgets/scan_control/scan_control.py,sha256=B5n2U2iVtTCY3Tx93JyBqzGC
 bec_widgets/widgets/spiral_progress_bar/__init__.py,sha256=4efbtcqCToMIw5bkQrTzy2TzuBCXvlhuUPh1bYC_Yzg,51
 bec_widgets/widgets/spiral_progress_bar/ring.py,sha256=7i5oKpW8eUQGvLyKce2-2rlaGDVLec__DoWp6hfJlRw,10524
 bec_widgets/widgets/spiral_progress_bar/spiral_progress_bar.py,sha256=cMi4g7zNTLrkkzZ9ChiIBTaqigDCYwzrgA2iRmq9dUI,24050
+bec_widgets/widgets/text_box/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bec_widgets/widgets/text_box/text_box.py,sha256=kykQ_Zcxh8IGcPEP5-oGGQwoZEpY9vhxRIM8TY8kTYg,4240
 bec_widgets/widgets/toolbar/__init__.py,sha256=d-TP4_cr_VbpwreMM4ePnfZ5YXsEPQ45ibEf75nuGoE,36
 bec_widgets/widgets/toolbar/toolbar.py,sha256=e0zCD_0q7K4NVhrzD8001Qvfxt-VhqHTgofchS9NgCM,5125
 bec_widgets/widgets/website/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -109,7 +111,7 @@ docs/assets/index_user_guide.svg,sha256=sRjKwOHVJStBYIQUFVcnfmbeXd2qAp0HYjleSp66
 docs/assets/rocket_launch_48dp.svg,sha256=pdrPrBcKWUa5OlgWKM0B6TA6qAW7E57d7C7YW2r1OT8,1070
 docs/developer/developer.md,sha256=7Z6sfkk_7BgwZ2vaX4z5_cJrs0miyeAYSGpqMbyBmOI,415
 docs/introduction/introduction.md,sha256=wp7jmhkUtJnSnEnmIAZGUcau_3-5e5-FohvZb63khw4,1432
-docs/user/customisation.md,sha256=Og0NuUsTs8HdwKtpHnycGmH8wCqOeYgj2ozlYRJ-Drk,249
+docs/user/customisation.md,sha256=MXqbljqokDXF3VhCeia1PITZe1mx1J3FfLTJ66TlaUA,3172
 docs/user/user.md,sha256=uCTcjclIi6rdjYRQebko6bWFEVsjyfshsVU3BDYrC-Y,1403
 docs/user/api_reference/api_reference.md,sha256=q2Imc48Rq6GcAP0R4bS3KuW5ptZZdsV4wxGJb3JJQHg,174
 docs/user/applications/applications.md,sha256=yOECfaYRUEDIxF-O0duOwSJlG4f93RylrpMjbw1-8Dg,100
@@ -127,9 +129,10 @@ docs/user/widgets/motor.gif,sha256=FtaWdRHx4UZaGJPpq8LNhMMgX4PFcAB6IZ93JCMEh_w,2
 docs/user/widgets/progress_bar.gif,sha256=5jh0Zw2BBGPuNxszV1DBLJCb4_6glIRX-U2ABjnsK2k,5263592
 docs/user/widgets/scatter_2D.gif,sha256=yHpsuAUseMafJjI_J5BcOhmE3nu9VFn_Xm9XHzJaH5I,13188862
 docs/user/widgets/spiral_progress_bar.md,sha256=QTgUDIl6XPuK_HwSfB6sNijZ4bss26biDg6B_mJ8Pxk,2208
+docs/user/widgets/text_box.md,sha256=i40AxKJP0PxrYW0x0up1VIovPFvemsaZoosGjOn4iZE,931
 docs/user/widgets/w1D.gif,sha256=tuHbleJpl6bJFNNC2OdndF5LF7IyfvlkFCMGZajrQPs,622773
 docs/user/widgets/website.md,sha256=wfudAupdtHX-Sfritg0xMWXZLLczJ4XwMLNWvu6ww-w,705
-docs/user/widgets/widgets.md,sha256=EfrElcZVh9jHt_0kIXdDtc7z3ErYGqwmVMxC_AHSGU0,370
+docs/user/widgets/widgets.md,sha256=NzRfrgd4LWmZHa2Cs_1G59LeY5uAlFdy5aP00AtGAjk,380
 tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/end-2-end/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/end-2-end/conftest.py,sha256=taLqiYVzOhJjMre5ypgQjB7wzSXP4soKANW3XfAjems,1773
@@ -154,6 +157,7 @@ tests/unit_tests/test_rpc_register.py,sha256=hECjZEimd440mwRrO0rg7L3PKN7__3DgjmE
 tests/unit_tests/test_scan_control.py,sha256=7dtGpE0g4FqUhhQeCkyJl-9o7NH3DFZJgEaqDmBYbBc,7551
 tests/unit_tests/test_spiral_progress_bar.py,sha256=yak3N9-TmEM3lQZPSROL4cAx9mior__se1XADlMScks,12418
 tests/unit_tests/test_stop_button.py,sha256=hOoWO0emkvd5bR_EExxCnKsiZgXKqf_uIGTwzWLxhDw,704
+tests/unit_tests/test_text_box_widget.py,sha256=cT0uEHt_6d-FwST0A_wE9sFW9E3F_nJbKhuBAeU4yHg,1862
 tests/unit_tests/test_waveform1d.py,sha256=j9-CCE0BkFVI3Gnv8pjV1gc9HwA5PYG0_ox1oZ60F6w,15272
 tests/unit_tests/test_website_widget.py,sha256=fBADIJJBAHU4Ro7u95kdemFVNv196UOcuO9oLHuHt8A,761
 tests/unit_tests/test_widget_io.py,sha256=FeL3ZYSBQnRt6jxj8VGYw1cmcicRQyHKleahw7XIyR0,3475
@@ -163,8 +167,8 @@ tests/unit_tests/test_configs/config_device_no_entry.yaml,sha256=hdvue9KLc_kfNzG
 tests/unit_tests/test_configs/config_scan.yaml,sha256=vo484BbWOjA_e-h6bTjSV9k7QaQHrlAvx-z8wtY-P4E,1915
 tests/unit_tests/test_msgs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tests/unit_tests/test_msgs/available_scans_message.py,sha256=m_z97hIrjHXXMa2Ex-UvsPmTxOYXfjxyJaGkIY6StTY,46532
-bec_widgets-0.61.0.dist-info/METADATA,sha256=nwiL8DuDWzYjWMcR_JGIZL2uTa8UFyC-NfJHBKxSpEI,1302
-bec_widgets-0.61.0.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
-bec_widgets-0.61.0.dist-info/entry_points.txt,sha256=80s2YKCNziN2ROUYbpDRyEmiejMf_dshmiYCdN7qNsU,70
-bec_widgets-0.61.0.dist-info/licenses/LICENSE,sha256=YRKe85CBRyP7UpEAWwU8_qSIyuy5-l_9C-HKg5Qm8MQ,1511
-bec_widgets-0.61.0.dist-info/RECORD,,
+bec_widgets-0.63.0.dist-info/METADATA,sha256=7zmXAhyzvbGnDsRQ9BIOv4jDaDOHgaiY6X2dXspqEM4,1302
+bec_widgets-0.63.0.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
+bec_widgets-0.63.0.dist-info/entry_points.txt,sha256=80s2YKCNziN2ROUYbpDRyEmiejMf_dshmiYCdN7qNsU,70
+bec_widgets-0.63.0.dist-info/licenses/LICENSE,sha256=YRKe85CBRyP7UpEAWwU8_qSIyuy5-l_9C-HKg5Qm8MQ,1511
+bec_widgets-0.63.0.dist-info/RECORD,,

docs/user/customisation.md

@@ -1,8 +1,118 @@
 (user.customisation)=
 # Customisation
 
-BEC Widgets are designed to be used with QtDesigner to quicly design GUI.
+## Leveraging BEC Widgets in custom GUI applications
 
+BEC Widgets can be used to compose a complete Qt graphical application, along with
+other QWidgets. The only requirement is to connect to BEC servers in order to get
+data, or to interact with BEC components. This role is devoted to the BECDispatcher,
+a singleton object which has to be instantiated **after the QApplication is created**.
+
+A typical BEC Widgets custom application "main" entry point should follow the template
+below: 
+
+```
+import argparse
+import sys
+
+from bec_widgets.utils.bec_dispatcher import BECDispatcher
+from qtpy.QtWidgets import QApplication
+
+# optional command line arguments processing
+parser = argparse.ArgumentParser(description="...")
+parser.add_argument( ...)
+...
+args = parser.parse_args()
+
+# creation of the Qt application
+app = QApplication([])
+
+# creation of BEC Dispatcher
+# /!\ important: after the QApplication has been instantiated
+bec_dispatcher = BECDispatcher()
+client = bec_dispatcher.client
+client.start()
+
+# (optional) processing of command line args,
+# creation of a main window depending on the command line arguments (or not)
+if args.xxx == "...":
+    window = ...
+ 
+# display of the main window and start of Qt event loop
+window.show()
+sys.exit(app.exec())
+```
+
+The main "window" object presents the layout of widgets to the user and allows
+users to interact. BEC Widgets must be placed in the window:
+
+```
+from qtpy.QWidgets import QMainWindow
+from bec_widgets.widgets import BECFigure
+
+window = QMainWindow()
+bec_figure = BECFigure(gui_id="my_gui_app_id")
+window.setCentralWidget(bec_figure)
+
+# prepare to plot samx motor vs bpm4i value
+bec_figure.plot(x_name="samx", y_name="bpm4i")
+```
+
+In the example just above, the resulting application will show a plot of samx
+positions on the horizontal axis, and beam intensity on the vertical axis
+(when the next scan will be started).
+
+It is important to ensure proper cleanup of the resources is done when application
+quits:
+
+```
+def final_cleanup():
+    bec_figure.clear_all()
+    bec_figure.client.shutdown()
+
+window.aboutToQuit.connect(final_cleanup)
+```
+
+Final example:
+
+```
+import sys
+from qtpy.QtWidgets import QMainWindow, QApplication
+from bec_widgets.widgets import BECFigure
+from bec_widgets.utils.bec_dispatcher import BECDispatcher
+
+# creation of the Qt application
+app = QApplication([])
+
+# creation of BEC Dispatcher
+bec_dispatcher = BECDispatcher()
+client = bec_dispatcher.client
+client.start()
+
+# creation of main window
+window = QMainWindow()
+
+# inserting BEC Widgets
+bec_figure = BECFigure(parent=window, gui_id="my_gui_app_id")
+window.setCentralWidget(bec_figure)
+
+bec_figure.plot(x_name="samx", y_name="bpm4i")
+
+# ensuring proper cleanup
+def final_cleanup():
+    bec_figure.clear_all()
+    bec_figure.client.shutdown()
+
+app.aboutToQuit.connect(final_cleanup)
+
+# execution
+window.show()
+sys.exit(app.exec())
+```
+
+## Writing applications using Qt Designer
+
+BEC Widgets are designed to be used with QtDesigner to quickly design GUI.
 
 ## Example of promoting widgets in Qt Designer
 

docs/user/widgets/text_box.md

@@ -0,0 +1,33 @@
+(user.widgets.text_box)=
+# [Text Box Widget](/api_reference/_autosummary/bec_widgets.cli.client.TextBoxWidget)
+**Purpose:**
+
+The Text Box Widget is a widget that allows you to display text within the BEC GUI. The widget can be used to display plain text or HTML text.
+
+**Key Features:**
+
+- set the text to display.
+- automatically detects if the text is plain text or HTML text.
+- set background color and font color.
+
+**Code example:**
+
+The following code snipped demonstrates how to create a `TextBox` widget using BEC Widgets within BEC.
+```python
+text_box = gui.add_dock().add_widget("TextBox")
+# set the text to display
+text_box.set_text("Hello, World!")
+# set the background color and font color
+text_box.set_color(backgroud_color="#FFF", font_color="#000")
+# set the text to display as HTML
+text_box.set_text("<h1>Welcome to BEC Widgets</h1><p>This is an example of displaying <strong>HTML</strong> text.</p>")
+```
+
+
+
+
+
+
+
+
+

docs/user/widgets/widgets.md

@@ -12,6 +12,7 @@ bec_figure/
 spiral_progress_bar/
 website/
 buttons/
+text_box/
 ```
 
 

pyproject.toml

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

tests/unit_tests/test_text_box_widget.py

@@ -0,0 +1,55 @@
+import re
+from unittest import mock
+
+import pytest
+
+from bec_widgets.widgets.text_box.text_box import TextBox
+
+from .client_mocks import mocked_client
+
+
+@pytest.fixture
+def text_box_widget(qtbot, mocked_client):
+    widget = TextBox(client=mocked_client)
+    qtbot.addWidget(widget)
+    qtbot.waitExposed(widget)
+    yield widget
+    widget.close()
+
+
+def test_textbox_widget(text_box_widget):
+    """Test the TextBox widget."""
+    text = "Hello World!"
+    text_box_widget.set_text(text)
+    assert text_box_widget.toPlainText() == text
+
+    text_box_widget.set_color("#FFDDC1", "#123456")
+    text_box_widget.set_font_size(20)
+    assert (
+        text_box_widget.styleSheet() == "background-color: #FFDDC1; color: #123456; font-size: 20px"
+    )
+    text_box_widget.set_color("white", "blue")
+    text_box_widget.set_font_size(14)
+    assert text_box_widget.styleSheet() == "background-color: white; color: blue; font-size: 14px"
+    text = "<h1>Welcome to PyQt6</h1><p>This is an example of displaying <strong>HTML</strong> text.</p>"
+    with mock.patch.object(text_box_widget, "setHtml") as mocked_set_html:
+        text_box_widget.set_text(text)
+        assert mocked_set_html.call_count == 1
+        assert mocked_set_html.call_args == mock.call(text)
+
+
+def test_textbox_change_theme(text_box_widget):
+    """Test change theme functionaility"""
+    # Default is dark theme
+    text_box_widget.change_theme()
+    assert text_box_widget.config.theme == "light"
+    assert (
+        text_box_widget.styleSheet()
+        == f"background-color: #FFF; color: #000; font-size: {text_box_widget.config.font_size}px"
+    )
+    text_box_widget.change_theme()
+    assert text_box_widget.config.theme == "dark"
+    assert (
+        text_box_widget.styleSheet()
+        == f"background-color: #000; color: #FFF; font-size: {text_box_widget.config.font_size}px"
+    )