bec-widgets 0.57.2__py3-none-any.whl → 0.57.3__py3-none-any.whl

CHANGELOG.md

@@ -2,6 +2,29 @@
 
 
 
+## v0.57.3 (2024-06-06)
+
+### Documentation
+
+* docs(bar): docs updated ([`4be0d14`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/4be0d14b7445c2322c2aef86257db168a841265c))
+
+* docs: fixed syntax of add_widget ([`a951ebf`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/a951ebf1be6c086d094aa8abef5e0dfd1b3b8558))
+
+* docs: added auto update; closes #206 ([`32da803`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/32da803df9f7259842c43e85ba9a0ce29a266d06))
+
+* docs: cleanup ([`07d60cf`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/07d60cf7355d2edadb3c5ef8b86607d74b360455))
+
+### Fix
+
+* fix(ring): automatic updates are disabled uf user specify updates manually with .set_update; 'scan_progres' do not reset number of rings ([`e883dba`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/e883dbad814dbcc0a19c341041c6d836e58a5918))
+
+* fix(ring): enable_auto_updates(True) do not reset properties of already setup bars ([`a2abad3`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/a2abad344f4c0039516eb60a825afb6822c5b19a))
+
+* fix(ring): set_min_max accepts floats ([`d44b1cf`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/d44b1cf8b107cf02deedd9154b77d01c7f9ed05d))
+
+* fix(ring): set_update changed to Literals, no need to specify endpoint manually ([`c5b6499`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/c5b6499e41eb1495bf260436ca3e1b036182c360))
+
+
 ## v0.57.2 (2024-06-06)
 
 ### Fix
@@ -136,32 +159,3 @@
 ### Fix
 
 * fix: removed apparently unnecessary sleep while waiting for an rpc response ([`7d64cac`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/7d64cac6610b39d3553ff650354f78ead8ee6b55))
-
-
-## v0.53.2 (2024-05-15)
-
-### Ci
-
-* ci: added echo to highlight the current branch ([`0490e80`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/0490e80c48563e4fb486bce903b3ce1f08863e83))
-
-### Fix
-
-* fix: check device class without importing to speed up initial import time ([`9f8fbdd`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/9f8fbdd5fc13cf2be10eacb41e10cf742864cd92))
-
-* fix: speed up initial import times using lazy import (from bec_lib) ([`d1e6cd3`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/d1e6cd388c6c9f345f52d6096d8a75a1fa7e6934))
-
-* fix: adapt to bec_lib changes (no more submodules in `__init__.py`) ([`5d09a13`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/5d09a13d8820a8bdb900733c97593b723a2fce1d))
-
-
-## v0.53.1 (2024-05-09)
-
-### Ci
-
-* ci: fixed rtd pages url ([`8ff3610`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/8ff36105d1e637c429915b4bfc2852d54a3c6f19))
-
-### Fix
-
-* fix: docs config ([`0f6a5e5`](https://gitlab.psi.ch/bec/bec_widgets/-/commit/0f6a5e5fa9530969c98a9266c9ca7b89a378ff70))
-
-
-## v0.53.0 (2024-05-09)

PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bec_widgets
-Version: 0.57.2
+Version: 0.57.3
 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

@@ -1890,7 +1890,7 @@ class Ring(RPCBase):
         """
 
     @rpc_call
-    def set_min_max_values(self, min_value: "int", max_value: "int"):
+    def set_min_max_values(self, min_value: "int | float", max_value: "int | float"):
         """
         None
         """
@@ -1902,9 +1902,13 @@ class Ring(RPCBase):
         """
 
     @rpc_call
-    def set_connections(self, slot: "str", endpoint: "str | EndpointInfo"):
+    def set_update(self, mode: "Literal['manual', 'scan', 'device']", device: "str" = None):
         """
-        None
+        Set the update mode for the ring widget
+
+        Args:
+            mode(str): Update mode for the ring widget. Can be "manual", "scan" or "device"
+            device(str): Device name for the device readback mode, only used when mode is "device"
         """
 
     @rpc_call

bec_widgets/widgets/spiral_progress_bar/ring.py

@@ -49,7 +49,7 @@ class RingConfig(ConnectionConfig):
         description="Background color for the progress bars. Can be tuple (R, G, B, A) or string HEX Code.",
     )
     index: int | None = Field(0, description="Index of the progress bar. 0 is outer ring.")
-    line_width: int | None = Field(5, description="Line widths for the progress bars.")
+    line_width: int | None = Field(10, description="Line widths for the progress bars.")
     start_position: int | None = Field(
         90,
         description="Start position for the progress bars in degrees. Default is 90 degrees - corespons to "
@@ -77,7 +77,7 @@ class Ring(BECConnector):
         "set_line_width",
         "set_min_max_values",
         "set_start_angle",
-        "set_connections",
+        "set_update",
         "reset_connection",
     ]
 
@@ -130,7 +130,7 @@ class Ring(BECConnector):
     def set_line_width(self, width: int):
         self.config.line_width = width
 
-    def set_min_max_values(self, min_value: int, max_value: int):
+    def set_min_max_values(self, min_value: int | float, max_value: int | float):
         self.config.min_value = min_value
         self.config.max_value = max_value
 
@@ -147,6 +147,27 @@ class Ring(BECConnector):
             converted_color = QtGui.QColor(*color)
         return converted_color
 
+    def set_update(self, mode: Literal["manual", "scan", "device"], device: str = None):
+        """
+        Set the update mode for the ring widget
+
+        Args:
+            mode(str): Update mode for the ring widget. Can be "manual", "scan" or "device"
+            device(str): Device name for the device readback mode, only used when mode is "device"
+        """
+        if mode == "manual":
+            self.bec_dispatcher.disconnect_slot(
+                getattr(self, self.config.connections.slot), self.config.connections.endpoint
+            )
+            self.config.connections.slot = None
+            self.config.connections.endpoint = None
+        elif mode == "scan":
+            self.set_connections("on_scan_progress", "scans/scan_progress")
+        elif mode == "device":
+            self.set_connections("on_device_readback", f"internal/devices/readback/{device}")
+
+        self.parent_progress_widget.enable_auto_updates(False)
+
     def set_connections(self, slot: str, endpoint: str | EndpointInfo):
         if self.config.connections.endpoint == endpoint and self.config.connections.slot == slot:
             return

bec_widgets/widgets/spiral_progress_bar/spiral_progress_bar.py

@@ -23,7 +23,7 @@ class SpiralProgressBarConfig(ConnectionConfig):
         10, description="Maximum number of progress bars to display."
     )
     num_bars: int | None = Field(1, description="Number of progress bars to display.")
