diff --git a/docs/references/bec-widgets/widget-gallery.md b/docs/references/bec-widgets/widget-gallery.md deleted file mode 100644 index 74ef29d..0000000 --- a/docs/references/bec-widgets/widget-gallery.md +++ /dev/null @@ -1,15 +0,0 @@ -# Widget Gallery - -Placeholder for the widget gallery reference page. - -## Overview - -Placeholder. - -## Key points - -Placeholder. - -## Related topics - -Placeholder. diff --git a/docs/references/bec-widgets/widget-gallery/bec_progressbar/assets/bec_progressbar.png b/docs/references/bec-widgets/widget-gallery/bec_progressbar/assets/bec_progressbar.png new file mode 100644 index 0000000..92c4278 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/bec_progressbar/assets/bec_progressbar.png differ diff --git a/docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_cli_examples.md b/docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_cli_examples.md new file mode 100644 index 0000000..5feb851 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_cli_examples.md @@ -0,0 +1,21 @@ + + +Create and update a progress bar: + +```python +progress = gui.bec.new(gui.available_widgets.BECProgressBar) +progress.set_minimum(0) +progress.set_maximum(100) +progress.set_value(25) +``` + +Customize the displayed label: + +```python +progress.label_template = "$value / $maximum ($percentage %)" +``` diff --git a/docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_description.md b/docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_description.md new file mode 100644 index 0000000..9b93123 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_description.md @@ -0,0 +1,3 @@ +BECProgressBar is a linear progress indicator with a configurable label template. Use it for custom progress feedback in utility layouts. + +![BECProgressBar widget](assets/bec_progressbar.png) diff --git a/docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_page.md b/docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_page.md new file mode 100644 index 0000000..8ec85e6 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_page.md @@ -0,0 +1,22 @@ +# BECProgressBar + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.progress.bec_progressbar.bec_progressbar.BECProgressBar + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/bec_queue/assets/queue.png b/docs/references/bec-widgets/widget-gallery/bec_queue/assets/queue.png new file mode 100644 index 0000000..a2ca0d3 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/bec_queue/assets/queue.png differ diff --git a/docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_cli_examples.md b/docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_cli_examples.md new file mode 100644 index 0000000..76590a4 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_cli_examples.md @@ -0,0 +1,22 @@ + + +Create the queue widget: + +```python +queue = gui.bec.new(gui.available_widgets.BECQueue) +``` + +Place it next to a ScanControl widget: + +```python +queue = gui.bec.new( + gui.available_widgets.BECQueue, + where="right", + relative_to="ScanControl", +) +``` diff --git a/docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_description.md b/docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_description.md new file mode 100644 index 0000000..c2107ac --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_description.md @@ -0,0 +1,3 @@ +BECQueue displays the scan queue and queue control buttons. Use it when an operator needs queue status visible in the Dock Area. + +![BECQueue widget](assets/queue.png) diff --git a/docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_page.md b/docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_page.md new file mode 100644 index 0000000..08d8c26 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/bec_queue/bec_queue_page.md @@ -0,0 +1,22 @@ +# BECQueue + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/bec_queue/bec_queue_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/bec_queue/bec_queue_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.services.bec_queue.bec_queue.BECQueue + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/bec_status_box/assets/status_box.png b/docs/references/bec-widgets/widget-gallery/bec_status_box/assets/status_box.png new file mode 100644 index 0000000..57206c7 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/bec_status_box/assets/status_box.png differ diff --git a/docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_cli_examples.md b/docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_cli_examples.md new file mode 100644 index 0000000..9510115 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_cli_examples.md @@ -0,0 +1,18 @@ + + +Create a status box: + +```python +status = gui.bec.new(gui.available_widgets.BECStatusBox) +``` + +Read the current top-level server state: + +```python +state = status.get_server_state() +``` diff --git a/docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_description.md b/docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_description.md new file mode 100644 index 0000000..af19b6c --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_description.md @@ -0,0 +1,3 @@ +BECStatusBox displays the status of core BEC services. Use it in operational layouts where service health should be visible at a glance. + +![BECStatusBox widget](assets/status_box.png) diff --git a/docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_page.md b/docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_page.md new file mode 100644 index 0000000..8293899 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_page.md @@ -0,0 +1,22 @@ +# BECStatusBox + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.services.bec_status_box.bec_status_box.BECStatusBox + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/dap_combo_box/assets/dap_combo_box.png b/docs/references/bec-widgets/widget-gallery/dap_combo_box/assets/dap_combo_box.png new file mode 100644 index 0000000..1fa315e Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/dap_combo_box/assets/dap_combo_box.png differ diff --git a/docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_cli_examples.md b/docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_cli_examples.md new file mode 100644 index 0000000..09c58df --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_cli_examples.md @@ -0,0 +1,17 @@ + + +Create a DapComboBox and select axes/model: + +```python +dap = gui.bec.new(gui.available_widgets.DapComboBox) +dap.select_x_axis("samx") +dap.select_y_axis("bpm4i") +dap.select_fit_model("GaussianModel") +``` + +The model name must be available in the current DAP service. Invalid model names raise an error. diff --git a/docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_description.md b/docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_description.md new file mode 100644 index 0000000..086100b --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_description.md @@ -0,0 +1,3 @@ +DapComboBox lists available DAP models and can emit a DAP configuration when x-axis, y-axis, and model are selected. Most users interact with DAP through Waveform, but this widget is useful in custom GUI compositions. + +![DapComboBox widget](assets/dap_combo_box.png) diff --git a/docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_page.md b/docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_page.md new file mode 100644 index 0000000..6c08968 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_page.md @@ -0,0 +1,22 @@ +# DapComboBox + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.dap.dap_combo_box.dap_combo_box.DapComboBox + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/device_browser/assets/device_browser.png b/docs/references/bec-widgets/widget-gallery/device_browser/assets/device_browser.png new file mode 100644 index 0000000..8ac52d8 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/device_browser/assets/device_browser.png differ diff --git a/docs/references/bec-widgets/widget-gallery/device_browser/device_browser_cli_examples.md b/docs/references/bec-widgets/widget-gallery/device_browser/device_browser_cli_examples.md new file mode 100644 index 0000000..81f8d28 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/device_browser/device_browser_cli_examples.md @@ -0,0 +1,22 @@ + + +Create a DeviceBrowser widget: + +```python +devices = gui.bec.new(gui.available_widgets.DeviceBrowser) +``` + +Place it beside the current Waveform: + +```python +devices = gui.bec.new( + gui.available_widgets.DeviceBrowser, + where="right", + relative_to="Waveform", +) +``` diff --git a/docs/references/bec-widgets/widget-gallery/device_browser/device_browser_description.md b/docs/references/bec-widgets/widget-gallery/device_browser/device_browser_description.md new file mode 100644 index 0000000..ab2df33 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/device_browser/device_browser_description.md @@ -0,0 +1,5 @@ +DeviceBrowser shows the devices available in the current BEC session. Use it to inspect configured devices and browse their metadata from the GUI. + +![DeviceBrowser widget](assets/device_browser.png) + +The useful interactions are GUI-based; from the BEC IPython client, create it in the Dock Area and then interact with the displayed device list. diff --git a/docs/references/bec-widgets/widget-gallery/device_browser/device_browser_page.md b/docs/references/bec-widgets/widget-gallery/device_browser/device_browser_page.md new file mode 100644 index 0000000..11f56fd --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/device_browser/device_browser_page.md @@ -0,0 +1,22 @@ +# DeviceBrowser + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/device_browser/device_browser_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/device_browser/device_browser_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.services.device_browser.device_browser.DeviceBrowser + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/heatmap/assets/heatmap_widget.png b/docs/references/bec-widgets/widget-gallery/heatmap/assets/heatmap_widget.png new file mode 100644 index 0000000..cdc46ad Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/heatmap/assets/heatmap_widget.png differ diff --git a/docs/references/bec-widgets/widget-gallery/heatmap/heatmap_cli_examples.md b/docs/references/bec-widgets/widget-gallery/heatmap/heatmap_cli_examples.md new file mode 100644 index 0000000..14ddde4 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/heatmap/heatmap_cli_examples.md @@ -0,0 +1,39 @@ + + +Create a Heatmap for `samx`, `samy`, and `bpm4i`: + +```python +heatmap = gui.bec.new(gui.available_widgets.Heatmap) +heatmap.plot( + device_x="samx", + device_y="samy", + device_z="bpm4i", + color_map="plasma", +) +``` + +Adjust interpolation and display settings: + +```python +heatmap.interpolation_method = "nearest" +heatmap.oversampling_factor = 2.0 +heatmap.enable_full_colorbar = True +``` + +Reload with explicit plotting options: + +```python +heatmap.plot( + device_x="samx", + device_y="samy", + device_z="bpm4i", + interpolation="linear", + oversampling_factor=1.5, + reload=True, +) +``` diff --git a/docs/references/bec-widgets/widget-gallery/heatmap/heatmap_description.md b/docs/references/bec-widgets/widget-gallery/heatmap/heatmap_description.md new file mode 100644 index 0000000..3d2b469 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/heatmap/heatmap_description.md @@ -0,0 +1,9 @@ +Heatmap displays 2D scan data using a color-mapped image. It is the right choice for grid scans and for step scans that should be interpolated onto a 2D surface. + +![Heatmap widget](assets/heatmap_widget.png) + +Common uses: + +- plot `x`, `y`, and detector intensity from grid scans +- interpolate irregular step-scan points +- tune oversampling, interpolation, and color maps diff --git a/docs/references/bec-widgets/widget-gallery/heatmap/heatmap_page.md b/docs/references/bec-widgets/widget-gallery/heatmap/heatmap_page.md new file mode 100644 index 0000000..66a34b3 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/heatmap/heatmap_page.md @@ -0,0 +1,22 @@ +# Heatmap + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/heatmap/heatmap_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/heatmap/heatmap_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.plots.heatmap.heatmap.Heatmap + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/image/assets/image_widget.png b/docs/references/bec-widgets/widget-gallery/image/assets/image_widget.png new file mode 100644 index 0000000..0641d51 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/image/assets/image_widget.png differ diff --git a/docs/references/bec-widgets/widget-gallery/image/image_cli_examples.md b/docs/references/bec-widgets/widget-gallery/image/image_cli_examples.md new file mode 100644 index 0000000..3e0c400 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/image/image_cli_examples.md @@ -0,0 +1,29 @@ + + +Create an Image widget and connect it to a detector signal. Replace `camera` and `image` with the device and signal names used at your beamline: + +```python +img = gui.bec.new(gui.available_widgets.Image) +img.device = "camera" +img.signal = "image" +``` + +Adjust the display: + +```python +img.color_map = "viridis" +img.enable_full_colorbar = True +img.log = True +``` + +Add and remove an ROI: + +```python +img.add_roi(name="beam_roi") +img.remove_roi("beam_roi") +``` diff --git a/docs/references/bec-widgets/widget-gallery/image/image_description.md b/docs/references/bec-widgets/widget-gallery/image/image_description.md new file mode 100644 index 0000000..edadde6 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/image/image_description.md @@ -0,0 +1,10 @@ +Image displays 2D data from detector signals. Use it for cameras, area detectors, and other image-like data streams that should be inspected as an image rather than as a curve. + +![Image widget](assets/image_widget.png) + +Common uses: + +- display live 2D detector output +- adjust color map and color range +- apply log or FFT display transformations +- create image ROIs for inspection diff --git a/docs/references/bec-widgets/widget-gallery/image/image_page.md b/docs/references/bec-widgets/widget-gallery/image/image_page.md new file mode 100644 index 0000000..af7eae4 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/image/image_page.md @@ -0,0 +1,22 @@ +# Image + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/image/image_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/image/image_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.plots.image.image.Image + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/index.md b/docs/references/bec-widgets/widget-gallery/index.md new file mode 100644 index 0000000..b503c29 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/index.md @@ -0,0 +1,48 @@ +# Widget Gallery + +This gallery lists the core BEC Widgets that are useful from a Dock Area in BEC Widgets V3. Each page shows what the widget is for and includes BEC IPython examples checked against the current source code. + +For general Dock Area placement commands, see +[Add Widgets to a Dock Area](../../../how-to/gui/add-widgets-to-dock-area.md){ data-preview }. + +## Plotting + +| Widget | Use it for | +| --- | --- | +| [Waveform](waveform/waveform_page.md) | Plot 1D live, history, or custom data and attach DAP model curves. | +| [MultiWaveform](multi_waveform/multi_waveform_page.md) | Display repeated waveform traces from one monitor signal. | +| [ScatterWaveform](scatter_waveform/scatter_waveform_page.md) | Plot x/y scan coordinates with a third signal as color. | +| [Image](image/image_page.md) | Display 2D detector images with color mapping and image processing controls. | +| [Heatmap](heatmap/heatmap_page.md) | Display 2D scan data as a color-mapped heatmap. | +| [MotorMap](motor_map/motor_map_page.md) | Track two motor positions and recent movement history. | + +## Control + +| Widget | Use it for | +| --- | --- | +| [ScanControl](scan_control/scan_control_page.md) | GUI control for selecting and submitting scans. | +| [DeviceBrowser](device_browser/device_browser_page.md) | Browse configured BEC devices in the GUI. | +| [PositionerBox](positioner_box/positioner_box_page.md) | Control one positioner from the Dock Area. | +| [PositionerBox2D](positioner_box_2d/positioner_box_2d_page.md) | Control two positioners as horizontal and vertical axes. | +| [PositionerGroup](positioner_group/positioner_group_page.md) | Display several PositionerBox controls in one grid. | +| [PositionIndicator](position_indicator/position_indicator_page.md) | Display a numeric position within a range. | + +## Services + +| Widget | Use it for | +| --- | --- | +| [BECQueue](bec_queue/bec_queue_page.md) | Show the current BEC scan queue. | +| [BECStatusBox](bec_status_box/bec_status_box_page.md) | Display BEC service health status. | + +## Utilities + +| Widget | Use it for | +| --- | --- | +| [RingProgressBar](ring_progress_bar/ring_progress_bar_page.md) | Display one or more circular progress indicators. | +| [BECProgressBar](bec_progressbar/bec_progressbar_page.md) | Display a linear progress value with a configurable label. | +| [TextBox](text_box/text_box_page.md) | Display plain text or HTML content. | +| [WebsiteWidget](website_widget/website_widget_page.md) | Embed a web page in the Dock Area. | +| [SignalLabel](signal_label/signal_label_page.md) | Display a selected signal value in a compact label. | +| [LogPanel](log_panel/log_panel_page.md) | Display and filter BEC logs. | +| [PdfViewerWidget](pdf_viewer_widget/pdf_viewer_widget_page.md) | Display and navigate PDF documents. | +| [DapComboBox](dap_combo_box/dap_combo_box_page.md) | Select a DAP model and emit a DAP configuration. | diff --git a/docs/references/bec-widgets/widget-gallery/log_panel/assets/logpanel.png b/docs/references/bec-widgets/widget-gallery/log_panel/assets/logpanel.png new file mode 100644 index 0000000..d964d3c Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/log_panel/assets/logpanel.png differ diff --git a/docs/references/bec-widgets/widget-gallery/log_panel/log_panel_cli_examples.md b/docs/references/bec-widgets/widget-gallery/log_panel/log_panel_cli_examples.md new file mode 100644 index 0000000..f58bc4e --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/log_panel/log_panel_cli_examples.md @@ -0,0 +1,22 @@ + + +Create a LogPanel: + +```python +logs = gui.bec.new(gui.available_widgets.LogPanel) +``` + +Place it below an existing Waveform: + +```python +logs = gui.bec.new( + gui.available_widgets.LogPanel, + where="bottom", + relative_to="Waveform", +) +``` diff --git a/docs/references/bec-widgets/widget-gallery/log_panel/log_panel_description.md b/docs/references/bec-widgets/widget-gallery/log_panel/log_panel_description.md new file mode 100644 index 0000000..e0a13ca --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/log_panel/log_panel_description.md @@ -0,0 +1,3 @@ +LogPanel displays BEC log messages and provides GUI-side filtering controls. Use it in diagnostic layouts when logs should stay visible beside plots or controls. + +![LogPanel widget](assets/logpanel.png) diff --git a/docs/references/bec-widgets/widget-gallery/log_panel/log_panel_page.md b/docs/references/bec-widgets/widget-gallery/log_panel/log_panel_page.md new file mode 100644 index 0000000..5c9f154 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/log_panel/log_panel_page.md @@ -0,0 +1,22 @@ +# LogPanel + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/log_panel/log_panel_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/log_panel/log_panel_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.utility.logpanel.logpanel.LogPanel + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/motor_map/assets/motor_map_widget.png b/docs/references/bec-widgets/widget-gallery/motor_map/assets/motor_map_widget.png new file mode 100644 index 0000000..d506591 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/motor_map/assets/motor_map_widget.png differ diff --git a/docs/references/bec-widgets/widget-gallery/motor_map/motor_map_cli_examples.md b/docs/references/bec-widgets/widget-gallery/motor_map/motor_map_cli_examples.md new file mode 100644 index 0000000..8d759ba --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/motor_map/motor_map_cli_examples.md @@ -0,0 +1,28 @@ + + +Create a MotorMap for two motors: + +```python +mm = gui.bec.new(gui.available_widgets.MotorMap) +mm.map(device_x="samx", device_y="samy") +``` + +Adjust the displayed history: + +```python +mm.max_points = 100 +mm.scatter_size = 8 +mm.precision = 3 +``` + +Read and reset the map data: + +```python +data = mm.get_data() +mm.reset_history() +``` diff --git a/docs/references/bec-widgets/widget-gallery/motor_map/motor_map_description.md b/docs/references/bec-widgets/widget-gallery/motor_map/motor_map_description.md new file mode 100644 index 0000000..9207e53 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/motor_map/motor_map_description.md @@ -0,0 +1,9 @@ +MotorMap visualizes the current and recent positions of two positioners. Use it to keep spatial context while moving motors or running 2D scans. + +![MotorMap widget](assets/motor_map_widget.png) + +Common uses: + +- follow `samx` and `samy` positions +- keep a bounded history of recent points +- inspect the latest motor-map data from Python diff --git a/docs/references/bec-widgets/widget-gallery/motor_map/motor_map_page.md b/docs/references/bec-widgets/widget-gallery/motor_map/motor_map_page.md new file mode 100644 index 0000000..58b168e --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/motor_map/motor_map_page.md @@ -0,0 +1,22 @@ +# MotorMap + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/motor_map/motor_map_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/motor_map/motor_map_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.plots.motor_map.motor_map.MotorMap + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/multi_waveform/assets/multi_waveform.png b/docs/references/bec-widgets/widget-gallery/multi_waveform/assets/multi_waveform.png new file mode 100644 index 0000000..d671170 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/multi_waveform/assets/multi_waveform.png differ diff --git a/docs/references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_cli_examples.md b/docs/references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_cli_examples.md new file mode 100644 index 0000000..b3d760b --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_cli_examples.md @@ -0,0 +1,27 @@ + + +Create the widget and connect it to a monitor signal. Replace `waveform_monitor` with the monitor available at your beamline: + +```python +mwf = gui.bec.new(gui.available_widgets.MultiWaveform) +mwf.plot("waveform_monitor", color_palette="plasma") +``` + +Limit the visible traces and adjust display properties: + +```python +mwf.set_curve_limit(50, flush_buffer=True) +mwf.highlight_last_curve = True +mwf.opacity = 60 +``` + +Clear the displayed traces: + +```python +mwf.clear_curves() +``` diff --git a/docs/references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_description.md b/docs/references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_description.md new file mode 100644 index 0000000..1d62ce9 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_description.md @@ -0,0 +1,9 @@ +MultiWaveform displays many waveform traces from the same monitor signal. Use it when each update produces a full 1D trace and you want to compare recent traces in one plot. + +![MultiWaveform widget](assets/multi_waveform.png) + +Common uses: + +- monitor repeated 1D detector traces +- keep the latest trace highlighted +- limit how many traces remain visible diff --git a/docs/references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_page.md b/docs/references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_page.md new file mode 100644 index 0000000..136745a --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_page.md @@ -0,0 +1,22 @@ +# MultiWaveform + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.plots.multi_waveform.multi_waveform.MultiWaveform + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/assets/pdf_viewer.png b/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/assets/pdf_viewer.png new file mode 100644 index 0000000..4549f52 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/assets/pdf_viewer.png differ diff --git a/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_cli_examples.md b/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_cli_examples.md new file mode 100644 index 0000000..91c5892 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_cli_examples.md @@ -0,0 +1,21 @@ + + +Create a PDF viewer and load a file: + +```python +pdf = gui.bec.new(gui.available_widgets.PdfViewerWidget) +pdf.load_pdf("/path/to/document.pdf") +``` + +Navigate the document: + +```python +pdf.fit_to_width() +pdf.next_page() +pdf.jump_to_page(3) +``` diff --git a/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_description.md b/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_description.md new file mode 100644 index 0000000..a8e2b3a --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_description.md @@ -0,0 +1,3 @@ +PdfViewerWidget displays PDF documents inside the Dock Area. Use it for beamline notes, experiment instructions, or reports that should stay visible during operation. + +![PdfViewerWidget](assets/pdf_viewer.png) diff --git a/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_page.md b/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_page.md new file mode 100644 index 0000000..379ae2a --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_page.md @@ -0,0 +1,20 @@ +# PdfViewerWidget + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_cli_examples.md" + +/// +/// tab | API + +Autogenerated API documentation is temporarily skipped for `PdfViewerWidget`. + +The widget source is importable at runtime, but the current package folder does not contain an `__init__.py` file, so +the static mkdocstrings collector cannot resolve the class reliably yet. + +/// diff --git a/docs/references/bec-widgets/widget-gallery/position_indicator/assets/position_indicator.png b/docs/references/bec-widgets/widget-gallery/position_indicator/assets/position_indicator.png new file mode 100644 index 0000000..2b1c00c Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/position_indicator/assets/position_indicator.png differ diff --git a/docs/references/bec-widgets/widget-gallery/position_indicator/position_indicator_cli_examples.md b/docs/references/bec-widgets/widget-gallery/position_indicator/position_indicator_cli_examples.md new file mode 100644 index 0000000..ee24eca --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/position_indicator/position_indicator_cli_examples.md @@ -0,0 +1,22 @@ + + +Create an indicator and set a range/value: + +```python +indicator = gui.bec.new(gui.available_widgets.PositionIndicator) +indicator.set_range(-5, 5) +indicator.set_value(1.2) +``` + +Change orientation and style: + +```python +indicator.vertical = True +indicator.indicator_width = 4 +indicator.rounded_corners = 6 +``` diff --git a/docs/references/bec-widgets/widget-gallery/position_indicator/position_indicator_description.md b/docs/references/bec-widgets/widget-gallery/position_indicator/position_indicator_description.md new file mode 100644 index 0000000..2bde2c7 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/position_indicator/position_indicator_description.md @@ -0,0 +1,3 @@ +PositionIndicator displays a value inside a defined range. Use it as a compact visual indicator for a motor position, limit span, or derived numeric value. + +![PositionIndicator widget](assets/position_indicator.png) diff --git a/docs/references/bec-widgets/widget-gallery/position_indicator/position_indicator_page.md b/docs/references/bec-widgets/widget-gallery/position_indicator/position_indicator_page.md new file mode 100644 index 0000000..996e633 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/position_indicator/position_indicator_page.md @@ -0,0 +1,22 @@ +# PositionIndicator + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/position_indicator/position_indicator_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/position_indicator/position_indicator_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.control.device_control.position_indicator.position_indicator.PositionIndicator + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/positioner_box/assets/device_box.png b/docs/references/bec-widgets/widget-gallery/positioner_box/assets/device_box.png new file mode 100644 index 0000000..712ed15 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/positioner_box/assets/device_box.png differ diff --git a/docs/references/bec-widgets/widget-gallery/positioner_box/positioner_box_cli_examples.md b/docs/references/bec-widgets/widget-gallery/positioner_box/positioner_box_cli_examples.md new file mode 100644 index 0000000..cfef5ec --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/positioner_box/positioner_box_cli_examples.md @@ -0,0 +1,24 @@ + + +Create a PositionerBox and assign `samx`: + +```python +pos = gui.bec.new(gui.available_widgets.PositionerBox) +pos.set_positioner("samx") +``` + +Place it below a Waveform by dock name: + +```python +pos = gui.bec.new( + gui.available_widgets.PositionerBox, + where="bottom", + relative_to="Waveform", +) +pos.set_positioner("samx") +``` diff --git a/docs/references/bec-widgets/widget-gallery/positioner_box/positioner_box_description.md b/docs/references/bec-widgets/widget-gallery/positioner_box/positioner_box_description.md new file mode 100644 index 0000000..aaf9b56 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/positioner_box/positioner_box_description.md @@ -0,0 +1,3 @@ +PositionerBox controls one positioner device. Use it when a profile or temporary Dock Area layout needs a compact motor control. + +![PositionerBox widget](assets/device_box.png) diff --git a/docs/references/bec-widgets/widget-gallery/positioner_box/positioner_box_page.md b/docs/references/bec-widgets/widget-gallery/positioner_box/positioner_box_page.md new file mode 100644 index 0000000..998004d --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/positioner_box/positioner_box_page.md @@ -0,0 +1,22 @@ +# PositionerBox + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/positioner_box/positioner_box_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/positioner_box/positioner_box_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.control.device_control.positioner_box.positioner_box.positioner_box.PositionerBox + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/positioner_box_2d/assets/positioner_box_2d.png b/docs/references/bec-widgets/widget-gallery/positioner_box_2d/assets/positioner_box_2d.png new file mode 100644 index 0000000..0a7b07a Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/positioner_box_2d/assets/positioner_box_2d.png differ diff --git a/docs/references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_cli_examples.md b/docs/references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_cli_examples.md new file mode 100644 index 0000000..92a9db0 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_cli_examples.md @@ -0,0 +1,21 @@ + + +Create a PositionerBox2D and assign two motors: + +```python +pos2d = gui.bec.new(gui.available_widgets.PositionerBox2D) +pos2d.set_positioner_hor("samx") +pos2d.set_positioner_ver("samy") +``` + +Disable one axis control temporarily: + +```python +pos2d.enable_controls_hor = False +pos2d.enable_controls_hor = True +``` diff --git a/docs/references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_description.md b/docs/references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_description.md new file mode 100644 index 0000000..46f05b7 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_description.md @@ -0,0 +1,3 @@ +PositionerBox2D controls two positioners in one widget, typically one horizontal and one vertical axis. Use it for two-axis alignment or mapping layouts. + +![PositionerBox2D widget](assets/positioner_box_2d.png) diff --git a/docs/references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_page.md b/docs/references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_page.md new file mode 100644 index 0000000..9130d98 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_page.md @@ -0,0 +1,22 @@ +# PositionerBox2D + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.control.device_control.positioner_box.positioner_box_2d.positioner_box_2d.PositionerBox2D + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/positioner_group/positioner_group_cli_examples.md b/docs/references/bec-widgets/widget-gallery/positioner_group/positioner_group_cli_examples.md new file mode 100644 index 0000000..cb59194 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/positioner_group/positioner_group_cli_examples.md @@ -0,0 +1,19 @@ + + +Create a group and add several motors: + +```python +group = gui.bec.new(gui.available_widgets.PositionerGroup) +group.set_positioners("samx samy") +``` + +Update the group later: + +```python +group.set_positioners("samx samy samz") +``` diff --git a/docs/references/bec-widgets/widget-gallery/positioner_group/positioner_group_description.md b/docs/references/bec-widgets/widget-gallery/positioner_group/positioner_group_description.md new file mode 100644 index 0000000..00136b9 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/positioner_group/positioner_group_description.md @@ -0,0 +1,3 @@ +PositionerGroup creates a grid of positioner controls. Use it when a workflow needs several motors available together without adding a separate dock for each motor. + +The device list is supplied as one space-separated string. diff --git a/docs/references/bec-widgets/widget-gallery/positioner_group/positioner_group_page.md b/docs/references/bec-widgets/widget-gallery/positioner_group/positioner_group_page.md new file mode 100644 index 0000000..c8a1023 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/positioner_group/positioner_group_page.md @@ -0,0 +1,22 @@ +# PositionerGroup + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/positioner_group/positioner_group_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/positioner_group/positioner_group_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.control.device_control.positioner_group.positioner_group.PositionerGroup + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/ring_progress_bar/assets/ring_progress_bar.png b/docs/references/bec-widgets/widget-gallery/ring_progress_bar/assets/ring_progress_bar.png new file mode 100644 index 0000000..0716065 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/ring_progress_bar/assets/ring_progress_bar.png differ diff --git a/docs/references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_cli_examples.md b/docs/references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_cli_examples.md new file mode 100644 index 0000000..4f9c5a5 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_cli_examples.md @@ -0,0 +1,23 @@ + + +Create a ring progress bar and add rings: + +```python +rings = gui.bec.new(gui.available_widgets.RingProgressBar) +ring = rings.add_ring() +ring.set_value(40) + +rings.set_center_label("40 %") +rings.set_gap(8) +``` + +Remove the last ring: + +```python +rings.remove_ring() +``` diff --git a/docs/references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_description.md b/docs/references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_description.md new file mode 100644 index 0000000..4b795aa --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_description.md @@ -0,0 +1,3 @@ +RingProgressBar displays one or more nested circular progress bars. Use it for compact progress/status displays in custom layouts. + +![RingProgressBar widget](assets/ring_progress_bar.png) diff --git a/docs/references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_page.md b/docs/references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_page.md new file mode 100644 index 0000000..bf5f4b1 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_page.md @@ -0,0 +1,22 @@ +# RingProgressBar + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.progress.ring_progress_bar.ring_progress_bar.RingProgressBar + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/scan_control/assets/scan_controller.png b/docs/references/bec-widgets/widget-gallery/scan_control/assets/scan_controller.png new file mode 100644 index 0000000..0f778d6 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/scan_control/assets/scan_controller.png differ diff --git a/docs/references/bec-widgets/widget-gallery/scan_control/scan_control_cli_examples.md b/docs/references/bec-widgets/widget-gallery/scan_control/scan_control_cli_examples.md new file mode 100644 index 0000000..d784b40 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/scan_control/scan_control_cli_examples.md @@ -0,0 +1,29 @@ + + +Create a ScanControl widget: + +```python +scan_control = gui.bec.new(gui.available_widgets.ScanControl) +``` + +Place it next to an existing Waveform by dock name: + +```python +scan_control = gui.bec.new( + gui.available_widgets.ScanControl, + where="left", + relative_to="Waveform", +) +``` + +Detach or attach the widget window: + +```python +scan_control.detach() +scan_control.attach() +``` diff --git a/docs/references/bec-widgets/widget-gallery/scan_control/scan_control_description.md b/docs/references/bec-widgets/widget-gallery/scan_control/scan_control_description.md new file mode 100644 index 0000000..f5f6094 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/scan_control/scan_control_description.md @@ -0,0 +1,5 @@ +ScanControl provides a GUI for choosing scan types, editing scan arguments, and submitting scans to BEC. Use it when you want scan submission controls inside the Dock Area. + +![ScanControl widget](assets/scan_controller.png) + +The widget is primarily operated through the GUI. From the BEC IPython client, the stable operation is to create it and optionally control dock attachment. diff --git a/docs/references/bec-widgets/widget-gallery/scan_control/scan_control_page.md b/docs/references/bec-widgets/widget-gallery/scan_control/scan_control_page.md new file mode 100644 index 0000000..b02cb2b --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/scan_control/scan_control_page.md @@ -0,0 +1,22 @@ +# ScanControl + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/scan_control/scan_control_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/scan_control/scan_control_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.control.scan_control.scan_control.ScanControl + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/scatter_waveform/assets/scatter_waveform.png b/docs/references/bec-widgets/widget-gallery/scatter_waveform/assets/scatter_waveform.png new file mode 100644 index 0000000..ab19887 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/scatter_waveform/assets/scatter_waveform.png differ diff --git a/docs/references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_cli_examples.md b/docs/references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_cli_examples.md new file mode 100644 index 0000000..fe053bc --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_cli_examples.md @@ -0,0 +1,31 @@ + + +Create a scatter plot from two motors and one detector signal: + +```python +scatter = gui.bec.new(gui.available_widgets.ScatterWaveform) +scatter.plot( + device_x="samx", + device_y="samy", + device_z="bpm4i", + color_map="plasma", +) +``` + +Update the color map or clear the plot: + +```python +scatter.color_map = "viridis" +scatter.clear_all() +``` + +Load the latest scan history into the widget: + +```python +scatter.update_with_scan_history(-1) +``` diff --git a/docs/references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_description.md b/docs/references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_description.md new file mode 100644 index 0000000..8bdeea3 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_description.md @@ -0,0 +1,9 @@ +ScatterWaveform plots points from two position-like signals and colors them by a third signal. Use it when the scan path is not naturally represented as a rectangular image or when you want to inspect point-by-point sampling. + +![ScatterWaveform widget](assets/scatter_waveform.png) + +Common uses: + +- visualize non-grid 2D scan paths +- inspect detector intensity along arbitrary scan trajectories +- compare with Heatmap interpolation for the same data diff --git a/docs/references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_page.md b/docs/references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_page.md new file mode 100644 index 0000000..551cd22 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_page.md @@ -0,0 +1,22 @@ +# ScatterWaveform + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.plots.scatter_waveform.scatter_waveform.ScatterWaveform + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/signal_label/assets/signal_label.png b/docs/references/bec-widgets/widget-gallery/signal_label/assets/signal_label.png new file mode 100644 index 0000000..b96e48d Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/signal_label/assets/signal_label.png differ diff --git a/docs/references/bec-widgets/widget-gallery/signal_label/signal_label_cli_examples.md b/docs/references/bec-widgets/widget-gallery/signal_label/signal_label_cli_examples.md new file mode 100644 index 0000000..80bdc75 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/signal_label/signal_label_cli_examples.md @@ -0,0 +1,24 @@ + + +Create a SignalLabel for one signal: + +```python +label = gui.bec.new( + gui.available_widgets.SignalLabel, + device="bpm4i", + signal="bpm4i", +) +``` + +Customize the display: + +```python +label.custom_label = "BPM" +label.decimal_places = 4 +label.show_default_units = True +``` diff --git a/docs/references/bec-widgets/widget-gallery/signal_label/signal_label_description.md b/docs/references/bec-widgets/widget-gallery/signal_label/signal_label_description.md new file mode 100644 index 0000000..7a51f99 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/signal_label/signal_label_description.md @@ -0,0 +1,3 @@ +SignalLabel displays the live value of a selected signal. Use it when a layout needs a compact readout rather than a full plot. + +![SignalLabel widget](assets/signal_label.png) diff --git a/docs/references/bec-widgets/widget-gallery/signal_label/signal_label_page.md b/docs/references/bec-widgets/widget-gallery/signal_label/signal_label_page.md new file mode 100644 index 0000000..adc04dd --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/signal_label/signal_label_page.md @@ -0,0 +1,22 @@ +# SignalLabel + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/signal_label/signal_label_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/signal_label/signal_label_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.utility.signal_label.signal_label.SignalLabel + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/text_box/assets/text_box.png b/docs/references/bec-widgets/widget-gallery/text_box/assets/text_box.png new file mode 100644 index 0000000..9b83e61 Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/text_box/assets/text_box.png differ diff --git a/docs/references/bec-widgets/widget-gallery/text_box/text_box_cli_examples.md b/docs/references/bec-widgets/widget-gallery/text_box/text_box_cli_examples.md new file mode 100644 index 0000000..630031e --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/text_box/text_box_cli_examples.md @@ -0,0 +1,19 @@ + + +Create a TextBox and set plain text: + +```python +text = gui.bec.new(gui.available_widgets.TextBox) +text.set_plain_text("Ready for alignment.") +``` + +Display simple HTML: + +```python +text.set_html_text("Status: ready") +``` diff --git a/docs/references/bec-widgets/widget-gallery/text_box/text_box_description.md b/docs/references/bec-widgets/widget-gallery/text_box/text_box_description.md new file mode 100644 index 0000000..a67d2d7 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/text_box/text_box_description.md @@ -0,0 +1,3 @@ +TextBox displays read-only plain text or HTML. Use it for notes, fit summaries, instructions, or compact status text inside a Dock Area profile. + +![TextBox widget](assets/text_box.png) diff --git a/docs/references/bec-widgets/widget-gallery/text_box/text_box_page.md b/docs/references/bec-widgets/widget-gallery/text_box/text_box_page.md new file mode 100644 index 0000000..b82e05a --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/text_box/text_box_page.md @@ -0,0 +1,22 @@ +# TextBox + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/text_box/text_box_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/text_box/text_box_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.editors.text_box.text_box.TextBox + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/waveform/assets/waveform_widget.png b/docs/references/bec-widgets/widget-gallery/waveform/assets/waveform_widget.png new file mode 100644 index 0000000..544c8cc Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/waveform/assets/waveform_widget.png differ diff --git a/docs/references/bec-widgets/widget-gallery/waveform/waveform_cli_examples.md b/docs/references/bec-widgets/widget-gallery/waveform/waveform_cli_examples.md new file mode 100644 index 0000000..994328a --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/waveform/waveform_cli_examples.md @@ -0,0 +1,43 @@ + + +Create a Waveform and plot `bpm4i` against `samx`: + +```python +wf = gui.bec.new(gui.available_widgets.Waveform) +wf.plot(device_x="samx", device_y="bpm4i") + +wf.title = "bpm4i during samx scan" +wf.x_label = "samx" +wf.y_label = "bpm4i" +``` + +Attach a DAP model when creating the source curve: + +```python +wf.plot(device_x="samx", device_y="bpm4i", dap="GaussianModel") +wf.get_dap_summary() +wf.get_dap_params() +``` + +Add a DAP model to an existing source curve: + +```python +wf.add_dap_curve(device_label="bpm4i-bpm4i", dap_name="GaussianModel") +``` + +Plot custom arrays and read them back: + +```python +import numpy as np + +x = np.linspace(-5, 5, 101) +y = np.exp(-(x**2)) + +wf.plot(x=x, y=y, label="custom gaussian", dap="GaussianModel") +data = wf.get_all_data() +``` diff --git a/docs/references/bec-widgets/widget-gallery/waveform/waveform_description.md b/docs/references/bec-widgets/widget-gallery/waveform/waveform_description.md new file mode 100644 index 0000000..f34c2fd --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/waveform/waveform_description.md @@ -0,0 +1,10 @@ +Waveform is the main 1D plotting widget. Use it for live device signals, completed scan history, custom arrays, and DAP-assisted curve fitting. It is the widget most users start with when they want to inspect detector intensity versus a motor position. + +![Waveform widget](assets/waveform_widget.png) + +Common uses: + +- plot a monitored device signal during a scan +- compare scan history with new measurements +- add fitted DAP curves such as `GaussianModel` +- read plotted data back into Python with `get_all_data()` diff --git a/docs/references/bec-widgets/widget-gallery/waveform/waveform_page.md b/docs/references/bec-widgets/widget-gallery/waveform/waveform_page.md new file mode 100644 index 0000000..dfe0ca8 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/waveform/waveform_page.md @@ -0,0 +1,22 @@ +# Waveform + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/waveform/waveform_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/waveform/waveform_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.plots.waveform.waveform.Waveform + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/docs/references/bec-widgets/widget-gallery/website_widget/assets/website.png b/docs/references/bec-widgets/widget-gallery/website_widget/assets/website.png new file mode 100644 index 0000000..fdd0cab Binary files /dev/null and b/docs/references/bec-widgets/widget-gallery/website_widget/assets/website.png differ diff --git a/docs/references/bec-widgets/widget-gallery/website_widget/website_widget_cli_examples.md b/docs/references/bec-widgets/widget-gallery/website_widget/website_widget_cli_examples.md new file mode 100644 index 0000000..2251db4 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/website_widget/website_widget_cli_examples.md @@ -0,0 +1,20 @@ + + +Create a WebsiteWidget and open a URL: + +```python +web = gui.bec.new(gui.available_widgets.WebsiteWidget) +web.set_url("https://bec.readthedocs.io/") +``` + +Use browser-like actions: + +```python +web.reload() +current_url = web.get_url() +``` diff --git a/docs/references/bec-widgets/widget-gallery/website_widget/website_widget_description.md b/docs/references/bec-widgets/widget-gallery/website_widget/website_widget_description.md new file mode 100644 index 0000000..793ac69 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/website_widget/website_widget_description.md @@ -0,0 +1,3 @@ +WebsiteWidget embeds a web page in a Dock Area. Use it for local dashboards, documentation, or beamline web tools that should be visible next to BEC Widgets. + +![WebsiteWidget](assets/website.png) diff --git a/docs/references/bec-widgets/widget-gallery/website_widget/website_widget_page.md b/docs/references/bec-widgets/widget-gallery/website_widget/website_widget_page.md new file mode 100644 index 0000000..f533db7 --- /dev/null +++ b/docs/references/bec-widgets/widget-gallery/website_widget/website_widget_page.md @@ -0,0 +1,22 @@ +# WebsiteWidget + +/// tab | Description + +--8<-- "references/bec-widgets/widget-gallery/website_widget/website_widget_description.md" + +/// +/// tab | BEC IPython examples + +--8<-- "references/bec-widgets/widget-gallery/website_widget/website_widget_cli_examples.md" + +/// +/// tab | API + +::: bec_widgets.widgets.editors.website.website.WebsiteWidget + options: + show_root_heading: true + heading_level: 2 + members_order: source + + +/// diff --git a/zensical.toml b/zensical.toml index 5ce8c70..783b1db 100644 --- a/zensical.toml +++ b/zensical.toml @@ -143,6 +143,31 @@ nav = [ # ] }, { "BEC Widgets" = [ { "GUI RPC Interface" = "references/bec-widgets/gui-rpc-interface.md" }, + { "Widget Gallery" = [ + "references/bec-widgets/widget-gallery/index.md", + { Waveform = "references/bec-widgets/widget-gallery/waveform/waveform_page.md" }, + { MultiWaveform = "references/bec-widgets/widget-gallery/multi_waveform/multi_waveform_page.md" }, + { ScatterWaveform = "references/bec-widgets/widget-gallery/scatter_waveform/scatter_waveform_page.md" }, + { Image = "references/bec-widgets/widget-gallery/image/image_page.md" }, + { Heatmap = "references/bec-widgets/widget-gallery/heatmap/heatmap_page.md" }, + { MotorMap = "references/bec-widgets/widget-gallery/motor_map/motor_map_page.md" }, + { ScanControl = "references/bec-widgets/widget-gallery/scan_control/scan_control_page.md" }, + { DeviceBrowser = "references/bec-widgets/widget-gallery/device_browser/device_browser_page.md" }, + { PositionerBox = "references/bec-widgets/widget-gallery/positioner_box/positioner_box_page.md" }, + { PositionerBox2D = "references/bec-widgets/widget-gallery/positioner_box_2d/positioner_box_2d_page.md" }, + { PositionerGroup = "references/bec-widgets/widget-gallery/positioner_group/positioner_group_page.md" }, + { PositionIndicator = "references/bec-widgets/widget-gallery/position_indicator/position_indicator_page.md" }, + { BECQueue = "references/bec-widgets/widget-gallery/bec_queue/bec_queue_page.md" }, + { BECStatusBox = "references/bec-widgets/widget-gallery/bec_status_box/bec_status_box_page.md" }, + { RingProgressBar = "references/bec-widgets/widget-gallery/ring_progress_bar/ring_progress_bar_page.md" }, + { BECProgressBar = "references/bec-widgets/widget-gallery/bec_progressbar/bec_progressbar_page.md" }, + { TextBox = "references/bec-widgets/widget-gallery/text_box/text_box_page.md" }, + { WebsiteWidget = "references/bec-widgets/widget-gallery/website_widget/website_widget_page.md" }, + { SignalLabel = "references/bec-widgets/widget-gallery/signal_label/signal_label_page.md" }, + { LogPanel = "references/bec-widgets/widget-gallery/log_panel/log_panel_page.md" }, + { PdfViewerWidget = "references/bec-widgets/widget-gallery/pdf_viewer_widget/pdf_viewer_widget_page.md" }, + { DapComboBox = "references/bec-widgets/widget-gallery/dap_combo_box/dap_combo_box_page.md" }, + ] }, ] }, { "Ophyd Devices" = [ # { "AsyncSignal" = "references/ophyd-devices/async-signal.md" }, @@ -208,6 +233,7 @@ paths = [ "../bec/bec_lib", "../bec/bec_server", "../bec/bec_ipython_client", + "../bec_widgets", "../bec-widgets", "../ophyd_devices", ] @@ -240,6 +266,9 @@ emoji_generator = "zensical.extensions.emoji.to_svg" emoji_index = "zensical.extensions.emoji.twemoji" [project.markdown_extensions.pymdownx.highlight] [project.markdown_extensions.pymdownx.inlinehilite] +[project.markdown_extensions.pymdownx.snippets] +base_path = ["docs"] +check_paths = true [project.markdown_extensions.pymdownx.keys] [project.markdown_extensions.pymdownx.mark] [project.markdown_extensions.pymdownx.smartsymbols]