imgui_data_loader 0.1.0__py3-none-any.whl

imgui_data_loader/__init__.py

@@ -0,0 +1,77 @@
+"""imgui_data_loader — a themed, configurable imgui file/folder open dialog.
+
+Quick start
+-----------
+>>> from imgui_data_loader import run_file_dialog, FileDialogConfig, FileType
+>>> result = run_file_dialog(FileDialogConfig(
+...     title="My App",
+...     filetypes=[FileType("Images", "*.tif *.png"), FileType("All Files", "*")],
+... ))
+>>> if result:
+...     print(result.paths)
+
+Embed it in your own imgui/hello_imgui app instead:
+>>> from imgui_data_loader import FileDialog, FileDialogConfig
+>>> dlg = FileDialog(FileDialogConfig(close_on_select=False))
+>>> # params.callbacks.show_gui = dlg.render
+>>> # each frame: r = dlg.take_result(); if r: ...
+"""
+
+from __future__ import annotations
+
+from ._assets import ensure_assets
+from .config import (
+    ButtonSpec,
+    DialogResult,
+    FileDialogConfig,
+    FileType,
+    PickKind,
+    flatten_filters,
+)
+from .dialog import FileDialog
+from .persistence import JsonPreferenceStore, PreferenceStore
+from .runner import run_file_dialog
+from .theme import Theme, to_vec4
+from .widgets import (
+    call_draw,
+    center_next_item,
+    center_text,
+    icon_button,
+    pop_button_style,
+    push_button_style,
+    text_wrapped_colored,
+    wrapped_tooltip,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # config
+    "FileDialogConfig",
+    "FileType",
+    "ButtonSpec",
+    "PickKind",
+    "DialogResult",
+    "flatten_filters",
+    # dialog + harness
+    "FileDialog",
+    "run_file_dialog",
+    "ensure_assets",
+    # theme
+    "Theme",
+    "to_vec4",
+    # persistence
+    "PreferenceStore",
+    "JsonPreferenceStore",
+    # reusable widgets
+    "icon_button",
+    "wrapped_tooltip",
+    "text_wrapped_colored",
+    "center_text",
+    "center_next_item",
+    "push_button_style",
+    "pop_button_style",
+    "call_draw",
+    # meta
+    "__version__",
+]

imgui_data_loader/_assets.py

@@ -0,0 +1,53 @@
+"""Asset / config-path helpers.
+
+The dialog relies on the FontAwesome 6 font so button icons render. That font
+ships inside ``imgui-bundle`` and hello_imgui loads it into the default font
+when the assets folder points at a directory containing
+``fonts/Font_Awesome_6_Free-Solid-900.otf``. :func:`ensure_assets` points
+hello_imgui at imgui-bundle's own bundled assets, so the library ships no fonts
+of its own.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+
+def imgui_bundle_assets_dir() -> Optional[str]:
+    """Path to imgui-bundle's bundled ``assets`` folder, or None."""
+    try:
+        import imgui_bundle
+
+        p = Path(imgui_bundle.__file__).parent / "assets"
+        return str(p) if p.is_dir() else None
+    except Exception:
+        return None
+
+
+def ensure_assets(assets_folder: Optional[str] = None) -> None:
+    """Point hello_imgui at an assets folder that provides the icon font.
+
+    Defaults to imgui-bundle's bundled assets. Pass ``assets_folder`` to use
+    your own (it must contain ``fonts/Font_Awesome_6_Free-Solid-900.otf`` for
+    the icons to show).
+    """
+    from imgui_bundle import hello_imgui
+
+    folder = assets_folder or imgui_bundle_assets_dir()
+    if folder:
+        hello_imgui.set_assets_folder(str(folder))
+
+
+def config_dir() -> Path:
+    """Per-user config dir (``$XDG_CONFIG_HOME/imgui_data_loader``)."""
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    d = Path(base) / "imgui_data_loader"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def default_ini_path(name: str = "file_dialog") -> str:
+    """Path for hello_imgui's ``.ini`` (window layout) file."""
+    return str(config_dir() / f"{name}.ini")

