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

docs/user/widgets/position_indicator/position_indicator.md

@@ -0,0 +1,76 @@
+(user.widgets.position_indicator)=
+
+# Position Indicator Widget
+
+````{tab} Overview
+
+The [`PositionIndicator`](/api_reference/_autosummary/bec_widgets.cli.client.PositionIndicator) widget is a simple yet effective tool for visually indicating the position of a motor within its set limits. This widget is particularly useful in applications where it is important to provide a visual cue of the motor's current position relative to its minimum and maximum values. The `PositionIndicator` can be easily integrated into your GUI application either through direct code instantiation or by using `QtDesigner`.
+
+## Key Features:
+- **Position Visualization**: Displays the current position of a motor on a linear scale, showing its location relative to the defined limits.
+- **Customizable Range**: The widget allows you to set the minimum and maximum range, adapting to different motor configurations.
+- **Real-Time Updates**: Responds to real-time updates, allowing the position indicator to move dynamically as the motor's position changes.
+- **QtDesigner Integration**: Can be added directly in code or through `QtDesigner`, making it adaptable to various use cases.
+
+````
+
+````{tab} Examples
+
+The `PositionIndicator` widget can be embedded within a GUI application through direct code instantiation or by using `QtDesigner`. Below are examples demonstrating how to create and use the `PositionIndicator` widget.
+
+## Example 1 - Creating a Position Indicator in Code
+
+In this example, we demonstrate how to create a `PositionIndicator` widget in code and connect it to a slider to simulate position updates.
+
+```python
+from qtpy.QtWidgets import QApplication, QSlider, QVBoxLayout, QWidget
+from bec_widgets.widgets.position_indicator import PositionIndicator
+
+app = QApplication([])
+
+# Create the PositionIndicator widget
+position_indicator = PositionIndicator()
+
+# Create a slider to simulate position changes
+slider = QSlider(Qt.Horizontal)
+slider.valueChanged.connect(lambda value: position_indicator.on_position_update(value / 100))
+
+# Create a layout and add the widgets
+layout = QVBoxLayout()
+layout.addWidget(position_indicator)
+layout.addWidget(slider)
+
+# Set up the main widget
+widget = QWidget()
+widget.setLayout(layout)
+widget.show()
+
+app.exec_()
+```
+
+## Example 2 - Setting the Range for the Position Indicator
+
+You can set the minimum and maximum range for the position indicator to reflect the actual limits of the motor.
+
+```python
+# Set the range for the position indicator
+position_indicator.set_range(min_value=0, max_value=200)
+```
+
+## Example 3 - Integrating the Position Indicator in QtDesigner
+
+The `PositionIndicator` can be added to your GUI layout using `QtDesigner`. Once added, you can connect it to the motor's position updates using the `on_position_update` slot.
+
+```python
+# Example: Updating the position in a QtDesigner-based application
+self.position_indicator.on_position_update(new_position_value)
+```
+
+````
+
+````{tab} API
+
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.PositionIndicator.rst
+```
+````

docs/user/widgets/positioner_box/positioner_box.md

@@ -0,0 +1,63 @@
+(user.widgets.positioner_box)=
+
+# Positioner Box Widget
+
+````{tab} Overview
+
+The [`PositionerBox`](/api_reference/_autosummary/bec_widgets.cli.client.PositionerBox) widget provides a graphical user interface to control a positioner device within the BEC environment. This widget allows users to interact with a positioner by setting setpoints, tweaking the motor position, and stopping motion. The device selection can be done via a small button under the device label, through `QtDesigner`, or by using the command line interface (CLI). This flexibility makes the `PositionerBox` an essential tool for tasks involving precise position control.
+
+## Key Features:
+- **Device Selection**: Easily select a positioner device by clicking the button under the device label or by configuring the widget in `QtDesigner`.
+- **Setpoint Control**: Directly set the positioner’s target setpoint and issue movement commands.
+- **Tweak Controls**: Adjust the motor position incrementally using the tweak left/right buttons.
+- **Real-Time Feedback**: Monitor the device’s current position and status, with live updates on whether the device is moving or idle.
+- **Flexible Integration**: Can be integrated into a GUI through `BECDockArea` or used as a standalone component in `QtDesigner`.
+````
+
+````{tab} Examples
+
+The `PositionerBox` 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 use the `PositionerBox` widget.
+
+## Example 1 - Creating a PositionerBox in Code
+
+In this example, we demonstrate how to create a `PositionerBox` widget in code and configure it for a specific device.
+
+```python
+from qtpy.QtWidgets import QApplication, QVBoxLayout, QWidget
+from bec_widgets.widgets.positioner_box import PositionerBox
+
+class MyGui(QWidget):
+    def __init__(self):
+        super().__init__()
+        self.setLayout(QVBoxLayout(self))  # Initialize the layout for the widget
+
+        # Create and add the PositionerBox to the layout
+        self.positioner_box = PositionerBox(device="motor1")
+        self.layout().addWidget(self.positioner_box)
+
+# Example of how this custom GUI might be used:
+app = QApplication([])
+my_gui = MyGui()
+my_gui.show()
+app.exec_()
+```
+
+## Example 2 - Selecting a Device via GUI
+
+Users can select the positioner device by clicking the button under the device label, which opens a dialog for device selection.
+
+## Example 3 - Customizing PositionerBox in QtDesigner
+
+The `PositionerBox` widget can be added to a GUI through `QtDesigner`. Once integrated, you can configure the default device and customize the widget’s appearance and behavior directly within the designer.
+
+```python
+# After adding the widget to a form in QtDesigner, you can configure the device:
+self.positioner_box.set_positioner("motor2")
+```
+````
+
+````{tab} API
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.PositionerBox.rst
+```
+````

