sciwidgets 0.1.2__tar.gz → 0.2.0__tar.gz

{sciwidgets-0.1.2/src/sciwidgets.egg-info → sciwidgets-0.2.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: sciwidgets
-Version: 0.1.2
+Version: 0.2.0
 Summary: PySide6 widgets for scientific desktop apps: math labels, sliders, parameter inputs and dialogs
 Author-email: Vahid Anari <vahid.anari8@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/vahid-anari/sciwidgets
 Project-URL: Repository, https://github.com/vahid-anari/sciwidgets
 Project-URL: Issues, https://github.com/vahid-anari/sciwidgets/issues
-Keywords: pyside6,qt,gui,widgets,scientific,slider,range-slider,latex,matplotlib,dialogs
+Keywords: pyside6,qt,gui,widgets,scientific,slider,range-slider,latex,matplotlib,dialogs,status-bar,menu
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Developers
@@ -24,6 +24,7 @@ License-File: LICENSE
 Requires-Dist: PySide6<7,>=6.5
 Requires-Dist: matplotlib>=3.7
 Requires-Dist: numpy>=1.24
+Requires-Dist: psutil>=5.9
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
@@ -35,7 +36,7 @@ PySide6 widgets for scientific desktop apps: math labels rendered with
 LaTeX/mathtext, dialogs, and parameter inputs such as sliders, range sliders
 and validated number fields.
 
-![Sliders demo](https://raw.githubusercontent.com/vahid-anari/sciwidgets/main/docs/images/sliders_demo.png)
+<img src="https://raw.githubusercontent.com/vahid-anari/sciwidgets/main/docs/images/sliders_demo.png" width="900" alt="Sliders demo">
 
 Right-click menu, Set Value and Edit Configuration:
 
@@ -64,13 +65,14 @@ and moved into this package so other apps can share them.
 
 ## Components
 
-| Import | Contents |
-|--------|----------|
-| `sciwidgets.labels` | `MathLabel` (LaTeX/mathtext label), `set_latex_enabled` |
-| `sciwidgets.params` | `FloatSlider`, `IntSlider`, `ArraySlider`, `FloatRangeSlider`, `IntRangeSlider`, `MultiVariableSlider`, `ParameterLineEdit`, `ParameterComboBox`, `ParameterToggle`, `NumericLineEdit`, `SliderFeature` |
-| `sciwidgets.dialogs` | `show_information`, `show_warning`, `show_critical`, `show_rich_information`, `show_about_dialog`, `ask_question`, `AskResult` |
-| `sciwidgets.style` | `SciStyle`, `apply_sci_style`, `sci_style_sheet` |
-| `sciwidgets.formatting` | `pretty_sci_text`, `value_to_text` and other format helpers |
+| Import | Contents | Docs |
+|--------|----------|------|
+| `sciwidgets.params` (sliders) | `FloatSlider`, `IntSlider`, `ArraySlider`, `FloatRangeSlider`, `IntRangeSlider`, `MultiVariableSlider`, `SliderFeature` | [Sliders](https://github.com/vahid-anari/sciwidgets/blob/main/docs/sliders.md) |
+| `sciwidgets.params` (inputs) | `ParameterLineEdit`, `ParameterComboBox`, `ParameterToggle`, `NumericLineEdit` | [Parameter widgets](https://github.com/vahid-anari/sciwidgets/blob/main/docs/params.md) |
+| `sciwidgets.labels` | `MathLabel`, `set_latex_enabled` | [Labels](https://github.com/vahid-anari/sciwidgets/blob/main/docs/labels.md) |
+| `sciwidgets.dialogs` | `show_information`, `show_warning`, `show_critical`, `show_rich_information`, `show_about_dialog`, `ask_question` | [Dialogs](https://github.com/vahid-anari/sciwidgets/blob/main/docs/dialogs.md) |
+| `sciwidgets.window` | `MenuBarController`, `StatusBarController` | [Window helpers](https://github.com/vahid-anari/sciwidgets/blob/main/docs/window.md) |
+| `sciwidgets.style`, `sciwidgets.formatting` | `apply_sci_style`, `SciStyle`, `value_to_text`, `pretty_sci_text` | [Style and formatting](https://github.com/vahid-anari/sciwidgets/blob/main/docs/style.md) |
 
 ## Install
 

{sciwidgets-0.1.2 → sciwidgets-0.2.0}/README.md

@@ -4,7 +4,7 @@ PySide6 widgets for scientific desktop apps: math labels rendered with
 LaTeX/mathtext, dialogs, and parameter inputs such as sliders, range sliders
 and validated number fields.
 
-![Sliders demo](https://raw.githubusercontent.com/vahid-anari/sciwidgets/main/docs/images/sliders_demo.png)
+<img src="https://raw.githubusercontent.com/vahid-anari/sciwidgets/main/docs/images/sliders_demo.png" width="900" alt="Sliders demo">
 
 Right-click menu, Set Value and Edit Configuration:
 
@@ -33,13 +33,14 @@ and moved into this package so other apps can share them.
 
 ## Components
 
-| Import | Contents |
-|--------|----------|
-| `sciwidgets.labels` | `MathLabel` (LaTeX/mathtext label), `set_latex_enabled` |
-| `sciwidgets.params` | `FloatSlider`, `IntSlider`, `ArraySlider`, `FloatRangeSlider`, `IntRangeSlider`, `MultiVariableSlider`, `ParameterLineEdit`, `ParameterComboBox`, `ParameterToggle`, `NumericLineEdit`, `SliderFeature` |
-| `sciwidgets.dialogs` | `show_information`, `show_warning`, `show_critical`, `show_rich_information`, `show_about_dialog`, `ask_question`, `AskResult` |
-| `sciwidgets.style` | `SciStyle`, `apply_sci_style`, `sci_style_sheet` |
-| `sciwidgets.formatting` | `pretty_sci_text`, `value_to_text` and other format helpers |
+| Import | Contents | Docs |
+|--------|----------|------|
+| `sciwidgets.params` (sliders) | `FloatSlider`, `IntSlider`, `ArraySlider`, `FloatRangeSlider`, `IntRangeSlider`, `MultiVariableSlider`, `SliderFeature` | [Sliders](https://github.com/vahid-anari/sciwidgets/blob/main/docs/sliders.md) |
+| `sciwidgets.params` (inputs) | `ParameterLineEdit`, `ParameterComboBox`, `ParameterToggle`, `NumericLineEdit` | [Parameter widgets](https://github.com/vahid-anari/sciwidgets/blob/main/docs/params.md) |
+| `sciwidgets.labels` | `MathLabel`, `set_latex_enabled` | [Labels](https://github.com/vahid-anari/sciwidgets/blob/main/docs/labels.md) |
+| `sciwidgets.dialogs` | `show_information`, `show_warning`, `show_critical`, `show_rich_information`, `show_about_dialog`, `ask_question` | [Dialogs](https://github.com/vahid-anari/sciwidgets/blob/main/docs/dialogs.md) |
+| `sciwidgets.window` | `MenuBarController`, `StatusBarController` | [Window helpers](https://github.com/vahid-anari/sciwidgets/blob/main/docs/window.md) |
+| `sciwidgets.style`, `sciwidgets.formatting` | `apply_sci_style`, `SciStyle`, `value_to_text`, `pretty_sci_text` | [Style and formatting](https://github.com/vahid-anari/sciwidgets/blob/main/docs/style.md) |
 
 ## Install
 

{sciwidgets-0.1.2 → sciwidgets-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sciwidgets"
-version = "0.1.2"
+version = "0.2.0"
 description = "PySide6 widgets for scientific desktop apps: math labels, sliders, parameter inputs and dialogs"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,6 +14,7 @@ authors = [{ name = "Vahid Anari", email = "vahid.anari8@gmail.com" }]
 keywords = [
     "pyside6", "qt", "gui", "widgets", "scientific",
     "slider", "range-slider", "latex", "matplotlib", "dialogs",
+    "status-bar", "menu",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -31,6 +32,7 @@ dependencies = [
     "PySide6>=6.5,<7",
     "matplotlib>=3.7",
     "numpy>=1.24",
+    "psutil>=5.9",
 ]
 
 [project.optional-dependencies]

{sciwidgets-0.1.2 → sciwidgets-0.2.0}/src/sciwidgets/labels/__main__.py

@@ -115,7 +115,7 @@ def _demo_main() -> int:
     render()
     root.addWidget(box)
 
-    win.resize(520, 560)
+    win.adjustSize()
     win.show()
     return app.exec()
 

{sciwidgets-0.1.2 → sciwidgets-0.2.0}/src/sciwidgets/params/__main__.py

@@ -72,7 +72,7 @@ def _demo_main() -> int:
 
     layout.addStretch(1)
 
-    win.resize(520, 420)
+    win.adjustSize()
     win.show()
     return app.exec()
 

sciwidgets-0.2.0/src/sciwidgets/window/__init__.py

@@ -0,0 +1,6 @@
+"""Main-window helpers: declarative menu bar and status bar."""
+
+from .menu_bar import MenuBarController, MenuSpec
+from .status_bar import StatusBarController
+
+__all__ = ["MenuBarController", "MenuSpec", "StatusBarController"]

sciwidgets-0.2.0/src/sciwidgets/window/__main__.py

@@ -0,0 +1,106 @@
+"""Demo for the window helpers: ``python -m sciwidgets.window``."""
+
+import sys
+import time
+
+from PySide6.QtCore import QTimer
+from PySide6.QtGui import QAction, QKeySequence
+from PySide6.QtWidgets import QApplication, QMainWindow, QPlainTextEdit
+
+from sciwidgets.window import MenuBarController, StatusBarController
+
+MENU_SPEC = {
+    "File": [
+        {"id": "open", "text": "Open…", "shortcut": QKeySequence.Open},
+        {"id": "recent", "submenu": "Open Recent", "items": [
+            {"id": "recent_1", "text": "maser_run_1.json"},
+            {"id": "recent_2", "text": "maser_run_2.json"},
+            {"id": "sep"},
+            {"id": "clear_recent", "text": "Clear Menu"},
+        ]},
+        {"id": "sep"},
+        {"id": "save", "text": "Save", "shortcut": QKeySequence.Save},
+        {"id": "sep"},
+        {"id": "quit", "text": "Quit", "shortcut": QKeySequence.Quit, "role": QAction.QuitRole},
+    ],
+    "Edit": [
+        {"id": "modify", "text": "Change Something", "shortcut": "Ctrl+E"},
+    ],
+    "Run": [
+        {"id": "solve", "text": "Solve (2 s, window stays responsive)", "shortcut": "Ctrl+R"},
+        {"id": "solve_blocking", "text": "Solve (2 s, blocking)", "shortcut": "Ctrl+Shift+R"},
+        {"id": "sep"},
+        {"id": "fail", "text": "Simulate Error"},
+    ],
+    "View": [
+        {"id": "toolbar", "text": "Show Toolbar", "checkable": True, "checked": True},
+    ],
+}
+
+
+def _demo_main() -> int:
+    """Run a main window with a menu bar, a toolbar and a status bar.
+
+    Returns:
+        int: Qt application exit code.
+    """
+    app = QApplication(sys.argv)
+    win = QMainWindow()
+    win.setWindowTitle("Window helpers demo")
+
+    log = QPlainTextEdit()
+    log.setReadOnly(True)
+    win.setCentralWidget(log)
+
+    menu = MenuBarController(win, MENU_SPEC, native_menubar=False)
+    status = StatusBarController(win, path_label="File")
+
+    # The same QActions can also live on a toolbar
+    toolbar = win.addToolBar("Main")
+    for action_id in ("open", "save", "solve"):
+        toolbar.addAction(menu.action(action_id))
+
+    def finish_solve() -> None:
+        status.set_state("Ready")
+        menu.set_enabled("solve", True)
+        menu.set_enabled("solve_blocking", True)
+        log.appendPlainText("solve finished")
+
+    def on_action(menu_path: str, action_id: str, checked: bool) -> None:
+        log.appendPlainText(f"{menu_path} → {action_id} (checked={checked})")
+        if action_id in ("open", "recent_1", "recent_2"):
+            name = "maser_run_2.json" if action_id == "recent_2" else "maser_run_1.json"
+            status.set_path(f"~/runs/{name}")
+        elif action_id == "save":
+            status.set_path(status.get_path() or "~/runs/untitled.json")
+        elif action_id == "modify":
+            status.set_modified(True)
+        elif action_id == "solve":
+            menu.set_enabled("solve", False)
+            menu.set_enabled("solve_blocking", False)
+            status.set_state("Solving…", busy=True)
+            QTimer.singleShot(2000, finish_solve)
+        elif action_id == "solve_blocking":
+            status.set_state("Solving…", busy=True)
+
+            def blocking_work() -> None:
+                time.sleep(2.0)  # stands in for a long computation
+                status.set_state("Ready")
+
+            QTimer.singleShot(50, blocking_work)  # return to the event loop first, so the state is drawn
+        elif action_id == "fail":
+            status.set_state("Error")
+        elif action_id == "toolbar":
+            toolbar.setVisible(checked)
+        elif action_id == "quit":
+            win.close()
+
+    menu.actionTriggered.connect(on_action)
+
+    win.resize(640, 360)
+    win.show()
+    return app.exec()
+
+
+if __name__ == "__main__":
+    raise SystemExit(_demo_main())

sciwidgets-0.2.0/src/sciwidgets/window/menu_bar.py

@@ -0,0 +1,247 @@
+"""Declarative menu-bar controller for a main window.
+
+The menu bar is described by a plain Python mapping and built in one call.
+Nested submenus, checkable actions, shortcuts and menu roles are supported,
+and every action is reported through a single signal.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from PySide6.QtCore import QObject, Signal
+from PySide6.QtGui import QAction, QKeySequence
+from PySide6.QtWidgets import QMainWindow, QMenu
+
+__all__ = ["MenuBarController", "MenuSpec"]
+
+MenuSpec = Dict[str, List[Dict[str, Any]]]
+"""Menu specification: menu title -> list of item dictionaries."""
+
+
+class MenuBarController(QObject):
+    """Build and manage a menu bar from a declarative specification.
+
+    The specification maps each top-level menu title to a list of items. An
+    item is one of:
+
+    * an action: ``{"id": "save", "text": "Save", "shortcut": "Ctrl+S"}``
+      with optional ``enabled``, ``checkable``, ``checked`` and ``role``;
+    * a separator: ``{"id": "sep"}``;
+    * a submenu: ``{"submenu": "Open Recent", "items": [...]}``.
+
+    Action ids must be unique across the whole menu bar; they are used to
+    look actions up later.
+
+    Signals:
+        actionTriggered (str, str, bool): Emitted when the user triggers an
+            action, with the menu path (e.g. ``"File/Open Recent"``), the
+            action id and the checked state.
+    """
+
+    actionTriggered = Signal(str, str, bool)
+
+    def __init__(
+            self,
+            window: QMainWindow,
+            menu_spec: Optional[MenuSpec] = None,
+            *,
+            native_menubar: bool = True,
+    ) -> None:
+        """Initialize the controller and build the menu bar.
+
+        Args:
+            window: Main window that owns the menu bar.
+            menu_spec: Menu specification. ``None`` builds an empty menu bar.
+            native_menubar: Whether to use the platform's native menu bar
+                (the global menu bar on macOS) when available.
+
+        Raises:
+            ValueError: If an action has no ``id`` or an id is used twice.
+        """
+        super().__init__(window)
+        self._w = window
+        self._menu_spec: MenuSpec = {}
+        self._actions: Dict[str, QAction] = {}
+        self.set_menu_spec(menu_spec or {}, native_menubar=native_menubar)
+
+    # ----- validation -----
+    @staticmethod
+    def _check_ids(menu_spec: MenuSpec) -> None:
+        """Check that every action has an id and that no id is repeated.
+
+        Args:
+            menu_spec: Menu specification to check.
+
+        Raises:
+            ValueError: If an action has no ``id`` or an id is used twice.
+        """
+        seen: Dict[str, str] = {}
+
+        def walk(items: List[Dict[str, Any]], path: str) -> None:
+            for item in items:
+                if "submenu" in item:
+                    walk(item.get("items", []), f"{path}/{item['submenu']}")
+                    continue
+                action_id = str(item.get("id", "")).strip()
+                if not action_id:
+                    raise ValueError(f"Menu item in '{path}' must define 'id': {item}")
+                if action_id == "sep":
+                    continue
+                if action_id in seen:
+                    raise ValueError(
+                        f"Duplicate menu action id {action_id!r} in '{path}' "
+                        f"(already used in '{seen[action_id]}')"
+                    )
+                seen[action_id] = path
+
+        for menu_name, items in menu_spec.items():
+            walk(items, menu_name)
+
+    # ----- construction -----
+    @staticmethod
+    def _to_keyseq(shortcut: Union[None, str, QKeySequence, QKeySequence.StandardKey]) -> Optional[QKeySequence]:
+        """Convert a shortcut value to a ``QKeySequence``.
+
+        Args:
+            shortcut: ``None``, a string such as ``"Ctrl+S"``, a
+                ``QKeySequence`` or a standard key such as
+                ``QKeySequence.Save``.
+
+        Returns:
+            The key sequence, or ``None`` if no shortcut was given.
+        """
+        if shortcut is None:
+            return None
+        if isinstance(shortcut, QKeySequence):
+            return shortcut
+        return QKeySequence(shortcut)
+
+    def _add_action(self, menu: QMenu, menu_name: str, item: Dict[str, Any]) -> None:
+        """Create an action from an item specification and add it to a menu.
+
+        Args:
+            menu: Menu that receives the action.
+            menu_name: Menu path reported by ``actionTriggered``.
+            item: Item specification with at least an ``id``.
+        """
+        action_id = str(item["id"]).strip()
+        act = QAction(str(item.get("text", action_id)), self._w)
+        act.setEnabled(bool(item.get("enabled", True)))
+        checkable = bool(item.get("checkable", False))
+        act.setCheckable(checkable)
+        if checkable:
+            act.setChecked(bool(item.get("checked", False)))
+
+        ks = self._to_keyseq(item.get("shortcut"))
+        if ks is not None:
+            act.setShortcut(ks)
+        role = item.get("role")
+        if role is not None:
+            act.setMenuRole(role)
+
+        act.triggered.connect(lambda c, m=menu_name, a=action_id: self.actionTriggered.emit(m, a, c))
+        menu.addAction(act)
+        self._actions[action_id] = act
+
+    def _populate_menu(self, menu: QMenu, menu_name: str, items: List[Dict[str, Any]]) -> None:
+        """Fill a menu from a list of item specifications.
+
+        Args:
+            menu: Menu to fill.
+            menu_name: Menu path of this branch.
+            items: Item specifications.
+        """
+        for item in items:
+            if "submenu" in item:
+                sub = menu.addMenu(str(item["submenu"]))
+                self._populate_menu(sub, f"{menu_name}/{item['submenu']}", item.get("items", []))
+            elif str(item["id"]).strip() == "sep":
+                menu.addSeparator()
+            else:
+                self._add_action(menu, menu_name, item)
+
+    def _build_menus(self, native_menubar: bool) -> None:
+        """Build the menu bar from the stored specification.
+
+        Args:
+            native_menubar: Whether to use the platform's native menu bar.
+        """
+        menubar = self._w.menuBar()
+        menubar.setNativeMenuBar(native_menubar)
+        menubar.clear()
+        for menu_name, items in self._menu_spec.items():
+            menu = menubar.addMenu(menu_name)
+            self._populate_menu(menu, menu_name, items)
+
+    # ----- public API -----
+    def set_menu_spec(self, menu_spec: MenuSpec, native_menubar: bool = True) -> None:
+        """Replace the specification and rebuild the menu bar.
+
+        The new specification is checked before the current menu bar is
+        touched.
+
+        Args:
+            menu_spec: New menu specification.
+            native_menubar: Whether to use the platform's native menu bar.
+
+        Raises:
+            ValueError: If an action has no ``id`` or an id is used twice.
+        """
+        self._check_ids(menu_spec)
+        self._menu_spec = menu_spec
+        self._actions.clear()
+        self._build_menus(native_menubar)
+
+    def action(self, action_id: str) -> QAction:
+        """Return the ``QAction`` for an id, e.g. to add it to a toolbar.
+
+        Args:
+            action_id: Action identifier.
+
+        Returns:
+            The action.
+
+        Raises:
+            KeyError: If no action has this id.
+        """
+        try:
+            return self._actions[action_id]
+        except KeyError:
+            raise KeyError(f"unknown menu action id {action_id!r}") from None
+
+    def set_enabled(self, action_id: str, enabled: bool) -> None:
+        """Enable or disable an action. Unknown ids are ignored.
+
+        Args:
+            action_id: Action identifier.
+            enabled: New enabled state.
+        """
+        act = self._actions.get(action_id)
+        if act is not None:
+            act.setEnabled(enabled)
+
+    def set_checked(self, action_id: str, checked: bool) -> None:
+        """Set the checked state of a checkable action (no signal).
+
+        Unknown ids are ignored.
+
+        Args:
+            action_id: Action identifier.
+            checked: New checked state.
+        """
+        act = self._actions.get(action_id)
+        if act is not None:
+            act.setChecked(checked)
+
+    def get_checked(self, action_id: str) -> bool:
+        """Return the checked state of an action.
+
+        Args:
+            action_id: Action identifier.
+
+        Returns:
+            The checked state, or ``False`` if the id is unknown.
+        """
+        act = self._actions.get(action_id)
+        return act.isChecked() if act is not None else False

sciwidgets-0.2.0/src/sciwidgets/window/status_bar.py

@@ -0,0 +1,263 @@
+"""Status-bar controller showing a state, a document path, elapsed time and memory."""
+
+from __future__ import annotations
+
+import os
+from enum import Enum
+from time import perf_counter_ns
+from typing import Iterable, Optional, Union
+
+import psutil
+from PySide6.QtCore import QObject, Qt, QTimer
+from PySide6.QtWidgets import QFrame, QHBoxLayout, QLabel, QLayout, QMainWindow, QWidget
+
+__all__ = ["StatusBarController"]
+
+
+def _compact_number(value: float) -> str:
+    """Format a number with fewer decimals as it grows (``1.23``, ``12.3``, ``123``)."""
+    if value < 10:
+        return f"{value:.2f}"
+    if value < 100:
+        return f"{value:.1f}"
+    return f"{value:.0f}"
+
+
+def _format_duration(ms: float) -> str:
+    """Format a duration in milliseconds with an automatic unit (ms, s, m, h)."""
+    if ms < 1000:
+        return f"{_compact_number(ms)} ms"
+    s = ms / 1000.0
+    if s < 60:
+        return f"{_compact_number(s)} s"
+    m = s / 60.0
+    if m < 60:
+        return f"{_compact_number(m)} m"
+    return f"{_compact_number(m / 60.0)} h"
+
+
+def _format_bytes(n: float) -> str:
+    """Format a byte count with an automatic unit (B, KB, MB, GB)."""
+    for unit in ("B", "KB", "MB"):
+        if n < 1000:
+            return f"{_compact_number(n)} {unit}"
+        n /= 1024.0
+    return f"{_compact_number(n)} GB"
+
+
+class StatusBarController(QObject):
+    """Manage a main window's status bar.
+
+    The left side shows the current state (e.g. ``"Ready"``) and, optionally,
+    the current document path with a ``*`` when there are unsaved changes.
+    The right side shows the process memory and the elapsed time of the last
+    busy state.
+
+    States are free text chosen by the app. A state set with ``busy=True``
+    starts the elapsed-time clock; the next state stops it and leaves the
+    final time visible::
+
+        status.set_state("Solving…", busy=True)
+        solve()
+        status.set_state("Ready")
+    """
+
+    def __init__(
+            self,
+            window: QMainWindow,
+            *,
+            ready_text: str = "Ready",
+            states: Iterable[Union[str, Enum]] = (),
+            show_path: bool = True,
+            path_label: str = "Path",
+            show_memory: bool = True,
+            show_time: bool = True,
+            timer_interval: int = 700,
+    ) -> None:
+        """Initialize the controller and build the status-bar widgets.
+
+        Args:
+            window: Main window whose status bar is managed.
+            ready_text: Initial state text.
+            states: All state texts the app will show. The state label is
+                sized for the widest one, so the path next to it does not
+                move when the state changes. A wider state shown later still
+                fits; the label then grows and keeps that width.
+            show_path: Whether to show the document path section.
+            path_label: Caption of the path section, e.g. ``"File"``.
+            show_memory: Whether to show the process memory.
+            show_time: Whether to show the elapsed time of busy states.
+            timer_interval: Refresh interval, in milliseconds, of the time and
+                memory displays while a busy state is active.
+        """
+        super().__init__(window)
+        self._sb = window.statusBar()
+        self._process = psutil.Process(os.getpid())
+        self._start_ns = 0
+        self._busy = False
+
+        self._path = ""
+        self._modified = False
+        self._path_label = path_label
+
+        self._timer = QTimer(self)
+        self._timer.setInterval(timer_interval)
+        self._timer.timeout.connect(self._refresh)
+
+        self._state_lbl = QLabel(ready_text)
+        self._path_lbl = QLabel() if show_path else None
+        self._memory_lbl = self._fixed_label("0.00 MB", 7) if show_memory else None
+        self._time_lbl = self._fixed_label("0.00 s", 7) if show_time else None
+
+        self._make_layout()
+        self._fit_state_width([ready_text, *states])
+        self._update_path_label()
+        self._update_memory()
+
+    # ----- construction -----
+    @staticmethod
+    def _fixed_label(text: str, chars: int) -> QLabel:
+        """Create a right-aligned label wide enough for ``chars`` digits."""
+        lbl = QLabel(text, alignment=Qt.AlignRight | Qt.AlignVCenter)
+        lbl.setFixedWidth(lbl.fontMetrics().horizontalAdvance("0" * chars) + 8)
+        return lbl
+
+    def _vline(self) -> QFrame:
+        """Create a sunken vertical separator."""
+        line = QFrame(self._sb)
+        line.setFrameShape(QFrame.VLine)
+        line.setFrameShadow(QFrame.Sunken)
+        return line
+
+    def _add_separator(self, layout: QLayout) -> None:
+        """Add a padded vertical separator to a layout."""
+        layout.addSpacing(10)
+        layout.addWidget(self._vline())
+        layout.addSpacing(10)
+
+    def _make_layout(self) -> None:
+        """Build the left (state, path) and right (memory, time) sections."""
+        left = QWidget()
+        ll = QHBoxLayout(left)
+        ll.setContentsMargins(0, 0, 0, 0)
+        ll.setSpacing(0)
+        ll.addSpacing(10)
+        ll.addWidget(self._state_lbl)
+        if self._path_lbl is not None:
+            self._add_separator(ll)
+            ll.addWidget(self._path_lbl)
+        ll.addStretch(1)
+        self._sb.addWidget(left, 1)
+
+        if self._memory_lbl is None and self._time_lbl is None:
+            return
+        right = QWidget()
+        rl = QHBoxLayout(right)
+        rl.setContentsMargins(0, 0, 0, 0)
+        rl.setSpacing(0)
+        for caption, lbl in (("Memory:", self._memory_lbl), ("Time:", self._time_lbl)):
+            if lbl is not None:
+                self._add_separator(rl)
+                rl.addWidget(QLabel(caption))
+                rl.addWidget(lbl)
+        rl.addSpacing(8)
+        self._sb.addPermanentWidget(right)
+
+    # ----- updates -----
+    def _update_time(self) -> None:
+        """Show the time elapsed since the current busy state started."""
+        if self._time_lbl is not None:
+            ms = (perf_counter_ns() - self._start_ns) / 1.0e6
+            self._time_lbl.setText(_format_duration(ms))
+
+    def _update_memory(self) -> None:
+        """Show the current memory use (resident set size) of the process."""
+        if self._memory_lbl is not None:
+            self._memory_lbl.setText(_format_bytes(self._process.memory_info().rss))
+
+    def _refresh(self) -> None:
+        """Timer slot: refresh time and memory."""
+        self._update_time()
+        self._update_memory()
+
+    def _update_path_label(self) -> None:
+        """Show the path, ``Untitled`` when empty, and ``*`` when modified."""
+        if self._path_lbl is None:
+            return
+        mark = " *" if self._modified else ""
+        text = f"{self._path_label}{mark}: {self._path or 'Untitled'}"
+        self._path_lbl.setText(text)
+        self._path_lbl.setToolTip(text)
+
+    @staticmethod
+    def _state_text(state: Union[str, Enum]) -> str:
+        """Return the display text of a state (an enum's value, or the string)."""
+        return state.value if isinstance(state, Enum) else str(state)
+
+    def _fit_state_width(self, states: Iterable[Union[str, Enum]]) -> None:
+        """Widen the state label to fit the given states; it never shrinks."""
+        fm = self._state_lbl.fontMetrics()
+        width = max((fm.horizontalAdvance(self._state_text(s)) for s in states), default=0) + 4
+        if width > self._state_lbl.minimumWidth():
+            self._state_lbl.setMinimumWidth(width)
+
+    # ----- public API -----
+    def set_state(self, state: Union[str, Enum], busy: bool = False) -> None:
+        """Show a new state.
+
+        A busy state starts the elapsed-time clock; any following state stops
+        it and keeps the final time on display. The new state appears when
+        control returns to the event loop, so run long tasks in a worker
+        thread, or start them with ``QTimer.singleShot`` after this call.
+
+        Args:
+            state: Text to show, or an enum whose value is the text.
+            busy: Whether a long-running task starts now.
+        """
+        self._timer.stop()
+        if self._busy:
+            self._update_time()
+        self._busy = bool(busy)
+        if self._busy:
+            self._start_ns = perf_counter_ns()
+            self._timer.start()
+
+        self._update_memory()
+        text = self._state_text(state)
+        self._fit_state_width([text])
+        self._state_lbl.setText(text)
+
+    def is_busy(self) -> bool:
+        """Return whether a busy state is active."""
+        return self._busy
+
+    def set_path(self, path: str) -> None:
+        """Show a document path.
+
+        A non-empty path clears the modified mark (the document was just
+        opened or saved); an empty path shows ``Untitled`` and keeps the mark.
+
+        Args:
+            path: Path to show.
+        """
+        self._path = path
+        if path:
+            self._modified = False
+        self._update_path_label()
+
+    def get_path(self) -> str:
+        """Return the shown document path."""
+        return self._path
+
+    def set_modified(self, modified: bool = True) -> None:
+        """Mark or unmark the document as having unsaved changes.
+
+        Args:
+            modified: Whether there are unsaved changes.
+        """
+        self._modified = bool(modified)
+        self._update_path_label()
+
+    def is_modified(self) -> bool:
+        """Return whether the document is marked as modified."""
+        return self._modified

{sciwidgets-0.1.2 → sciwidgets-0.2.0/src/sciwidgets.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: sciwidgets
-Version: 0.1.2
+Version: 0.2.0
 Summary: PySide6 widgets for scientific desktop apps: math labels, sliders, parameter inputs and dialogs
 Author-email: Vahid Anari <vahid.anari8@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/vahid-anari/sciwidgets
 Project-URL: Repository, https://github.com/vahid-anari/sciwidgets
 Project-URL: Issues, https://github.com/vahid-anari/sciwidgets/issues
-Keywords: pyside6,qt,gui,widgets,scientific,slider,range-slider,latex,matplotlib,dialogs
+Keywords: pyside6,qt,gui,widgets,scientific,slider,range-slider,latex,matplotlib,dialogs,status-bar,menu
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Developers
@@ -24,6 +24,7 @@ License-File: LICENSE
 Requires-Dist: PySide6<7,>=6.5
 Requires-Dist: matplotlib>=3.7
 Requires-Dist: numpy>=1.24
+Requires-Dist: psutil>=5.9
 Provides-Extra: dev
 Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
@@ -35,7 +36,7 @@ PySide6 widgets for scientific desktop apps: math labels rendered with
 LaTeX/mathtext, dialogs, and parameter inputs such as sliders, range sliders
 and validated number fields.
 
-![Sliders demo](https://raw.githubusercontent.com/vahid-anari/sciwidgets/main/docs/images/sliders_demo.png)
+<img src="https://raw.githubusercontent.com/vahid-anari/sciwidgets/main/docs/images/sliders_demo.png" width="900" alt="Sliders demo">
 
 Right-click menu, Set Value and Edit Configuration:
 
@@ -64,13 +65,14 @@ and moved into this package so other apps can share them.
 
 ## Components
 
-| Import | Contents |
-|--------|----------|
-| `sciwidgets.labels` | `MathLabel` (LaTeX/mathtext label), `set_latex_enabled` |
-| `sciwidgets.params` | `FloatSlider`, `IntSlider`, `ArraySlider`, `FloatRangeSlider`, `IntRangeSlider`, `MultiVariableSlider`, `ParameterLineEdit`, `ParameterComboBox`, `ParameterToggle`, `NumericLineEdit`, `SliderFeature` |
-| `sciwidgets.dialogs` | `show_information`, `show_warning`, `show_critical`, `show_rich_information`, `show_about_dialog`, `ask_question`, `AskResult` |
-| `sciwidgets.style` | `SciStyle`, `apply_sci_style`, `sci_style_sheet` |
-| `sciwidgets.formatting` | `pretty_sci_text`, `value_to_text` and other format helpers |
+| Import | Contents | Docs |
+|--------|----------|------|
+| `sciwidgets.params` (sliders) | `FloatSlider`, `IntSlider`, `ArraySlider`, `FloatRangeSlider`, `IntRangeSlider`, `MultiVariableSlider`, `SliderFeature` | [Sliders](https://github.com/vahid-anari/sciwidgets/blob/main/docs/sliders.md) |
+| `sciwidgets.params` (inputs) | `ParameterLineEdit`, `ParameterComboBox`, `ParameterToggle`, `NumericLineEdit` | [Parameter widgets](https://github.com/vahid-anari/sciwidgets/blob/main/docs/params.md) |
+| `sciwidgets.labels` | `MathLabel`, `set_latex_enabled` | [Labels](https://github.com/vahid-anari/sciwidgets/blob/main/docs/labels.md) |
+| `sciwidgets.dialogs` | `show_information`, `show_warning`, `show_critical`, `show_rich_information`, `show_about_dialog`, `ask_question` | [Dialogs](https://github.com/vahid-anari/sciwidgets/blob/main/docs/dialogs.md) |
+| `sciwidgets.window` | `MenuBarController`, `StatusBarController` | [Window helpers](https://github.com/vahid-anari/sciwidgets/blob/main/docs/window.md) |
+| `sciwidgets.style`, `sciwidgets.formatting` | `apply_sci_style`, `SciStyle`, `value_to_text`, `pretty_sci_text` | [Style and formatting](https://github.com/vahid-anari/sciwidgets/blob/main/docs/style.md) |
 
 ## Install
 

{sciwidgets-0.1.2 → sciwidgets-0.2.0}/src/sciwidgets.egg-info/SOURCES.txt

@@ -30,4 +30,8 @@ src/sciwidgets/params/sliders/_right_click_overlay.py
 src/sciwidgets/params/sliders/base.py
 src/sciwidgets/params/sliders/multi.py
 src/sciwidgets/params/sliders/range.py
-src/sciwidgets/params/sliders/single.py
+src/sciwidgets/params/sliders/single.py
+src/sciwidgets/window/__init__.py
+src/sciwidgets/window/__main__.py
+src/sciwidgets/window/menu_bar.py
+src/sciwidgets/window/status_bar.py

{sciwidgets-0.1.2 → sciwidgets-0.2.0}/src/sciwidgets.egg-info/requires.txt

@@ -1,6 +1,7 @@
 PySide6<7,>=6.5
 matplotlib>=3.7
 numpy>=1.24
+psutil>=5.9
 
 [dev]
 build