bec-widgets 0.94.6__py3-none-any.whl → 0.95.0__py3-none-any.whl

docs/user/widgets/toggle/toggle.md

@@ -0,0 +1,66 @@
+(user.widgets.toggle)=
+
+# Toggle Switch Widget
+
+````{tab} Overview
+
+The [`Toggle Switch`](/api_reference/_autosummary/bec_widgets.cli.client.ToggleSwitch) widget provides a simple, customizable toggle switch that can be used to represent binary states (e.g., on/off, true/false) within a GUI. This widget is designed to be used directly in code or added through `QtDesigner`, making it versatile for various applications where a user-friendly switch is needed.
+
+## Key Features:
+- **Binary State Representation**: Represents a simple on/off state with a smooth toggle animation.
+- **Customizable Appearance**: Allows customization of track and thumb colors for both active and inactive states.
+- **Smooth Animation**: Includes a smooth animation when toggling between states, enhancing user interaction.
+- **QtDesigner Integration**: Can be added directly through `QtDesigner` or instantiated in code.
+
+````
+
+````{tab} Examples
+
+The `Toggle Switch` widget can be integrated within a GUI application either through direct code instantiation or by using `QtDesigner`. Below are examples demonstrating how to create and customize the `Toggle Switch` widget.
+
+## Example 1 - Creating a Toggle Switch in Code
+
+In this example, we demonstrate how to create a `ToggleSwitch` widget in code and customize its appearance.
+
+```python
+from qtpy.QtWidgets import QApplication, QVBoxLayout, QWidget
+from bec_widgets.widgets.toggle_switch import ToggleSwitch
+
+class MyGui(QWidget):
+    def __init__(self):
+        super().__init__()
+        self.setLayout(QVBoxLayout(self))  # Initialize the layout for the widget
+
+        # Create and add the ToggleSwitch to the layout
+        self.toggle_switch = ToggleSwitch()
+        self.layout().addWidget(self.toggle_switch)
+
+# Example of how this custom GUI might be used:
+app = QApplication([])
+my_gui = MyGui()
+my_gui.show()
+app.exec_()
+```
+
+## Example 2 - Customizing the Toggle Switch Appearance
+
+The `ToggleSwitch` widget allows you to customize its appearance by changing the track and thumb colors for both active and inactive states. Below is an example of how to set these properties.
+
+```python
+# Set the active and inactive track and thumb colors
+self.toggle_switch.active_track_color = QColor(0, 122, 204)  # Active state track color (blue)
+self.toggle_switch.inactive_track_color = QColor(200, 200, 200)  # Inactive state track color (grey)
+self.toggle_switch.active_thumb_color = QColor(255, 255, 255)  # Active state thumb color (white)
+self.toggle_switch.inactive_thumb_color = QColor(255, 255, 255)  # Inactive state thumb color (white)
+```
+
+## Example 3 - Integrating the Toggle Switch in QtDesigner
+
+The `ToggleSwitch` can be added as a custom widget in `QtDesigner`. Once integrated, you can configure its properties through the designer's property editor. After adding the widget to a form in QtDesigner, you can manipulate it in your PyQt/PySide application:
+
+```python
+# For instance:
+self.toggle_switch.setChecked(True)
+```
+
+````

docs/user/widgets/waveform/waveform_widget.md

