docs(user): widget gallery with documentation added

docs/conf.py

@@ -41,6 +41,7 @@ extensions = [
     "sphinx_copybutton",
     "myst_parser",
     "sphinx_design",
+    "sphinx_inline_tabs",
 ]
 
 myst_enable_extensions = [

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_figure/bec_figure.md

@@ -0,0 +1,105 @@
+(user.widgets.bec_figure)=
+# BECFigure
+
+````{tab} Overview
+
+[`BECFigure`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure) is a robust framework that provides a fast, flexible plotting environment, similar to the Matplotlib figure. With BECFigure, users can dynamically change layouts, add or remove subplots, and customize their plotting environment in real-time. This flexibility makes BECFigure an ideal tool for both rapid prototyping and detailed data visualization.
+
+- **Dynamic Layout Management**: Easily add, remove, and rearrange subplots within `BECFigure`, enabling tailored visualization setups.
+- **Widget Integration**: Incorporate various specialized widgets like [`WaveformWidget`](user.widgets.waveform_widget), [`ImageWidget`](user.widgets.image_widget) , and [`MotorMapWidget`](user.widgets.motor_map) into `BECFigure`. Note that these widgets can also be used individually. For more details, please refer to the documentation for each individual widget.
+- **Interactive Controls**: Provides interactive tools for zooming, panning, and adjusting plots on the fly, streamlining the data exploration process.
+
+**Schema of the BECFigure components**
+
+![BECFigure.png](BECFigure.png)
+
+````
+
+````{tab} Examples - CLI
+In the following examples, we will use `BECIPythonClient` with a predefined `BECDockArea` as the `gui` object. These tutorials focus on how to work with the `BECFigure` framework, such as changing layouts, adding new elements, and accessing them. For more detailed examples of each individual component, please refer to the example sections of each individual widget: [`WaveformWidget`](user.widgets.waveform_widget), [`MotorMapWidget`](user.widgets.motor_map), [`ImageWidget`](user.widgets.image_widget).
+
+## Example 1 - Adding subplots to BECFigure
+
+In this example, we will demonstrate how to add different subplots to a single `BECFigure` widget.
+
+```python
+# Add a new dock with BECFigure widget
+fig = gui.add_dock().add_widget('BECFigure')
+
+# Add a WaveformWidget to the BECFigure
+plt1 = fig.plot(x_name='samx', y_name='bpm4i')
+
+# Add a second WaveformWidget to the BECFigure, specifying new=True to add it as a new subplot
+plt2 = fig.plot(x_name='samx', y_name='bpm3i', new=True)
+
+# Add a MotorMapWidget to the BECFigure
+mm = fig.motor_map(motor_x='samx', motor_y='samy')
+
+# Add an ImageWidget to the BECFigure
+img = fig.image('eiger')
+```
+```{note}
+By default, the [`.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) methods always find the first widget of that type in the layout and interact with it. If you want to add a new subplot of the same type, you must either specify the coordinates of the new subplot or use the `new=True` keyword argument, as shown above when adding the second WaveformWidget. Additionally, you can directly add a subplot to a specific, unoccupied position in the layout by specifying the `row` and `col` arguments, such as `fig.plot(x_name='samx', y_name='bpm4i', row=1, col=1)`.
+```
+
+## Example 2 - Changing the layout of BECFigure
+
+The previous example added four subplots into a single `BECFigure` widget. By default, new widgets are always added to the bottom of the BECFigure. However, you can change the layout of the BECFigure by using the [`change_layout`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.change_layout) method, specifying the number of rows and/or columns.
+
+```python
+# Change the layout of the BECFigure to have 4 columns -> 4x1 matrix layout
+fig.change_layout(max_columns=4) 
+
+# Change the layout of the BECFigure to have 2 rows -> 2x2 matrix layout
+fig.change_layout(max_rows=2) 
+```
+
+## Example 3 - Accessing Subplots in BECFigure
+
+The subplots in BECFigure can be accessed in a similar way to Matplotlib figures using the [`axes`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.axes) property. Each subplot can be accessed by its index coordinates within the layout, specified by the row and column index (starting at 0). In following example, we will access the subplots and modify their titles. The layout is a 2x2 matrix, so the subplots are indexed as follows:
+
+```python
+# Access the first subplot in the first row and first column (0, 0)
+subplot1 = fig.axes(0, 0)
+
+# Access the second subplot in the first row and second column (0, 1)
+subplot2 = fig.axes(0, 1)
+
+# Access the first subplot in the second row and first column (1, 0)
+subplot3 = fig.axes(1, 0)
+
+# Example: Set title for the first subplot
+subplot1.set_title("Waveform 1")
+
+# Example: Set title for the second subplot
+subplot2.set_title("Waveform 2")
+
+# Example: Set title for the third subplot
+subplot3.set_title("Motor Map")
+```
+
+In this example, we accessed three different subplots based on their row and column positions and modified their titles.
+
+## Example 4 - Removing Subplots from BECFigure
+
+You may want to remove certain subplots from the `BECFigure`. This can be done using the [`remove`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.remove) method, which takes the row and column index of the subplot you want to remove. The [`remove`](/api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst#bec_widgets.cli.client.BECFigure.remove) method could be also called on the subplot itself.
+
+```python
+
+# Remove the subplot in the second row and second column (1, 1)
+fig.remove(1, 1)
+
+# Remove the subplot in the first row and first column (0, 0)
+fig.remove(0, 0)
+
+# Remove previously accessed subplot plt2 from Example 1
+plt2.remove()
+```
+
+````
+
+````{tab} API
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.BECFigure.rst
+```
+````

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/bec_status_box/bec_status_box.md