imgui_data_loader/config.py

@@ -0,0 +1,196 @@
+"""Configuration objects for the file dialog.
+
+None of these require an active imgui context, so a config can be built and
+inspected anywhere (``_default_buttons`` only imports icon *string constants*).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    List,
+    Optional,
+    Sequence,
+    Union,
+)
+
+from .theme import Theme
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .dialog import FileDialog
+    from .persistence import PreferenceStore
+
+# A draw callback may take the FileDialog instance or nothing; both are
+# accepted (see widgets.call_draw for the arity handling).
+DrawCallback = Callable[..., None]
+
+
+class PickKind(str, Enum):
+    """What a button asks the OS picker for."""
+
+    OPEN_FILE = "open_file"
+    SELECT_FOLDER = "select_folder"
+    SAVE_FILE = "save_file"
+
+
+@dataclass
+class FileType:
+    """A named file filter, e.g. ``FileType("Images", "*.tif *.png")``.
+
+    ``patterns`` is a space-separated glob string (portable_file_dialogs
+    format). A list/tuple of patterns is also accepted and joined.
+    """
+
+    name: str
+    patterns: str = "*"
+
+    def __post_init__(self) -> None:
+        if isinstance(self.patterns, (list, tuple)):
+            self.patterns = " ".join(self.patterns)
+
+
+def flatten_filters(filetypes: Sequence[FileType]) -> List[str]:
+    """Flatten ``[FileType, ...]`` into pfd's ``[name, patterns, ...]`` list."""
+    out: List[str] = []
+    for ft in filetypes:
+        out.append(ft.name)
+        out.append(ft.patterns)
+    return out
+
+
+@dataclass
+class ButtonSpec:
+    """One picker button on the dialog.
+
+    Parameters
+    ----------
+    label : str
+        Button text.
+    kind : PickKind
+        Which native picker to open.
+    icon : str
+        A FontAwesome 6 icon character (e.g. ``fa.ICON_FA_FOLDER_OPEN``);
+        optional.
+    tooltip : str
+        Hover tooltip.
+    multiselect : bool
+        For ``OPEN_FILE`` only: allow selecting several files.
+    filetypes : list[FileType] | None
+        Overrides the dialog-wide ``filetypes`` for this button.
+    title : str | None
+        Native dialog window title (defaults to ``label``).
+    """
+
+    label: str
+    kind: PickKind = PickKind.OPEN_FILE
+    icon: str = ""
+    tooltip: str = ""
+    multiselect: bool = False
+    filetypes: Optional[List[FileType]] = None
+    title: Optional[str] = None
+
+
+@dataclass
+class DialogResult:
+    """Outcome of the dialog.
+
+    ``paths`` holds the selected path(s); it is empty when the user quit /
+    cancelled. ``bool(result)`` is True only for a real, non-empty selection.
+    """
+
+    paths: List[str] = field(default_factory=list)
+    kind: Optional[PickKind] = None
+    cancelled: bool = False
+
+    @property
+    def path(self) -> Optional[str]:
+        """First selected path, or None."""
+        return self.paths[0] if self.paths else None
+
+    def __bool__(self) -> bool:
+        return bool(self.paths) and not self.cancelled
+
+
+def _default_buttons() -> List[ButtonSpec]:
+    from imgui_bundle import icons_fontawesome_6 as fa
+
+    return [
+        ButtonSpec(
+            "Open File(s)",
+            PickKind.OPEN_FILE,
+            icon=fa.ICON_FA_FILE_IMAGE,
+            tooltip="Select one or more files",
+            multiselect=True,
+        ),
+        ButtonSpec(
+            "Select Folder",
+            PickKind.SELECT_FOLDER,
+            icon=fa.ICON_FA_FOLDER_OPEN,
+            tooltip="Select a folder",
+        ),
+    ]
+
+
+@dataclass
+class FileDialogConfig:
+    """Everything the dialog can be told to do.
+
+    All fields have sensible defaults; the empty ``FileDialogConfig()`` gives
+    an "Open File(s)" + "Select Folder" launcher.
+
+    Content slots (``header_draw``, ``top_draw``, ``info``, ``options_draw``,
+    ``footer_draw``) are callbacks that draw arbitrary imgui inside the dialog.
+    Each callback may accept the :class:`FileDialog` instance or no argument.
+    """
+
+    # --- header / branding ---
+    title: str = "Open Data"
+    subtitle: str = ""
+
+    # --- picker buttons ---
+    buttons: List[ButtonSpec] = field(default_factory=_default_buttons)
+    filetypes: List[FileType] = field(
+        default_factory=lambda: [FileType("All Files", "*")]
+    )
+    default_dir: str = ""
+
+    # --- look ---
+    theme: Theme = field(default_factory=Theme.dark)
+
+    # --- content slots (each: fn(dialog) or fn()) ---
+    header_draw: Optional[DrawCallback] = None
+    top_draw: Optional[DrawCallback] = None
+    info: Union[DrawCallback, Sequence[DrawCallback], None] = None
+    options_draw: Optional[DrawCallback] = None
+    footer_draw: Optional[DrawCallback] = None
+
+    # --- footer labels / behavior ---
+    options_label: str = "Options"
+    show_options_button: bool = True
+    show_quit_button: bool = True
+    quit_label: str = "Quit"
+    quit_on_escape: bool = True
+    close_on_select: bool = True
+
+    # --- window / harness (used by run_file_dialog) ---
+    window_title: Optional[str] = None
+    window_size: tuple = (360, 720)
+    resizable: bool = True
+    ini_path: Optional[str] = None
+    assets_folder: Optional[str] = None
+
+    # --- integrations ---
+    persistence: "Optional[PreferenceStore]" = None
+    on_select: Optional[Callable[[DialogResult], None]] = None
+    on_cancel: Optional[Callable[[], None]] = None
+
+    def info_callbacks(self) -> List[DrawCallback]:
+        """Normalize ``info`` to a list of callbacks."""
+        if self.info is None:
+            return []
+        if callable(self.info):
+            return [self.info]
+        return list(self.info)

