bec_widgets#

Submodules#

Classes#

BECWidget

Mixin class for all BEC widgets, to handle cleanup

Functions#

SafeProperty(prop_type, *prop_args[, popup_error, ...])

Decorator to create a Qt Property with safe getter and setter so that

SafeSlot(*slot_args, **slot_kwargs)

Function with args, acting like a decorator, applying "error_managed" decorator + Qt Slot

Package Contents#

class BECWidget(client=None, config: bec_widgets.utils.bec_connector.ConnectionConfig = None, gui_id: str | None = None, theme_update: bool = False, start_busy: bool = False, **kwargs)#

Bases: bec_widgets.utils.bec_connector.BECConnector

Mixin class for all BEC widgets, to handle cleanup

Base class for all BEC widgets. This class should be used as a mixin class for all BEC widgets, e.g.:

>>> class MyWidget(BECWidget, QWidget):
>>>     def __init__(self, parent=None, client=None, config=None, gui_id=None):
>>>         super().__init__(parent=parent, client=client, config=config, gui_id=gui_id)
Parameters:

  • client (BECClient, optional) – The BEC client.

  • config (ConnectionConfig, optional) – The connection configuration.

  • gui_id (str, optional) – The GUI ID.

  • theme_update (bool, optional) – Whether to subscribe to theme updates. Defaults to False. When set to True, the widget’s apply_theme method will be called when the theme changes.

_connect_to_theme_change()#

Connect to the theme change signal.

_install_busy_loader() → bec_widgets.utils.busy_loader.BusyLoaderOverlay | None#

Create the busy overlay on demand and cache it in _busy_overlay. Returns the overlay instance or None if not a QWidget.

_show_busy_overlay() → None#

Create and attach the loading overlay to this widget if QWidget is present.

_update_overlay_theme(theme: str)#
_update_theme(theme: str | None = None)#

Update the theme.

apply_theme(theme: str)#

Apply the theme to the widget.

Parameters:

theme (str, optional) – The theme to be applied.

attach()#
cleanup()#

Cleanup the widget.

closeEvent(event)#

Wrap the close even to ensure the rpc_register is cleaned up.

create_busy_state_widget() → qtpy.QtWidgets.QWidget#

Method to create a custom busy state widget to be shown in the busy overlay. Child classes should overrid this method to provide a custom widget if desired.

Returns:

The custom busy state widget.

Return type:

QWidget

Note

The implementation here is a SpinnerWidget with a “Loading…” label. This is the default busy state widget for all BECWidgets. However, child classes with specific needs for the busy state can easily overrite this method to provide a custom widget. The signature of the method must be preserved to ensure compatibility with the busy overlay system. If the widget provides a ‘cleanup’ method, it will be called when the overlay is cleaned up.

The widget may connect to the _busy_overlay signals foreground_color_changed and scrim_color_changed to update its colors when the theme changes.

detach()#

Detach the widget from its parent dock widget (if widget is in the dock), making it a floating widget.

get_help_md() → str#

Method to override in subclasses to provide help text in markdown format.

Returns:

The help text in markdown format.

Return type:

str

is_busy() → bool#

Check if the loading overlay is enabled.

Returns:

True if the loading overlay is enabled, False otherwise.

Return type:

bool

screenshot(file_name: str | None = None)#

Take a screenshot of the dock area and save it to a file.

screenshot_bytes(*, max_width: int | None = None, max_height: int | None = None, fmt: str = 'PNG', quality: int = -1) → qtpy.QtCore.QByteArray#

Grab this widget, optionally scale to a max size, and return encoded image bytes.

If max_width/max_height are omitted (the default), capture at full resolution.

Parameters:

  • max_width (int, optional) – Maximum width of the screenshot.

  • max_height (int, optional) – Maximum height of the screenshot.

  • fmt (str, optional) – Image format (e.g., “PNG”, “JPEG”).

  • quality (int, optional) – Image quality (0-100), -1 for default.