@@ -0,0 +1,38 @@
+(user.widgets.bec_status_box)=
+# BEC Status Box
+
+````{tab} Overview
+
+The [`BEC Status Box`](/api_reference/_autosummary/bec_widgets.cli.client.BECStatusBox) widget is designed to monitor the status and health of all running BEC processes. This widget provides a real-time overview of the BEC core services, including DeviceServer, ScanServer, SciHub, ScanBundler, and FileWriter. The top-level display indicates the overall state of the BEC services, while the collapsed view allows users to delve into the status of each individual process. By double-clicking on a specific process, users can access a detailed popup window with live updates of the metrics for that process.
+
+## Key Features:
+- **Comprehensive Service Monitoring**: Track the state of individual BEC services, including real-time updates on their health and status.
+- **Automatic Service Tracking**: Automatically detects and monitors additional clients connecting to the BEC services.
+- **Detailed Metrics**: Provides live updates of the metrics for each process, accessible through an interactive popup window.
+
+![BECStatus](./bec_status_box.gif)
+````
+
+````{tab} Examples
+
+The `BECStatusBox` 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 `BECStatusBox` widget.
+
+## Example 1 - Adding BEC Status Box to BECDockArea
+
+In this example, we demonstrate how to add a `BECStatusBox` widget to a `BECDockArea`, allowing users to monitor the status of BEC processes directly from the GUI.
+
+```python
+# Add a new dock with a BECStatusBox widget
+bec_status_box = gui.add_dock().add_widget("BECStatusBox")
+```
+
+```{hint}
+Once the `BECStatusBox` is added, users can interact with it to view the status of individual processes. By expanding the view, you can see the status of each BEC service in detail.
+```
+````
+
+````{tab} API
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.BECStatusBox.rst
+```
+````

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

docs/user/widgets/buttons/buttons.md

@@ -0,0 +1,50 @@
+(user.widgets.buttons)=
+
+# Service Buttons
+
+````{tab} Overview
+
+This section consolidates various custom buttons used within the BEC GUIs, providing essential controls for managing operations and processes. These buttons are designed for easy integration into different layouts within the BEC environment, allowing users to embed functional controls into their applications seamlessly.
+
+## Stop Button
+
+The `Stop Button` is a specialized control that provides an immediate interface to halt ongoing operations in the BEC Client. It is essential for scenarios where operations need to be terminated quickly, such as in the case of an error or when an operation needs to be interrupted by the user.
+
+**Key Features:**
+- **Immediate Termination**: Instantly halts the execution of the current script or process.
+- **Queue Management**: Clears any pending operations in the scan queue, ensuring the system is reset and ready for new tasks.
+
+````
+
+````{tab} Examples
+
+Integrating the `StopButton` into a BEC GUI layout is straightforward. The following example demonstrates how to embed a `StopButton` within a custom GUI layout using `QtWidgets`.
+
+## Example 1 - Embedding a Stop Button in a Custom GUI Layout
+
+This example shows how to create a simple GUI layout with a `StopButton` integrated, allowing the user to halt processes directly from the interface.
+
+```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)
+
+# Example of how this custom GUI might be used:
+my_gui = MyGui()
+my_gui.show()
+```
+````
+
+````{tab} API
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.StopButton.rst
+```
+````

