bec-widgets 0.94.7__py3-none-any.whl → 0.95.1__py3-none-any.whl

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.7"
+version = "0.95.1"
 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)

docs/user/widgets/bec_figure.md

@@ -1,146 +0,0 @@
-(user.widgets.bec_figure)=
-# BECFigure
-[`BECFigure`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure) is a widget that provides a graphical user interface for creating and managing plots. It is a versatile tool that allows users to create a wide range of plots, from simple 1D waveforms to complex 2D scatter plots. BECFigure is designed to be user-friendly and interactive, enabling users to customize plots and visualize data in real-time.
-In the following, we describe 4 different type of widgets thaat are available in BECFigure. 
-
-**Schema of the BECFigure**
-
-![BECFigure.png](BECFigure.png)
-
-## [1D Waveform Widget](/api_reference/_autosummary/bec_widgets.cli.client.BECWaveform)
-
-**Purpose:** This widget provides a straightforward visualization of 1D data. It is particularly useful for plotting positioner movements against detector readings, enabling users to observe correlations and patterns in a simple, linear format.
-
-**Key Features:**
-- Real-time plotting of positioner versus detector values.
-- Interactive controls for zooming and panning through the data.
-- Customizable visual elements such as line color and style.
-
-**Example of Use:**
-![Waveform 1D](./w1D.gif)
-
-**Code example 1 - adding curves**
-
-The following code snipped demonstrates how to create a 1D waveform plot using BEC Widgets within BEC. More details about BEC Widgets in BEC can be found in the getting started section within the [introduction to the command line.](user.command_line_introduction)
-```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')
-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 of 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")
-```
-
-**Code example 2 - Adding Data Processing Pipeline Curve with LMFit Models**
-
-Together with the scan curve, one 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, one has 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)
-
-(user.widgets.scatter_2d)=
-## [2D Scatter Plot](/api_reference/_autosummary/bec_widgets.cli.client.BECWaveform)
-
-**Purpose:** 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.
-
-**Key Features:**
-
-- 2D scatter plot with color-coded data points based on a third variable (two positioners for x/y vs. one detector for colormap).
-- Interactive false color map for enhanced data interpretation.
-- Tools for selecting and inspecting specific data points.
-
-**Example of Use:**
-![Waveform 1D](./scatter_2D.gif)
-
-**Code example**
-The following code snipped demonstrates how to create a 2D scatter plot using BEC Widgets within BEC.
-```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')
-```
-
-(user.widgets.motor_map)=
-## [Motor Position Map](/api_reference/_autosummary/bec_widgets.cli.client.BECMotorMap)
-
-**Purpose:** A specialized component derived from the Motor Alignment Tool. It's focused on tracking and visualizing the position of motors, crucial for precise alignment and movement tracking during scans.
-
-**Key Features:**
-- Real-time tracking of motor positions.
-- Visual representation of motor trajectories, aiding in alignment tasks.
-
-**Example of Use:**
-![Waveform 1D](./motor.gif)
-
-**Code example**
-The following code snipped demonstrates how to create a motor map using BEC Widgets within BEC.
-```python
-# add a motor map to the gui
-mot_map = gui.add_dock().add_widget('BECFigure').motor_map('samx', 'samy')
-# change the number of points displayed
-```
-
-(user.widgets.image_2d)=
-## [Image Plot](/api_reference/_autosummary/bec_widgets.cli.client.BECImageItem)
-
-**Purpose:** A versatile widget for visualizing 2D image data, such as camera images. It provides a detailed representation of image data, with an attached color and scale bar to dynamically adjust the image display.
-
-**Key Features:**
-- Live-plotting of 2D image data from cameras (*if data stream is available in BEC*).
-- Color maps and scale bars for customizing image display.
-**Example of Use:**
-![Image 2D](./image_plot.gif)
-
-**Code example**
-The following code snipped demonstrates how to create a motor map using BEC Widgets within BEC.
-```python
-# add a camera view for the eiger camera to the gui
-cam_widget = gui.add_dock().add_widget('BECFigure').image('eiger')
-# set the title of the camera view
-cam_widget.set_title("Camera Image Eiger")
-# change the color map range, e.g. from 0 to 100, per default it is autoscaling
-# Note, the simulation has hot pixels on the detector
-cam_widget.set_vrange(vmin=0, vmax=100)
-```

docs/user/widgets/bec_status_box.md

@@ -1,30 +0,0 @@
-(user.widgets.bec_status_box)=
-# BEC Status Box
-**Purpose:**
-
-The [BECStatusBox](/api_reference/_autosummary/bec_widgets.cli.client.BECStatusBox) is a widget that allows you to monitor the status/health of the all running BEC processes. The widget generates the view automatically and updates the status of the processes in real-time. The top level indicates the overall state of the BEC core services (DeviceServer, ScanServer, SciHub, ScanBundler and FileWriter), but you can also see the status of each individual process by opening the collapsed view. In the collapsed view, you can double click on each process to get a popup window with live updates of the metrics for each process in real-time.
-
-**Key Features:**
-
-- monitor the state of individual BEC services.
-- automatically track BEC services, i.e. additional clients connecting.
-- live-updates of the metrics for each process.
-
-**Example of Use:**
-![BECStatus](./bec_status_box.gif)
-
-**Code example:**
-
-The following code snipped demonstrates how to create a `BECStatusBox` widget using BEC Widgets within BEC.
-```python
-bec_status_box = gui.add_dock().add_widget("BECStatusBox")
-```
-
-
-
-
-
-
-
-
-

docs/user/widgets/buttons.md

@@ -1,37 +0,0 @@
-(user.widgets.buttons)=
-# Buttons Widgets
-
-This section consolidates various custom buttons used within the BEC GUIs, facilitating the integration of these
-controls into different layouts.
-
-## Stop Button
-
-**Purpose:**
-
-The `Stop Button` provides a user interface control to immediately halt the execution of the current operation in the
-BEC Client. It is designed for easy integration into any BEC GUI layout.
-
-**Key Features:**
-
-- **Immediate Termination:** Halts the execution of the current script or process.
-- **Queue Management:** Clears any pending operations in the scan queue, ensuring the system is ready for new tasks.
-
-**Code example:**
-
-Integrating the `StopButton` into a BEC GUI layout is straightforward. The following example demonstrates how to embed
-a `StopButton` within a GUI layout:
-
-```python
-from qtpy.QtWidgets import QWidget, QVBoxLayout
-from bec_widgets.widgets.buttons import StopButton
-
-
-class MyGui(QWidget):
-    def __init__(self):
-        super().__init__()
-        self.setLayout(QVBoxLayout(self))  # Initialize the layout for the widget
-
-        # Create and add the StopButton to the layout
-        self.stop_button = StopButton()
-        self.layout().addWidget(self.stop_button)
-```