imgui_data_loader 0.1.0__py3-none-any.whl

imgui_data_loader/persistence.py

@@ -0,0 +1,88 @@
+"""Optional persistence for recent files + last-used directory.
+
+Pass any object implementing :class:`PreferenceStore` as
+``FileDialogConfig.persistence``. The dialog will seed the picker's start
+directory from :meth:`default_dir` and call :meth:`record_selection` after a
+successful pick. :class:`JsonPreferenceStore` is a batteries-included default.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import List, Optional
+
+from ._assets import config_dir
+
+try:  # Protocol is 3.8+, runtime_checkable too
+    from typing import Protocol, runtime_checkable
+except ImportError:  # pragma: no cover
+    Protocol = object  # type: ignore
+
+    def runtime_checkable(x):  # type: ignore
+        return x
+
+
+@runtime_checkable
+class PreferenceStore(Protocol):
+    """Minimal interface the dialog uses for persistence."""
+
+    def default_dir(self) -> str:
+        """Directory to open the native picker in (``""`` to fall back)."""
+        ...
+
+    def recent(self) -> List[str]:
+        """Most-recent-first list of previously selected paths."""
+        ...
+
+    def record_selection(self, result) -> None:
+        """Persist a completed :class:`DialogResult`."""
+        ...
+
+
+class JsonPreferenceStore:
+    """A JSON-file-backed :class:`PreferenceStore`.
+
+    Stores a capped most-recent-first list plus the last-used directory.
+    """
+
+    def __init__(self, path: Optional[str] = None, max_recent: int = 20):
+        self.path = Path(path) if path else (config_dir() / "recent.json")
+        self.max_recent = max_recent
+        self._data = {"recent": [], "last_dir": ""}
+        self._load()
+
+    def _load(self) -> None:
+        try:
+            if self.path.is_file():
+                loaded = json.loads(self.path.read_text())
+                if isinstance(loaded, dict):
+                    self._data.update(loaded)
+        except Exception:
+            pass
+
+    def _save(self) -> None:
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text(json.dumps(self._data, indent=2))
+        except Exception:
+            pass
+
+    def default_dir(self) -> str:
+        d = self._data.get("last_dir", "")
+        return d if d and Path(d).exists() else ""
+
+    def recent(self) -> List[str]:
+        return list(self._data.get("recent", []))
+
+    def record_selection(self, result) -> None:
+        paths = list(getattr(result, "paths", None) or [])
+        if not paths:
+            return
+        recent = [p for p in self._data.get("recent", []) if p not in paths]
+        for p in reversed(paths):
+            recent.insert(0, p)
+        self._data["recent"] = recent[: self.max_recent]
+        first = Path(paths[0])
+        self._data["last_dir"] = str(first if first.is_dir() else first.parent)
+        self._save()

imgui_data_loader/runner.py

@@ -0,0 +1,68 @@
+"""One-shot harness: open the dialog in its own window and return the result."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ._assets import default_ini_path, ensure_assets
+from .config import DialogResult, FileDialogConfig
+from .dialog import FileDialog
+
+
+def run_file_dialog(
+    config: Optional[FileDialogConfig] = None,
+    *,
+    runner_params=None,
+) -> DialogResult:
+    """Show the dialog, block until the user picks or quits, return the result.
+
+    Parameters
+    ----------
+    config : FileDialogConfig | None
+        Dialog configuration.
+    runner_params : hello_imgui.RunnerParams | None
+        Advanced: supply your own runner params (e.g. to select a null backend
+        for headless tests). Window title/size/ini are filled in from
+        ``config`` only when not already set.
+
+    Returns
+    -------
+    DialogResult
+        ``bool(result)`` is True for a real selection; the paths are in
+        ``result.paths``. A quit / cancel yields an empty, ``cancelled`` result.
+    """
+    from imgui_bundle import hello_imgui, immapp
+
+    config = config or FileDialogConfig()
+    ensure_assets(config.assets_folder)
+
+    dlg = FileDialog(config)
+    params = runner_params if runner_params is not None else hello_imgui.RunnerParams()
+    params.app_window_params.window_title = config.window_title or config.title
+    if config.window_size:
+        params.app_window_params.window_geometry.size = tuple(config.window_size)
+        params.app_window_params.window_geometry.size_auto = False
+    params.app_window_params.resizable = config.resizable
+    # Route the layout .ini. hello_imgui resolves ini_filename relative to
+    # ini_folder_type (default: the current working directory), so an empty or
+    # relative name would drop a file next to wherever the app was launched.
+    # Pin it to an absolute path instead (default: ~/.config/imgui_data_loader).
+    if not params.ini_filename:
+        ini = config.ini_path or default_ini_path()
+        params.ini_filename = ini
+        if os.path.isabs(ini):
+            params.ini_folder_type = hello_imgui.IniFolderType.absolute_path
+            parent = os.path.dirname(ini)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+    params.callbacks.show_gui = dlg.render
+
+    addons = immapp.AddOnsParams()
+    addons.with_markdown = True
+    addons.with_implot = False
+    addons.with_implot3d = False
+
+    immapp.run(runner_params=params, add_ons_params=addons)
+
+    return dlg.result or DialogResult(paths=[], kind=None, cancelled=True)