docs/user/widgets/device_input/device_input.md

@@ -0,0 +1,100 @@
+(user.widgets.device_input)=
+
+# Device Input Widgets
+
+````{tab} Overview
+
+The `Device Input Widgets` consist of two primary widgets: `DeviceLineEdit` and `DeviceComboBox`. Both widgets are designed to facilitate the selection of devices within the BEC environment, allowing users to filter, search, and select devices dynamically. These widgets are highly customizable and can be integrated into a GUI either through direct code instantiation or by using `QtDesigner`.
+
+## DeviceLineEdit
+The `DeviceLineEdit` widget provides a line edit interface with autocomplete functionality for device names, making it easier for users to quickly search and select devices.
+
+## DeviceComboBox
+The `DeviceComboBox` widget offers a dropdown interface for device selection, providing a more visual way to browse through available devices.
+
+## Key Features:
+- **Device Filtering**: Both widgets allow users to filter devices by their class names, ensuring that only relevant devices are shown.
+- **Default Device Setting**: Users can set a default device to be pre-selected when the widget is initialized.
+- **Real-Time Autocomplete (LineEdit)**: The `DeviceLineEdit` widget supports real-time autocomplete, helping users find devices faster.
+- **Dropdown Selection (ComboBox)**: The `DeviceComboBox` widget displays devices in a dropdown list, making selection straightforward.
+- **QtDesigner Integration**: Both widgets can be added as custom widgets in `QtDesigner` or instantiated directly in code.
+
+````
+
+````{tab} Examples
+
+Both `DeviceLineEdit` and `DeviceComboBox` can be integrated within a GUI application through direct code instantiation or by using `QtDesigner`. Below are examples demonstrating how to create and use these widgets.
+
+
+## Example 1 - Creating a DeviceLineEdit in Code
+
+In this example, we demonstrate how to create a `DeviceLineEdit` widget in code and customize its behavior.
+
+```python
+from qtpy.QtWidgets import QApplication, QVBoxLayout, QWidget
+from bec_widgets.widgets.device_line_edit import DeviceLineEdit
+
+class MyGui(QWidget):
+    def __init__(self):
+        super().__init__()
+        self.setLayout(QVBoxLayout(self))  # Initialize the layout for the widget
+
+        # Create and add the DeviceLineEdit to the layout
+        self.device_line_edit = DeviceLineEdit(device_filter="Motor")
+        self.layout().addWidget(self.device_line_edit)
+
+# Example of how this custom GUI might be used:
+app = QApplication([])
+my_gui = MyGui()
+my_gui.show()
+app.exec_()
+```
+
+## Example 2 - Creating a DeviceComboBox in Code
+
+Similarly, here is an example of creating a `DeviceComboBox` widget in code and customizing its behavior.
+
+```python
+from qtpy.QtWidgets import QApplication, QVBoxLayout, QWidget
+from bec_widgets.widgets.device_combo_box import DeviceComboBox
+
+class MyGui(QWidget):
+    def __init__(self):
+        super().__init__()
+        self.setLayout(QVBoxLayout(self))  # Initialize the layout for the widget
+
+        # Create and add the DeviceComboBox to the layout
+        self.device_combo_box = DeviceComboBox(device_filter="Motor")
+        self.layout().addWidget(self.device_combo_box)
+
+# Example of how this custom GUI might be used:
+app = QApplication([])
+my_gui = MyGui()
+my_gui.show()
+app.exec_()
+```
+
+## Example 3 - Setting Default Device
+
+Both `DeviceLineEdit` and `DeviceComboBox` allow you to set a default device that will be selected when the widget is initialized.
+
+```python
+# Set default device for DeviceLineEdit
+self.device_line_edit.set_default_device("motor1")
+
+# Set default device for DeviceComboBox
+self.device_combo_box.set_default_device("motor2")
+```
+````
+
+````{tab} API - ComboBox
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.DeviceComboBox.rst
+```
+````
+
+````{tab} API - LineEdit
+```{eval-rst}
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.DeviceLineEdit.rst
+```
+````

docs/user/widgets/dock_area/bec_dock_area.md

@@ -0,0 +1,105 @@
+(user.widgets.bec_dock_area)=
+
+# BECDockArea
+
+```{tab} Overview
+
+[`BECDockArea`](/api_reference/_autosummary/bec_widgets.cli.client.BECDockArea) is a powerful and flexible container designed to host various widgets and docks within a grid layout. It provides an environment for organizing and managing complex user interfaces, making it ideal for applications that require multiple tools and data visualizations to be displayed simultaneously. BECDockArea is particularly useful for embedding not only visualization tools but also other interactive components, allowing users to tailor their workspace to their specific needs.
+
+- **Flexible Dock Management**: Easily add, remove, and rearrange docks within `BECDockArea`, providing a customized layout for different tasks.
+- **State Persistence**: Save and restore the state of the dock area, enabling consistent user experiences across sessions.
+- **Dock Customization**: Add docks with customizable positions, names, and behaviors, such as floating or closable docks.
+- **Integration with Widgets**: Integrate various widgets like [`WaveformWidget`](user.widgets.waveform_widget), [`ImageWidget`](user.widgets.image_widget), and [`MotorMapWidget`](user.widgets.motor_map) into `BECDockArea`, either as standalone tools or as part of a more complex interface.
+```
+
+````{tab} Examples - CLI
+In the following examples, we will use `BECIPythonClient` as the main object to interact with the `BECDockArea`. These tutorials focus on how to work with the `BECDockArea` framework, such as adding and removing docks, saving and restoring layouts, and managing the docked widgets. By default the `BECDockArea` is refered as `gui` in `BECIPythonClient`. For more detailed examples of each individual component, please refer to the example sections of each individual [`widget`](user.widgets).
+
+## Example 1 - Adding Docks to BECDockArea
+
+In this example, we will demonstrate how to add different docks to a single `BECDockArea` widget. New docks are always added to the bottom of the dock area by default; however, you can specify the position of the dock by using the `position` and `relative_to` arguments.
+
+```python
+# Add a new dock with a WaveformWidget to the BECDockArea
+dock1 = gui.add_dock(name="Waveform Dock", widget="BECWaveformWidget")
+
+# Add a second dock with a MotorMapWidget to the BECDockArea to the right of the first dock
+dock2 = gui.add_dock(name="Motor Map Dock", widget="BECMotorMapWidget",relative_to="Waveform Dock", position="right")
+
+# Add a third dock with an ImageWidget to the BECDockArea, placing it on bottom of the dock area
+dock3 = gui.add_dock(name="Image Dock", widget="BECImageWidget")
+```
+
+```{hint}
+You can move docks around by dragging them with the mouse using the dock's title bar. The dock will snap to the grid layout of the dock area.
+```
+
+## Example 2 - Access of Docks in BECDockArea
+
+Docks can be accessed by their name or by the dock object. The dock object can be used to modify the dock properties or to add widgets to the dock.
+
+```python
+# All docks can be accessed by their name from the panels dictionary
+gui.panels
+
+# Output
+{'Waveform Dock': <BECDock object at 0x168b983d0>,
+ 'Motor Map Dock': <BECDock object at 0x13a969250>,
+ 'Image Dock': <BECDock object at 0x13f267950>}
+ 
+# Access the dock by its name
+dock1 = gui.panels["Waveform Dock"]
+
+# Access the widget object of the dock
+waveform_widget = dock1.widget_list[0]
+```
+
+## Example 3 - Detaching and Attaching Docks in BECDockArea
+
+Docks in `BECDockArea` can be detached (floated) or reattached to the main dock area. This is useful when you want to temporarily undock a widget for better visibility or organization. 
+
+```python
+# Detach the dock named "Waveform Dock"
+gui.detach_dock(dock_name="Waveform Dock")
+
+# Docks can be also detached by the dock object
+dock2.detach()
+dock3.detach()
+
+# Docks can be individually reattached to the main dock area
+dock2.attach()
+
+# Reattach all floating docks to the main dock area
+gui.attach_all()
+```
+
+```{note}
+Floating docks are always returned to the original dock area if they are closed manually. Docks can also be detached by double-clicking on the dock title.
+```
+
+## Example 4 - Removing Docks from BECDockArea
+
+Docks can be removed from the dock area by their name or by the dock object. The dock object can be used to remove the dock from the dock area.
+
+```python
+# Removing docks by their name
+gui.remove_dock(dock_name="Waveform Dock")
+
+# Removing docks by the dock object
+dock2.remove()
+
+# Removing all docks from the dock area
+gui.clear_all()
+```
+
+```{warning}
+When removing a dock, all widgets within the dock will be removed as well. This action cannot be undone, and all references to the dock and its widgets will be lost.
+```
+````
+
+````{tab} API
+```{eval-rst} 
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.BECDockArea.rst
+```
+````
+

docs/user/widgets/image/image_widget.md

@@ -0,0 +1,84 @@
+(user.widgets.image_widget)=
+
+# Image Widget
+
+````{tab} Overview
+
+The Image Widget is a versatile tool designed for visualizing 2D image data, such as camera images, in real-time. Directly integrated with the `BEC` framework, it can display live data streams from connected cameras or other image sources within the current `BEC` session. The widget provides advanced customization options for color maps and scale bars, allowing users to tailor the visualization to their specific needs.
+
+## 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`.
+- **Live Data Visualization**: Real-time plotting of 2D image data from cameras or other image sources, provided that a data stream is available in the BEC session.
+- **Customizable Color Maps and Scale Bars**: Users can customize the appearance of images with various color maps and adjust scale bars to better interpret the visualized data.
+- **Real-time Image Processing**: Apply real-time image processing techniques directly within the widget to enhance the quality or analyze specific aspects of the images such as rotation, log scaling, and FFT.
+- **Data Export**: Export visualized image data to various formats such as PNG, TIFF, or H5 for further analysis or reporting.
+- **Interactive Controls**: Offers interactive controls for zooming, panning, and adjusting the visual properties of the images on the fly.
+
+![Image 2D](./image_plot.gif)
+````
+
+````{tab} Examples - CLI
+
+`ImageWidget` can be embedded in both [`BECFigure`](user.widgets.bec_figure) and [`BECDockArea`](user.widgets.bec_dock_area), 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 Image Widget to BECFigure
+
+In this example, we demonstrate how to add an `ImageWidget` to a [`BECFigure`](user.widgets.bec_figure) to visualize live data from a connected camera.
+
+```python
+# Add a new dock with BECFigure widget
+fig = gui.add_dock().add_widget('BECFigure')
+
+# Add an ImageWidget to the BECFigure
+img_widget = fig.image(source='eiger')
+img_widget.set_title("Camera Image Eiger")
+```
+
+## Example 2 - Adding Image Widget as a Dock in BECDockArea
+
+Adding `ImageWidget` into a [`BECDockArea`](user.widgets.bec_dock_area) is similar to adding any other widget. The widget has the same API as the one in [`BECFigure`](user.widgets.bec_figure); however, as an independent widget outside [`BECFigure`](user.widgets.bec_figure), it has its own toolbar, allowing users to configure the widget without needing CLI commands.
+
+```python
+# Add an ImageWidget to the BECDockArea
+img_widget = gui.add_dock().add_widget('BECImageWidget')
+
+# Visualize live data from a camera with range from 0 to 100
+img_widget.image(source='eiger')
+img_widget.set_vrange(vmin=0, vmax=100)
+```
+
+## Example 3 - Customizing Image Display
+
+This example demonstrates how to customize the color map and scale bar for an image being visualized in an `ImageWidget`.
+
+```python
+# Set the color map and adjust the scale bar range
+img_widget.set_colormap("viridis")
+img_widget.set_vrange(vmin=10, vmax=200)
+```
+
+## Example 4 - Real-time Image Processing
+
+The `ImageWidget` provides real-time image processing capabilities, such as rotating, scaling, and applying FFT to the displayed images. The following example demonstrates how to rotate an image by 90 degrees, transpose it, and apply FFT.
+
+```python
+# Rotate the image by 90 degrees
+img_widget.set_rotation(deg_90=1)
+
+# Transpose the image
+img_widget.set_transpose(enable=True)
+
+# Apply FFT to the image
+img_widget.set_fft(enable=True)
+
+# Set the logarithmic scale for the image display
+img_widget.set_log(enable=True)
+```
+
+````
+
+````{tab} API
+```{eval-rst}  
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.BECImageWidget.rst
+```
+````

