plesty.lib.ui.panel

Panel contract: one dockable unit of the PLESTY shell.

A 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: MonitorPanel is just the first implementation.

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

DOCK_AREAS

Classes

Panel

Base class for the dockable units of a Shell.

Module Contents

plesty.lib.ui.panel.DOCK_AREAS: tuple[str, Ellipsis] = ('left', 'right', 'top', 'bottom')

class plesty.lib.ui.panel.Panel(*, name: str | None = None, title: str | None = None, area: str = 'right', floating: bool = False, closable: bool = True, weight: float = 1.0, min_width: int | None = None, min_height: int | None = None)

Bases: abc.ABC

Base class for the dockable units of a Shell.

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

Configure how the shell should place this panel.

Parameters:

name (Optional[str]) – Stable identifier used as the layout key; must be unique within a shell. Defaults to the class name.
title (Optional[str]) – Title shown in the panel’s bar; defaults to name.
area (str) – Initial docking area — one of DOCK_AREAS.
floating (bool) – Start as a free-floating window instead of docked.
closable (bool) – Allow the operator to close the panel (it can always be brought back from the shell’s Panels menu).
weight (float) – 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.
min_width (Optional[int]) – Minimum widget width in pixels.
min_height (Optional[int]) – Minimum widget height in pixels.

Raises:

ValueError – If area is not a known docking area.

kind: ClassVar[str] = 'panel': Panel category, used for layout keys and styling hooks.

name = 'Panel'

title = 'Panel'

area = 'right'

floating = False

closable = True

weight = 1.0

min_width = None

min_height = None

_widget: Any = None

abstractmethod build(parent: Any = None) → Any

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.

Parameters:: parent (Any) – The parent widget the shell provides.
Returns:: The widget to show inside the sub-window.
Return type:: Any

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.

Return type:: None

status() → str

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

Returns:: The status text; empty by default.
Return type:: str

close() → None

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

Return type:: None

property widget: Any

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

Return type:: Any

ensure_widget(parent: Any = None) → Any

Build the widget on first use and return it.

Parameters:: parent (Any) – The parent widget passed to build().
Returns:: The panel’s widget.
Return type:: Any

describe() → dict[str, Any]

Return a JSON-serializable description of this panel.

Returns:: Identity and placement, as stored in a saved layout.
Return type:: dict[str, Any]