docs/user/widgets/progress_bar/ring_progress_bar.md

@@ -0,0 +1,103 @@
+(user.widgets.ring_progress_bar)=
+
+# Ring Progress Bar
+
+````{tab} Overview
+
+The [`Ring Progress Bar`](/api_reference/_autosummary/bec_widgets.cli.client.RingProgressBar) widget is a circular progress bar designed to visualize the progress of tasks in a clear and intuitive manner. This widget is particularly useful in applications where task progress needs to be represented as a percentage. The `Ring Progress Bar` can be controlled directly via its API or can be hooked up to track the progress of a device readback or scan, providing real-time visual feedback.
+
+## Key Features:
+- **Circular Progress Visualization**: Displays a circular progress bar to represent task completion.
+- **Device and Scan Integration**: Hooks into device readbacks or scans to automatically update the progress bar based on real-time data.
+- **Multiple Rings**: Supports multiple progress rings within the same widget to track different tasks in parallel.
+- **Customizable Visual Elements**: Allows customization of colors, line widths, and other visual elements for each progress ring.
+
+![RingProgressBar](./progress_bar.gif)
+
+````
+
+````{tab} Example
+
+## Example 1 - Adding Ring Progress Bar to BECDockArea
+
+In this example, we demonstrate how to add a `RingProgressBar` widget to a `BECDockArea` to visualize the progress of a task.
+
+```python
+# Add a new dock with a RingProgressBar widget
+progress = gui.add_dock().add_widget("RingProgressBar")
+
+# Customize the size of the progress ring
+progress.set_line_widths(20)
+```
+
+## Example 2 - Adding Multiple Rings to Track Parallel Tasks
+
+By default, the `RingProgressBar` widget displays a single ring. You can add additional rings to track multiple tasks simultaneously.
+
+```python
+# Add a second ring to the RingProgressBar
+progress.add_ring()
+
+# Customize the rings
+progress.rings[0].set_line_widths(20)  # Set the width of the first ring
+progress.rings[1].set_line_widths(10)  # Set the width of the second ring
+```
+
+## Example 3 - Integrating with Device Readback and Scans
+
+The `RingProgressBar` can automatically update based on the progress of scans or device readbacks. This example shows how to set up the progress rings to reflect these updates.
+
+```python
+# Set the first ring to update based on scan progress
+progress.rings[0].set_update("scan")
+
+# Set the second ring to update based on a device readback (e.g., samx)
+progress.rings[1].set_update("device", "samx")
+```
+
+## Example 4 - Customizing Visual Elements of the Rings
+
+The `RingProgressBar` widget offers various customization options, such as changing colors, line widths, and the gap between rings.
+
+```python
+# Set the color of the first ring to blue
+progress.rings[0].set_color("blue")
+
+# Set the background color of the second ring
+progress.rings[1].set_background("gray")
+
+# Adjust the gap between the rings
+progress.set_gap(5)
+
+# Set the diameter of the progress bar
+progress.set_diameter(150)
+```
+
+## Example 5 - Manual Updates and Precision Control
+
+While the `RingProgressBar` supports automatic updates, you can also manually control the progress and set the precision for each ring.
+
+```python
+# Disable automatic updates and manually set the progress value
+progress.enable_auto_updates(False)
+progress.rings[0].set_value(75)  # Set the first ring to 75%
+
+# Set precision for the progress display
+progress.set_precision(2)  # Display progress with two decimal places
+
+
+# Setting multiple rigns with different values
+progress.set_number_of_bars(3)
+
+# Set the values of the rings to 50, 75, and 25 from outer to inner ring
+progress.set_value([50, 75, 25])
+```
+
+````
+
+````{tab} API
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.RingProgressBar.rst
+```
+````
+

docs/user/widgets/queue/queue.md

@@ -0,0 +1,41 @@
+(user.widgets.bec_queue)=
+
+# BEC Queue Widget
+
+````{tab} Overview
+
+The [`BEC Queue Widget`](/api_reference/_autosummary/bec_widgets.cli.client.BECQueue) provides a real-time display of the BEC scan queue, allowing users to monitor and track the status of ongoing and pending scans. The widget automatically updates to reflect the current state of the scan queue, displaying critical information such as scan numbers, types, and statuses. This widget is particularly useful for users who need to manage and oversee multiple scans in the BEC environment.
+
+## Key Features:
+- **Real-Time Queue Monitoring**: Displays the current state of the BEC scan queue, with automatic updates as the queue changes.
+- **Detailed Scan Information**: Provides a clear view of scan numbers, types, and statuses, helping users track the progress and state of each scan.
+- **Interactive Table Layout**: The queue is presented in a table format, with customizable columns that stretch to fit the available space.
+- **Flexible Integration**: The widget can be integrated into both [`BECDockArea`](user.widgets.bec_dock_area) and used as an individual component in your application through `QtDesigner`.
+
+````
+
+````{tab} Examples
+
+The `BEC Queue Widget` can be embedded within a [`BECDockArea`](user.widgets.bec_dock_area) or used as an individual component in your application through `QtDesigner`. Below are examples demonstrating how to create and use the `BEC Queue Widget`.
+
+## Example 1 - Adding BEC Queue Widget to BECDockArea
+
+In this example, we demonstrate how to add a `BECQueue` widget to a `BECDockArea`, allowing users to monitor the BEC scan queue directly from the GUI.
+
+```python
+# Add a new dock with a BECQueue widget
+bec_queue = gui.add_dock().add_widget("BECQueue")
+```
+
+```{hint}
+The `BECQueue` widget automatically updates as the scan queue changes, providing real-time feedback on the status of each scan.
+Once the widget is added, it will automatically display the current scan queue
+```
+
+````
+
+````{tab} API
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.BECQueue.rst
+```
+````

