Skip to content

Add Widgets to a Dock Area

Goal

Add BEC Widgets to an existing Dock Area from the BEC IPython client and control where they appear.

Use this guide when you already have BEC running with a Dock Area and want to add widgets with commands instead of the toolbar. The examples use gui.bec, which is the default Dock Area in the Terminal + Dock layout.

Prerequisites

  • BEC is running with a Dock Area.
  • You are using the BEC IPython client.

1. Choose a widget

Available widget classes are exposed through gui.available_widgets. Use tab completion to inspect the available widgets. In the BEC IPython client, type gui.available_widgets. and press the tab key.

gui.available_widgets

For example, Waveform, PositionerBox, and ScanControl can be created from the Dock Area:

gui.available_widgets.Waveform
gui.available_widgets.PositionerBox
gui.available_widgets.ScanControl

2. Add a widget

Use gui.bec.new(...) to add a widget to the Dock Area:

wf = gui.bec.new(gui.available_widgets.Waveform)

The returned object is the widget reference. Keep it in a variable when you want to configure it immediately:

wf.title = "bpm4i during samx scan"
wf.x_label = "samx"
wf.y_label = "bpm4i"

3. Place a widget relative to another widget

Use where and relative_to when the new widget should be placed next to an existing widget. In the BEC IPython client, use the dock tab name as the reference:

pos = gui.bec.new(
    gui.available_widgets.PositionerBox,
    where="bottom",
    relative_to="Waveform",
)
pos.set_positioner("samx")

where can be "left", "right", "top", or "bottom".

Add another widget to the right of the same Waveform:

wf2 = gui.bec.new(
    gui.available_widgets.Waveform,
    where="right",
    relative_to="Waveform",
)

Use existing widget names

From the BEC IPython client, relative_to uses the name shown on the dock tab, for example "Waveform", "ScanControl", or "PositionerBox".

If the same widget type appears multiple times, Dock Area indexes the repeated names. The first widget keeps the base name, and later widgets use names such as "Waveform_0" and "Waveform_1".

4. Add a widget as a tab

Use tab_with when the new widget should share the same dock area as another widget:

wf_history = gui.bec.new(
    gui.available_widgets.Waveform,
    tab_with="Waveform",
)
wf_history.title = "History comparison"

You can tab more widgets with the same named dock:

scan = gui.bec.new(
    gui.available_widgets.ScanControl,
    tab_with="Waveform",
)

5. Inspect the Dock Area

List the BEC Widgets currently contained in the Dock Area:

gui.bec.widget_map()
gui.bec.widget_list()

Inspect the splitter layout when you need to understand how widgets are arranged:

gui.bec.describe_layout()

6. Remove widgets when needed

Remove one widget by dock name:

gui.bec.delete("Waveform_0")

Clear the full Dock Area:

gui.bec.delete_all()

Deleting widgets changes the current layout

If the current Dock Area profile is saved later, the saved profile will contain the updated layout. Save under a new profile name when you want to keep the original layout.

Result

You added widgets to a Dock Area, placed them relative to existing widgets, created tabbed widgets, and inspected the resulting layout from the BEC IPython client.