imgui_data_loader/theme.py

@@ -0,0 +1,88 @@
+"""Colors and style for the file dialog.
+
+A :class:`Theme` is a plain dataclass of RGBA float tuples, so it can be
+constructed, copied, and inspected without an active imgui context (handy in
+tests). Colors are converted to ``imgui.ImVec4`` lazily at draw time.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Tuple
+
+from imgui_bundle import imgui
+
+Color = Tuple[float, float, float, float]
+
+
+def to_vec4(color) -> "imgui.ImVec4":
+    """Coerce an ``(r, g, b[, a])`` tuple (or an ImVec4) to ``imgui.ImVec4``."""
+    if isinstance(color, imgui.ImVec4):
+        return color
+    r, g, b = color[0], color[1], color[2]
+    a = color[3] if len(color) > 3 else 1.0
+    return imgui.ImVec4(r, g, b, a)
+
+
+@dataclass(frozen=True)
+class Theme:
+    """Color palette + a couple of rounding knobs for the dialog.
+
+    Every field is an ``(r, g, b, a)`` float tuple in the 0..1 range. Build a
+    variant with :meth:`replace`, e.g. ``Theme.dark().replace(accent=(...))``.
+    """
+
+    bg: Color = (0.11, 0.11, 0.12, 1.0)
+    bg_card: Color = (0.16, 0.16, 0.17, 1.0)
+    accent: Color = (0.20, 0.50, 0.85, 1.0)
+    accent_hover: Color = (0.25, 0.55, 0.90, 1.0)
+    accent_active: Color = (0.15, 0.45, 0.80, 1.0)
+    text: Color = (1.0, 1.0, 1.0, 1.0)
+    text_dim: Color = (0.75, 0.75, 0.77, 1.0)
+    border: Color = (0.35, 0.35, 0.37, 0.7)
+    secondary: Color = (0.35, 0.35, 0.37, 1.0)
+    secondary_hover: Color = (0.42, 0.42, 0.44, 1.0)
+    secondary_active: Color = (0.28, 0.28, 0.30, 1.0)
+    ok: Color = (0.40, 1.00, 0.40, 1.0)
+    warn: Color = (1.00, 0.80, 0.20, 1.0)
+    err: Color = (1.00, 0.40, 0.40, 1.0)
+    na: Color = (0.50, 0.50, 0.50, 1.0)
+    frame_bg: Color = (0.22, 0.22, 0.23, 1.0)
+    frame_bg_hovered: Color = (0.28, 0.28, 0.29, 1.0)
+    separator: Color = (0.35, 0.35, 0.37, 0.6)
+    # icon_button face (neutral bg behind the accent-colored icon + label)
+    button_face: Color = (0.18, 0.18, 0.20, 1.0)
+    button_face_hover: Color = (0.22, 0.22, 0.25, 1.0)
+    button_face_active: Color = (0.15, 0.15, 0.17, 1.0)
+    frame_rounding: float = 6.0
+    child_rounding: float = 6.0
+
+    @staticmethod
+    def dark() -> "Theme":
+        return Theme()
+
+    @staticmethod
+    def light() -> "Theme":
+        return Theme(
+            bg=(0.94, 0.94, 0.95, 1.0),
+            bg_card=(0.99, 0.99, 1.00, 1.0),
+            accent=(0.10, 0.45, 0.80, 1.0),
+            accent_hover=(0.15, 0.50, 0.85, 1.0),
+            accent_active=(0.05, 0.40, 0.75, 1.0),
+            text=(0.10, 0.10, 0.12, 1.0),
+            text_dim=(0.35, 0.35, 0.40, 1.0),
+            border=(0.70, 0.70, 0.74, 0.9),
+            secondary=(0.80, 0.80, 0.83, 1.0),
+            secondary_hover=(0.86, 0.86, 0.89, 1.0),
+            secondary_active=(0.72, 0.72, 0.75, 1.0),
+            frame_bg=(0.88, 0.88, 0.90, 1.0),
+            frame_bg_hovered=(0.82, 0.82, 0.85, 1.0),
+            separator=(0.70, 0.70, 0.74, 0.6),
+            button_face=(0.90, 0.90, 0.92, 1.0),
+            button_face_hover=(0.85, 0.85, 0.88, 1.0),
+            button_face_active=(0.80, 0.80, 0.83, 1.0),
+        )
+
+    def replace(self, **changes) -> "Theme":
+        """Return a copy with the given fields overridden."""
+        return replace(self, **changes)

imgui_data_loader/widgets.py

@@ -0,0 +1,127 @@
+"""Reusable, themed imgui helpers.
+
+These are standalone: call them from your own ``info``/``options`` callbacks to
+match the dialog's look (centered text, wrapped tooltips, accent icon buttons).
+Colors accept either an ``imgui.ImVec4`` or a plain ``(r, g, b[, a])`` tuple.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+from imgui_bundle import hello_imgui, imgui
+
+from .theme import Theme, to_vec4
+
+
+def call_draw(cb, dialog) -> None:
+    """Invoke a draw callback, passing ``dialog`` only if it takes an argument.
+
+    Supports ``fn(dialog)``, ``fn()``, bound methods, and ``fn(*args)``.
+    """
+    if cb is None:
+        return
+    try:
+        params = inspect.signature(cb).parameters.values()
+        wants_arg = any(
+            p.kind
+            in (
+                p.POSITIONAL_ONLY,
+                p.POSITIONAL_OR_KEYWORD,
+                p.VAR_POSITIONAL,
+            )
+            for p in params
+        )
+    except (TypeError, ValueError):
+        wants_arg = True
+    if wants_arg:
+        cb(dialog)
+    else:
+        cb()
+
+
+def wrapped_tooltip(text: str, wrap_em: float = 24.0) -> None:
+    """A tooltip whose text wraps to ``wrap_em`` em units (fits narrow dialogs)."""
+    imgui.begin_tooltip()
+    try:
+        imgui.push_text_wrap_pos(hello_imgui.em_size(wrap_em))
+        imgui.text_unformatted(text)
+        imgui.pop_text_wrap_pos()
+    finally:
+        imgui.end_tooltip()
+
+
+def text_wrapped_colored(color, text: str) -> None:
+    """Colored equivalent of ``imgui.text_wrapped``."""
+    imgui.push_style_color(imgui.Col_.text, to_vec4(color))
+    try:
+        imgui.text_wrapped(text)
+    finally:
+        imgui.pop_style_color()
+
+
+def center_text(text: str, color=None) -> None:
+    """Draw horizontally centered text."""
+    avail_w = imgui.get_content_region_avail().x
+    text_sz = imgui.calc_text_size(text)
+    imgui.set_cursor_pos_x(imgui.get_cursor_pos_x() + (avail_w - text_sz.x) * 0.5)
+    if color is not None:
+        imgui.text_colored(to_vec4(color), text)
+    else:
+        imgui.text(text)
+
+
+def center_next_item(width: float) -> None:
+    """Move the cursor so the next ``width``-wide item is centered."""
+    avail_w = imgui.get_content_region_avail().x
+    imgui.set_cursor_pos_x(imgui.get_cursor_pos_x() + (avail_w - width) * 0.5)
+
+
+def push_button_style(theme: Theme, primary: bool = True) -> None:
+    """Push button colors (accent if ``primary`` else neutral). Pair with
+    :func:`pop_button_style`."""
+    if primary:
+        imgui.push_style_color(imgui.Col_.button, to_vec4(theme.accent))
+        imgui.push_style_color(imgui.Col_.button_hovered, to_vec4(theme.accent_hover))
+        imgui.push_style_color(imgui.Col_.button_active, to_vec4(theme.accent_active))
+    else:
+        imgui.push_style_color(imgui.Col_.button, to_vec4(theme.secondary))
+        imgui.push_style_color(imgui.Col_.button_hovered, to_vec4(theme.secondary_hover))
+        imgui.push_style_color(imgui.Col_.button_active, to_vec4(theme.secondary_active))
+    imgui.push_style_color(imgui.Col_.text, to_vec4(theme.text))
+    imgui.push_style_var(imgui.StyleVar_.frame_rounding, theme.frame_rounding)
+    imgui.push_style_var(imgui.StyleVar_.frame_border_size, 0.0)
+
+
+def pop_button_style() -> None:
+    imgui.pop_style_var(2)
+    imgui.pop_style_color(4)
+
+
+def icon_button(
+    icon: str,
+    label: str,
+    size,
+    theme: Theme = None,
+    tooltip: str = "",
+) -> bool:
+    """A neutral-faced button with an accent-colored icon + label and a blue
+    outline. ``icon`` may be empty. Returns True on click."""
+    if theme is None:
+        theme = Theme.dark()
+    imgui.push_style_color(imgui.Col_.button, to_vec4(theme.button_face))
+    imgui.push_style_color(imgui.Col_.button_hovered, to_vec4(theme.button_face_hover))
+    imgui.push_style_color(imgui.Col_.button_active, to_vec4(theme.button_face_active))
+    imgui.push_style_color(imgui.Col_.text, to_vec4(theme.accent))
+    imgui.push_style_color(imgui.Col_.border, to_vec4(theme.accent))
+    imgui.push_style_var(imgui.StyleVar_.frame_rounding, theme.frame_rounding)
+    imgui.push_style_var(imgui.StyleVar_.frame_border_size, 1.5)
+
+    button_text = f"{icon}  {label}" if icon else label
+    clicked = imgui.button(button_text, size)
+    if tooltip and imgui.is_item_hovered():
+        wrapped_tooltip(tooltip)
+
+    imgui.pop_style_var(2)
+    imgui.pop_style_color(5)
+    return clicked