@@ -0,0 +1,132 @@
+(user.widgets.waveform_widget)=
+
+# Waveform Widget
+
+````{tab} Overview
+
+The Waveform Widget is used to display 1D detector signals. The widget is directly integrated with the `BEC` framework and can display real-time data from detectors loaded in the current `BEC` session as well as custom data from users.
+
+## Key Features:
+- **Flexible Integration**: The widget can be integrated into both [`BECFigure`](user.widgets.bec_figure) and [`BECDockArea`](user.widgets.bec_dock_area), or used as an individual component in your application through `BECDesigner`.
+- **Data Visualization**: Real-time plotting of positioner versus detector values from the BEC session, as well as static plotting of custom data.
+- **Real-time Data Processing**: Add real-time Data Processing Pipeline (DAP) to the real-time acquisition.
+- **Data Export**: Export data to CSV, H5, and other formats.
+- **Customizable Visual Elements**: Customize visual elements such as line color and style.
+- **Interactive Controls**: Interactive controls for zooming and panning through the data.
+
+![Waveform 1D](./w1D.gif)
+````
+
+````{tab} Examples - CLI
+
+`WaveformWidget` can be embedded in both `BECFigure` and `BECDockArea`, or used as an individual component in your application through `BECDesigner`. However, the command-line API is the same for all cases.
+
+## Example 1 - Adding Waveform Widget to BECFigure
+
+In this example, we will demonstrate how to add two different `WaveformWidgets` into a single `BECFigure` widget.
+
+```python
+# Add new dock with BECFigure widget
+fig = gui.add_dock().add_widget('BECFigure')
+
+# Add two WaveformWidgets to the BECFigure
+plt1 = fig.plot(x_name='samx', y_name='bpm4i')
+plt2 = fig.plot(x_name='samx', y_name='bpm3i')
+```
+
+## Example 2 - Adding Waveform Widget as a dock with BECDockArea
+
+Adding `WaveformWidget` into a `BECDockArea` is similar to adding any other widget. The widget has the same API as the one in BECFigure; however, as an independent widget outside BECFigure, it has its own toolbar, allowing users to configure the widget without needing CLI commands.
+
+```python
+# Add new WaveformWidgets to the BECDockArea
+plt1 = gui.add_dock().add_widget('BECWaveformWidget')
+plt2 = gui.add_dock().add_widget('BECWaveformWidget')
+
+# Add signals to the WaveformWidget
+plt1.plot(x_name='samx', y_name='bpm4i')
+plt2.plot(x_name='samx', y_name='bpm3i')
+```
+
+## Example 3 - Adding Waveform Widget with curves
+```python
+# adds a new dock, a new BECFigure and a BECWaveForm to the dock
+plt = gui.add_dock().add_widget('BECFigure').plot(x_name='samx', y_name='bpm4i')
+
+# add a second curve to the same plot 
+plt.plot(x_name='samx', y_name='bpm3i')
+
+# set axis labels
+plt.set_title("Gauss plots vs. samx")
+plt.set_x_label("Motor X")
+plt.set_y_label("Gauss Signal (A.U.")
+```
+
+```{note}
+The return value of the simulated devices *bpm4i* and *bpm3i* may not be Gaussian signals, but they can be easily configured with the code snippet below. For more details, please check the documentation for the [simulation](https://bec.readthedocs.io/en/latest/developer/devices/bec_sim.html).
+```
+
+```python
+# bpm4i uses GaussianModel and samx as a reference; default settings
+dev.bpm4i.sim.select_sim_model("GaussianModel")
+
+# bpm3i uses StepModel and samx as a reference; default settings
+dev.bpm3i.sim.select_sim_model("StepModel")
+```
+## Example 4 - Adding Data Processing Pipeline Curve with LMFit Models
+
+In addition to the scan curve, you can also add a second curve that fits the signal using a specified model from [LMFit](https://lmfit.github.io/lmfit-py/builtin_models.html). The following code snippet demonstrates how to create a 1D waveform curve with an attached DAP process, or how to add a DAP process to an existing curve using the BEC CLI. Please note that for this example, both devices were set as Gaussian signals.
+
+```python
+# Add a new dock, a new BECFigure, and a BECWaveForm to the dock with a GaussianModel DAP
+plt = gui.add_dock().add_widget('BECFigure').plot(x_name='samx', y_name='bpm4i', dap="GaussianModel")
+
+# Add a second curve to the same plot without DAP
+plt.plot(x_name='samx', y_name='bpm3a')
+
+# Add DAP to the second curve
+plt.add_dap(x_name='samx', y_name='bpm3a', dap="GaussianModel")
+
+```
+
+To get the parameters of the fit, you need to retrieve the curve objects and call the `dap_params` property.
+
+```python
+# Get the curve object by name from the legend
+dap_bpm4i = plt.get_curve("bpm4i-bpm4i-GaussianModel")
+dap_bpm3a = plt.get_curve("bpm3a-bpm3a-GaussianModel")
+
+# Get the parameters of the fit
+print(dap_bpm4i.dap_params)
+# Output
+{'amplitude': 197.399639720862,
+ 'center': 5.013486095404885,
+ 'sigma': 0.9820868875739888}
+
+print(dap_bpm3a.dap_params)
+# Output
+{'amplitude': 698.3072786185278,
+ 'center': 0.9702840866173836,
+ 'sigma': 1.97139754785518}
+```
+
+![Waveform 1D_DAP](./bec_figure_dap.gif)
+
+## Example 5 - 2D Waveform Scatter Plot
+
+The 2D scatter plot widget is designed for more complex data visualization. It employs a false color map to represent a third dimension (z-axis), making it an ideal tool for visualizing multidimensional data sets.
+
+```python
+# adds a new dock, a new BECFigure and a BECWaveForm to the dock
+plt = gui.add_dock().add_widget('BECFigure').add_plot(x_name='samx', y_name='samy', z_name='bpm4i')
+```
+
+![Scatter 2D](./scatter_2D.gif)
+
+````
+
+````{tab} API
+```{eval-rst}  
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.BECWaveform.rst
+```
+````

docs/user/widgets/website/website.md

@@ -0,0 +1,69 @@
+(user.widgets.website)=
+
+# Website Widget
+
+````{tab} Overview
+
+The [`Website Widget`](/api_reference/_autosummary/bec_widgets.cli.client.WebsiteWidget) is a versatile tool that allows users to display websites directly within the BEC GUI. This widget is useful for embedding documentation, dashboards, or any web-based tools within the application interface. It is designed to be integrated within a [`BECDockArea`](user.widgets.bec_dock_area) or used as an individual component in your application through `QtDesigner`.
+
+## Key Features:
+- **URL Display**: Set and display any website URL within the widget.
+- **Navigation Controls**: Navigate through the website’s history with back and forward controls.
+- **Reload Functionality**: Reload the currently displayed website to ensure up-to-date content.
+
+````
+
+````{tab} Examples - CLI
+
+The `WebsiteWidget` can be embedded within a [`BECDockArea`](user.widgets.bec_dock_area) or used as an individual component in your application through `QtDesigner`. The following examples demonstrate how to create and use the `WebsiteWidget` in different scenarios.
+
+## Example 1 - Adding Website Widget to BECDockArea
+
+In this example, we demonstrate how to add a `WebsiteWidget` to a `BECDockArea` and set the URL of the website to be displayed.
+
+```python
+# Add a new dock with a WebsiteWidget
+web = gui.add_dock().add_widget("WebsiteWidget")
+
+# Set the URL of the website to display
+web.set_url("https://bec.readthedocs.io/en/latest/")
+```
+
+## Example 2 - Navigating within the Website Widget
+
+The `WebsiteWidget` allows users to navigate back and forward through the website’s history. This example shows how to implement these navigation controls.
+
+```python
+# Go back in the website history
+web.back()
+
+# Go forward in the website history
+web.forward()
+```
+
+## Example 3 - Reloading the Website
+
+To ensure that the displayed website content is up-to-date, you can use the reload functionality.
+
+```python
+# Reload the current website
+web.reload()
+```
+
+## Example 4 - Retrieving the Current URL
+
+You may want to retrieve the current URL being displayed in the `WebsiteWidget`. The following example demonstrates how to access the current URL.
+
+```python
+# Get the current URL of the WebsiteWidget
+current_url = web.get_url()
+print(f"The current URL is: {current_url}")
+```
+
+````
+
+````{tab} API
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.WebsiteWidget.rst
+```
+````

docs/user/widgets/widgets.md

@@ -1,20 +1,220 @@
 (user.widgets)=
 # Widgets
-BEC Widgets includes a variety of visualization widgets designed to cater to diverse data representation needs in beamline experiments. These widgets enhance the user experience by providing intuitive and interactive data visualizations.
 
-```{toctree}
----
-maxdepth: 2
-hidden: false
----
+BEC Widgets offers a range of tools designed to make data visualization in beamline experiments easier and more
+interactive. These widgets help users better understand their data by providing clear, intuitive displays that enhance
+the overall experience.
+
+## Widget Containers
+
+Serves as containers to organise and display other widgets.
+
+````{grid} 3
+:gutter: 2
+
+```{grid-item-card}  BEC Dock Area
+:link: user.widgets.bec_dock_area
+:link-type: ref
+:img-top: /assets/widget_screenshots/dock_area.png
+
+Quickly build dynamic GUI.
+
+```
+
+```{grid-item-card}  BEC Figure
+:link: user.widgets.bec_figure
+:link-type: ref
+:img-top: /assets/widget_screenshots/figure.png
+
+Display 1D and 2D data.
+```
+````
+
+## Plotting Widgets
+
+Plotting widgets are used to display data in a graphical format.
+
+````{grid} 3
+:gutter: 2
+
+```{grid-item-card}  Waveform Widget
+:link: user.widgets.waveform_widget
+:link-type: ref
+:img-top: /assets/widget_screenshots/waveform_widget.png
+
+Display 1D detector signals.
+```
+
+```{grid-item-card}  Image Widget
+:link: user.widgets.image_widget
+:link-type: ref
+:img-top: /assets/widget_screenshots/image_widget.png
+
+Display signal from 2D detector.
+```
+
+```{grid-item-card}  Motor Map Widget
+:link: user.widgets.motor_map
+:link-type: ref
+:img-top: /assets/widget_screenshots/motor_map_widget.png
+
+Track position for motors.
+```
+
+````
+
+## Device Control Widgets
+
+Control and monitor devices/scan in the BEC environment.
+
+````{grid} 3
+:gutter: 2
+
+```{grid-item-card}  Scan Control Widget
+:link: user.widgets.scan_control
+:link-type: ref
+:img-top: /assets/widget_screenshots/scan_controller.png
+
+Launch scans.
+```
+
+```{grid-item-card}  Device Browser
+:link: user.widgets.device_browser
+:link-type: ref
+:img-top: /assets/widget_screenshots/device_browser.png
+
+Find and drag devices.
+```
+
+```{grid-item-card}  Positioner Box
+:link: user.widgets.positioner_box
+:link-type: ref
+:img-top: /assets/widget_screenshots/device_box.png
+
+Control individual device.
+```
 
-bec_figure/
-ring_progress_bar/
-website/
-buttons/
-text_box/
-bec_status_box/
+```{grid-item-card} Ring Progress Bar 
+:link: user.widgets.ring_progress_bar
+:link-type: ref
+:img-top: /assets/widget_screenshots/ring_progress_bar.png
 
+Nested progress bar.
 ```
 
+````
+
+## BEC Service Widgets
+
+Visualise the status of BEC services.
+
+````{grid} 3
+:gutter: 2
+
+```{grid-item-card} BEC Status Box
+:link: user.widgets.bec_status_box
+:link-type: ref
+:img-top: /assets/widget_screenshots/status_box.png
+
+Display status of BEC services.
+```
+
+```{grid-item-card} BEC Queue Table 
+:link: user.widgets.bec_queue
+:link-type: ref
+:img-top: /assets/widget_screenshots/queue.png
+
+Display current scan queue.
+```
+````
+
+## BEC Utility Widgets
+
+Various utility widgets to enhance user experience.
+
+````{grid} 3
+:gutter: 2
+
+```{grid-item-card} Service Buttons
+:link: user.widgets.buttons
+:link-type: ref
+:img-top: /assets/widget_screenshots/buttons.png
+
+Various service buttons.
+```
+
+```{grid-item-card} Device Input Widgets
+:link: user.widgets.device_input
+:link-type: ref
+:img-top: /assets/widget_screenshots/device_inputs.png
+
+Choose individual device from current session.
+```
+
+```{grid-item-card} Text Box Widget
+:link: user.widgets.text_box
+:link-type: ref
+:img-top: /assets/widget_screenshots/text_box.png
+
+Display custom text or HTML content.
+```
+
+```{grid-item-card} Website Widget
+:link: user.widgets.website
+:link-type: ref
+:img-top: /assets/widget_screenshots/website.png
+
+Display website content.
+```
+
+```{grid-item-card} Toogle Widget
+:link: user.widgets.toggle
+:link-type: ref
+:img-top: /assets/widget_screenshots/toggle.png
+
+Angular like toggle switch.
+```
+
+```{grid-item-card} Spinner 
+:link: user.widgets.spinner
+:link-type: ref
+:img-top: /assets/widget_screenshots/spinner.gif
+
+Display spinner widget for loading or device movement.
+```
+
+```{grid-item-card} Position Indicator
+:link: user.widgets.position_indicator
+:link-type: ref
+:img-top: /assets/widget_screenshots/position_indicator.png
+
+Display position of motor withing its limits.
+```
+````
+
+```{toctree}
+---
+maxdepth: 1
+hidden: true
+---
+
+dock_area/bec_dock_area.md
+bec_figure/bec_figure.md
+waveform/waveform_widget.md
+image/image_widget.md
+motor_map/motor_map.md
+scan_control/scan_control.md
+progress_bar/ring_progress_bar.md
+bec_status_box/bec_status_box.md
+queue/queue.md
+buttons/buttons.md
+device_browser/device_browser.md
+positioner_box/positioner_box.md
+text_box/text_box.md
+website/website.md
+toggle/toggle.md
+spinner/spinner.md
+device_input/device_input.md
+position_indicator/position_indicator.md
 
+```

pyproject.toml

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

tests/unit_tests/client_mocks.py

@@ -18,6 +18,20 @@ class FakeDevice:
         self.signals = {self.name: {"value": 1.0}}
         self.description = {self.name: {"source": self.name, "dtype": "number", "shape": []}}
         self.readout_priority = readout_priority
+        self._config = {
+            "readoutPriority": "baseline",
+            "deviceClass": "ophyd_devices.SimPositioner",
+            "deviceConfig": {
+                "delay": 1,
+                "limits": [-50, 50],
+                "tolerance": 0.01,
+                "update_frequency": 400,
+            },
+            "deviceTags": ["user motors"],
+            "enabled": enabled,
+            "readOnly": False,
+            "name": self.name,
+        }
 
     def __contains__(self, item):
         return item == self.name

tests/unit_tests/test_device_browser.py

@@ -0,0 +1,83 @@
+from typing import TYPE_CHECKING
+from unittest import mock
+
+import pytest
+from qtpy.QtCore import Qt
+
+from bec_widgets.widgets.device_browser.device_browser import DeviceBrowser
+
+from .client_mocks import mocked_client
+
+if TYPE_CHECKING:
+    from qtpy.QtWidgets import QListWidgetItem
+
+    from bec_widgets.widgets.device_browser.device_item.device_item import DeviceItem
+
+
+@pytest.fixture
+def device_browser(qtbot, mocked_client):
+    dev_browser = DeviceBrowser(client=mocked_client)
+    qtbot.addWidget(dev_browser)
+    qtbot.waitExposed(dev_browser)
+    yield dev_browser
+
+
+def test_device_browser_init_with_devices(device_browser):
+    """
+    Test that the device browser is initialized with the correct number of devices.
+    """
+    device_list = device_browser.ui.device_list
+    assert device_list.count() == len(device_browser.dev)
+
+
+def test_device_browser_filtering(qtbot, device_browser):
+    """
+    Test that the device browser is able to filter the device list.
+    """
+    device_list = device_browser.ui.device_list
+    device_browser.ui.filter_input.setText("sam")
+    qtbot.wait(1000)
+    assert device_list.count() == 3
+
+    device_browser.ui.filter_input.setText("nonexistent")
+    qtbot.wait(1000)
+    assert device_list.count() == 0
+
+    device_browser.ui.filter_input.setText("")
+    qtbot.wait(1000)
+    assert device_list.count() == len(device_browser.dev)
+
+
+def test_device_item_mouse_press_event(device_browser, qtbot):
+    """
+    Test that the mousePressEvent is triggered correctly.
+    """
+    # Simulate a left mouse press event on the device item
+    device_item: QListWidgetItem = device_browser.ui.device_list.itemAt(0, 0)
+    widget: DeviceItem = device_browser.ui.device_list.itemWidget(device_item)
+    qtbot.mousePress(widget.label, Qt.MouseButton.LeftButton)
+
+
+def test_device_item_mouse_press_event_creates_drag(device_browser, qtbot):
+    """
+    Test that the mousePressEvent is triggered correctly and initiates a drag.
+    """
+    device_item: QListWidgetItem = device_browser.ui.device_list.itemAt(0, 0)
+    widget: DeviceItem = device_browser.ui.device_list.itemWidget(device_item)
+    device_name = widget.device
+    with mock.patch("qtpy.QtGui.QDrag.exec_") as mock_exec:
+        with mock.patch("qtpy.QtGui.QDrag.setMimeData") as mock_set_mimedata:
+            qtbot.mousePress(widget.label, Qt.MouseButton.LeftButton)
+            mock_set_mimedata.assert_called_once()
+            mock_exec.assert_called_once()
+            assert mock_set_mimedata.call_args[0][0].text() == device_name
+
+
+def test_device_item_double_click_event(device_browser, qtbot):
+    """
+    Test that the mouseDoubleClickEvent is triggered correctly.
+    """
+    # Simulate a left mouse press event on the device item
+    device_item: QListWidgetItem = device_browser.ui.device_list.itemAt(0, 0)
+    widget: DeviceItem = device_browser.ui.device_list.itemWidget(device_item)
+    qtbot.mouseDClick(widget, Qt.LeftButton)