-    gap: int | None = Field(10, description="Gap between progress bars.")
+    gap: int | None = Field(20, description="Gap between progress bars.")
     auto_updates: bool | None = Field(
         True, description="Enable or disable updates based on scan queue status."
     )
@@ -118,7 +118,7 @@ class SpiralProgressBar(BECConnector, QWidget):
 
         # For updating bar behaviour
         self._auto_updates = True
-        self._rings = []
+        self._rings = None
 
         if num_bars is not None:
             self.config.num_bars = max(
@@ -186,13 +186,22 @@ class SpiralProgressBar(BECConnector, QWidget):
             Ring: Ring object.
         """
         if self.config.num_bars < self.config.max_number_of_bars:
-            ring = Ring(parent_progress_widget=self, **kwargs)
-            ring.config.index = self.config.num_bars
+            ring_index = self.config.num_bars
+            ring_config = RingConfig(
+                widget_class="Ring",
+                index=ring_index,
+                start_positions=90 * 16,
+                directions=-1,
+                **kwargs,
+            )
+            ring = Ring(parent_progress_widget=self, config=ring_config)
             self.config.num_bars += 1
             self._rings.append(ring)
             self.config.rings.append(ring.config)
             if self.config.color_map:
                 self.set_colors_from_map(self.config.color_map)
+            base_line_width = self._rings[ring.config.index].config.line_width
+            self.set_line_widths(base_line_width, ring.config.index)
             self.update()
             return ring
 
@@ -211,6 +220,7 @@ class SpiralProgressBar(BECConnector, QWidget):
         self._reindex_rings()
         if self.config.color_map:
             self.set_colors_from_map(self.config.color_map)
+        del ring
         self.update()
 
     def _reindex_rings(self):
@@ -269,9 +279,30 @@ class SpiralProgressBar(BECConnector, QWidget):
         num_bars = max(
             self.config.min_number_of_bars, min(num_bars, self.config.max_number_of_bars)
         )
-        if num_bars != self.config.num_bars:
-            self.config.num_bars = num_bars
-            self.initialize_bars()
+        current_num_bars = self.config.num_bars
+
+        if num_bars > current_num_bars:
+            for i in range(current_num_bars, num_bars):
+                new_ring_config = RingConfig(
+                    widget_class="Ring", index=i, start_positions=90 * 16, directions=-1
+                )
+                self.config.rings.append(new_ring_config)
+                new_ring = Ring(parent_progress_widget=self, config=new_ring_config)
+                self._rings.append(new_ring)
+
+        elif num_bars < current_num_bars:
+            for i in range(current_num_bars - 1, num_bars - 1, -1):
+                self.remove_ring(i)
+
+        self.config.num_bars = num_bars
+
+        if self.config.color_map:
+            self.set_colors_from_map(self.config.color_map)
+
+        base_line_width = self._rings[0].config.line_width
+        self.set_line_widths(base_line_width)
+
+        self.update()
 
     def set_value(self, values: int | list, ring_index: int = None):
         """
@@ -443,8 +474,6 @@ class SpiralProgressBar(BECConnector, QWidget):
                 if report_instructions:
                     instruction_type = list(report_instructions[0].keys())[0]
                     if instruction_type == "scan_progress":
-                        if self.config.num_bars != 1:
-                            self.set_number_of_bars(1)
                         self._hook_scan_progress(ring_index=0)
                     elif instruction_type == "readback":
                         devices = report_instructions[0].get("readback").get("devices")

{bec_widgets-0.57.2.dist-info → bec_widgets-0.57.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bec_widgets
-Version: 0.57.2
+Version: 0.57.3
 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.57.2.dist-info → bec_widgets-0.57.3.dist-info}/RECORD

@@ -2,11 +2,11 @@
 .gitlab-ci.yml,sha256=RF2JeGh8tG09DyAOwEu991IZy3C8Vm6lI8O_4Dr9B9Q,12239
 .pylintrc,sha256=OstrgmEyP0smNFBKoIN5_26-UmNZgMHnbjvAWX0UrLs,18535
 .readthedocs.yaml,sha256=aSOc277LqXcsTI6lgvm_JY80lMlr69GbPKgivua2cS0,603
-CHANGELOG.md,sha256=pG4sxxA4UKrOCZsHzC7nzYA5A7dwla6lFKnMujn04rQ,6889
+CHANGELOG.md,sha256=5H1fQ0fZSKvNRSrVkZJ00ZkSff7DzKmFjg35jPc8vTg,7199
 LICENSE,sha256=YRKe85CBRyP7UpEAWwU8_qSIyuy5-l_9C-HKg5Qm8MQ,1511
-PKG-INFO,sha256=VKjVy_MzeMyq50c2kmwfQ9hoe6abecAZIR6nSJcwVck,1178
+PKG-INFO,sha256=NUwnybNOdIQRdfaJCymSOUpaYxAZhsEK9CIhk0hPz2I,1178
 README.md,sha256=y4jB6wvArS7N8_iTbKWnSM_oRAqLA2GqgzUR-FMh5sU,2645
-pyproject.toml,sha256=mYnyN3JxG1ULTqPhRsHj5xvuD0wUNtZydA6gaSddQSE,1822
+pyproject.toml,sha256=ZLJ-JsjWQsfDxZAyCiSNk5Io50lUBDI-SlY562nGgEw,1822
 .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,7 +17,7 @@ bec_widgets/assets/bec_widgets_icon.png,sha256=K8dgGwIjalDh9PRHUsSQBqgdX7a00nM3i
 bec_widgets/assets/terminal_icon.png,sha256=bJl7Tft4Fi2uxvuXI8o14uMHnI9eAWKSU2uftXCH9ws,3889
 bec_widgets/cli/__init__.py,sha256=tLD8HWgyURhMjYlKZ43pBu-qvGD1LI5o3n3rEieg-70,43
 bec_widgets/cli/auto_updates.py,sha256=8x4_SrD8Hh1RbrUWXLfisw6X5v8Mij2DiTfjvn9dkUw,4692
-bec_widgets/cli/client.py,sha256=DaBkuNB38XhOdNuAmd7UPaEy4kEWCgOdWWfMsPBsWAI,53089
+bec_widgets/cli/client.py,sha256=E6t7gZzM3-YogkKdFz53PIXdHnkWhKyfSwRr2lu2hz0,53363
 bec_widgets/cli/client_utils.py,sha256=7u8P9EYgLPJuAcHxnFiZi-gCZohO3vAn0W7dqsSrs4M,10660
 bec_widgets/cli/generate_cli.py,sha256=tBt-F4Xccg9Pj2zuDEGHd0Ho1fKLfCf3PuSa8KmelQk,4431
 bec_widgets/cli/rpc_register.py,sha256=QxXUZu5XNg00Yf5O3UHWOXg3-f_pzKjjoZYMOa-MOJc,2216
@@ -82,8 +82,8 @@ bec_widgets/widgets/motor_control/selection/selection.ui,sha256=vXXpvNWuL6xyHhW7
 bec_widgets/widgets/scan_control/__init__.py,sha256=IOfHl15vxb_uC6KN62-PeUzbBha_vQyqkkXbJ2HU674,38
 bec_widgets/widgets/scan_control/scan_control.py,sha256=B5n2U2iVtTCY3Tx93JyBqzGCDCmWhWwAOhbPelLI-bs,17168
 bec_widgets/widgets/spiral_progress_bar/__init__.py,sha256=4efbtcqCToMIw5bkQrTzy2TzuBCXvlhuUPh1bYC_Yzg,51
-bec_widgets/widgets/spiral_progress_bar/ring.py,sha256=WlS3L3mSxFQNtc8T_XEPM7IoVeXYnM2SE5ImjvX6kJU,7097
-bec_widgets/widgets/spiral_progress_bar/spiral_progress_bar.py,sha256=AjQsZDEqPlTn0kE4xkYKOj2ae5vJ9gW-k3yz1Y32vsY,22543
+bec_widgets/widgets/spiral_progress_bar/ring.py,sha256=zYz_wq5f-mfI32_melkxyzMbx4RStUU1bpwMp0jm9d4,8057
+bec_widgets/widgets/spiral_progress_bar/spiral_progress_bar.py,sha256=BWhkuVrHUhLWDlpNNhhFfH2cU_tIhB-nhJMH-SLiPyE,23599
 bec_widgets/widgets/toolbar/__init__.py,sha256=d-TP4_cr_VbpwreMM4ePnfZ5YXsEPQ45ibEf75nuGoE,36
 bec_widgets/widgets/toolbar/toolbar.py,sha256=e0zCD_0q7K4NVhrzD8001Qvfxt-VhqHTgofchS9NgCM,5125
 docs/Makefile,sha256=i2WHuFlgfyAPEW4ssEP8NY4cOibDJrVjvzSEU8_Ggwc,634
@@ -108,16 +108,17 @@ docs/user/customisation.md,sha256=Og0NuUsTs8HdwKtpHnycGmH8wCqOeYgj2ozlYRJ-Drk,24
 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
-docs/user/getting_started/command_line_introduction.md,sha256=qTGXnxyRajxv7AXbZaPVVOA5D6zBnK0M0ZF0bniymEM,8683
-docs/user/getting_started/getting_started.md,sha256=zYzoHC8xvHF5wDK66thkdamf8mKKNEudiA-fCOzbedM,358
+docs/user/getting_started/auto_updates.md,sha256=Gicx3lplI6JRBlnPj_VL6IhqOIcsWjYF4_EdZSCje2A,3754
+docs/user/getting_started/getting_started.md,sha256=lxZXCr6HAkM61oo5Bu-YjINSKo4wihWhAPJdotEAAVQ,358
 docs/user/getting_started/gui_complex_gui.gif,sha256=ovv9u371BGG5GqhzyBMl4mvqMHLfJS0ylr-dR0Ydwtw,6550393
 docs/user/getting_started/installation.md,sha256=nBl2Hfvo6ua3-tVZn1B-UG0hCTlrFY6_ibXHWnXeegs,1135
+docs/user/getting_started/quick_start.md,sha256=MNXEaww5hiQY7N7AQhrmbxdYQHimFk_iKQW8tS-72cU,9337
 docs/user/widgets/bec_figure.md,sha256=Ph8ajmESk71Y9nBJsLKLiN-YvGJwN4FdN_Rs3jcObwE,5068
 docs/user/widgets/image_plot.gif,sha256=_mVFhMTXGqwDOcEtrBHMZj5Thn2sLhDAHEeL2XyHN-s,14098977
 docs/user/widgets/motor.gif,sha256=FtaWdRHx4UZaGJPpq8LNhMMgX4PFcAB6IZ93JCMEh_w,2280719
 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=fnkg1cRM9y49MwYVXDukHGu80SXHxsI9mU9ZfDkENPs,1114
+docs/user/widgets/spiral_progress_bar.md,sha256=QTgUDIl6XPuK_HwSfB6sNijZ4bss26biDg6B_mJ8Pxk,2208
 docs/user/widgets/w1D.gif,sha256=tuHbleJpl6bJFNNC2OdndF5LF7IyfvlkFCMGZajrQPs,622773
 docs/user/widgets/widgets.md,sha256=NFdqTlLTHXueErLzvw4wHwTUrzRSEuRelb1fiT4PySg,352
 tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -150,7 +151,7 @@ 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.57.2.dist-info/METADATA,sha256=VKjVy_MzeMyq50c2kmwfQ9hoe6abecAZIR6nSJcwVck,1178
-bec_widgets-0.57.2.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
-bec_widgets-0.57.2.dist-info/licenses/LICENSE,sha256=YRKe85CBRyP7UpEAWwU8_qSIyuy5-l_9C-HKg5Qm8MQ,1511
-bec_widgets-0.57.2.dist-info/RECORD,,
+bec_widgets-0.57.3.dist-info/METADATA,sha256=NUwnybNOdIQRdfaJCymSOUpaYxAZhsEK9CIhk0hPz2I,1178
+bec_widgets-0.57.3.dist-info/WHEEL,sha256=zEMcRr9Kr03x1ozGwg5v9NQBKn3kndp6LSoSlVg-jhU,87
+bec_widgets-0.57.3.dist-info/licenses/LICENSE,sha256=YRKe85CBRyP7UpEAWwU8_qSIyuy5-l_9C-HKg5Qm8MQ,1511
+bec_widgets-0.57.3.dist-info/RECORD,,

docs/user/getting_started/auto_updates.md

@@ -0,0 +1,82 @@
+(user.auto_updates)=
+# Auto updates
+BEC Widgets provides a simple way to update the entire GUI configuration based on events. These events can be of different types, such as a new scan being started or completed, a button being pressed, a device reporting an error or the existence of a specific metadata key. This allows the users to streamline the experience of the GUI and to focus on the data and the analysis, rather than on the GUI itself.
+
+The default auto update only takes control over a single `BECFigure` widget, which is automatically added to the GUI instance. The update instance is accessible via the `bec.gui.auto_updates` object. The user can disable / enable the auto updates by setting the `enabled` attribute of the `bec.gui.auto_updates` object, e.g. 
+
+```python
+bec.gui.auto_updates.enabled = False
+```
+
+Without further customization, the auto update will automatically update the `BECFigure` widget based on the currently performed scan. The behaviour is determined by the `handler` method of the `AutoUpdate` class: 
+
+````{dropdown} Auto Updates Handler
+:icon: code-square
+:animate: fade-in-slide-down
+:open: 
+```{literalinclude} ../../../bec_widgets/cli/auto_updates.py
+:pyobject: AutoUpdates.handler
+```
+````
+
+As shown, the default handler switches between different scan names and updates the `BECFigure` widget accordingly. If the scan is a line scan, the `simple_line_scan` update method is executed. 
+
+````{dropdown} Auto Updates Simple Line Scan
+:icon: code-square
+:animate: fade-in-slide-down
+:open: 
+```{literalinclude} ../../../bec_widgets/cli/auto_updates.py
+:pyobject: AutoUpdates.simple_line_scan
+```
+````
+
+As it can be seen from the above snippet, the update method gets the default figure by calling the `get_default_figure` method. If the figure is not found, maybe because the user has deleted or closed it, no update is performed. If the figure is found, the scan info is used to extract the first reported device for the x axis and the first device of the monitored devices for the y axis. The y axis can also be set by the user using the `selected_device` attribute:
+
+```python
+bec.gui.auto_updates.selected_device = 'bpm4i'
+```
+
+
+````{dropdown} Auto Updates Code
+:icon: code-square
+:animate: fade-in-slide-down
+```{literalinclude} ../../../bec_widgets/cli/auto_updates.py
+```
+````
+
+## Custom Auto Updates
+The beamline can customize their default behaviour through customized auto update classes. This can be achieved by modifying the class located in the beamline plugin repository: `<beamline_plugin>/bec_widgets/auto_updates.py`. The class should inherit from the `AutoUpdates` class and overwrite the `handler` method. 
+
+```python
+from bec_widgets.cli.auto_updates import AutoUpdates, ScanInfo
+
+
+class PlotUpdate(AutoUpdates):
+    create_default_dock = True
+    enabled = True
+
+    # def simple_line_scan(self, info: ScanInfo) -> None:
+    #     """
+    #     Simple line scan.
+    #     """
+    #     fig = self.get_default_figure()
+    #     if not fig:
+    #         return
+    #     dev_x = info.scan_report_devices[0]
+    #     dev_y = self.get_selected_device(info.monitored_devices, self.gui.selected_device)
+    #     if not dev_y:
+    #         return
+    #     fig.clear_all()
+    #     plt = fig.plot(x_name=dev_x, y_name=dev_y)
+    #     plt.set(title=f"Custom Plot {info.scan_number}", x_label=dev_x, y_label=dev_y)
+
+    def handler(self, info: ScanInfo) -> None:
+        # EXAMPLES:
+        # if info.scan_name == "line_scan" and info.scan_report_devices:
+        #     self.simple_line_scan(info)
+        #     return
+        # if info.scan_name == "grid_scan" and info.scan_report_devices:
+        #     self.run_grid_scan_update(info)
+        #     return
+        super().handler(info)
+```

docs/user/getting_started/getting_started.md

@@ -9,5 +9,6 @@ hidden: true
 ---
 
 installation/
-command_line_introduction/
+quick_start/
+auto_updates/
 ```

docs/user/getting_started/{command_line_introduction.md → quick_start.md}

@@ -1,34 +1,53 @@
 (user.command_line_introduction)=
-# Command Line Introduction
-In order to use BEC Widgets as a plotting tool for BEC, it needs to be [installed](#user.installation) in the same python environment as the BECIpythonClient. If that is the case, it will automatically launch a GUI and assign the control of the GUI to the `gui` object in the client. The GUI backend will also be automatically connect to the BEC server, giving access to all information on the server and allowing the user to visualize the data in real-time.
+# Quick start
+In order to use BEC Widgets as a plotting tool for BEC, it needs to be [installed](#user.installation) in the same Python environment as the BEC IPython client (please refer to the [BEC documentation](https://bec.readthedocs.io/en/latest/user/command_line_interface.html#start-up) for more details). Upon startup, the client will automatically launch a GUI and store it as a `bec.gui` object in the client. The GUI backend will also be automatically connect to the BEC server, giving access to all information on the server and allowing the user to visualize the data in real-time.
 
 ## BECDockArea
-The `gui` object represents the top level of hierarchy in BEC Widgets. It is a [`BECDockArea`](/api_reference/_autosummary/bec_widgets.cli.client.BECDockArea) based on the [pyqtgraph.dockarea](https://pyqtgraph.readthedocs.io/en/latest/api_reference/dockarea.html). The GUI can be further composed of multiple [`BECDock`](/api_reference/_autosummary/bec_widgets.cli.client.BECDock)s that can be detached and attached to the main area. These docks allow users to freely arrange and customize the widgets they add to the gui, giving them the necessary freedom to design the user interface they desire.
+The `bec.gui` object is your entry point to BEC Widgets. It is a [`BECDockArea`](/api_reference/_autosummary/bec_widgets.cli.client.BECDockArea) instance that can be composed of multiple [`BECDock`](/api_reference/_autosummary/bec_widgets.cli.client.BECDock)s that can be attached / detached to the main area. These docks allow users to freely arrange and customize the widgets they add to the gui, providing a flexible and customizable interface to visualize data. 
 
 ## Widgets
-Widgets are the building blocks of the BEC Widgets framework. They are the visual components that allow users to interact with the data and control the behavior of the application. Each dock can contain multiple widgets, although we recommend using a direct mapping of a single widget to a dock. We currently support two type of widgets:
-- [`BECFigure`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure): A widget that can be used to visualize data from BEC. It is automatically connected to the BEC server and can be used to plot data from BEC.
-- [`SpiralProgressBar`](/api_reference/_autosummary/bec_widgets.cli.client.SpiralProgressBar): A custom widget that can be used to show progress in a spiral shape.
+Widgets are the building blocks of the BEC Widgets framework. They are the visual components that allow users to interact with the data and control the behavior of the application. Each dock can contain multiple widgets, albeit we recommend for most use cases a single widget per dock. BEC Widgets provides a set of core widgets (cf. [widgets](#user.widgets)). More widgets can be added by the users, and we invite you to explore the [developer documentation](developer.widgets) to learn how to create custom widgets.
+For the introduction given here, we will focus on the `BECFigure` widget, as it is the most commonly used widget for visualizing data from BEC. The same access pattern can be used for all other widgets.
 
 **BECFigure**
-The [`BECFigure`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure) widget is one of the core widgets developed for BEC and designed to be flexible and can be used to visualize different types of data. It can be used to visualize [1D Waveform](user.widgets.waveform_1d), [2D Scatter Plot](user.widgets.scatter_2d), [Motor Position Map](user.widgets.motor_map) and 2D image data. As mentioned before, starting the BECIPythonClient will automatically launch a `gui` with a single dock area and a BECFigure widget attached to it. This widget is accessible via the `fig` object from the client directly. We also provide two methods [`plot()`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.plot), [`image()`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.image) and [`motor_map()`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.motor_map) as shortcuts to add a plot, image or motor map to the BECFigure.
+
+The [`BECFigure`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure) widget is one of the core widgets developed for BEC and can be used to visualize different plot types, such as [1D waveforms](user.widgets.waveform_1d), [2D scatter plots](user.widgets.scatter_2d), [position maps](user.widgets.motor_map) and [2D images](user.widgets.image_2d). 
+If BEC Widgets is installed, the default behaviour of BEC is to automatically add a BECFigure Widget to the existing GUI instance. This widget is directly accessible via the `fig` object from the client. Moreover, a best-effort attempt is made to automatically determine the best plot type based on the currently performed scan. This behaviour can be changed or disabled by the user. For more details, please refer to the [auto update](user.auto_updates) section.
+
+<!-- We also provide two methods [`plot()`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.plot), [`image()`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.image) and [`motor_map()`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.motor_map) as shortcuts to add a plot, image or motor map to the BECFigure. -->
 
 **Waveform Plot** 
+
  The [`BECWaveForm`](/api_reference/_autosummary/bec_widgets.cli.client.BECWaveform) is a widget that can be used to visualize 1D waveform data, i.e. to plot data of a monitor against a motor position. The method [`plot()`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.plot) of BECFigure adds a BECWaveForm widget to the figure, and returns the plot object. 
 
 ```python
-plt = fig.add_plot('samx', 'bpm4i')
+plt = fig.plot(x_name='samx', y_name='bpm4i')
+```
+Here, we create a new plot with a subscription to the devices `samx` and `bpm4i` and assign the plot to the object `plt`. We can now use this object to further customize the plot, e.g. changing the title ([`set_title()`](/api_reference/_autosummary/bec_widgets.cli.client.BECWaveform.rst#bec_widgets.cli.client.BECWaveform.set_title)), axis labels ([`set_x_label()`](/api_reference/_autosummary/bec_widgets.cli.client.BECWaveform.rst#bec_widgets.cli.client.BECWaveform.set_x_label)) or limits ([`set_x_lim()`](/api_reference/_autosummary/bec_widgets.cli.client.BECWaveform.rst#bec_widgets.cli.client.BECWaveform.set_x_lim)). We invite you to explore the API of the BECWaveForm in the [documentation](user.widgets.waveform_1d) or directly in the command line.
+
+To plot custom data, i.e. data that is not directly available through a scan in BEC, we can use the same method, but provide the data directly to the plot. 
+
+```python
+plt = fig.plot([1,2,3,4], [1,4,9,16])
+# or 
+plt = fig.plot(x=[1,2,3,4], y=[1,4,9,16])
+# or 
+plt = fig.plot(x=np.array([1,2,3,4]), y=np.array([1,4,9,16]))
+# or 
+plt = fig.plot(np.random.rand(10,2))
 ```
-Here, we assign the plot to the object `plt`. We can now use this object to further customize the plot, e.g. changing the title ([`set_title()`](/api_reference/_autosummary/bec_widgets.cli.client.BECWaveform.rst#bec_widgets.cli.client.BECWaveform.set_title)), axis labels ([`set_x_label()`](/api_reference/_autosummary/bec_widgets.cli.client.BECWaveform.rst#bec_widgets.cli.client.BECWaveform.set_x_label)) or limits ([`set_x_lim()`](/api_reference/_autosummary/bec_widgets.cli.client.BECWaveform.rst#bec_widgets.cli.client.BECWaveform.set_x_lim)). We invite you to explore the API of the BECWaveForm in the [documentation](user.widgets.waveform_1d) or directly in the command line.
 
 **Scatter Plot**
+
 The [`BECWaveForm`](/api_reference/_autosummary/bec_widgets.cli.client.BECWaveForm) widget can also be used to visualize 2D scatter plots. More details on setting up the scatter plot are available in the widget documentation of the [scatter plot](user.widgets.scatter_2d).
 
 **Motor Map**
+
 The [`BECMotorMap`](/api_reference/_autosummary/bec_widgets.cli.client.BECMotorMap) widget can be used to visualize the position of motors. It's focused on tracking and visualizing the position of motors, crucial for precise alignment and movement tracking during scans. More details on setting up the motor map are available in the widget documentation of the [motor map](user.widgets.motor_map).
 
 **Image Plot**
-The [`BECImageItem`](/api_reference/_autosummary/bec_widgets.cli.client.BECImageItem) widget can be used to visualize 2D image data for example a camera. More details on setting up the image plot are available in the widget documentation of the [image plot](user.widgets.image)
+
+The [`BECImageItem`](/api_reference/_autosummary/bec_widgets.cli.client.BECImageItem) widget can be used to visualize 2D image data for example a camera. More details on setting up the image plot are available in the widget documentation of the [image plot](user.widgets.image).
 
 ### Useful Commands
 We recommend users to explore the API of the widgets by themselves since we assume that the user interface is supposed to be intuitive and self-explanatory. We appreciate feedback from user in order to constantly improve the experience and allow easy access to the gui, widgets and their functionality. We recommend checking the [API documentation](user.api_reference), but also by using BEC Widgets, exploring the available functions and check their dockstrings.
@@ -43,32 +62,32 @@ gui.panels # returns a dictionary of all docks in the gui
 gui.add_dock() # adds a new dock to the gui
 
 dock = gui.panels['dock_2']
-dock.add_widget_bec('BECFigure') # adds a new widget of BECFigure to the dock
+dock.add_widget('BECFigure') # adds a new widget of BECFigure to the dock
 dock.widget_list # returns a list of all widgets in the dock
 
 figure = dock.widget_list[0] # assigns the created BECFigure to figure
-plt = figure.add_plot('samx', 'bpm4i') # adds a BECWaveForm plot to the figure
+plt = figure.plot(x_name='samx', y_name='bpm4i') # adds a BECWaveForm plot to the figure
 plt.curves # returns a list of all curves in the plot
 ```
 
-We note that commands can also be chained. For example, `gui.add_dock().add_widget_bec('BECFigure')` will add a new dock to the gui and add a new widget of `BECFigure` to the dock. 
+We note that commands can also be chained. For example, `gui.add_dock().add_widget('BECFigure')` will add a new dock to the gui and add a new widget of `BECFigure` to the dock. 
 
 ## Composing a larger GUI
 The example given above introduces BEC Widgets with its different components, and provides an overview of how to interact with the widgets. Nevertheless, another power aspect of BEC Widgets lies in the ability to compose a larger GUI with multiple docks and widgets. This section aims to provide a tutorial like guide on how to compose a more complex GUI that (A) live-plots a 1D waveform, (B) plots data from a camera, and (C) tracks the positions of two motors.
 Let's assume BEC was just started and the `gui` object is available in the client. A single dock is already attached together with a BEC Figure. Let's add the 1D waveform to this dock, change the color of the line to white and add the title *1D Waveform* to the plot.
 
 ```python
-plt = fig.add_plot('samx', 'bpm4i')
+plt = fig.plot(x_name='samx', y_name='bpm4i')
 plt.curves[0].set_color(color="white")
 plt.set_title('1D Waveform')
 ```
 
 Next, we add 2 new docks to the gui, one to plot the data of a camera and one to track the positions of two motors. 
 ```ipython
-cam_widget= gui.add_dock(name="cam_dock").add_widget_bec('BECFigure').image("eiger")
-motor_widget = gui.add_dock(name="mot_dock").add_widget_bec('BECFigure').motor_map("samx", "samy")
+cam_widget= gui.add_dock(name="cam_dock").add_widget('BECFigure').image("eiger")
+motor_widget = gui.add_dock(name="mot_dock").add_widget('BECFigure').motor_map("samx", "samy")
 ```
-Note, we chain commands here which is possible since the `add_dock` and `add_widget_bec` methods return the dock and the widget respectively. We can now further customize the widgets by changing the title, axis labels, etc.
+Note, we chain commands here which is possible since the `add_dock` and `add_widget` methods return the dock and the widget respectively. We can now further customize the widgets by changing the title, axis labels, etc.
 
 ```python
 cam_widget.set_title("Camera Image Eiger")
@@ -78,7 +97,7 @@ As a final step, we can now add also a SpiralProgressBar to a new dock, and perf
 As you see in the example below, all docks are arranged below each other. This is the default behavior of the `add_dock` method. However, the docks can be freely arranged by drag and drop as desired by the user. We invite you to explore this by yourself following the example in the video, and build your custom GUI with BEC Widgets.
 
 ```python
-prog_bar = gui.add_dock(name="prog_dock").add_widget_bec('SpiralProgressBar')
+prog_bar = gui.add_dock(name="prog_dock").add_widget('SpiralProgressBar')
 prog_bar.set_line_widths(15)
 scans.grid_scan(dev.samy, -2, 2, 10, dev.samx, -5, 5, 10, exp_time=0.1, relative=False)
 ```

docs/user/widgets/spiral_progress_bar.md

@@ -1,6 +1,12 @@
 (user.widgets.spiral_progress_bar)=
 # [Spiral Progress Bar](/api_reference/_autosummary/bec_widgets.cli.client.SpiralProgressBar)
-**Purpose** The Spiral Progress Bar widget is a circular progress bar that can be used to visualize the progress of a task. The widget is designed to be used in applications where the progress of a task is represented as a percentage. The Spiral Progress Bar widget is a part of the BEC Widgets library and can be controlled directly using its API, or hooked up to the progress of a device readback or scan.
+
+**Purpose:**
+
+The Spiral Progress Bar widget is a circular progress bar that can be used to visualize the progress of a task. The
+widget is designed to be used in applications where the progress of a task is represented as a percentage. The Spiral
+Progress Bar widget is a part of the BEC Widgets library and can be controlled directly using its API, or hooked up to
+the progress of a device readback or scan.
 
 **Key Features:**
 
@@ -11,11 +17,38 @@
 **Example of Use:**
 ![SpiralProgressBar](./progress_bar.gif)
 
-**Code example**
-The following code snipped demonstrates how to create a 2D scatter plot using BEC Widgets within BEC.
+**Code example:**
+
+The following code snipped demonstrates how to create a `SpiralProgressBar` using BEC Widgets within BEC.
 ```python
 # adds a new dock with a spiral progress bar
 progress = gui.add_dock().add_widget("SpiralProgressBar")
 # customize the size of the ring
 progress.set_line_width(20)
-```
+```
+
+By default, the Spiral Progress Bar widget will display a single ring. To add more rings, use the add_ring method:
+
+```python
+# adds a new dock with a spiral progress bar
+progress.add_ring()
+```
+
+To access rings and specify their properties, you can use `progress.rings` with an index specifying the ring index (
+starting from 0):
+
+```python
+progress.rings[0].set_line_width(20)  # set the width of the first ring
+progress.rings[1].set_line_width(10)  # set the width of the second ring
+```
+
+By default, the `SpiralProgressBar` widget is set with `progress.enable_auto_update(True)`, which will automatically
+update the bars in the widget. To manually set updates for each progress bar, use the set_update method. Note that
+manually updating a ring will disable the automatic update for the whole widget:
+
+```python
+progress.rings[0].set_update("scan")  # set the update of the first ring to be an overall scan progress
+progress.rings[1].set_update("device",
+                             "samx")  # set the update of the second ring to be a device readback (in this case, samx)
+```
+

pyproject.toml

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