docs/user/widgets/scan_control/scan_control.md

@@ -0,0 +1,46 @@
+(user.widgets.scan_control)=
+
+# Scan Control Widget
+
+````{tab} Overview
+
+The [`Scan Control`](/api_reference/_autosummary/bec_widgets.cli.client.ScanControl) widget provides a graphical user interface (GUI) to manage various scan operations in a BEC environment. It is designed to interact with the BEC server, enabling users to start and stop scans. The widget automatically creates the necessary input form based on the scan's signature and gui_config, making it highly adaptable to different scanning processes.
+
+## Key Features:
+- **Automatic Interface Generation**: Automatically generates a control interface based on scan signatures and `gui_config`.
+- **Dynamic Argument Bundling**: Supports the dynamic addition and removal of argument bundles such as positioners controls.
+- **Visual Parameter Grouping**: Provides a visual representation of scan parameters, grouped by their functionality.
+- **Integrated Scan Controls**: Includes start abd stop controls for managing scan execution.
+
+```{note}
+By default, this widget supports scans that are derived from the following base classes and have a defined `gui_config`:
+- [ScanBase](https://beamline-experiment-control.readthedocs.io/en/latest/api_reference/_autosummary/bec_server.scan_server.scans.ScanBase.html)
+- [SyncFlyScanBase](https://beamline-experiment-control.readthedocs.io/en/latest/api_reference/_autosummary/bec_server.scan_server.scans.SyncFlyScanBase.html)
+- [AsyncFlyScanBase](https://beamline-experiment-control.readthedocs.io/en/latest/api_reference/_autosummary/bec_server.scan_server.scans.AsyncFlyScanBase.html)
+```
+
+```{hint}
+The full procedure how to design `gui_config` for your custom scan class is described in the [Scan GUI Configuration](https://bec.readthedocs.io/en/latest/developer/scans/scan_gui_config.html) tutorial.
+```
+
+````
+
+````{tab} Examples
+
+The `ScanControl` widget can be integrated within a [`BECDockArea`](user.widgets.bec_dock_area) or used as an individual component in your application through `QtDesigner`. Below are examples demonstrating how to create and use the `ScanControl` widget.
+
+## Example 1 - Adding Scan Control Widget to BECDockArea
+
+In this example, we demonstrate how to add a `ScanControl` widget to a `BECDockArea`, enabling the user to control scan operations directly from the GUI.
+
+```python
+# Add a new dock with a ScanControl widget
+scan_control = gui.add_dock().add_widget("ScanControl")
+```
+````
+
+````{tab} API
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.ScanControl.rst
+```
+````

docs/user/widgets/spinner/spinner.md

@@ -0,0 +1,75 @@
+(user.widgets.spinner)=
+
+# Spinner Widget
+
+````{tab} Overview
+
+The [`SpinnerWidget`](/api_reference/_autosummary/bec_widgets.cli.client.SpinnerWidget) is a simple and versatile widget designed to indicate loading or movement within an application. It is commonly used to show that a device is in motion or that an operation is ongoing. The `SpinnerWidget` can be easily integrated into your GUI application either through direct code instantiation or by using `QtDesigner`.
+
+## Key Features:
+- **Loading Indicator**: Provides a visual indication of ongoing operations or device movement.
+- **Smooth Animation**: Features a smooth, continuous spinning animation to catch the user's attention.
+- **Easy Integration**: Can be added directly in code or through `QtDesigner`, making it adaptable to various use cases.
+- **Customizable Appearance**: Automatically adapts to the application's theme, ensuring visual consistency.
+
+````
+
+````{tab} Examples
+
+The `SpinnerWidget` can be embedded within a GUI application through direct code instantiation or by using `QtDesigner`. Below are examples demonstrating how to create and use the `SpinnerWidget`.
+
+## Example 1 - Creating a Spinner Widget in Code
+
+In this example, we demonstrate how to create a `SpinnerWidget` in code and start the spinner to indicate an ongoing operation.
+
+```python
+from qtpy.QtWidgets import QApplication, QMainWindow
+from bec_widgets.widgets.spinner_widget import SpinnerWidget
+
+app = QApplication([])
+
+# Create a main window
+window = QMainWindow()
+
+# Create a SpinnerWidget instance
+spinner = SpinnerWidget()
+
+# Start the spinner
+spinner.start()
+
+# Set the spinner as the central widget
+window.setCentralWidget(spinner)
+window.show()
+
+app.exec_()
+```
+
+## Example 2 - Stopping the Spinner
+
+You can stop the spinner to indicate that an operation has completed.
+
+```python
+# Stop the spinner
+spinner.stop()
+```
+
+## Example 3 - Integrating the Spinner Widget in QtDesigner
+
+The `SpinnerWidget` can be added to your GUI layout using `QtDesigner`. Once added, you can control the spinner using the `start` and `stop` methods, similar to the code examples above.
+
+```python
+# Example: Start the spinner in a QtDesigner-based application
+self.spinner_widget.start()
+
+# Example: Stop the spinner in a QtDesigner-based application
+self.spinner_widget.stop()
+```
+
+````
+
+````{tab} API
+
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.widgets.spinner.spinner.SpinnerWidget.rst
+```
+````