imgui_data_loader/dialog.py

@@ -0,0 +1,348 @@
+"""The :class:`FileDialog` widget.
+
+Render it inside a hello_imgui / immapp frame (set ``params.callbacks.show_gui
+= dialog.render``). Buttons trigger the OS-native picker via
+``portable_file_dialogs``; when a selection completes it lands on
+:attr:`FileDialog.result`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Optional
+
+from imgui_bundle import (
+    hello_imgui,
+    icons_fontawesome_6 as fa,
+    imgui,
+    imgui_ctx,
+    portable_file_dialogs as pfd,
+)
+
+from .config import (
+    ButtonSpec,
+    DialogResult,
+    FileDialogConfig,
+    FileType,
+    PickKind,
+    flatten_filters,
+)
+from .theme import Theme, to_vec4
+from .widgets import (
+    call_draw,
+    center_next_item,
+    center_text,
+    icon_button,
+    pop_button_style,
+    push_button_style,
+    wrapped_tooltip,
+)
+
+
+class FileDialog:
+    """A themed, configurable file/folder open dialog.
+
+    Parameters
+    ----------
+    config : FileDialogConfig | None
+        Behavior and content. Defaults to a plain "Open File(s) / Select
+        Folder" launcher.
+    """
+
+    def __init__(self, config: Optional[FileDialogConfig] = None):
+        self.config = config or FileDialogConfig()
+        self._pending = None  # active portable_file_dialogs handle
+        self._pending_kind: Optional[PickKind] = None
+        self._result: Optional[DialogResult] = None
+        self._open_options = False
+
+    # ------------------------------------------------------------------
+    # public surface
+    # ------------------------------------------------------------------
+    @property
+    def theme(self) -> Theme:
+        return self.config.theme
+
+    @property
+    def result(self) -> Optional[DialogResult]:
+        """Last completed result (peek; does not clear)."""
+        return self._result
+
+    def take_result(self) -> Optional[DialogResult]:
+        """Return the last result and clear it (for embedded per-frame polling)."""
+        r, self._result = self._result, None
+        return r
+
+    def open_options(self) -> None:
+        """Programmatically open the Options popup on the next frame."""
+        self._open_options = True
+
+    def cancel(self) -> None:
+        """Finish with an empty, cancelled result (as the Quit button does)."""
+        self._finish(DialogResult(paths=[], kind=None, cancelled=True))
+
+    # ------------------------------------------------------------------
+    # native picker plumbing
+    # ------------------------------------------------------------------
+    def _start_dir(self) -> str:
+        if self.config.default_dir:
+            return str(self.config.default_dir)
+        store = self.config.persistence
+        if store is not None:
+            try:
+                d = store.default_dir()
+                if d:
+                    return str(d)
+            except Exception:
+                pass
+        return str(Path.home())
+
+    def _filters_for(self, btn: ButtonSpec) -> List[str]:
+        fts = btn.filetypes if btn.filetypes is not None else self.config.filetypes
+        return flatten_filters(fts or [FileType("All Files", "*")])
+
+    def _launch(self, btn: ButtonSpec) -> None:
+        start = self._start_dir()
+        title = btn.title or btn.label
+        if btn.kind == PickKind.OPEN_FILE:
+            opt = pfd.opt.multiselect if btn.multiselect else pfd.opt.none
+            self._pending = pfd.open_file(title, start, self._filters_for(btn), opt)
+        elif btn.kind == PickKind.SELECT_FOLDER:
+            self._pending = pfd.select_folder(title, start)
+        elif btn.kind == PickKind.SAVE_FILE:
+            self._pending = pfd.save_file(title, start, self._filters_for(btn))
+        else:
+            return
+        self._pending_kind = btn.kind
+
+    def _poll(self) -> None:
+        if self._pending is None or not self._pending.ready():
+            return
+        raw = self._pending.result()
+        kind = self._pending_kind
+        self._pending = None
+        self._pending_kind = None
+        if isinstance(raw, list):
+            paths = [p for p in raw if p]
+        elif raw:
+            paths = [raw]
+        else:
+            paths = []
+        # An empty result means the user cancelled the native picker itself;
+        # stay open so they can try another button.
+        if paths:
+            self._finish(DialogResult(paths=paths, kind=kind, cancelled=False))
+
+    def _finish(self, result: DialogResult) -> None:
+        self._result = result
+        cfg = self.config
+        if not result.cancelled:
+            if cfg.persistence is not None:
+                try:
+                    cfg.persistence.record_selection(result)
+                except Exception:
+                    pass
+            if cfg.on_select is not None:
+                cfg.on_select(result)
+            if cfg.close_on_select:
+                self._request_exit()
+        else:
+            if cfg.on_cancel is not None:
+                cfg.on_cancel()
+            self._request_exit()
+
+    @staticmethod
+    def _request_exit() -> None:
+        try:
+            hello_imgui.get_runner_params().app_shall_exit = True
+        except Exception:
+            pass
+
+    # ------------------------------------------------------------------
+    # rendering
+    # ------------------------------------------------------------------
+    def render(self) -> None:
+        """Draw one frame of the dialog. Use as ``callbacks.show_gui``."""
+        theme = self.theme
+        imgui.push_style_color(imgui.Col_.window_bg, to_vec4(theme.bg))
+        imgui.push_style_color(imgui.Col_.child_bg, imgui.ImVec4(0, 0, 0, 0))
+        imgui.push_style_color(imgui.Col_.text, to_vec4(theme.text))
+        imgui.push_style_color(imgui.Col_.border, to_vec4(theme.border))
+        imgui.push_style_color(imgui.Col_.separator, to_vec4(theme.separator))
+        imgui.push_style_color(imgui.Col_.frame_bg, to_vec4(theme.frame_bg))
+        imgui.push_style_color(imgui.Col_.frame_bg_hovered, to_vec4(theme.frame_bg_hovered))
+        imgui.push_style_color(imgui.Col_.check_mark, to_vec4(theme.accent))
+        imgui.push_style_var(imgui.StyleVar_.window_padding, hello_imgui.em_to_vec2(1.0, 0.8))
+        imgui.push_style_var(imgui.StyleVar_.frame_padding, hello_imgui.em_to_vec2(0.6, 0.4))
+        imgui.push_style_var(imgui.StyleVar_.item_spacing, hello_imgui.em_to_vec2(0.6, 0.4))
+        imgui.push_style_var(imgui.StyleVar_.frame_rounding, theme.frame_rounding)
+
+        with imgui_ctx.begin_child(
+            "##idl_main",
+            size=imgui.ImVec2(0, 0),
+            window_flags=imgui.WindowFlags_.no_scrollbar,
+        ):
+            imgui.push_id("imgui_data_loader")
+
+            self._draw_header()
+
+            imgui.dummy(hello_imgui.em_to_vec2(0, 0.3))
+            imgui.separator()
+            imgui.dummy(hello_imgui.em_to_vec2(0, 0.3))
+
+            if self.config.top_draw is not None:
+                call_draw(self.config.top_draw, self)
+                imgui.dummy(hello_imgui.em_to_vec2(0, 0.2))
+
+            self._draw_buttons()
+            self._draw_info_card()
+            self._draw_options_popup()
+            self._poll()
+            self._draw_footer()
+
+            imgui.pop_id()
+
+        imgui.pop_style_var(4)
+        imgui.pop_style_color(8)
+
+    def _button_width(self) -> float:
+        avail_w = imgui.get_content_region_avail().x
+        return min(avail_w - hello_imgui.em_size(2), hello_imgui.em_size(16))
+
+    def _draw_header(self) -> None:
+        if self.config.header_draw is not None:
+            call_draw(self.config.header_draw, self)
+            return
+        imgui.dummy(hello_imgui.em_to_vec2(0, 0.3))
+        center_text(self.config.title, self.theme.accent)
+        if self.config.subtitle:
+            center_text(self.config.subtitle, self.theme.text_dim)
+
+    def _draw_buttons(self) -> None:
+        btn_w = self._button_width()
+        btn_h = hello_imgui.em_size(1.8)
+        for i, btn in enumerate(self.config.buttons):
+            center_next_item(btn_w)
+            imgui.push_id(i)
+            if icon_button(
+                btn.icon,
+                btn.label,
+                imgui.ImVec2(btn_w, btn_h),
+                theme=self.theme,
+                tooltip=btn.tooltip,
+            ):
+                self._launch(btn)
+            imgui.pop_id()
+            imgui.dummy(hello_imgui.em_to_vec2(0, 0.2))
+
+    def _draw_info_card(self) -> None:
+        callbacks = self.config.info_callbacks()
+        if not callbacks:
+            return
+        theme = self.theme
+        imgui.dummy(hello_imgui.em_to_vec2(0, 0.2))
+        avail_w = imgui.get_content_region_avail().x
+        card_w = avail_w - hello_imgui.em_size(1)
+        center_next_item(card_w)
+
+        imgui.push_style_color(imgui.Col_.child_bg, to_vec4(theme.bg_card))
+        imgui.push_style_var(imgui.StyleVar_.child_rounding, theme.child_rounding)
+        imgui.push_style_var(imgui.StyleVar_.cell_padding, hello_imgui.em_to_vec2(0.4, 0.2))
+
+        child_flags = imgui.ChildFlags_.borders | imgui.ChildFlags_.auto_resize_y
+        window_flags = imgui.WindowFlags_.no_scrollbar
+        with imgui_ctx.begin_child(
+            "##idl_info",
+            size=imgui.ImVec2(card_w, 0),
+            child_flags=child_flags,
+            window_flags=window_flags,
+        ):
+            imgui.dummy(hello_imgui.em_to_vec2(0, 0.2))
+            imgui.indent(hello_imgui.em_size(0.6))
+            for j, cb in enumerate(callbacks):
+                if j:
+                    imgui.dummy(hello_imgui.em_to_vec2(0, 0.2))
+                imgui.push_id(1000 + j)
+                call_draw(cb, self)
+                imgui.pop_id()
+            imgui.unindent(hello_imgui.em_size(0.6))
+            imgui.dummy(hello_imgui.em_to_vec2(0, 0.3))
+
+        imgui.pop_style_var(2)
+        imgui.pop_style_color()
+
+    def _draw_options_popup(self) -> None:
+        if self.config.options_draw is None:
+            return
+        if self._open_options:
+            imgui.open_popup("##idl_options")
+            self._open_options = False
+        if not imgui.begin_popup("##idl_options", imgui.WindowFlags_.always_auto_resize):
+            return
+        try:
+            imgui.text_colored(
+                to_vec4(self.theme.accent),
+                f"{fa.ICON_FA_GEARS}  {self.config.options_label}",
+            )
+            imgui.separator()
+            imgui.dummy(hello_imgui.em_to_vec2(0, 0.2))
+            call_draw(self.config.options_draw, self)
+            imgui.dummy(hello_imgui.em_to_vec2(0, 0.3))
+            if imgui.button("Close", imgui.ImVec2(hello_imgui.em_size(6), 0)):
+                imgui.close_current_popup()
+        finally:
+            imgui.end_popup()
+
+    def _draw_footer(self) -> None:
+        cfg = self.config
+        if cfg.footer_draw is not None:
+            imgui.dummy(hello_imgui.em_to_vec2(0, 0.3))
+            call_draw(cfg.footer_draw, self)
+            self._handle_escape()
+            return
+
+        show_options = cfg.options_draw is not None and cfg.show_options_button
+        show_quit = cfg.show_quit_button
+        if not (show_options or show_quit):
+            self._handle_escape()
+            return
+
+        imgui.dummy(hello_imgui.em_to_vec2(0, 0.3))
+        theme = self.theme
+        style = imgui.get_style()
+        # size each button to its (icon + label) text so custom labels don't clip
+        opt_text = f"{fa.ICON_FA_GEARS}  {cfg.options_label}"
+        quit_text = f"{fa.ICON_FA_XMARK}  {cfg.quit_label}"
+        pad = style.frame_padding.x * 2 + hello_imgui.em_size(0.6)
+        min_w = hello_imgui.em_size(4.5)
+        opt_w = max(imgui.calc_text_size(opt_text).x + pad, min_w)
+        quit_w = max(imgui.calc_text_size(quit_text).x + pad, min_w)
+        spacing = style.item_spacing.x
+        row_w = 0.0
+        if show_options:
+            row_w += opt_w
+        if show_quit:
+            row_w += quit_w
+        if show_options and show_quit:
+            row_w += spacing
+        center_next_item(row_w)
+
+        btn_h = hello_imgui.em_size(1.5)
+        push_button_style(theme, primary=False)
+        if show_options:
+            if imgui.button(opt_text, imgui.ImVec2(opt_w, btn_h)):
+                self._open_options = True
+            if imgui.is_item_hovered():
+                wrapped_tooltip(cfg.options_label)
+            if show_quit:
+                imgui.same_line()
+        if show_quit:
+            if imgui.button(quit_text, imgui.ImVec2(quit_w, btn_h)):
+                self.cancel()
+        pop_button_style()
+
+        self._handle_escape()
+
+    def _handle_escape(self) -> None:
+        if self.config.quit_on_escape and imgui.is_key_pressed(imgui.Key.escape):
+            self.cancel()