Returns:

The screenshot image bytes.

Return type:

QByteArray

set_busy(enabled: bool) → None#

Set the busy state of the widget. This will show or hide the loading overlay, which will block user interaction with the widget and show the busy_state_widget if provided. Per default, the busy state widget is a spinner with “Loading…” text.

Parameters:

enabled (bool) – Whether to enable the busy state.

ICON_NAME = 'widgets'#
USER_ACCESS = ['remove', 'attach', 'detach']#
SafeProperty(prop_type, *prop_args, popup_error: bool = False, default: Any = None, auto_emit: bool = False, emit_value: Literal['stored', 'input'] | Callable[[object, object], object] = 'stored', emit_on_change: bool = True, **prop_kwargs)#

Decorator to create a Qt Property with safe getter and setter so that Qt Designer won’t crash if an exception occurs in either method.

Parameters:

  • prop_type – The property type (e.g., str, bool, int, custom classes, etc.)

  • popup_error (bool) – If True, show a popup for any error; otherwise, ignore or log silently.

  • default – Any default/fallback value to return if the getter raises an exception.

  • auto_emit (bool) – If True, automatically emit property_changed signal when setter is called. Requires the widget to have a property_changed signal (str, object). Note: This is different from Qt’s ‘notify’ parameter which expects a Signal.

  • emit_value – Controls which value is emitted when auto_emit=True. - “stored” (default): emit the value from the getter after setter runs - “input”: emit the raw setter input - callable: called as emit_value(self_, value) after setter and must return the value to emit

  • emit_on_change (bool) – If True, emit only when the stored value changes.

  • *prop_args – Passed along to the underlying Qt Property constructor (check https://doc.qt.io/qt-6/properties.html).

  • **prop_kwargs –

    Passed along to the underlying Qt Property constructor (check https://doc.qt.io/qt-6/properties.html).

Usage:

@SafeProperty(int, default=-1) def some_value(self) -> int:

# your getter logic return … # if an exception is raised, returns -1

@some_value.setter def some_value(self, val: int):

# your setter logic …

# With auto-emit for toolbar sync: @SafeProperty(bool, auto_emit=True) def fft(self) -> bool:

return self._fft

@fft.setter def fft(self, value: bool):

self._fft = value # property_changed.emit(“fft”, value) is called automatically

# With custom emit modes: @SafeProperty(int, auto_emit=True, emit_value=”stored”) def precision_stored(self) -> int:

return self._precision_stored

@precision_stored.setter def precision_stored(self, value: int):

self._precision_stored = max(0, int(value))

@SafeProperty(int, auto_emit=True, emit_value=”input”) def precision_input(self) -> int:

return self._precision_input

@precision_input.setter def precision_input(self, value: int):

self._precision_input = max(0, int(value))

@SafeProperty(int, auto_emit=True, emit_value=lambda _self, v: int(v) * 10) def precision_callable(self) -> int:

return self._precision_callable

@precision_callable.setter def precision_callable(self, value: int):

self._precision_callable = max(0, int(value))

SafeSlot(*slot_args, **slot_kwargs)#

Function with args, acting like a decorator, applying “error_managed” decorator + Qt Slot to the passed function, to display errors instead of potentially raising an exception

‘popup_error’ keyword argument can be passed with boolean value if a dialog should pop up, otherwise error display is left to the original exception hook ‘verify_sender’ keyword argument can be passed with boolean value if the sender should be verified before executing the slot. If True, the slot will only execute if the sender is a QObject. This is useful to prevent function calls from already deleted objects. ‘raise_error’ keyword argument can be passed with boolean value if the error should be raised after the error is displayed. This is useful to propagate the error to the caller but should be used with great care to avoid segfaults.

The keywords above are stored in a container which can be overridden by passing ‘_override_slot_params’ keyword argument with a dictionary containing the keywords to override. This is useful to override the default behavior of the decorator for a specific function call.