plesty.lib.ui.panel
===================

.. py:module:: plesty.lib.ui.panel

.. autoapi-nested-parse::

   Panel contract: one dockable unit of the PLESTY shell.

   A :class:`Panel` is anything the shell can place in a sub-window — a live
   view, a device control form, a run status board. The contract is deliberately
   small and toolkit-agnostic: a panel says what it is called, builds its widget
   once, and is ticked on the shell's clock. Everything the shell does with it
   (docking, floating, resizing, tabbing, saving the layout) needs nothing else.

   Keeping the contract free of the concrete view types is what lets one shell
   host a monitor beside a controller: :class:`~plesty.lib.ui.MonitorPanel` is
   just the first implementation.

   .. code-block:: python

       class RunStatusPanel(Panel):
           kind = "status"

           def build(self, parent):
               from PySide6.QtWidgets import QLabel
               self._label = QLabel("waiting…", parent)
               return self._label

           def tick(self):
               self._label.setText(self.journal.status()["state"])



Attributes
----------

.. autoapisummary::

   plesty.lib.ui.panel.DOCK_AREAS


Classes
-------

.. autoapisummary::

   plesty.lib.ui.panel.Panel


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

.. py:data:: DOCK_AREAS
   :type:  tuple[str, Ellipsis]
   :value: ('left', 'right', 'top', 'bottom')


.. py:class:: Panel(*, name: Optional[str] = None, title: Optional[str] = None, area: str = 'right', floating: bool = False, closable: bool = True, weight: float = 1.0, min_width: Optional[int] = None, min_height: Optional[int] = None)

   Bases: :py:obj:`abc.ABC`


   Base class for the dockable units of a :class:`~plesty.lib.ui.Shell`.

   Subclasses implement :meth:`build` and usually :meth:`tick`. The panel
   owns its widget; the shell owns where the widget sits, and remembers that
   placement between sessions through :attr:`name`.

   Configure how the shell should place this panel.

   :param name: Stable identifier used as the layout key; must be
                unique within a shell. Defaults to the class name.
   :param title: Title shown in the panel's bar; defaults to *name*.
   :param area: Initial docking area — one of :data:`DOCK_AREAS`.
   :param floating: Start as a free-floating window instead of docked.
   :param closable: Allow the operator to close the panel (it can always
                    be brought back from the shell's Panels menu).
   :param weight: Share of the area's space this panel starts with,
                  relative to its neighbours: a plot 3, a readout strip 1.
                  Only the initial arrangement — the operator resizes from
                  there, and a saved layout overrides it.
   :param min_width: Minimum widget width in pixels.
   :param min_height: Minimum widget height in pixels.

   :raises ValueError: If *area* is not a known docking area.


   .. py:attribute:: kind
      :type:  ClassVar[str]
      :value: 'panel'


      Panel category, used for layout keys and styling hooks.


   .. py:attribute:: name
      :value: 'Panel'



   .. py:attribute:: title
      :value: 'Panel'



   .. py:attribute:: area
      :value: 'right'



   .. py:attribute:: floating
      :value: False



   .. py:attribute:: closable
      :value: True



   .. py:attribute:: weight
      :value: 1.0



   .. py:attribute:: min_width
      :value: None



   .. py:attribute:: min_height
      :value: None



   .. py:attribute:: _widget
      :type:  Any
      :value: None



   .. py:method:: build(parent: Any = None) -> Any
      :abstractmethod:


      Create and return the panel's widget.

      Called once, when the panel is added to a shell. Toolkit imports
      belong inside this method, so that constructing a panel — and
      describing it, and testing it — needs no GUI installed.

      :param parent: The parent widget the shell provides.

      :returns: The widget to show inside the sub-window.



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

      Advance the panel on the shell's clock.

      Called at the shell's refresh interval on the GUI thread. Implementations
      must return quickly: drain a source, redraw, and nothing more.



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

      Return the one-line status shown in the panel's title bar.

      :returns: The status text; empty by default.



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

      Release whatever the panel holds; called when the shell shuts down.



   .. py:property:: widget
      :type: Any


      The built widget, or ``None`` before the panel was added to a shell.


   .. py:method:: ensure_widget(parent: Any = None) -> Any

      Build the widget on first use and return it.

      :param parent: The parent widget passed to :meth:`build`.

      :returns: The panel's widget.



   .. py:method:: describe() -> dict[str, Any]

      Return a JSON-serializable description of this panel.

      :returns: Identity and placement, as stored in a saved layout.