docs/user/widgets/text_box/text_box.md

@@ -0,0 +1,74 @@
+(user.widgets.text_box)=
+
+# Text Box Widget
+
+````{tab} Overview
+
+The [`Text Box Widget`](/api_reference/_autosummary/bec_widgets.cli.client.TextBox) is a versatile widget that allows users to display text within the BEC GUI. It supports both plain text and HTML, making it useful for displaying simple messages or more complex formatted content. This widget is particularly suited for integrating textual content directly into the user interface, whether as a standalone message box or as part of a larger application interface.
+
+## Key Features:
+- **Text Display**: Display either plain text or HTML content, with automatic detection of the format.
+- **Customizable Appearance**: Set the background and font colors to match the design of your application.
+- **Font Size Adjustment**: Customize the font size of the displayed text for better readability.
+
+````
+
+````{tab} Examples - CLI
+
+The `TextBox` widget can be integrated 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 customize the `TextBox` widget in various scenarios.
+
+## Example 1 - Adding Text Box Widget to BECDockArea
+
+In this example, we demonstrate how to add a `TextBox` widget to a `BECDockArea` and set the text to be displayed.
+
+```python
+# Add a new dock with a TextBox widget
+text_box = gui.add_dock().add_widget("TextBox")
+
+# Set the text to display
+text_box.set_text("Hello, World!")
+```
+
+## Example 2 - Displaying HTML Content
+
+The `TextBox` widget can automatically detect and render HTML content. This example shows how to display formatted HTML text.
+
+```python
+# 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>")
+```
+
+## Example 3 - Customizing Appearance
+
+The `TextBox` widget allows you to customize the background and font colors to fit your application's design. Below is an example of how to set these properties.
+
+```python
+# Set the background color to white and the font color to black
+text_box.set_color(background_color="#FFF", font_color="#000")
+```
+
+## Example 4 - Adjusting Font Size
+
+To improve readability or fit more text within the widget, you can adjust the font size.
+
+```python
+# Set the font size to 14 pixels
+text_box.set_font_size(14)
+```
+
+````
+
+````{tab} API
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.TextBox.rst
+```
+````
+
+
+
+
+
+
+
+
+

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
+```
+````