bec_widgets.utils.bec_widget
============================

.. py:module:: bec_widgets.utils.bec_widget


Classes
-------

.. autoapisummary::

   bec_widgets.utils.bec_widget.BECWidget


Module Contents
---------------

.. py: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: :py:obj:`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)


   :param client: The BEC client.
   :type client: BECClient, optional
   :param config: The connection configuration.
   :type config: ConnectionConfig, optional
   :param gui_id: The GUI ID.
   :type gui_id: str, optional
   :param theme_update: 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.
   :type theme_update: bool, optional


   .. py:method:: _connect_to_theme_change()

      Connect to the theme change signal.



   .. py:method:: _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.



   .. py:method:: _show_busy_overlay() -> None

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



   .. py:method:: _update_overlay_theme(theme: str)


   .. py:method:: _update_theme(theme: str | None = None)

      Update the theme.



   .. py:method:: apply_theme(theme: str)

      Apply the theme to the widget.

      :param theme: The theme to be applied.
      :type theme: str, optional



   .. py:method:: attach()


   .. py:method:: cleanup()

      Cleanup the widget.



   .. py:method:: closeEvent(event)

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



   .. py:method:: 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.
      :rtype: 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.



   .. py:method:: detach()

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



   .. py:method:: get_help_md() -> str

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

      :returns: The help text in markdown format.
      :rtype: str



   .. py:method:: is_busy() -> bool

      Check if the loading overlay is enabled.

      :returns: True if the loading overlay is enabled, False otherwise.
      :rtype: bool



   .. py:method:: screenshot(file_name: str | None = None)

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



   .. py:method:: 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.

      :param max_width: Maximum width of the screenshot.
      :type max_width: int, optional
      :param max_height: Maximum height of the screenshot.
      :type max_height: int, optional
      :param fmt: Image format (e.g., "PNG", "JPEG").
      :type fmt: str, optional
      :param quality: Image quality (0-100), -1 for default.
      :type quality: int, optional

      :returns: The screenshot image bytes.
      :rtype: QByteArray



   .. py:method:: 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.

      :param enabled: Whether to enable the busy state.
      :type enabled: bool



   .. py:attribute:: ICON_NAME
      :value: 'widgets'



   .. py:attribute:: USER_ACCESS
      :value: ['remove', 'attach', 'detach']