docs/user/widgets/motor_map/motor_map.md

@@ -0,0 +1,80 @@
+(user.widgets.motor_map)=
+
+# Motor Map Widget
+
+````{tab} Overview
+
+The Motor Map Widget is a specialized tool for tracking and visualizing the positions of motors in real-time. This widget is crucial for applications requiring precise alignment and movement tracking during scans. It provides an intuitive way to monitor motor trajectories, ensuring accurate positioning throughout the scanning process.
+
+## 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`.
+- **Real-time Motor Position Visualization**: Tracks motor positions in real-time and visually represents motor trajectories.
+- **Customizable Visual Elements**: The appearance of all widget components is fully customizable, including scatter size and background values.
+- **Interactive Controls**: Interactive controls for zooming, panning, and adjusting the visual properties of motor trajectories on the fly.
+
+![MotorMap](./motor.gif)
+````
+
+````{tab} Examples CLI
+`MotorMapWidget` can be embedded in both [`BECFigure`](user.widgets.bec_figure) and [`BECDockArea`](user.widgets.bec_dock_area), 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 Motor Map Widget to BECFigure
+
+In this example, we will demonstrate how to add two different `MotorMapWidgets` into a single [`BECFigure`](user.widgets.bec_figure) widget.
+
+```python
+# Add new dock with BECFigure widget
+fig = gui.add_dock().add_widget('BECFigure')
+
+# Add two WaveformWidgets to the BECFigure
+mm1 = fig.motor_map(motor_x='samx', motor_y='samy')
+mm2 = fig.motor_map(motor_x='aptrx', motor_y='aptry',new=True)
+```
+
+## Example 2 - Adding Motor Map Widget as a Dock in BECDockArea
+
+Adding `MotorMapWidget` into a [`BECDockArea`](user.widgets.bec_dock_area) 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 MotorMaps to the BECDockArea
+mm1 = gui.add_dock().add_widget('BECMotorMapWidget')
+mm2 = gui.add_dock().add_widget('BECMotorMapWidget')
+
+# Add signals to the MotorMaps
+mm1.change_motors(motor_x='samx', motor_y='samy')
+mm2.change_motors(motor_x='aptrx', motor_y='aptry')
+```
+
+## Example 3 - Customizing Motor Map Display
+
+The `MotorMapWidget` allows customization of its visual elements to better suit the needs of your application. Below is an example of how to adjust the scatter size, set background values, and limit the number of points displayed from the position buffer.
+
+```python
+# Set scatter size
+mm1.set_scatter_size(scatter_size=5)
+
+# Set background value
+mm1.set_background_value(background_value=0)
+
+# Limit the number of points displayed and saved in the position buffer
+mm1.set_max_points(max_points=500)
+```
+
+## Example 4 - Changing Motors and Resetting History
+
+You can dynamically change the motors being tracked and reset the history of the motor trajectories during the session.
+
+```python
+# Reset the history of motor movements
+mm1.reset_history()
+
+# Change the motors being tracked
+mm1.change_motors(motor_x='aptrx', motor_y='aptry')
+```
+````
+
+````{tab} API
+```{eval-rst}  
+.. include:: /api_reference/_autosummary/bec_widgets.cli.client.BECMotorMap.rst
+```
+````

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/ring_progress_bar.md

@@ -1,54 +0,0 @@
-(user.widgets.spiral_progress_bar)=
-# [Ring Progress Bar](/api_reference/_autosummary/bec_widgets.cli.client.RingProgressBar)
-
-**Purpose:**
-
-The ring 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:**
-
-- circular progress bar to show updates on the progress of a task.
-- hooks to update the progress bar from a device readback or scan.
-- multiple progress rings to show different tasks in parallel.
-
-**Example of Use:**
-![RingProgressBar](./progress_bar.gif)
-
-**Code example:**
-
-The following code snipped demonstrates how to create a `RingProgressBar` using BEC Widgets within BEC.
-```python
-# adds a new dock with a ring progress bar
-progress = gui.add_dock().add_widget("RingProgressBar")
-# customize the size of the ring
-progress.set_line_width(20)
-```
-
-By default, the Ring Progress Bar widget will display a single ring. To add more rings, use the add_ring method:
-
-```python
-# adds a new dock with a ring 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 `RingProgressBar` 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)
-```
-

docs/user/widgets/scan_control.md

@@ -1,35 +0,0 @@
-(user.widgets.scan_control)=
-
-# Scan Control
-
-**Purpose:**
-
-The `ScanControl` widget is designed to generate a graphical user interface (GUI) to control various scan operations
-based on the scan's signature and `gui_config`. The widget is used to control the scan operations, such as starting,
-stopping, and pausing the scan. The widget also provides a graphical representation of the scan progress and the scan
-status. The widget is designed to be used in conjunction with the `ScanServer` and `ScanBundler` services from the BEC
-core services.
-
-By default the widget supports only the scans which have defined `gui_config` and are inhereted from these scan classes:
-
-- [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)
-
-**Key Features:**
-
-- Automatically generates a control interface based on scan signatures and `gui_config`.
-- Supports adding and removing argument bundles dynamically.
-- Provides a visual representation of scan parameters grouped by functionality.
-- Integrates start and stop controls for executing and halting scans.
-
-**Example of Use:**
-
-**Code example:**
-The following code snipped demonstrates how to create a `ScanControl` widget using BEC Widgets within `BECIPythonClient`
-
-![ScanControl](./scan_control.gif)
-
-```python
-scan_control = gui.add_dock().add_widget("ScanControl")
-```

docs/user/widgets/scan_control/scan_control.md

@@ -0,0 +1,41 @@
+(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 `ScanServer` and `ScanBundler` services from the BEC core, enabling users to start and stop. The widget automatically generates controls 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)
+```
+````
+
+````{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.md

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

docs/user/widgets/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
+```
+````

docs/user/widgets/website.md

@@ -1,21 +0,0 @@
-(user.widgets.website)=
-# [Website Widget](/api_reference/_autosummary/bec_widgets.cli.client.WebsiteWidget)
-**Purpose:**
-
-The Website Widget is a widget that allows you to display a website within the BEC GUI. The widget can be used to display any website. 
-
-**Key Features:**
-
-- set the URL of the website to display.
-- reload the website.
-- navigate back and forward in the website history.
-
-**Code example:**
-
-The following code snipped demonstrates how to create a `WebsiteWidget` using BEC Widgets within BEC.
-```python
-# adds a new dock with a website widget
-web = gui.add_dock().add_widget("Website")
-# set the URL of the website to display
-web.set_url("https://bec.readthedocs.io/en/latest/")
-```

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

@@ -2,19 +2,207 @@
 # 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}
+## Widget Frameworks
----
-maxdepth: 2
-hidden: false
----
 
-bec_figure/
+Serves as containers to organise and display other widgets.
-ring_progress_bar/
+
-website/
+````{grid} 3
-buttons/
+:gutter: 2
-text_box/
+
-bec_status_box/
+```{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}  Positioner Box
+:link: user.widgets.positioner_box
+:link-type: ref
+:img-top: /assets/widget_screenshots/device_box.png
+
+Control individual device.
+```
+
+```{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
+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
+
+```